@databricks/appkit 0.81.0 → 0.83.0

package/dist/cli/package-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-manager.js","names":[],"sources":["../../src/cli/package-manager.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\n\ntype PackageManager = \"pnpm\" | \"npm\" | \"yarn\" | \"bun\";\n\nfunction isPackageManager(value: string): value is PackageManager {\n  return (\n    value === \"pnpm\" || value === \"npm\" || value === \"yarn\" || value === \"bun\"\n  );\n}\n\n/**\n * Prefers the project's packageManager field, then its lockfiles, then\n * npm_config_user_agent. The launcher (e.g. npx) may use a different manager.\n */\nexport function detectPackageManager(\n  cwd: string,\n  fallback: PackageManager = \"pnpm\",\n): PackageManager {\n  try {\n    const pkg = JSON.parse(\n      fs.readFileSync(path.join(cwd, \"package.json\"), \"utf-8\"),\n    ) as { packageManager?: unknown } | null;\n    if (typeof pkg?.packageManager === \"string\") {\n      const name = pkg.packageManager.split(\"@\")[0];\n      if (isPackageManager(name)) return name;\n    }\n  } catch {\n    // A missing or unreadable manifest still permits lockfile detection.\n  }\n\n  if (fs.existsSync(path.join(cwd, \"pnpm-lock.yaml\"))) return \"pnpm\";\n  if (fs.existsSync(path.join(cwd, \"yarn.lock\"))) return \"yarn\";\n  if (\n    fs.existsSync(path.join(cwd, \"bun.lock\")) ||\n    fs.existsSync(path.join(cwd, \"bun.lockb\"))\n  ) {\n    return \"bun\";\n  }\n  if (\n    fs.existsSync(path.join(cwd, \"package-lock.json\")) ||\n    fs.existsSync(path.join(cwd, \"npm-shrinkwrap.json\"))\n  ) {\n    return \"npm\";\n  }\n\n  const userAgent = process.env.npm_config_user_agent;\n  if (userAgent) {\n    const firstToken = userAgent.split(\"/\")[0];\n    if (isPackageManager(firstToken)) return firstToken;\n  }\n\n  return fallback;\n}\n\n/**\n * Command strings for each package manager.\n * Per-PM forms for: install, build (script), add, exec.\n * Scripts always use explicit `run` (e.g., `pnpm run build`).\n */\nexport const PM_COMMANDS: Record<\n  PackageManager,\n  {\n    install: string;\n    build: string;\n    add: (pkgs: string) => string;\n    exec: string;\n  }\n> = {\n  pnpm: {\n    install: \"pnpm install\",\n    build: \"pnpm run build\",\n    add: (pkgs) => `pnpm add ${pkgs}`,\n    exec: \"pnpm exec\",\n  },\n  npm: {\n    install: \"npm install\",\n    build: \"npm run build\",\n    add: (pkgs) => `npm install ${pkgs}`,\n    exec: \"npx\",\n  },\n  yarn: {\n    install: \"yarn install\",\n    build: \"yarn run build\",\n    add: (pkgs) => `yarn add ${pkgs}`,\n    exec: \"yarn dlx\",\n  },\n  bun: {\n    install: \"bun install\",\n    build: \"bun run build\",\n    add: (pkgs) => `bun add ${pkgs}`,\n    exec: \"bun x\",\n  },\n};\n\nexport type { PackageManager };\n"],"mappings":";;;;AAKA,SAAS,iBAAiB,OAAwC;AAChE,QACE,UAAU,UAAU,UAAU,SAAS,UAAU,UAAU,UAAU;;;;;;AAQzE,SAAgB,qBACd,KACA,WAA2B,QACX;AAChB,KAAI;EACF,MAAM,MAAM,KAAK,MACf,GAAG,aAAa,KAAK,KAAK,KAAK,eAAe,EAAE,QAAQ,CACzD;AACD,MAAI,OAAO,KAAK,mBAAmB,UAAU;GAC3C,MAAM,OAAO,IAAI,eAAe,MAAM,IAAI,CAAC;AAC3C,OAAI,iBAAiB,KAAK,CAAE,QAAO;;SAE/B;AAIR,KAAI,GAAG,WAAW,KAAK,KAAK,KAAK,iBAAiB,CAAC,CAAE,QAAO;AAC5D,KAAI,GAAG,WAAW,KAAK,KAAK,KAAK,YAAY,CAAC,CAAE,QAAO;AACvD,KACE,GAAG,WAAW,KAAK,KAAK,KAAK,WAAW,CAAC,IACzC,GAAG,WAAW,KAAK,KAAK,KAAK,YAAY,CAAC,CAE1C,QAAO;AAET,KACE,GAAG,WAAW,KAAK,KAAK,KAAK,oBAAoB,CAAC,IAClD,GAAG,WAAW,KAAK,KAAK,KAAK,sBAAsB,CAAC,CAEpD,QAAO;CAGT,MAAM,YAAY,QAAQ,IAAI;AAC9B,KAAI,WAAW;EACb,MAAM,aAAa,UAAU,MAAM,IAAI,CAAC;AACxC,MAAI,iBAAiB,WAAW,CAAE,QAAO;;AAG3C,QAAO;;;;;;;AAQT,MAAa,cAQT;CACF,MAAM;EACJ,SAAS;EACT,OAAO;EACP,MAAM,SAAS,YAAY;EAC3B,MAAM;EACP;CACD,KAAK;EACH,SAAS;EACT,OAAO;EACP,MAAM,SAAS,eAAe;EAC9B,MAAM;EACP;CACD,MAAM;EACJ,SAAS;EACT,OAAO;EACP,MAAM,SAAS,YAAY;EAC3B,MAAM;EACP;CACD,KAAK;EACH,SAAS;EACT,OAAO;EACP,MAAM,SAAS,WAAW;EAC1B,MAAM;EACP;CACF"}

package/dist/connectors/lakebase/index.js

@@ -2,8 +2,8 @@ import { createWorkspaceClient } from "../../shared/src/workspace-client/factory
 import { getClientOptions } from "../../context/client-options.js";
 import { ConfigurationError } from "../../errors/configuration.js";
 import "../../errors/index.js";
-import { ServiceContext } from "../../context/service-context.js";
 import { createLogger } from "../../logging/logger.js";
+import { ServiceContext } from "../../context/service-context.js";
 import { createLakebasePoolManager } from "./pool-manager.js";
 import { RoutingPool } from "./routing-pool.js";
 import { RequestedClaimsPermissionSet, createLakebasePool, generateDatabaseCredential, getLakebaseOrmConfig, getLakebasePgConfig, getUsernameWithApiLookup, getUsernameWithApiLookup as getUsernameWithApiLookup$1, getWorkspaceClient } from "@databricks/lakebase";

package/dist/connectors/lakebase/routing-pool.d.ts

