@databricks/appkit 0.82.0 → 0.83.0

package/CLAUDE.md

@@ -122,12 +122,15 @@ npx @databricks/appkit docs <query>
 - [Function: fromSupervisorApi()](./docs/api/appkit/Function.fromSupervisorApi.md): Creates an AgentAdapter backed by the Databricks AI Gateway
 - [Function: functionToolToDefinition()](./docs/api/appkit/Function.functionToolToDefinition.md): Parameters
 - [Function: generateDatabaseCredential()](./docs/api/appkit/Function.generateDatabaseCredential.md): Generate OAuth credentials for Postgres database connection using the proper Postgres API.
+- [Function: getCurrentActorId()](./docs/api/appkit/Function.getCurrentActorId.md): The initiating user in a caller scope; no user actor exists in service scope.
+- [Function: getCurrentPrincipalKey()](./docs/api/appkit/Function.getCurrentPrincipalKey.md): Get the principal key for future cache keying.
 - [Function: getExecutionContext()](./docs/api/appkit/Function.getExecutionContext.md): Get the current execution context.
 - [Function: getLakebaseOrmConfig()](./docs/api/appkit/Function.getLakebaseOrmConfig.md): Get Lakebase connection configuration for ORMs that don't accept pg.Pool directly.
 - [Function: getLakebasePgConfig()](./docs/api/appkit/Function.getLakebasePgConfig.md): Get Lakebase connection configuration for PostgreSQL clients.
 - [Function: getPluginManifest()](./docs/api/appkit/Function.getPluginManifest.md): Loads and validates the manifest from a plugin constructor.
 - [Function: getResourceRequirements()](./docs/api/appkit/Function.getResourceRequirements.md): Gets the resource requirements from a plugin's manifest.
 - [Function: getUsernameWithApiLookup()](./docs/api/appkit/Function.getUsernameWithApiLookup.md): Resolves the PostgreSQL username for a Lakebase connection.
+- [Function: getWarehouseId()](./docs/api/appkit/Function.getWarehouseId.md): Get the configured SQL warehouse ID after app initialization.
 - [Function: getWorkspaceClient()](./docs/api/appkit/Function.getWorkspaceClient.md): Get workspace client from config or SDK default auth chain
 - [Function: id()](./docs/api/appkit/Function.id.md): Returns
 - [Function: includes()](./docs/api/appkit/Function.includes.md): Passes when the value contains substring.
@@ -175,6 +178,7 @@ npx @databricks/appkit docs <query>
 - [Interface: AutoInheritToolsConfig](./docs/api/appkit/Interface.AutoInheritToolsConfig.md): Auto-inherit configuration. When enabled for a given agent origin, agents
 - [Interface: BasePluginConfig](./docs/api/appkit/Interface.BasePluginConfig.md): Base configuration interface for AppKit plugins
 - [Interface: CacheConfig](./docs/api/appkit/Interface.CacheConfig.md): Configuration for the CacheInterceptor. Controls TTL, size limits, storage backend, and probabilistic cleanup.
+- [Interface: CallerContext](./docs/api/appkit/Interface.CallerContext.md): Caller identity and workspace for one immutable execution scope.
 - [Interface: CustomJudgeSpec](./docs/api/appkit/Interface.CustomJudgeSpec.md): A custom LLM-judge definition: a prompt template and choice→score mapping.
 - [Interface: DatabaseCredential](./docs/api/appkit/Interface.DatabaseCredential.md): Database credentials with OAuth token for Postgres connection
 - [Interface: DatabaseRegistry](./docs/api/appkit/Interface.DatabaseRegistry.md): CANONICAL augmentation target. Empty by default; the generated database.d.ts
@@ -262,6 +266,7 @@ npx @databricks/appkit docs <query>
 - [Type Alias: AgentTools](./docs/api/appkit/TypeAlias.AgentTools.md): Per-agent tool record. String keys map to inline tools, toolkit entries,
 - [Type Alias: AgentToolsFn()](./docs/api/appkit/TypeAlias.AgentToolsFn.md): Function form of AgentDefinition.tools. Receives the typed
 - [Type Alias: BaseSystemPromptOption](./docs/api/appkit/TypeAlias.BaseSystemPromptOption.md)
+- [Type Alias: CallerPrincipal](./docs/api/appkit/TypeAlias.CallerPrincipal.md): The caller identity whose permissions authorize execution, not its resources.
 - [Type Alias: ConfigSchema](./docs/api/appkit/TypeAlias.ConfigSchema.md): Configuration schema definition for plugin config.
 - [Type Alias: DatabaseApiConfig<TSchema>](./docs/api/appkit/TypeAlias.DatabaseApiConfig.md): Full generated CRUD for every declared table by default. Set false to disable
 - [Type Alias: DatabaseApiWriteOperation](./docs/api/appkit/TypeAlias.DatabaseApiWriteOperation.md): Generated HTTP write operations.
@@ -269,6 +274,7 @@ npx @databricks/appkit docs <query>
 - [Type Alias: DatabaseExports](./docs/api/appkit/TypeAlias.DatabaseExports.md): Typed database API published by the plugin.
 - [Type Alias: EntityHooks<TTable>](./docs/api/appkit/TypeAlias.EntityHooks.md): Response shaping and mutation lifecycle declared for one table.
 - [Type Alias: EvalProgress](./docs/api/appkit/TypeAlias.EvalProgress.md)
+- [Type Alias: ExecutionContext](./docs/api/appkit/TypeAlias.ExecutionContext.md)
 - [Type Alias: ExecutionResult<T>](./docs/api/appkit/TypeAlias.ExecutionResult.md): Discriminated union for plugin execution results.
 - [Type Alias: FileAction](./docs/api/appkit/TypeAlias.FileAction.md): Every action the files plugin can perform.
 - [Type Alias: FilePolicy()](./docs/api/appkit/TypeAlias.FilePolicy.md): A policy function that decides whether user may perform action on

package/dist/appkit/package.js

@@ -1,6 +1,6 @@
 //#region package.json
 var name = "@databricks/appkit";
-var version = "0.82.0";
+var version = "0.83.0";
 
 //#endregion
 export { name, version };

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"}