@dbx-tools/appkit 0.9.119 → 0.9.121

package/lib/src/tool-operations.js

@@ -0,0 +1,43 @@
+/** Zod-owned operation contracts converted into native AppKit agent tools. */
+import { defineTool } from "@databricks/appkit/beta";
+/** Preserve operation inference while declaring an exported operation map. */
+export function defineOperations(operations) {
+    return operations;
+}
+/** Convert exported Zod operation contracts into a native AppKit tool registry. */
+export function toolRegistryFromOperations(operations) {
+    return Object.fromEntries(Object.entries(operations).flatMap(([name, operation]) => {
+        const metadata = operation.schema.meta();
+        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),
+                }),
+            ],
+        ];
+    }));
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidG9vbC1vcGVyYXRpb25zLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3Rvb2wtb3BlcmF0aW9ucy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSw4RUFBOEU7QUFFOUUsT0FBTyxFQUFFLFVBQVUsRUFBcUIsTUFBTSx5QkFBeUIsQ0FBQztBQThCeEUsOEVBQThFO0FBQzlFLE1BQU0sVUFBVSxnQkFBZ0IsQ0FFOUIsVUFFRDtJQUNDLE9BQU8sVUFBVSxDQUFDO0FBQ3BCLENBQUM7QUFFRCxtRkFBbUY7QUFDbkYsTUFBTSxVQUFVLDBCQUEwQixDQUN4QyxVQUF5RTtJQUV6RSxPQUFPLE1BQU0sQ0FBQyxXQUFXLENBQ3ZCLE1BQU0sQ0FBQyxPQUFPLENBQUMsVUFBVSxDQUFDLENBQUMsT0FBTyxDQUFDLENBQUMsQ0FBQyxJQUFJLEVBQUUsU0FBUyxDQUFDLEVBQUUsRUFBRTtRQUN2RCxNQUFNLFFBQVEsR0FBRyxTQUFTLENBQUMsTUFBTSxDQUFDLElBQUksRUFBMkMsQ0FBQztRQUNsRixNQUFNLElBQUksR0FBRyxRQUFRLEVBQUUsVUFBVSxJQUFJLEVBQUUsQ0FBQztRQUN4QyxJQUFJLElBQUksQ0FBQyxTQUFTLEtBQUssSUFBSTtZQUFFLE9BQU8sRUFBRSxDQUFDO1FBQ3ZDLE1BQU0sTUFBTSxHQUFHLElBQUksQ0FBQyxNQUFNLElBQUksT0FBTyxDQUFDO1FBQ3RDLE1BQU0sUUFBUSxHQUFHLElBQUksQ0FBQyxRQUFRLEtBQUssSUFBSSxJQUFJLE1BQU0sS0FBSyxhQUFhLENBQUM7UUFDcEUsTUFBTSxXQUFXLEdBQUcsU0FBUyxDQUFDLE1BQU0sQ0FBQyxXQUFXLEVBQUUsSUFBSSxFQUFFLENBQUM7UUFDekQsSUFBSSxDQUFDLFdBQVcsRUFBRSxDQUFDO1lBQ2pCLE1BQU0sSUFBSSxTQUFTLENBQUMsb0JBQW9CLElBQUksb0NBQW9DLENBQUMsQ0FBQztRQUNwRixDQUFDO1FBQ0QsT0FBTztZQUNMO2dCQUNFLElBQUk7Z0JBQ0osVUFBVSxDQUFDO29CQUNULFdBQVc7b0JBQ1gsTUFBTSxFQUFFLFNBQVMsQ0FBQyxNQUFNO29CQUN4QixXQUFXLEVBQUU7d0JBQ1gsTUFBTTt3QkFDTixHQUFHLENBQUMsUUFBUSxDQUFDLENBQUMsQ0FBQyxFQUFFLFdBQVcsRUFBRSxJQUFJLEVBQUUsQ0FBQyxDQUFDLENBQUMsRUFBRSxDQUFDO3dCQUMxQyxHQUFHLENBQUMsSUFBSSxDQUFDLG1CQUFtQixLQUFLLFNBQVM7NEJBQ3hDLENBQUMsQ0FBQyxFQUFFOzRCQUNKLENBQUMsQ0FBQyxFQUFFLG1CQUFtQixFQUFFLElBQUksQ0FBQyxtQkFBbUIsRUFBRSxDQUFDO3dCQUN0RCxHQUFHLENBQUMsSUFBSSxDQUFDLFVBQVUsS0FBSyxTQUFTLENBQUMsQ0FBQyxDQUFDLEVBQUUsQ0FBQyxDQUFDLENBQUMsRUFBRSxVQUFVLEVBQUUsSUFBSSxDQUFDLFVBQVUsRUFBRSxDQUFDO3FCQUMxRTtvQkFDRCxHQUFHLENBQUMsSUFBSSxDQUFDLGVBQWUsS0FBSyxTQUFTO3dCQUNwQyxDQUFDLENBQUMsRUFBRTt3QkFDSixDQUFDLENBQUMsRUFBRSxlQUFlLEVBQUUsSUFBSSxDQUFDLGVBQWUsRUFBRSxDQUFDO29CQUM5QyxPQUFPLEVBQUUsQ0FBQyxLQUFLLEVBQUUsTUFBTSxFQUFFLEVBQUUsQ0FBQyxTQUFTLENBQUMsT0FBTyxDQUFDLFNBQVMsQ0FBQyxNQUFNLENBQUMsS0FBSyxDQUFDLEtBQUssQ0FBQyxFQUFFLE1BQU0sQ0FBQztpQkFDckYsQ0FBQzthQUNIO1NBQ0YsQ0FBQztJQUNKLENBQUMsQ0FBQyxDQUNILENBQUM7QUFDSixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLyoqIFpvZC1vd25lZCBvcGVyYXRpb24gY29udHJhY3RzIGNvbnZlcnRlZCBpbnRvIG5hdGl2ZSBBcHBLaXQgYWdlbnQgdG9vbHMuICovXG5cbmltcG9ydCB7IGRlZmluZVRvb2wsIHR5cGUgVG9vbFJlZ2lzdHJ5IH0gZnJvbSBcIkBkYXRhYnJpY2tzL2FwcGtpdC9iZXRhXCI7XG5pbXBvcnQgeyB6IH0gZnJvbSBcInpvZFwiO1xuXG4vKiogTWV0YWRhdGEgc3RvcmVkIHVuZGVyIGBhcHBraXRUb29sYCBieSBhIFpvZCBzY2hlbWEncyBgLm1ldGEoKWAgdmFsdWUuICovXG5leHBvcnQgaW50ZXJmYWNlIEFwcEtpdFRvb2xNZXRhIHtcbiAgLyoqIE9wdCBpbiB0byBleHBvc2luZyB0aGlzIG9wZXJhdGlvbiBhcyBhbiBhZ2VudCB0b29sLiAqL1xuICByZWFkb25seSBhZ2VudFRvb2w/OiBib29sZWFuO1xuICAvKiogVG9vbCBzaWRlLWVmZmVjdCBjbGFzc2lmaWNhdGlvbi4gRGVmYXVsdHMgdG8gYHdyaXRlYC4gKi9cbiAgcmVhZG9ubHkgZWZmZWN0PzogXCJyZWFkXCIgfCBcIndyaXRlXCIgfCBcImRlc3RydWN0aXZlXCI7XG4gIC8qKiBSZXF1aXJlIGh1bWFuIGFwcHJvdmFsIGJlZm9yZSBleGVjdXRpb24uICovXG4gIHJlYWRvbmx5IGFwcHJvdmFsPzogYm9vbGVhbjtcbiAgLyoqIFdoZXRoZXIgZXhlY3V0aW9uIHJlcXVpcmVzIGFuIGF1dGhlbnRpY2F0ZWQgdXNlciBjb250ZXh0LiAqL1xuICByZWFkb25seSByZXF1aXJlc1VzZXJDb250ZXh0PzogYm9vbGVhbjtcbiAgLyoqIFdoZXRoZXIgcmVwZWF0ZWQgY2FsbHMgd2l0aCB0aGUgc2FtZSBpbnB1dCBhcmUgc2FmZS4gKi9cbiAgcmVhZG9ubHkgaWRlbXBvdGVudD86IGJvb2xlYW47XG4gIC8qKiBXaGV0aGVyIEFwcEtpdCBtYXkgaW5oZXJpdCB0aGUgdG9vbCBhdXRvbWF0aWNhbGx5LiAqL1xuICByZWFkb25seSBhdXRvSW5oZXJpdGFibGU/OiBib29sZWFuO1xufVxuXG4vKiogU2hhcGUgcGxhY2VkIGluIGEgWm9kIHNjaGVtYSdzIGAubWV0YSgpYCB2YWx1ZS4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgQXBwS2l0T3BlcmF0aW9uU2NoZW1hTWV0YSB7XG4gIHJlYWRvbmx5IGFwcGtpdFRvb2w/OiBBcHBLaXRUb29sTWV0YTtcbn1cblxuLyoqIE9uZSB0eXBlZCBvcGVyYXRpb24gYmFja2VkIGJ5IGEgc2luZ2xlIFpvZCBpbnB1dCBjb250cmFjdC4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgQXBwS2l0T3BlcmF0aW9uPFRTY2hlbWEgZXh0ZW5kcyB6LlpvZFR5cGUgPSB6LlpvZFR5cGUsIFRSZXN1bHQgPSB1bmtub3duPiB7XG4gIHJlYWRvbmx5IHNjaGVtYTogVFNjaGVtYTtcbiAgcmVhZG9ubHkgZXhlY3V0ZTogKGlucHV0OiB6Lm91dHB1dDxUU2NoZW1hPiwgc2lnbmFsPzogQWJvcnRTaWduYWwpID0+IFRSZXN1bHQgfCBQcm9taXNlPFRSZXN1bHQ+O1xufVxuXG4vKiogUHJlc2VydmUgb3BlcmF0aW9uIGluZmVyZW5jZSB3aGlsZSBkZWNsYXJpbmcgYW4gZXhwb3J0ZWQgb3BlcmF0aW9uIG1hcC4gKi9cbmV4cG9ydCBmdW5jdGlvbiBkZWZpbmVPcGVyYXRpb25zPFxuICBjb25zdCBUU2NoZW1hcyBleHRlbmRzIFJlYWRvbmx5PFJlY29yZDxzdHJpbmcsIHouWm9kVHlwZT4+LFxuPihvcGVyYXRpb25zOiB7XG4gIHJlYWRvbmx5IFtUTmFtZSBpbiBrZXlvZiBUU2NoZW1hc106IEFwcEtpdE9wZXJhdGlvbjxUU2NoZW1hc1tUTmFtZV0sIHVua25vd24+O1xufSk6IHR5cGVvZiBvcGVyYXRpb25zIHtcbiAgcmV0dXJuIG9wZXJhdGlvbnM7XG59XG5cbi8qKiBDb252ZXJ0IGV4cG9ydGVkIFpvZCBvcGVyYXRpb24gY29udHJhY3RzIGludG8gYSBuYXRpdmUgQXBwS2l0IHRvb2wgcmVnaXN0cnkuICovXG5leHBvcnQgZnVuY3Rpb24gdG9vbFJlZ2lzdHJ5RnJvbU9wZXJhdGlvbnMoXG4gIG9wZXJhdGlvbnM6IFJlYWRvbmx5PFJlY29yZDxzdHJpbmcsIEFwcEtpdE9wZXJhdGlvbjx6LlpvZFR5cGUsIHVua25vd24+Pj4sXG4pOiBUb29sUmVnaXN0cnkge1xuICByZXR1cm4gT2JqZWN0LmZyb21FbnRyaWVzKFxuICAgIE9iamVjdC5lbnRyaWVzKG9wZXJhdGlvbnMpLmZsYXRNYXAoKFtuYW1lLCBvcGVyYXRpb25dKSA9PiB7XG4gICAgICBjb25zdCBtZXRhZGF0YSA9IG9wZXJhdGlvbi5zY2hlbWEubWV0YSgpIGFzIEFwcEtpdE9wZXJhdGlvblNjaGVtYU1ldGEgfCB1bmRlZmluZWQ7XG4gICAgICBjb25zdCB0b29sID0gbWV0YWRhdGE/LmFwcGtpdFRvb2wgPz8ge307XG4gICAgICBpZiAodG9vbC5hZ2VudFRvb2wgIT09IHRydWUpIHJldHVybiBbXTtcbiAgICAgIGNvbnN0IGVmZmVjdCA9IHRvb2wuZWZmZWN0ID8/IFwid3JpdGVcIjtcbiAgICAgIGNvbnN0IGFwcHJvdmFsID0gdG9vbC5hcHByb3ZhbCA9PT0gdHJ1ZSB8fCBlZmZlY3QgPT09IFwiZGVzdHJ1Y3RpdmVcIjtcbiAgICAgIGNvbnN0IGRlc2NyaXB0aW9uID0gb3BlcmF0aW9uLnNjaGVtYS5kZXNjcmlwdGlvbj8udHJpbSgpO1xuICAgICAgaWYgKCFkZXNjcmlwdGlvbikge1xuICAgICAgICB0aHJvdyBuZXcgVHlwZUVycm9yKGBBcHBLaXQgb3BlcmF0aW9uICR7bmFtZX0gcmVxdWlyZXMgYSBab2Qgc2NoZW1hIGRlc2NyaXB0aW9uYCk7XG4gICAgICB9XG4gICAgICByZXR1cm4gW1xuICAgICAgICBbXG4gICAgICAgICAgbmFtZSxcbiAgICAgICAgICBkZWZpbmVUb29sKHtcbiAgICAgICAgICAgIGRlc2NyaXB0aW9uLFxuICAgICAgICAgICAgc2NoZW1hOiBvcGVyYXRpb24uc2NoZW1hLFxuICAgICAgICAgICAgYW5ub3RhdGlvbnM6IHtcbiAgICAgICAgICAgICAgZWZmZWN0LFxuICAgICAgICAgICAgICAuLi4oYXBwcm92YWwgPyB7IGRlc3RydWN0aXZlOiB0cnVlIH0gOiB7fSksXG4gICAgICAgICAgICAgIC4uLih0b29sLnJlcXVpcmVzVXNlckNvbnRleHQgPT09IHVuZGVmaW5lZFxuICAgICAgICAgICAgICAgID8ge31cbiAgICAgICAgICAgICAgICA6IHsgcmVxdWlyZXNVc2VyQ29udGV4dDogdG9vbC5yZXF1aXJlc1VzZXJDb250ZXh0IH0pLFxuICAgICAgICAgICAgICAuLi4odG9vbC5pZGVtcG90ZW50ID09PSB1bmRlZmluZWQgPyB7fSA6IHsgaWRlbXBvdGVudDogdG9vbC5pZGVtcG90ZW50IH0pLFxuICAgICAgICAgICAgfSxcbiAgICAgICAgICAgIC4uLih0b29sLmF1dG9Jbmhlcml0YWJsZSA9PT0gdW5kZWZpbmVkXG4gICAgICAgICAgICAgID8ge31cbiAgICAgICAgICAgICAgOiB7IGF1dG9Jbmhlcml0YWJsZTogdG9vbC5hdXRvSW5oZXJpdGFibGUgfSksXG4gICAgICAgICAgICBleGVjdXRlOiAoaW5wdXQsIHNpZ25hbCkgPT4gb3BlcmF0aW9uLmV4ZWN1dGUob3BlcmF0aW9uLnNjaGVtYS5wYXJzZShpbnB1dCksIHNpZ25hbCksXG4gICAgICAgICAgfSksXG4gICAgICAgIF0sXG4gICAgICBdO1xuICAgIH0pLFxuICApO1xufVxuIl19