@@ -1,4 +1,4 @@
-import "../../context/user-context.js";
+import "../../context/caller-context.js";
 import { Pool, PoolClient, QueryResult, QueryResultRow } from "pg";
 
 //#region src/connectors/lakebase/routing-pool.d.ts

package/dist/connectors/lakebase/routing-pool.js

@@ -1,11 +1,11 @@
-import { getUserContext } from "../../context/execution-context.js";
+import { getCallerContext } from "../../context/execution-context.js";
 
 //#region src/connectors/lakebase/routing-pool.ts
 /**
 * A `pg.Pool`-like wrapper that routes queries to the appropriate pool
 * based on the current execution context.
 *
-* When called inside `runInUserContext()` (set up by `Plugin.asUser(req)`),
+* When called inside `runInCallerContext()` (set up by `Plugin.asUser(req)`),
 * queries route to the per-user pool returned by `resolveUserPool`.
 * Otherwise, queries route to the service-principal pool.
 *
@@ -19,7 +19,7 @@ var RoutingPool = class {
 		this.resolveUserPool = resolveUserPool;
 	}
 	activePool() {
-		const userCtx = getUserContext();
+		const userCtx = getCallerContext();
 		return userCtx ? this.resolveUserPool(userCtx) : this.spPool;
 	}
 	query(text, values) {

package/dist/connectors/lakebase/routing-pool.js.map

@@ -1 +1 @@
-{"version":3,"file":"routing-pool.js","names":[],"sources":["../../../src/connectors/lakebase/routing-pool.ts"],"sourcesContent":["import type { Pool, PoolClient, QueryResult, QueryResultRow } from \"pg\";\n\nimport { getUserContext } from \"../../context/execution-context\";\nimport type { UserContext } from \"../../context/user-context\";\n\n/**\n * Subset of `pg.Pool` exposed by the Lakebase plugin.\n *\n * RoutingPool does not extend EventEmitter — event listener methods\n * like `on('error', ...)` are not available. Use `query()`, `connect()`,\n * and `end()` for all pool operations.\n */\nexport interface LakebasePool {\n  query<T extends QueryResultRow = any>(\n    text: string,\n    values?: unknown[],\n  ): Promise<QueryResult<T>>;\n  connect(): Promise<PoolClient>;\n  end(): Promise<void>;\n  readonly totalCount: number;\n  readonly idleCount: number;\n  readonly waitingCount: number;\n}\n\n/**\n * A `pg.Pool`-like wrapper that routes queries to the appropriate pool\n * based on the current execution context.\n *\n * When called inside `runInUserContext()` (set up by `Plugin.asUser(req)`),\n * queries route to the per-user pool returned by `resolveUserPool`.\n * Otherwise, queries route to the service-principal pool.\n *\n * This enables OBO (On-Behalf-Of) without custom `asUser()` overrides —\n * the base class sets up AsyncLocalStorage context, and the RoutingPool\n * reads it transparently.\n */\nexport class RoutingPool implements LakebasePool {\n  constructor(\n    private spPool: Pool,\n    private resolveUserPool: (ctx: UserContext) => Pool,\n  ) {}\n\n  private activePool(): Pool {\n    const userCtx = getUserContext();\n    return userCtx ? this.resolveUserPool(userCtx) : this.spPool;\n  }\n\n  query<T extends QueryResultRow = any>(\n    text: string,\n    values?: unknown[],\n  ): Promise<QueryResult<T>> {\n    return this.activePool().query<T>(text, values);\n  }\n\n  connect(): Promise<PoolClient> {\n    return this.activePool().connect();\n  }\n\n  async end(): Promise<void> {\n    await this.spPool.end();\n  }\n\n  get totalCount() {\n    return this.spPool.totalCount;\n  }\n  get idleCount() {\n    return this.spPool.idleCount;\n  }\n  get waitingCount() {\n    return this.spPool.waitingCount;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AAoCA,IAAa,cAAb,MAAiD;CAC/C,YACE,AAAQ,QACR,AAAQ,iBACR;EAFQ;EACA;;CAGV,AAAQ,aAAmB;EACzB,MAAM,UAAU,gBAAgB;AAChC,SAAO,UAAU,KAAK,gBAAgB,QAAQ,GAAG,KAAK;;CAGxD,MACE,MACA,QACyB;AACzB,SAAO,KAAK,YAAY,CAAC,MAAS,MAAM,OAAO;;CAGjD,UAA+B;AAC7B,SAAO,KAAK,YAAY,CAAC,SAAS;;CAGpC,MAAM,MAAqB;AACzB,QAAM,KAAK,OAAO,KAAK;;CAGzB,IAAI,aAAa;AACf,SAAO,KAAK,OAAO;;CAErB,IAAI,YAAY;AACd,SAAO,KAAK,OAAO;;CAErB,IAAI,eAAe;AACjB,SAAO,KAAK,OAAO"}
+{"version":3,"file":"routing-pool.js","names":[],"sources":["../../../src/connectors/lakebase/routing-pool.ts"],"sourcesContent":["import type { Pool, PoolClient, QueryResult, QueryResultRow } from \"pg\";\n\nimport type { CallerContext } from \"../../context/caller-context\";\nimport { getCallerContext } from \"../../context/execution-context\";\n\n/**\n * Subset of `pg.Pool` exposed by the Lakebase plugin.\n *\n * RoutingPool does not extend EventEmitter — event listener methods\n * like `on('error', ...)` are not available. Use `query()`, `connect()`,\n * and `end()` for all pool operations.\n */\nexport interface LakebasePool {\n  query<T extends QueryResultRow = any>(\n    text: string,\n    values?: unknown[],\n  ): Promise<QueryResult<T>>;\n  connect(): Promise<PoolClient>;\n  end(): Promise<void>;\n  readonly totalCount: number;\n  readonly idleCount: number;\n  readonly waitingCount: number;\n}\n\n/**\n * A `pg.Pool`-like wrapper that routes queries to the appropriate pool\n * based on the current execution context.\n *\n * When called inside `runInCallerContext()` (set up by `Plugin.asUser(req)`),\n * queries route to the per-user pool returned by `resolveUserPool`.\n * Otherwise, queries route to the service-principal pool.\n *\n * This enables OBO (On-Behalf-Of) without custom `asUser()` overrides —\n * the base class sets up AsyncLocalStorage context, and the RoutingPool\n * reads it transparently.\n */\nexport class RoutingPool implements LakebasePool {\n  constructor(\n    private spPool: Pool,\n    private resolveUserPool: (ctx: CallerContext) => Pool,\n  ) {}\n\n  private activePool(): Pool {\n    const userCtx = getCallerContext();\n    return userCtx ? this.resolveUserPool(userCtx) : this.spPool;\n  }\n\n  query<T extends QueryResultRow = any>(\n    text: string,\n    values?: unknown[],\n  ): Promise<QueryResult<T>> {\n    return this.activePool().query<T>(text, values);\n  }\n\n  connect(): Promise<PoolClient> {\n    return this.activePool().connect();\n  }\n\n  async end(): Promise<void> {\n    await this.spPool.end();\n  }\n\n  get totalCount() {\n    return this.spPool.totalCount;\n  }\n  get idleCount() {\n    return this.spPool.idleCount;\n  }\n  get waitingCount() {\n    return this.spPool.waitingCount;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AAoCA,IAAa,cAAb,MAAiD;CAC/C,YACE,AAAQ,QACR,AAAQ,iBACR;EAFQ;EACA;;CAGV,AAAQ,aAAmB;EACzB,MAAM,UAAU,kBAAkB;AAClC,SAAO,UAAU,KAAK,gBAAgB,QAAQ,GAAG,KAAK;;CAGxD,MACE,MACA,QACyB;AACzB,SAAO,KAAK,YAAY,CAAC,MAAS,MAAM,OAAO;;CAGjD,UAA+B;AAC7B,SAAO,KAAK,YAAY,CAAC,SAAS;;CAGpC,MAAM,MAAqB;AACzB,QAAM,KAAK,OAAO,KAAK;;CAGzB,IAAI,aAAa;AACf,SAAO,KAAK,OAAO;;CAErB,IAAI,YAAY;AACd,SAAO,KAAK,OAAO;;CAErB,IAAI,eAAe;AACjB,SAAO,KAAK,OAAO"}

package/dist/context/caller-context.d.ts

@@ -0,0 +1,22 @@
+import { ServiceContextState } from "./service-context.js";
+
+//#region src/context/caller-context.d.ts
+/** The caller identity whose permissions authorize execution, not its resources. */
+type CallerPrincipal = Readonly<{
+  type: "user";
+  userId: string;
+  userName?: string;
+  userEmail?: string;
+}>;
+/** Caller identity and workspace for one immutable execution scope. */
+interface CallerContext {
+  readonly client: ServiceContextState["client"];
+  readonly principal: CallerPrincipal;
+  /** Truncated SHA-256 hash of the caller token, used to detect rotation. */
+  readonly tokenFingerprint?: string;
+  readonly workspaceId: Promise<string>;
+}
+type ExecutionContext = ServiceContextState | CallerContext;
+//#endregion
+export { CallerContext, CallerPrincipal, ExecutionContext };
+//# sourceMappingURL=caller-context.d.ts.map

package/dist/context/caller-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"caller-context.d.ts","names":[],"sources":["../../src/context/caller-context.ts"],"mappings":";;;;KAGY,eAAA,GAAkB,QAAA;EAC5B,IAAA;EACA,MAAA;EACA,QAAA;EACA,SAAA;AAAA;;UAIe,aAAA;EAAA,SACN,MAAA,EAAQ,mBAAA;EAAA,SACR,SAAA,EAAW,eAAA;EANX;EAAA,SAQA,gBAAA;EAAA,SACA,WAAA,EAAa,OAAA;AAAA;AAAA,KAkBZ,gBAAA,GAAmB,mBAAA,GAAsB,aAAA"}

package/dist/context/caller-context.js

@@ -0,0 +1,21 @@
+//#region src/context/caller-context.ts
+const snapshots = /* @__PURE__ */ new WeakSet();
+/** Snapshot identity without freezing the SDK client's internal lifecycle. */
+function snapshotCallerContext(ctx) {
+	if (snapshots.has(ctx)) return ctx;
+	const snapshot = Object.freeze({
+		client: ctx.client,
+		principal: Object.freeze({ ...ctx.principal }),
+		tokenFingerprint: ctx.tokenFingerprint,
+		workspaceId: ctx.workspaceId
+	});
+	snapshots.add(snapshot);
+	return snapshot;
+}
+function isCallerContext(ctx) {
+	return "principal" in ctx && ctx.principal.type === "user";
+}
+
+//#endregion
+export { isCallerContext, snapshotCallerContext };
+//# sourceMappingURL=caller-context.js.map

package/dist/context/caller-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"caller-context.js","names":[],"sources":["../../src/context/caller-context.ts"],"sourcesContent":["import type { ServiceContextState } from \"./service-context\";\n\n/** The caller identity whose permissions authorize execution, not its resources. */\nexport type CallerPrincipal = Readonly<{\n  type: \"user\";\n  userId: string;\n  userName?: string;\n  userEmail?: string;\n}>;\n\n/** Caller identity and workspace for one immutable execution scope. */\nexport interface CallerContext {\n  readonly client: ServiceContextState[\"client\"];\n  readonly principal: CallerPrincipal;\n  /** Truncated SHA-256 hash of the caller token, used to detect rotation. */\n  readonly tokenFingerprint?: string;\n  readonly workspaceId: Promise<string>;\n}\n\nconst snapshots = new WeakSet<CallerContext>();\n\n/** Snapshot identity without freezing the SDK client's internal lifecycle. */\nexport function snapshotCallerContext(ctx: CallerContext): CallerContext {\n  if (snapshots.has(ctx)) return ctx;\n  const snapshot = Object.freeze({\n    client: ctx.client,\n    principal: Object.freeze({ ...ctx.principal }),\n    tokenFingerprint: ctx.tokenFingerprint,\n    workspaceId: ctx.workspaceId,\n  });\n  snapshots.add(snapshot);\n  return snapshot;\n}\n\nexport type ExecutionContext = ServiceContextState | CallerContext;\n\nexport function isCallerContext(ctx: ExecutionContext): ctx is CallerContext {\n  return \"principal\" in ctx && ctx.principal.type === \"user\";\n}\n"],"mappings":";AAmBA,MAAM,4BAAY,IAAI,SAAwB;;AAG9C,SAAgB,sBAAsB,KAAmC;AACvE,KAAI,UAAU,IAAI,IAAI,CAAE,QAAO;CAC/B,MAAM,WAAW,OAAO,OAAO;EAC7B,QAAQ,IAAI;EACZ,WAAW,OAAO,OAAO,EAAE,GAAG,IAAI,WAAW,CAAC;EAC9C,kBAAkB,IAAI;EACtB,aAAa,IAAI;EAClB,CAAC;AACF,WAAU,IAAI,SAAS;AACvB,QAAO;;AAKT,SAAgB,gBAAgB,KAA6C;AAC3E,QAAO,eAAe,OAAO,IAAI,UAAU,SAAS"}

package/dist/context/deprecation.js

@@ -0,0 +1,14 @@
+import { createLogger } from "../logging/logger.js";
+
+//#region src/context/deprecation.ts
+const logger = createLogger("execution-context");
+const warned = /* @__PURE__ */ new Set();
+function warnContextDeprecation(name, replacement) {
+	if (warned.has(name)) return;
+	warned.add(name);
+	logger.warn(`${name} is deprecated. Use ${replacement} instead.`);
+}
+
+//#endregion
+export { warnContextDeprecation };
+//# sourceMappingURL=deprecation.js.map

package/dist/context/deprecation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deprecation.js","names":[],"sources":["../../src/context/deprecation.ts"],"sourcesContent":["import { createLogger } from \"../logging/logger\";\n\nconst logger = createLogger(\"execution-context\");\nconst warned = new Set<string>();\n\nexport function warnContextDeprecation(\n  name: string,\n  replacement: string,\n): void {\n  if (warned.has(name)) return;\n  warned.add(name);\n  logger.warn(`${name} is deprecated. Use ${replacement} instead.`);\n}\n"],"mappings":";;;AAEA,MAAM,SAAS,aAAa,oBAAoB;AAChD,MAAM,yBAAS,IAAI,KAAa;AAEhC,SAAgB,uBACd,MACA,aACM;AACN,KAAI,OAAO,IAAI,KAAK,CAAE;AACtB,QAAO,IAAI,KAAK;AAChB,QAAO,KAAK,GAAG,KAAK,sBAAsB,YAAY,WAAW"}

