@dbx-tools/appkit 0.9.118 → 0.9.120

package/src/files-cache.ts

@@ -1,28 +1,23 @@
 /**
- * AppKit-global filesystem cache with user-isolated process-local LRU values.
+ * AppKit-global filesystem cache with user-isolated process-local values.
  *
  * @module
  */
 
 import { Plugin, toPlugin, type BasePluginConfig, type PluginManifest } from "@databricks/appkit";
+import { cacheKeys, closeCache, createCache, getOrSet } from "@dbx-tools/cache/cache";
 import { errorUtils, log, object } from "@dbx-tools/shared-core";
 import { posixPath, type CacheValue, type FileSystemCache } from "@dbx-tools/shared-fs";
-import { LRUCache } from "lru-cache";
 
 const DEFAULT_TTL_MS = 60_000;
 const DEFAULT_INVALIDATION_BATCH_MS = 25;
 const DEFAULT_MAX_ENTRIES = 1_000;
-const DEFAULT_MAX_BYTES = 64 * 1024 * 1024;
 const DEFAULT_MAX_SCOPES = 256;
 const logger = log.logger("files-cache");
 
-interface RetainedEntry {
-  value: CacheValue;
-}
-
 interface ScopeState {
   cache: FileSystemCache;
-  entries: LRUCache<string, RetainedEntry>;
+  entries: ReturnType<typeof createCache>;
   group: GroupState;
   scope: ResolvedFilesCacheScope;
   sources: Map<string, Promise<object>>;
@@ -36,7 +31,6 @@ interface GroupState {
 
 interface ResolvedFilesCacheConfig {
   invalidationBatchMs: number;
-  maxBytes: number;
   maxEntries: number;
   maxScopes: number;
   ttlMs: number;
@@ -57,8 +51,6 @@ export interface FilesCachePluginConfig extends BasePluginConfig {
   invalidationBatchMs?: number;
   /** Maximum entries retained in each user L1. Defaults to 1,000. */
   maxEntries?: number;
-  /** Maximum retained bytes in each user L1. Defaults to 64 MiB. */
-  maxBytes?: number;
   /** Maximum active user scopes retained by the process. Defaults to 256. */
   maxScopes?: number;
 }
@@ -101,7 +93,7 @@ export interface FilesCacheExports {
 export class FilesCacheManager {
   private readonly config: ResolvedFilesCacheConfig;
   private readonly groups = new Map<string, GroupState>();
-  private readonly scopes: LRUCache<string, ScopeState>;
+  private readonly scopes: ReturnType<typeof createCache>;
 
   constructor(config: FilesCachePluginConfig = {}) {
     this.config = {
@@ -112,15 +104,9 @@ export class FilesCacheManager {
         "invalidationBatchMs",
       ),
       maxEntries: positiveInteger(config.maxEntries, DEFAULT_MAX_ENTRIES, "maxEntries"),
-      maxBytes: positiveInteger(config.maxBytes, DEFAULT_MAX_BYTES, "maxBytes"),
       maxScopes: positiveInteger(config.maxScopes, DEFAULT_MAX_SCOPES, "maxScopes"),
     };
-    this.scopes = new LRUCache({
-      max: this.config.maxScopes,
-      dispose: (state) => {
-        state.group.scopes.delete(state);
-      },
-    });
+    this.scopes = createCache({ maxEntries: this.config.maxScopes, useClone: false });
   }
 
   /** Return one user-isolated cache within a host/workspace invalidation group. */
@@ -158,12 +144,23 @@ export class FilesCacheManager {
       userKey: scope.userKey,
       workspaceId: scope.workspaceId,
     });
-    let state = this.scopes.get(scopeKey);
+    let state = await this.scopes.get<ScopeState>(scopeKey);
     if (!state) {
+      if ([...cacheKeys(this.scopes)].length >= this.config.maxScopes) {
+        const oldestKey = cacheKeys(this.scopes).next().value;
+        if (oldestKey) {
+          const oldest = await this.scopes.get<ScopeState>(oldestKey);
+          if (oldest) {
+            oldest.group.scopes.delete(oldest);
+            await closeCache(oldest.entries);
+          }
+          await this.scopes.delete(oldestKey);
+        }
+      }
       const group = this.group(scope);
       state = this.createScope(scope, group);
       group.scopes.add(state);
-      this.scopes.set(scopeKey, state);
+      await this.scopes.set(scopeKey, state);
     }
     return state;
   }
@@ -180,7 +177,11 @@ export class FilesCacheManager {
       group.timer = undefined;
     }
     await this.flush();
-    this.scopes.clear();
+    for (const key of cacheKeys(this.scopes)) {
+      const state = await this.scopes.get<ScopeState>(key);
+      if (state) await closeCache(state.entries);
+    }
+    await closeCache(this.scopes);
     this.groups.clear();
   }
 
@@ -203,11 +204,7 @@ export class FilesCacheManager {
     const state = {} as ScopeState;
     state.scope = scope;
     state.group = group;
-    state.entries = new LRUCache({
-      max: this.config.maxEntries,
-      maxSize: this.config.maxBytes,
-      sizeCalculation: (entry, cacheKey) => retainedSize(cacheKey, entry),
-    });
+    state.entries = createCache({ maxEntries: this.config.maxEntries, useClone: false });
     state.sources = new Map();
     state.cache = {
       read: <T extends CacheValue>(cacheKey: string, load: () => T | Promise<T>) =>
@@ -224,16 +221,21 @@ export class FilesCacheManager {
     load: () => T | Promise<T>,
   ): Promise<T> {
     if (!state.group.pending.has(key)) {
-      const retained = state.entries.get(key);
-      if (retained) return retained.value as T;
+      const retained = await state.entries.get<T>(key);
+      if (retained !== undefined) return retained;
     }
-    const value = await load();
-    state.entries.set(key, { value }, { ttl: state.scope.ttlMs });
-    return value;
+    if (state.group.pending.has(key)) {
+      const value = await load();
+      await state.entries.set(key, value, { ttl: state.scope.ttlMs });
+      return value;
+    }
+    return (await getOrSet(state.entries, key, () => Promise.resolve(load()), {
+      ttl: state.scope.ttlMs,
+    })) as T;
   }
 
   private *keys(state: ScopeState): Iterable<string> {
-    for (const key of state.entries.keys()) {
+    for (const key of cacheKeys(state.entries)) {
       if (!state.group.pending.has(key)) yield key;
     }
   }
@@ -245,7 +247,7 @@ export class FilesCacheManager {
       state.group.timer = undefined;
       void this.flushInvalidations(state.group).catch((error) => {
         logger.warn("filesystem cache invalidation batch failed", {
-          error: errorUtils.errorMessage(error),
+          error: errorUtils.toError(error),
         });
       });
     }, this.config.invalidationBatchMs);
@@ -259,12 +261,12 @@ export class FilesCacheManager {
     const keys = [...group.pending];
     group.pending.clear();
     for (const state of group.scopes) {
-      for (const key of keys) state.entries.delete(key);
+      await Promise.all(keys.map((key) => state.entries.delete(key)));
     }
   }
 }
 
-/** AppKit plugin that owns process-local filesystem LRU caches. */
+/** AppKit plugin that owns process-local filesystem caches. */
 export class FilesCachePlugin extends Plugin<FilesCachePluginConfig> {
   static manifest = {
     name: "files-cache",
@@ -324,11 +326,3 @@ function positiveDuration(value: number | undefined, fallback: number, name: str
 function positiveInteger(value: number | undefined, fallback: number, name: string): number {
   return Math.floor(positiveDuration(value, fallback, name));
 }
-
-function retainedSize(key: string, entry: RetainedEntry): number {
-  try {
-    return Buffer.byteLength(key) + Buffer.byteLength(JSON.stringify(entry.value));
-  } catch {
-    return Number.MAX_SAFE_INTEGER;
-  }
-}

package/src/identity.ts

@@ -52,9 +52,9 @@
  * @module
  */
 
-import { ConfigurationError } from "@databricks/appkit";
+import { ConfigurationError, Plugin } from "@databricks/appkit";
 import { configUtils } from "@dbx-tools/core";
-import { stringUtils, token } from "@dbx-tools/shared-core";
+import { log, stringUtils, token } from "@dbx-tools/shared-core";
 
 /**
  * Header the Databricks Apps front door forwards the caller's OBO token on.
@@ -158,3 +158,68 @@ export function useServicePrincipal(mode: IdentityMode, req?: HeaderBearing): bo
   if (mode === "user") return false;
   return requestAccessToken(req) === undefined;
 }
+
+const logger = log.logger("appkit");
+const skippedAsUser = new Set<string>();
+const AS_USER_SKIP_WARN = "Skipping user impersonation";
+const AS_USER_PATCHED = Symbol.for("dbx-tools.appkit.asUserDevLog");
+
+/**
+ * In development, keep AppKit `asUser` behavior. The first missing-token skip
+ * for a forwarded email or user id uses AppKit's own warn; later skips for
+ * that user, and every skip with no forwarded identity, are silent. Request
+ * objects are not a stable key: each plugin call typically has its own `req`.
+ *
+ * No-op outside development, when `Plugin.asUser` is missing or not a
+ * function, or if the prototype cannot be rewritten. Failures never throw:
+ * AppKit keeps its original `asUser`. Extra arguments are forwarded so a
+ * later signature change still reaches the original method.
+ */
+export function installAsUserDevelopmentPatch(): void {
+  if (process.env.NODE_ENV !== "development") return;
+  try {
+    const proto = Plugin.prototype as unknown as Record<PropertyKey, unknown>;
+    if (proto[AS_USER_PATCHED] === true) return;
+    const original = proto.asUser;
+    if (typeof original !== "function") return;
+    proto[AS_USER_PATCHED] = true;
+    proto.asUser = function patchedAsUser(this: unknown, req: unknown, ...rest: unknown[]) {
+      const headers = asHeaderBearing(req);
+      const args = [req, ...rest];
+      if (!headers || requestAccessToken(headers) !== undefined) {
+        return Function.prototype.apply.call(original, this, args);
+      }
+      return withAsUserSkipWarnSuppressed(headers, () =>
+        Function.prototype.apply.call(original, this, args),
+      );
+    };
+  } catch (error) {
+    logger.debug("asUser development patch skipped", { error: String(error) });
+  }
+}
+
+function asHeaderBearing(req: unknown): HeaderBearing | undefined {
+  if (req === null || typeof req !== "object") return undefined;
+  if (typeof (req as HeaderBearing).header !== "function") return undefined;
+  return req as HeaderBearing;
+}
+
+function withAsUserSkipWarnSuppressed<T>(req: HeaderBearing, fn: () => T): T {
+  const user = requestUserEmail(req) ?? requestUserId(req);
+  if (user && !skippedAsUser.has(user)) {
+    skippedAsUser.add(user);
+    return fn();
+  }
+  const warn = console.warn;
+  console.warn = (...args: unknown[]) => {
+    if (!log.isLevelEnabled("debug") && args.some((value) => typeof value === "string" && value.includes(AS_USER_SKIP_WARN))) {
+      return;
+    }
+    warn.apply(console, args as Parameters<typeof console.warn>);
+  };
+  try {
+    return fn();
+  } finally {
+    console.warn = warn;
+  }
+}

package/src/interceptor.ts

@@ -20,7 +20,7 @@
  */
 
 import { Plugin, toPlugin, type BasePluginConfig, type PluginManifest } from "@databricks/appkit";
-import { log } from "@dbx-tools/shared-core";
+import { errorUtils, log } from "@dbx-tools/shared-core";
 import type { LakebaseConnection } from "./lakebase-resolver.ts";
 
 const logger = log.logger("interceptor");
@@ -120,7 +120,10 @@ export function createInterceptorContext(env: ResolvedAppEnv): InterceptorRuntim
       } catch (error) {
         // Match AppKit: a failing lifecycle handler is logged, never fatal, and
         // never blocks its siblings.
-        logger.warn("lifecycle handler failed", { event, error });
+        logger.warn("lifecycle handler failed", {
+          event,
+          error: errorUtils.toError(error),
+        });
       }
     }
   };

package/src/lakebase-resolver.ts

@@ -40,11 +40,13 @@ import {
   ExecutionError,
   getUsernameWithApiLookup,
   getWorkspaceClient,
+  type LakebasePool,
   ValidationError,
 } from "@databricks/appkit";
 import { configUtils, projectUtils } from "@dbx-tools/core";
 import {
   asyncUtils,
+  errorUtils,
   log,
   object,
   options as sharedOptions,
@@ -113,6 +115,23 @@ export interface LakebaseConnection extends LakebaseConnectionInputs {
   sslMode: SslMode;
 }
 
+/**
+ * Capture AppKit's existing service-principal Lakebase pool.
+ *
+ * Call this during `setup:complete`, outside any `asUser()` scope. AppKit's
+ * exported pool routes dynamically by request context, but its runtime
+ * `activePool()` method returns the already-created underlying pool selected in
+ * the current context. Capturing it once at startup pins application-owned
+ * storage to the service principal without creating another pool or connection.
+ *
+ * A future AppKit version may export a fixed pool directly; in that case the
+ * pool has no `activePool()` method and is returned unchanged.
+ */
+export function captureServicePrincipalPool(pool: LakebasePool): LakebasePool {
+  const routingPool = pool as LakebasePool & { activePool?: () => LakebasePool };
+  return routingPool.activePool?.call(pool) ?? pool;
+}
+
 /**
  * Every field of the Lakebase REST payloads is modelled as optional and
  * validated at the boundary rather than asserted with a cast: the pickers below
@@ -778,7 +797,10 @@ function isAlreadyExistsError(error: unknown): boolean {
  * echo request context, so it goes to the log instead.
  */
 function operationFailed(opName: string, opError: unknown): ExecutionError {
-  logger.error("autopg: operation failed", { operation: opName, error: opError });
+  logger.error("autopg: operation failed", {
+    operation: opName,
+    error: errorUtils.toError(opError),
+  });
   const code = object.isRecord(opError) ? (opError.code ?? opError.reason) : undefined;
   return new ExecutionError(`Lakebase operation failed: ${opName}`, {
     context: {

package/src/migration.ts

@@ -31,10 +31,8 @@ export function handleOwnershipMigrationError(
   const key = `${options.scope}\0${message}`;
   if (loggedOwnershipErrors.has(key)) return true;
   loggedOwnershipErrors.add(key);
-  if (log.isLevelEnabled("debug")) {
-    options.logger.error(options.event, cause);
-  } else {
-    options.logger.warn(options.event, { error: message, ...options.context });
-  }
+  const error = errorUtils.toError(cause);
+  if (log.isLevelEnabled("debug")) options.logger.error(options.event, { error });
+  else options.logger.warn(options.event, { error, ...options.context });
   return true;
 }

package/src/plugin-execution.ts

@@ -1,7 +1,7 @@
 /** AppKit-specific adapters over the shared intercepted-execution contract. */
 
 import { ExecutionError } from "@databricks/appkit";
-import { execution, type Logger } from "@dbx-tools/shared-core";
+import { errorUtils, execution, type Logger } from "@dbx-tools/shared-core";
 
 /** Inputs for one plugin operation routed through AppKit interceptors. */
 export interface RunPluginExecutionOptions<T, Settings> {
@@ -32,7 +32,7 @@ export function runPluginExecution<T, Settings>(
       options.logger.warn("execution-failed", {
         operation: failure.operation,
         status: failure.status,
-        error: failure.message,
+        error: errorUtils.toError(failure.message),
       });
       return new ExecutionError(`${options.plugin}: ${failure.operation} failed`, {
         context: { operation: failure.operation, status: failure.status },

package/src/provision.ts

@@ -128,7 +128,7 @@ export async function provisionCacheSchema(
   } catch (err) {
     logger.warn("autopg: cache provisioning failed (continuing)", {
       schema: CACHE_SCHEMA,
-      error: errorUtils.errorMessage(err),
+      error: errorUtils.toError(err),
     });
   } finally {
     await pool.end().catch(() => {});

package/src/tool-operations.ts

@@ -0,0 +1,80 @@
+/** Zod-owned operation contracts converted into native AppKit agent tools. */
+
+import { defineTool, type ToolRegistry } from "@databricks/appkit/beta";
+import { z } from "zod";
+
+/** Metadata stored under `appkitTool` by a Zod schema's `.meta()` value. */
+export interface AppKitToolMeta {
+  /** Opt in to exposing this operation as an agent tool. */
+  readonly agentTool?: boolean;
+  /** Tool side-effect classification. Defaults to `write`. */
+  readonly effect?: "read" | "write" | "destructive";
+  /** Require human approval before execution. */
+  readonly approval?: boolean;
+  /** Whether execution requires an authenticated user context. */
+  readonly requiresUserContext?: boolean;
+  /** Whether repeated calls with the same input are safe. */
+  readonly idempotent?: boolean;
+  /** Whether AppKit may inherit the tool automatically. */
+  readonly autoInheritable?: boolean;
+}
+
+/** Shape placed in a Zod schema's `.meta()` value. */
+export interface AppKitOperationSchemaMeta {
+  readonly appkitTool?: AppKitToolMeta;
+}
+
+/** One typed operation backed by a single Zod input contract. */
+export interface AppKitOperation<TSchema extends z.ZodType = z.ZodType, TResult = unknown> {
+  readonly schema: TSchema;
+  readonly execute: (input: z.output<TSchema>, signal?: AbortSignal) => TResult | Promise<TResult>;
+}
+
+/** Preserve operation inference while declaring an exported operation map. */
+export function defineOperations<
+  const TSchemas extends Readonly<Record<string, z.ZodType>>,
+>(operations: {
+  readonly [TName in keyof TSchemas]: AppKitOperation<TSchemas[TName], unknown>;
+}): typeof operations {
+  return operations;
+}
+
+/** Convert exported Zod operation contracts into a native AppKit tool registry. */
+export function toolRegistryFromOperations(
+  operations: Readonly<Record<string, AppKitOperation<z.ZodType, unknown>>>,
+): ToolRegistry {
+  return Object.fromEntries(
+    Object.entries(operations).flatMap(([name, operation]) => {
+      const metadata = operation.schema.meta() as AppKitOperationSchemaMeta | undefined;
+      const tool = metadata?.appkitTool ?? {};
+      if (tool.agentTool !== true) return [];
+      const effect = tool.effect ?? "write";
+      const approval = tool.approval === true || effect === "destructive";
+      const description = operation.schema.description?.trim();
+      if (!description) {
+        throw new TypeError(`AppKit operation ${name} requires a Zod schema description`);
+      }
+      return [
+        [
+          name,
+          defineTool({
+            description,
+            schema: operation.schema,
+            annotations: {
+              effect,
+              ...(approval ? { destructive: true } : {}),
+              ...(tool.requiresUserContext === undefined
+                ? {}
+                : { requiresUserContext: tool.requiresUserContext }),
+              ...(tool.idempotent === undefined ? {} : { idempotent: tool.idempotent }),
+            },
+            ...(tool.autoInheritable === undefined
+              ? {}
+              : { autoInheritable: tool.autoInheritable }),
+            execute: (input, signal) => operation.execute(operation.schema.parse(input), signal),
+          }),
+        ],
+      ];
+    }),
+  );
+}