package/lib/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/_auto-configure.ts","../src/appkit.ts","../src/brand-context.ts","../src/bundle.ts","../src/cache-storage.ts","../src/child-process.ts","../src/databricks.ts","../src/files-cache.ts","../src/identity.ts","../src/interceptor.ts","../src/lakebase-resolver.ts","../src/migration.ts","../src/pgaddress.ts","../src/plugin-execution.ts","../src/plugin-registry.ts","../src/provision.ts","../src/request-tags.ts","../src/tool-provider.ts","../src/toolkit-entries.ts","../index.ts"],"version":"5.9.3"}
+{"root":["../src/_auto-configure.ts","../src/appkit.ts","../src/brand-context.ts","../src/bundle.ts","../src/cache-storage.ts","../src/child-process.ts","../src/databricks.ts","../src/files-cache.ts","../src/identity.ts","../src/interceptor.ts","../src/lakebase-resolver.ts","../src/migration.ts","../src/pgaddress.ts","../src/plugin-execution.ts","../src/plugin-registry.ts","../src/provision.ts","../src/request-tags.ts","../src/tool-operations.ts","../src/tool-provider.ts","../src/toolkit-entries.ts","../index.ts"],"version":"5.9.3"}

package/package.json

@@ -20,7 +20,7 @@
   },
   "devDependencies": {
     "@databricks/appkit": "0.81.0",
-    "@dbx-tools/projen": "^0.9.119",
+    "@dbx-tools/projen": "^0.9.121",
     "@types/node": "^24.6.0",
     "typescript": "^5.9.3",
     "vitest": "3.2.4"
@@ -30,13 +30,13 @@
   },
   "dependencies": {
     "@databricks/sdk-experimental": "^0.17.0",
-    "@dbx-tools/auth": "^0.9.119",
-    "@dbx-tools/cache": "^0.9.119",
-    "@dbx-tools/core": "^0.9.119",
-    "@dbx-tools/lakebase": "^0.9.119",
-    "@dbx-tools/postgres": "^0.9.119",
-    "@dbx-tools/shared-core": "^0.9.119",
-    "@dbx-tools/shared-fs": "^0.9.119",
+    "@dbx-tools/auth": "^0.9.121",
+    "@dbx-tools/cache": "^0.9.121",
+    "@dbx-tools/core": "^0.9.121",
+    "@dbx-tools/lakebase": "^0.9.121",
+    "@dbx-tools/postgres": "^0.9.121",
+    "@dbx-tools/shared-core": "^0.9.121",
+    "@dbx-tools/shared-fs": "^0.9.121",
     "zod": "4.3.6"
   },
   "main": "./lib/index.js",