package/dist/context/execution-context.d.ts

@@ -1,15 +1,23 @@
-import { ExecutionContext } from "./user-context.js";
+import { UserContext } from "./user-context.js";
+import { ServiceContextState } from "./service-context.js";
+import { CallerContext } from "./caller-context.js";
 
 //#region src/context/execution-context.d.ts
 /**
  * Get the current execution context.
  *
- * - If running inside a user context (via asUser), returns the user context
+ * - If running inside a caller context (via asUser), returns the caller context
  * - Otherwise, returns the service context
  *
  * @throws Error if ServiceContext is not initialized
  */
-declare function getExecutionContext(): ExecutionContext;
+declare function getExecutionContext(): ServiceContextState | (CallerContext & UserContext);
+/**
+ * Get the principal key for future cache keying: `app` or `user:<id>`.
+ */
+declare function getCurrentPrincipalKey(): string;
+/** The initiating user in a caller scope; no user actor exists in service scope. */
+declare function getCurrentActorId(): string | undefined;
 //#endregion
-export { getExecutionContext };
+export { getCurrentActorId, getCurrentPrincipalKey, getExecutionContext };
 //# sourceMappingURL=execution-context.d.ts.map

package/dist/context/execution-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execution-context.d.ts","names":[],"sources":["../../src/context/execution-context.ts"],"mappings":";;;;;;;;;;;iBAoCgB,mBAAA,CAAA,GAAuB,gBAAA"}
+{"version":3,"file":"execution-context.d.ts","names":[],"sources":["../../src/context/execution-context.ts"],"mappings":";;;;;;;;;AAkFA;;;;iBAbgB,mBAAA,CAAA,GACZ,mBAAA,IACC,aAAA,GAAgB,WAAA;AAiBrB;;;AAAA,iBANgB,sBAAA,CAAA;;iBAMA,iBAAA,CAAA"}

package/dist/context/execution-context.js

@@ -1,68 +1,70 @@
-import { ConfigurationError } from "../errors/configuration.js";
-import "../errors/index.js";
+import { captureWarehouseId, runWithResourceBindings } from "../resources/warehouse.js";
+import { snapshotCallerContext } from "./caller-context.js";
+import { warnContextDeprecation } from "./deprecation.js";
+import { legacyUserContext } from "./user-context.js";
 import { ServiceContext } from "./service-context.js";
-import { isUserContext } from "./user-context.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 
 //#region src/context/execution-context.ts
-/**
-* AsyncLocalStorage for execution context.
-* Used to pass user context through the call stack without explicit parameters.
-*/
 const executionContextStorage = new AsyncLocalStorage();
+function runInCallerScope(callerContext, fn, legacyResources) {
+	const caller = snapshotCallerContext(callerContext);
+	return runWithResourceBindings(legacyResources, () => executionContextStorage.run(caller, fn));
+}
 /**
-* Run a function in the context of a user.
-* All calls within the function will have access to the user context.
+* Run a function with an immutable snapshot of the caller context.
+* Nested and concurrent scopes keep their own identities.
 *
-* @param userContext - The user context to use
+* @param callerContext - The caller context to use
 * @param fn - The function to run
 * @returns The result of the function
 */