@@ -114,6 +114,10 @@
         "types": "./lib/src/request-tags.d.ts",
         "default": "./lib/src/request-tags.js"
       },
+      "./tool-operations": {
+        "types": "./lib/src/tool-operations.d.ts",
+        "default": "./lib/src/tool-operations.js"
+      },
       "./tool-provider": {
         "types": "./lib/src/tool-provider.d.ts",
         "default": "./lib/src/tool-provider.js"
@@ -129,7 +133,7 @@
       "./package.json": "./package.json"
     }
   },
-  "version": "0.9.119",
+  "version": "0.9.121",
   "types": "./lib/index.d.ts",
   "dbxToolsConfig": {
     "tags": [
@@ -206,6 +210,10 @@
       "types": "./lib/src/request-tags.d.ts",
       "default": "./lib/src/request-tags.js"
     },
+    "./tool-operations": {
+      "types": "./lib/src/tool-operations.d.ts",
+      "default": "./lib/src/tool-operations.js"
+    },
     "./tool-provider": {
       "types": "./lib/src/tool-provider.d.ts",
       "default": "./lib/src/tool-provider.js"

package/src/appkit.ts

@@ -48,6 +48,7 @@ import {
   lifecycleBridge,
   type ResolvedAppEnv,
 } from "./interceptor.ts";
+import { installAsUserDevelopmentPatch } from "./identity.ts";
 import { applyLakebaseEnv, type LakebaseConnection } from "./lakebase-resolver.ts";
 import { provisionCacheSchema } from "./provision.ts";
 
@@ -298,6 +299,7 @@ function interceptorList(interceptor: CreateAppConfig["interceptor"]): Intercept
 export async function createApp<T extends AppKitPlugins>(
   config?: CreateAppConfig<T>,
 ): Promise<PluginMap<T>> {
+  installAsUserDevelopmentPatch();
   const plugins = pluginNames(config);
   const interceptors = interceptorList(config?.interceptor);
   logger.debug("createApp: start", {

package/src/cache-storage.ts

@@ -217,7 +217,7 @@ export function loadPersistentStorage(): PersistentStorageConstructor | undefine
     return loaded;
   } catch (err) {
     logger.debug("soft persistent cache skipped (PersistentStorage unavailable)", {
-      error: errorUtils.errorMessage(err),
+      error: errorUtils.toError(err),
     });
     persistentStorageCtor = undefined;
     return undefined;
@@ -330,7 +330,7 @@ async function createPersistentStorage(
     return storage;
   } catch (err) {
     logger.debug("soft persistent cache unavailable", {
-      error: errorUtils.errorMessage(err),
+      error: errorUtils.toError(err),
     });
     if (pool) {
       await pool.end().catch(() => {});

package/src/files-cache.ts

@@ -247,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);

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),
+          }),
+        ],
+      ];
+    }),
+  );
+}