-function runInUserContext(userContext, fn) {
-	return executionContextStorage.run(userContext, fn);
+function runInCallerContext(callerContext, fn) {
+	return runInCallerScope(callerContext, fn);
 }
 /**
 * Get the current execution context.
 *
-* - If running inside a user context (via asUser), returns the user context
+* - If running inside a caller context (via asUser), returns the caller context
 * - Otherwise, returns the service context
 *
 * @throws Error if ServiceContext is not initialized
 */
 function getExecutionContext() {
-	const userContext = executionContextStorage.getStore();
-	if (userContext) return userContext;
+	const callerContext = executionContextStorage.getStore();
+	if (callerContext) return legacyUserContext(callerContext, captureWarehouseId());
 	return ServiceContext.get();
 }
 /**
-* Get the current user ID for cache keying and telemetry.
-*
-* Returns the user ID if in user context, otherwise the service user ID.
+* Get the principal key for future cache keying: `app` or `user:<id>`.
 */
-function getCurrentUserId() {
-	const ctx = getExecutionContext();
-	if (isUserContext(ctx)) return ctx.userId;
-	return ctx.serviceUserId;
+function getCurrentPrincipalKey() {
+	const caller = getCallerContext();
+	return caller ? `user:${caller.principal.userId}` : "app";
+}
+/** The initiating user in a caller scope; no user actor exists in service scope. */
+function getCurrentActorId() {
+	return getCallerContext()?.principal.userId;
 }
 /**
-* Get the WorkspaceClient for the current execution context.
+* @deprecated Use getCurrentPrincipalKey for new cache keys or getCurrentActorId
+* for audit. Preserves the bare user or service ID for existing callers.
 */
-function getWorkspaceClient() {
-	return getExecutionContext().client;
+function getCurrentUserId() {
+	warnContextDeprecation("getCurrentUserId", "getCurrentPrincipalKey (cache) or getCurrentActorId (audit)");
+	return getCurrentActorId() ?? ServiceContext.get().serviceUserId;
 }
 /**
-* Get the warehouse ID promise.
+* Get the WorkspaceClient for the current execution context.
 */
-function getWarehouseId() {
-	const ctx = getExecutionContext();
-	if (!ctx.warehouseId) throw ConfigurationError.resourceNotFound("Warehouse ID", "No plugin requires a SQL Warehouse. Add a sql_warehouse resource to your plugin manifest, or set DATABRICKS_WAREHOUSE_ID");
-	return ctx.warehouseId;
+function getWorkspaceClient() {
+	return (getCallerContext() ?? ServiceContext.get()).client;
 }
 /**
 * Get the workspace ID promise.
 */
 function getWorkspaceId() {
-	return getExecutionContext().workspaceId;
+	return (getCallerContext() ?? ServiceContext.get()).workspaceId;
 }
 /**
 * Check if currently running in a user context.
@@ -71,14 +73,14 @@ function isInUserContext() {
 	return executionContextStorage.getStore() !== void 0;
 }
 /**
-* Get the user context if one is active, otherwise `undefined`.
+* Get the caller context if one is active, otherwise `undefined`.
 * Unlike `getExecutionContext()`, this does not require `ServiceContext`
 * to be initialized and never throws.
 */
-function getUserContext() {
+function getCallerContext() {
 	return executionContextStorage.getStore();
 }
 
 //#endregion
-export { getCurrentUserId, getExecutionContext, getUserContext, getWarehouseId, getWorkspaceClient, getWorkspaceId, isInUserContext, runInUserContext };
+export { getCallerContext, getCurrentActorId, getCurrentPrincipalKey, getCurrentUserId, getExecutionContext, getWorkspaceClient, getWorkspaceId, isInUserContext, runInCallerContext };
 //# sourceMappingURL=execution-context.js.map

package/dist/context/execution-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"execution-context.js","names":[],"sources":["../../src/context/execution-context.ts"],"sourcesContent":["import { AsyncLocalStorage } from \"node:async_hooks\";\n\nimport { ConfigurationError } from \"../errors\";\nimport { ServiceContext } from \"./service-context\";\nimport {\n  type ExecutionContext,\n  isUserContext,\n  type UserContext,\n} from \"./user-context\";\n\n/**\n * AsyncLocalStorage for execution context.\n * Used to pass user context through the call stack without explicit parameters.\n */\nconst executionContextStorage = new AsyncLocalStorage<UserContext>();\n\n/**\n * Run a function in the context of a user.\n * All calls within the function will have access to the user context.\n *\n * @param userContext - The user context to use\n * @param fn - The function to run\n * @returns The result of the function\n */\nexport function runInUserContext<T>(userContext: UserContext, fn: () => T): T {\n  return executionContextStorage.run(userContext, fn);\n}\n\n/**\n * Get the current execution context.\n *\n * - If running inside a user context (via asUser), returns the user context\n * - Otherwise, returns the service context\n *\n * @throws Error if ServiceContext is not initialized\n */\nexport function getExecutionContext(): ExecutionContext {\n  const userContext = executionContextStorage.getStore();\n  if (userContext) {\n    return userContext;\n  }\n  return ServiceContext.get();\n}\n\n/**\n * Get the current user ID for cache keying and telemetry.\n *\n * Returns the user ID if in user context, otherwise the service user ID.\n */\nexport function getCurrentUserId(): string {\n  const ctx = getExecutionContext();\n  if (isUserContext(ctx)) {\n    return ctx.userId;\n  }\n  return ctx.serviceUserId;\n}\n\n/**\n * Get the WorkspaceClient for the current execution context.\n */\nexport function getWorkspaceClient() {\n  return getExecutionContext().client;\n}\n\n/**\n * Get the warehouse ID promise.\n */\nexport function getWarehouseId(): Promise<string> {\n  const ctx = getExecutionContext();\n  if (!ctx.warehouseId) {\n    throw ConfigurationError.resourceNotFound(\n      \"Warehouse ID\",\n      \"No plugin requires a SQL Warehouse. Add a sql_warehouse resource to your plugin manifest, or set DATABRICKS_WAREHOUSE_ID\",\n    );\n  }\n  return ctx.warehouseId;\n}\n\n/**\n * Get the workspace ID promise.\n */\nexport function getWorkspaceId(): Promise<string> {\n  return getExecutionContext().workspaceId;\n}\n\n/**\n * Check if currently running in a user context.\n */\nexport function isInUserContext(): boolean {\n  const ctx = executionContextStorage.getStore();\n  return ctx !== undefined;\n}\n\n/**\n * Get the user context if one is active, otherwise `undefined`.\n * Unlike `getExecutionContext()`, this does not require `ServiceContext`\n * to be initialized and never throws.\n */\nexport function getUserContext(): UserContext | undefined {\n  return executionContextStorage.getStore();\n}\n"],"mappings":";;;;;;;;;;;AAcA,MAAM,0BAA0B,IAAI,mBAAgC;;;;;;;;;AAUpE,SAAgB,iBAAoB,aAA0B,IAAgB;AAC5E,QAAO,wBAAwB,IAAI,aAAa,GAAG;;;;;;;;;;AAWrD,SAAgB,sBAAwC;CACtD,MAAM,cAAc,wBAAwB,UAAU;AACtD,KAAI,YACF,QAAO;AAET,QAAO,eAAe,KAAK;;;;;;;AAQ7B,SAAgB,mBAA2B;CACzC,MAAM,MAAM,qBAAqB;AACjC,KAAI,cAAc,IAAI,CACpB,QAAO,IAAI;AAEb,QAAO,IAAI;;;;;AAMb,SAAgB,qBAAqB;AACnC,QAAO,qBAAqB,CAAC;;;;;AAM/B,SAAgB,iBAAkC;CAChD,MAAM,MAAM,qBAAqB;AACjC,KAAI,CAAC,IAAI,YACP,OAAM,mBAAmB,iBACvB,gBACA,2HACD;AAEH,QAAO,IAAI;;;;;AAMb,SAAgB,iBAAkC;AAChD,QAAO,qBAAqB,CAAC;;;;;AAM/B,SAAgB,kBAA2B;AAEzC,QADY,wBAAwB,UAAU,KAC/B;;;;;;;AAQjB,SAAgB,iBAA0C;AACxD,QAAO,wBAAwB,UAAU"}
+{"version":3,"file":"execution-context.js","names":[],"sources":["../../src/context/execution-context.ts"],"sourcesContent":["import { AsyncLocalStorage } from \"node:async_hooks\";\n\nimport {\n  captureWarehouseId,\n  getWarehouseId as getResourceWarehouseId,\n  runWithResourceBindings,\n  type WarehouseBinding,\n} from \"../resources/warehouse\";\nimport { type CallerContext, snapshotCallerContext } from \"./caller-context\";\nimport { warnContextDeprecation } from \"./deprecation\";\nimport { ServiceContext, type ServiceContextState } from \"./service-context\";\nimport {\n  legacyUserContext,\n  toCallerContext,\n  type UserContext,\n} from \"./user-context\";\n\nconst executionContextStorage = new AsyncLocalStorage<CallerContext>();\n\nfunction runInCallerScope<T>(\n  callerContext: CallerContext,\n  fn: () => T,\n  legacyResources?: WarehouseBinding,\n): T {\n  const caller = snapshotCallerContext(callerContext);\n  return runWithResourceBindings(legacyResources, () =>\n    executionContextStorage.run(caller, fn),\n  );\n}\n\n/**\n * Run a function with an immutable snapshot of the caller context.\n * Nested and concurrent scopes keep their own identities.\n *\n * @param callerContext - The caller context to use\n * @param fn - The function to run\n * @returns The result of the function\n */\nexport function runInCallerContext<T>(\n  callerContext: CallerContext,\n  fn: () => T,\n): T {\n  return runInCallerScope(callerContext, fn);\n}\n\n/** @deprecated Use runInCallerContext. */\nexport function runInUserContext<T>(\n  userContext: UserContext | (CallerContext & Pick<UserContext, \"warehouseId\">),\n  fn: () => T,\n): T {\n  warnContextDeprecation(\"runInUserContext\", \"runInCallerContext\");\n  if (!(\"principal\" in userContext) || \"warehouseId\" in userContext) {\n    return runInCallerScope(\n      toCallerContext(userContext),\n      fn,\n      Object.freeze({ warehouseId: userContext.warehouseId }),\n    );\n  }\n  return runInCallerContext(toCallerContext(userContext), fn);\n}\n\n/**\n * Get the current execution context.\n *\n * - If running inside a caller context (via asUser), returns the caller context\n * - Otherwise, returns the service context\n *\n * @throws Error if ServiceContext is not initialized\n */\nexport function getExecutionContext():\n  | ServiceContextState\n  | (CallerContext & UserContext) {\n  const callerContext = executionContextStorage.getStore();\n  if (callerContext) {\n    return legacyUserContext(callerContext, captureWarehouseId());\n  }\n  return ServiceContext.get();\n}\n\n/**\n * Get the principal key for future cache keying: `app` or `user:<id>`.\n */\nexport function getCurrentPrincipalKey(): string {\n  const caller = getCallerContext();\n  return caller ? `user:${caller.principal.userId}` : \"app\";\n}\n\n/** The initiating user in a caller scope; no user actor exists in service scope. */\nexport function getCurrentActorId(): string | undefined {\n  return getCallerContext()?.principal.userId;\n}\n\n/**\n * @deprecated Use getCurrentPrincipalKey for new cache keys or getCurrentActorId\n * for audit. Preserves the bare user or service ID for existing callers.\n */\nexport function getCurrentUserId(): string {\n  warnContextDeprecation(\n    \"getCurrentUserId\",\n    \"getCurrentPrincipalKey (cache) or getCurrentActorId (audit)\",\n  );\n  return getCurrentActorId() ?? ServiceContext.get().serviceUserId;\n}\n\n/**\n * Get the WorkspaceClient for the current execution context.\n */\nexport function getWorkspaceClient() {\n  return (getCallerContext() ?? ServiceContext.get()).client;\n}\n\n/**\n * @deprecated Import getWarehouseId from @databricks/appkit instead of context.\n */\nexport function getWarehouseId(): Promise<string> {\n  warnContextDeprecation(\n    \"context.getWarehouseId\",\n    \"getWarehouseId() from @databricks/appkit\",\n  );\n  return getResourceWarehouseId();\n}\n\n/**\n * Get the workspace ID promise.\n */\nexport function getWorkspaceId(): Promise<string> {\n  return (getCallerContext() ?? ServiceContext.get()).workspaceId;\n}\n\n/**\n * Check if currently running in a user context.\n */\nexport function isInUserContext(): boolean {\n  const ctx = executionContextStorage.getStore();\n  return ctx !== undefined;\n}\n\n/**\n * Get the caller context if one is active, otherwise `undefined`.\n * Unlike `getExecutionContext()`, this does not require `ServiceContext`\n * to be initialized and never throws.\n */\nexport function getCallerContext(): CallerContext | undefined {\n  return executionContextStorage.getStore();\n}\n\n/** @deprecated Use getCallerContext and its principal field. */\nexport function getUserContext(): (CallerContext & UserContext) | undefined {\n  warnContextDeprecation(\"getUserContext\", \"getCallerContext\");\n  const scope = executionContextStorage.getStore();\n  return scope ? legacyUserContext(scope, captureWarehouseId()) : undefined;\n}\n"],"mappings":";;;;;;;;AAiBA,MAAM,0BAA0B,IAAI,mBAAkC;AAEtE,SAAS,iBACP,eACA,IACA,iBACG;CACH,MAAM,SAAS,sBAAsB,cAAc;AACnD,QAAO,wBAAwB,uBAC7B,wBAAwB,IAAI,QAAQ,GAAG,CACxC;;;;;;;;;;AAWH,SAAgB,mBACd,eACA,IACG;AACH,QAAO,iBAAiB,eAAe,GAAG;;;;;;;;;;AA2B5C,SAAgB,sBAEkB;CAChC,MAAM,gBAAgB,wBAAwB,UAAU;AACxD,KAAI,cACF,QAAO,kBAAkB,eAAe,oBAAoB,CAAC;AAE/D,QAAO,eAAe,KAAK;;;;;AAM7B,SAAgB,yBAAiC;CAC/C,MAAM,SAAS,kBAAkB;AACjC,QAAO,SAAS,QAAQ,OAAO,UAAU,WAAW;;;AAItD,SAAgB,oBAAwC;AACtD,QAAO,kBAAkB,EAAE,UAAU;;;;;;AAOvC,SAAgB,mBAA2B;AACzC,wBACE,oBACA,8DACD;AACD,QAAO,mBAAmB,IAAI,eAAe,KAAK,CAAC;;;;;AAMrD,SAAgB,qBAAqB;AACnC,SAAQ,kBAAkB,IAAI,eAAe,KAAK,EAAE;;;;;AAiBtD,SAAgB,iBAAkC;AAChD,SAAQ,kBAAkB,IAAI,eAAe,KAAK,EAAE;;;;;AAMtD,SAAgB,kBAA2B;AAEzC,QADY,wBAAwB,UAAU,KAC/B;;;;;;;AAQjB,SAAgB,mBAA8C;AAC5D,QAAO,wBAAwB,UAAU"}

package/dist/context/index.d.ts

@@ -1,3 +1,4 @@
-import { ServiceContext } from "./service-context.js";
 import { UserContext } from "./user-context.js";
-import { getExecutionContext } from "./execution-context.js";
+import { ServiceContext } from "./service-context.js";
+import { CallerContext, CallerPrincipal, ExecutionContext } from "./caller-context.js";
+import { getCurrentActorId, getCurrentPrincipalKey, getExecutionContext } from "./execution-context.js";

package/dist/context/index.js

@@ -1,4 +1,5 @@
+import { isCallerContext } from "./caller-context.js";
 import { ServiceContext } from "./service-context.js";
-import { getCurrentUserId, getExecutionContext, getWarehouseId, getWorkspaceClient, getWorkspaceId, runInUserContext } from "./execution-context.js";
+import { getCallerContext, getCurrentActorId, getCurrentPrincipalKey, getCurrentUserId, getExecutionContext, getWorkspaceClient, getWorkspaceId, runInCallerContext } from "./execution-context.js";
 
 export { getWorkspaceClient };

package/dist/context/service-context.d.ts

@@ -1,24 +1,28 @@
 import { ClientOptions, WorkspaceClient } from "../workspace-client/index.js";
 import { UserContext } from "./user-context.js";
+import { CallerContext } from "./caller-context.js";
 
 //#region src/context/service-context.d.ts
 /**
- * Service context holds the service principal client and shared resources.
+ * Service context holds the service principal identity and workspace client.
  * This is initialized once at app startup and shared across all requests.
  */
 interface ServiceContextState {
   /** WorkspaceClient authenticated as the service principal */
-  client: WorkspaceClient;
+  readonly client: WorkspaceClient;
   /** The service principal's user ID */
-  serviceUserId: string;
-  /** Promise that resolves to the warehouse ID (only present when a plugin requires `SQL_WAREHOUSE` resource) */
-  warehouseId?: Promise<string>;
+  readonly serviceUserId: string;
+  /**
+   * @deprecated Use getWarehouseId() from @databricks/appkit.
+   * Retained for backward compatibility.
+   */
+  readonly warehouseId?: Promise<string>;
   /** Promise that resolves to the workspace ID */
-  workspaceId: Promise<string>;
+  readonly workspaceId: Promise<string>;
 }
 /**
  * ServiceContext is a singleton that manages the service principal's
- * WorkspaceClient and shared resources like warehouse/workspace IDs.
+ * WorkspaceClient and workspace ID. WarehouseResource owns warehouse bindings.
  *
  * It's initialized once at app startup and provides the foundation
  * for both service principal and user context execution.
@@ -30,12 +34,12 @@ declare class ServiceContext {
    * Initialize the service context. Should be called once at app startup.
    * Safe to call multiple times - will return the same instance.
    *
-   * @param options - Which shared resources to resolve (derived from plugin manifests).
+   * @param options - A resolved warehouse ID, or a boolean enabling discovery.
    * @param client - Optional pre-configured WorkspaceClient to use instead
    *   of creating one from environment credentials.
    */
   static initialize(options?: {
-    warehouseId?: boolean;
+    warehouseId?: boolean | string;
   }, client?: WorkspaceClient): Promise<ServiceContextState>;
   /**
    * Get the initialized service context.
@@ -47,14 +51,17 @@ declare class ServiceContext {
    */
   static isInitialized(): boolean;
   /**
-   * Create a user context from request headers.
+   * Create an immutable caller context from the existing user request headers.
    *
    * @param token - The user's access token from x-forwarded-access-token header
    * @param userId - The user's ID from x-forwarded-user header
    * @param userName - Optional user name
+   * @param userEmail - Optional email from x-forwarded-email
    * @throws Error if token is not provided
    */
-  static createUserContext(token: string, userId: string, userName?: string, userEmail?: string): UserContext;
+  static createCallerContext(token: string, userId: string, userName?: string, userEmail?: string): CallerContext;
+  /** @deprecated Use ServiceContext.createCallerContext. */
+  static createUserContext(token: string, userId: string, userName?: string, userEmail?: string): CallerContext & UserContext;
   /**
    * Get the client options for WorkspaceClient.
    * Exposed for testing purposes.
@@ -62,7 +69,6 @@ declare class ServiceContext {
   static getClientOptions(): ClientOptions;
   private static createContext;
   private static getWorkspaceId;
-  private static getWarehouseId;
   /**
    * Reset the service context. Only for testing purposes.
    */

package/dist/context/service-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service-context.d.ts","names":[],"sources":["../../src/context/service-context.ts"],"mappings":";;;;;;AAqBA;;UAAiB,mBAAA;EAEP;EAAR,MAAA,EAAQ,eAAA;EAMK;EAJb,aAAA;EAIoB;EAFpB,WAAA,GAAc,OAAA;EAJN;EAMR,WAAA,EAAa,OAAA;AAAA;;;;;;AAUf;;cAAa,cAAA;EAAA,eACI,QAAA;EAAA,eACA,WAAA;EAaZ;;;;;;;;EAAA,OAHU,UAAA,CACX,OAAA;IAAY,WAAA;EAAA,GACZ,MAAA,GAAS,eAAA,GACR,OAAA,CAAQ,mBAAA;EADA;;;;EAAA,OAmBJ,GAAA,CAAA,GAAO,mBAAA;EAAA;;;EAAA,OAaP,aAAA,CAAA;EAcL;;;;;;;;EAAA,OAFK,iBAAA,CACL,KAAA,UACA,MAAA,UACA,QAAA,WACA,SAAA,YACC,WAAA;EAqLI;;;;EAAA,OA1IA,gBAAA,CAAA,GAAoB,aAAA;EAAA,eAIN,aAAA;EAAA,eA2CA,cAAA;EAAA,eAuBA,cAAA;;;;SAoEd,KAAA,CAAA;AAAA"}
+{"version":3,"file":"service-context.d.ts","names":[],"sources":["../../src/context/service-context.ts"],"mappings":";;;;;;;AAuBA;;UAAiB,mBAAA;EAEE;EAAA,SAAR,MAAA,EAAQ,eAAA;EASK;EAAA,SAPb,aAAA;EAOoB;;;;EAAA,SAFpB,WAAA,GAAc,OAAA;EAAA;EAAA,SAEd,WAAA,EAAa,OAAA;AAAA;;;AAUxB;;;;;cAAa,cAAA;EAAA,eACI,QAAA;EAAA,eACA,WAAA;EAuGZ;;;;;;;;EAAA,OA7FU,UAAA,CACX,OAAA;IAAY,WAAA;EAAA,GACZ,MAAA,GAAS,eAAA,GACR,OAAA,CAAQ,mBAAA;EADT;;;;EAAA,OAmBK,GAAA,CAAA,GAAO,mBAAA;EAaP;;;EAAA,OAAA,aAAA,CAAA;EAgBL;;;;;;;;;EAAA,OAHK,mBAAA,CACL,KAAA,UACA,MAAA,UACA,QAAA,WACA,SAAA,YACC,aAAA;EA4DI;EAAA,OAxBA,iBAAA,CACL,KAAA,UACA,MAAA,UACA,QAAA,WACA,SAAA,YACC,aAAA,GAAgB,WAAA;EAuBE;;;;EAAA,OAJd,gBAAA,CAAA,GAAoB,aAAA;EAAA,eAIN,aAAA;EAAA,eA4CA,cAAA;;;;SA0Bd,KAAA,CAAA;AAAA"}

package/dist/context/service-context.js

@@ -5,12 +5,16 @@ import { AuthenticationError } from "../errors/authentication.js";
 import { ConfigurationError } from "../errors/configuration.js";
 import { InitializationError } from "../errors/initialization.js";
 import "../errors/index.js";
+import { WarehouseResource } from "../resources/warehouse.js";
+import { snapshotCallerContext } from "./caller-context.js";
+import { warnContextDeprecation } from "./deprecation.js";
+import { legacyUserContext } from "./user-context.js";
 import { createHash } from "node:crypto";
 
 //#region src/context/service-context.ts
 /**
 * ServiceContext is a singleton that manages the service principal's
-* WorkspaceClient and shared resources like warehouse/workspace IDs.
+* WorkspaceClient and workspace ID. WarehouseResource owns warehouse bindings.
 *
 * It's initialized once at app startup and provides the foundation
 * for both service principal and user context execution.
@@ -22,7 +26,7 @@ var ServiceContext = class ServiceContext {
 	* Initialize the service context. Should be called once at app startup.
 	* Safe to call multiple times - will return the same instance.
 	*
-	* @param options - Which shared resources to resolve (derived from plugin manifests).
+	* @param options - A resolved warehouse ID, or a boolean enabling discovery.
 	* @param client - Optional pre-configured WorkspaceClient to use instead
 	*   of creating one from environment credentials.
 	*/
@@ -48,33 +52,44 @@ var ServiceContext = class ServiceContext {
 		return ServiceContext.instance !== null;
 	}
 	/**
-	* Create a user context from request headers.
+	* Create an immutable caller context from the existing user request headers.
 	*
 	* @param token - The user's access token from x-forwarded-access-token header
 	* @param userId - The user's ID from x-forwarded-user header
 	* @param userName - Optional user name
+	* @param userEmail - Optional email from x-forwarded-email
 	* @throws Error if token is not provided
 	*/
-	static createUserContext(token, userId, userName, userEmail) {
+	static createCallerContext(token, userId, userName, userEmail) {
 		if (!token) throw AuthenticationError.missingToken("user token");
 		const host = process.env.DATABRICKS_HOST;
 		if (!host) throw ConfigurationError.missingEnvVar("DATABRICKS_HOST");
 		const serviceCtx = ServiceContext.get();
-		return {
-			client: createWorkspaceClient({
-				token,
-				host,
-				authType: "pat",
-				clientOptions: getClientOptions()
-			}),
-			userId,
-			userName,
-			userEmail,
-			tokenFingerprint: createHash("sha256").update(token).digest("hex").slice(0, 16),
-			warehouseId: serviceCtx.warehouseId,
-			workspaceId: serviceCtx.workspaceId,
-			isUserContext: true
-		};
+		const userClient = createWorkspaceClient({
+			token,
+			host,
+			authType: "pat",
+			clientOptions: getClientOptions()
+		});
+		const tokenFingerprint = createHash("sha256").update(token).digest("hex").slice(0, 16);
+		return snapshotCallerContext({
+			client: userClient,
+			principal: {
+				type: "user",
+				userId,
+				userName,
+				userEmail
+			},
+			tokenFingerprint,
+			workspaceId: serviceCtx.workspaceId
+		});
+	}
+	/** @deprecated Use ServiceContext.createCallerContext. */
+	static createUserContext(token, userId, userName, userEmail) {
+		warnContextDeprecation("ServiceContext.createUserContext", "ServiceContext.createCallerContext");
+		const caller = ServiceContext.createCallerContext(token, userId, userName, userEmail);
+		const warehouseId = WarehouseResource.get()?.warehouseId;
+		return legacyUserContext(caller, () => warehouseId);
 	}
 	/**
 	* Get the client options for WorkspaceClient.
@@ -86,19 +101,22 @@ var ServiceContext = class ServiceContext {
 	static async createContext(options, client) {
 		try {
 			const wsClient = client ?? createWorkspaceClient({ clientOptions: getClientOptions() });
-			const [resolvedWorkspaceId, currentUser, resolvedWarehouseId] = await Promise.all([
+			const [resolvedWorkspaceId, currentUser, resolvedResources] = await Promise.all([
 				ServiceContext.getWorkspaceId(wsClient),
 				wsClient.currentUser.me(),
-				options?.warehouseId ? ServiceContext.getWarehouseId(wsClient) : Promise.resolve(void 0)
+				WarehouseResource.resolve(wsClient, options?.warehouseId)
 			]);
 			if (!currentUser.id) throw ConfigurationError.resourceNotFound("Service user ID");
-			const warehouseId = options?.warehouseId && resolvedWarehouseId !== void 0 ? Promise.resolve(resolvedWarehouseId) : void 0;
-			return {
+			const resources = WarehouseResource.bind(resolvedResources);
+			return Object.freeze({
 				client: wsClient,
 				serviceUserId: currentUser.id,
-				warehouseId,
+				get warehouseId() {
+					warnContextDeprecation("ServiceContextState.warehouseId", "getWarehouseId() from @databricks/appkit");
+					return resources.warehouseId;
+				},
 				workspaceId: Promise.resolve(resolvedWorkspaceId)
-			};
+			});
 		} catch (e) {
 			if (e instanceof ConfigError) throw ConfigurationError.databricksAuthenticationSetupFailed(e.baseMessage, { cause: e });
 			throw e;
@@ -117,41 +135,13 @@ var ServiceContext = class ServiceContext {
 		if (!response["x-databricks-org-id"]) throw ConfigurationError.resourceNotFound("Workspace ID");
 		return response["x-databricks-org-id"];
 	}
-	static async getWarehouseId(client) {
-		if (process.env.DATABRICKS_WAREHOUSE_ID) return process.env.DATABRICKS_WAREHOUSE_ID;
-		const agenticMode = process.env.DATABRICKS_APPS_AGENTIC_MODE === "true" || process.env.DATABRICKS_APPS_AGENTIC_MODE === "1";
-		if (process.env.NODE_ENV === "development" && !agenticMode) {
-			const response = await client.apiClient.request({
-				path: "/api/2.0/sql/warehouses",
-				method: "GET",
-				headers: new Headers(),
-				raw: false,
-				query: { skip_cannot_use: "true" }
-			});
-			const priorities = {
-				RUNNING: 0,
-				STOPPED: 1,
-				STARTING: 2,
-				STOPPING: 3,
-				DELETED: 99,
-				DELETING: 99
-			};
-			const warehouses = (response.warehouses || []).sort((a, b) => {
-				return priorities[a.state] - priorities[b.state];
-			});
-			if (response.warehouses.length === 0) throw ConfigurationError.resourceNotFound("Warehouse ID", "Please configure the DATABRICKS_WAREHOUSE_ID environment variable");
-			const firstWarehouse = warehouses[0];
-			if (firstWarehouse.state === "DELETED" || firstWarehouse.state === "DELETING" || !firstWarehouse.id) throw ConfigurationError.resourceNotFound("Warehouse ID", "Please configure the DATABRICKS_WAREHOUSE_ID environment variable");
-			return firstWarehouse.id;
-		}
-		throw ConfigurationError.resourceNotFound("Warehouse ID", "Please configure the DATABRICKS_WAREHOUSE_ID environment variable");
-	}
 	/**
 	* Reset the service context. Only for testing purposes.
 	*/
 	static reset() {
 		ServiceContext.instance = null;
 		ServiceContext.initPromise = null;
+		WarehouseResource.reset();
 	}
 };