@databricks/appkit 0.83.0 → 0.84.0

package/dist/core/appkit.js.map

@@ -1 +1 @@
-{"version":3,"file":"appkit.js","names":["#context","#pluginInstances","#setupPromises","#lifecycle","productVersion"],"sources":["../../src/core/appkit.ts"],"sourcesContent":["import type {\n  BasePlugin,\n  CacheConfig,\n  InputPluginMap,\n  OptionalConfigPluginDef,\n  PluginConstructor,\n  PluginData,\n  PluginMap,\n} from \"shared\";\n\nimport { version as productVersion } from \"../../package.json\";\nimport { CacheManager } from \"../cache\";\nimport { ServiceContext } from \"../context\";\nimport {\n  isInternalTelemetryEnabled,\n  TelemetryReporter,\n} from \"../internal-telemetry\";\nimport { createLogger } from \"../logging/logger\";\nimport { isPlainObject } from \"../plugin/plugin\";\nimport { uiVariants } from \"../plugins/ui-variants\";\nimport { ResourceRegistry, ResourceType } from \"../registry\";\nimport { getConfiguredWarehouseId } from \"../resources/warehouse\";\nimport type { TelemetryConfig } from \"../telemetry\";\nimport { TelemetryManager } from \"../telemetry\";\nimport type { WorkspaceClient } from \"../workspace-client\";\nimport { LifecycleManager } from \"./lifecycle-manager\";\nimport { isToolProvider, PluginContext } from \"./plugin-context\";\n\nconst logger = createLogger(\"appkit\");\n\n/**\n * Internal teardown entry for the test harness (see `createTestApp`).\n * Symbol-keyed so it cannot collide with — or be shadowed by — a plugin\n * manifest name, and so it stays off the public `PluginMap` surface.\n * @internal\n */\nexport const disposeApp = Symbol(\"appkit.internal.dispose\");\n\nexport class AppKit<TPlugins extends InputPluginMap> {\n  #pluginInstances: Record<string, BasePlugin> = {};\n  #setupPromises: Promise<void>[] = [];\n  #context: PluginContext;\n  /** Owns the shutdown sequence; assigned once every plugin has started. */\n  #lifecycle: LifecycleManager | undefined;\n\n  private constructor(config: { plugins: TPlugins }) {\n    const { plugins, ...globalConfig } = config;\n\n    this.#context = new PluginContext();\n\n    const pluginEntries = Object.entries(plugins);\n\n    const corePlugins = pluginEntries.filter(([_, p]) => {\n      return (p?.plugin?.phase ?? \"normal\") === \"core\";\n    });\n    const normalPlugins = pluginEntries.filter(\n      ([_, p]) => (p?.plugin?.phase ?? \"normal\") === \"normal\",\n    );\n    const deferredPlugins = pluginEntries.filter(\n      ([_, p]) => (p?.plugin?.phase ?? \"normal\") === \"deferred\",\n    );\n\n    for (const [name, pluginData] of corePlugins) {\n      if (pluginData) {\n        this.createAndRegisterPlugin(globalConfig, name, pluginData, {\n          context: this.#context,\n        });\n      }\n    }\n\n    for (const [name, pluginData] of normalPlugins) {\n      if (pluginData) {\n        this.createAndRegisterPlugin(globalConfig, name, pluginData, {\n          context: this.#context,\n        });\n      }\n    }\n\n    for (const [name, pluginData] of deferredPlugins) {\n      if (pluginData) {\n        this.createAndRegisterPlugin(globalConfig, name, pluginData, {\n          context: this.#context,\n        });\n      }\n    }\n  }\n\n  private createAndRegisterPlugin<T extends PluginConstructor>(\n    config: Omit<{ plugins: TPlugins }, \"plugins\">,\n    name: string,\n    pluginData: OptionalConfigPluginDef<T>,\n    extraData?: Record<string, unknown>,\n  ) {\n    const { plugin: Plugin, config: pluginConfig } = pluginData;\n    const baseConfig = {\n      ...config,\n      ...Plugin.DEFAULT_CONFIG,\n      ...pluginConfig,\n      name,\n      ...extraData,\n    };\n    const pluginInstance = new Plugin(baseConfig);\n\n    if (typeof pluginInstance.attachContext === \"function\") {\n      pluginInstance.attachContext({\n        context: this.#context,\n        telemetryConfig: baseConfig.telemetry,\n      });\n    }\n\n    this.#pluginInstances[name] = pluginInstance;\n\n    this.#context.registerPlugin(name, pluginInstance);\n    if (isToolProvider(pluginInstance)) {\n      this.#context.registerToolProvider(name, pluginInstance);\n    }\n\n    this.#setupPromises.push(pluginInstance.setup());\n\n    const self = this;\n\n    // The manifest `name` is camelCase, so it doubles as the public handle key\n    // (`appkit.aiSearch`). The kebab HTTP route is derived separately.\n    Object.defineProperty(this, name, {\n      get() {\n        const plugin = self.#pluginInstances[name];\n        return self.wrapWithAsUser(plugin);\n      },\n      enumerable: true,\n    });\n  }\n\n  /**\n   * Binds all function properties in an exports object to the given context.\n   * Recurses into plain objects to handle nested APIs (e.g., volume APIs).\n   */\n  private bindExportMethods(\n    exports: Record<string, unknown>,\n    context: BasePlugin,\n  ) {\n    for (const key in exports) {\n      if (!Object.hasOwn(exports, key)) continue;\n      const val = exports[key];\n      if (typeof val === \"function\") {\n        exports[key] = (val as (...args: unknown[]) => unknown).bind(context);\n      } else if (isPlainObject(val)) {\n        this.bindExportMethods(val as Record<string, unknown>, context);\n      }\n    }\n  }\n\n  /**\n   * Wraps a plugin's exports with an `asUser` method that returns\n   * a user-scoped version of the exports.\n   *\n   * When `exports()` returns a callable (function), it is returned as-is\n   * since the plugin manages its own `asUser` per-call (e.g. files plugin).\n   * When it returns a plain object, the standard `asUser` wrapper is added.\n   *\n   * The OBO-side wrapping lives inside `Plugin.asUser` — calling\n   * `plugin.asUser(req).exports()` returns exports whose functions already\n   * run inside the user's AsyncLocalStorage scope. AppKit only adapts the\n   * shape; it does not own the user-context concept.\n   */\n  private wrapWithAsUser<T extends BasePlugin>(plugin: T) {\n    // If plugin doesn't implement exports(), return empty object\n    const pluginExports = plugin.exports?.() ?? {};\n\n    // If exports is a function, the plugin manages its own asUser pattern\n    if (typeof pluginExports === \"function\") {\n      return pluginExports;\n    }\n\n    const objExports = pluginExports as Record<string, unknown>;\n    this.bindExportMethods(objExports, plugin);\n\n    // If plugin doesn't support asUser (no asUser method), return exports as-is\n    if (typeof (plugin as any).asUser !== \"function\") {\n      return objExports;\n    }\n\n    return {\n      ...objExports,\n      /**\n       * Execute operations using the user's identity from the request.\n       * Returns user-scoped exports where all methods execute with the\n       * user's Databricks credentials instead of the service principal.\n       */\n      asUser: (req: import(\"express\").Request) =>\n        (plugin as any).asUser(req).exports() as Record<string, unknown>,\n    };\n  }\n\n  static async _createApp<\n    T extends PluginData<PluginConstructor, unknown, string>[],\n  >(\n    config: {\n      plugins?: T;\n      telemetry?: TelemetryConfig;\n      cache?: CacheConfig;\n      client?: WorkspaceClient;\n      onPluginsReady?: (appkit: PluginMap<T>) => void | Promise<void>;\n      disableInternalTelemetry?: boolean;\n      /**\n       * Skip installing the SIGTERM/SIGINT handlers. Internal, and not exposed\n       * on {@link createApp}: only the test harness sets it, because it boots\n       * repeatedly in one process and manages its own teardown, so\n       * accumulating signal handlers would be a leak.\n       */\n      installSignalHandlers?: boolean;\n    } = {},\n  ): Promise<PluginMap<T>> {\n    // Initialize core services\n    TelemetryManager.initialize(config?.telemetry);\n    await CacheManager.getInstance(config?.cache);\n\n    const withDefaults = AppKit.withDefaultPlugins(config.plugins as T);\n    const rawPlugins = AppKit.filterDevOnlyPlugins(withDefaults);\n\n    // Collect manifest resources via registry\n    const registry = new ResourceRegistry();\n    registry.collectResources(rawPlugins);\n    registry.validate();\n\n    // Derive ServiceContext needs from what manifests declared\n    const needsWarehouse = registry\n      .getRequired()\n      .some((r) => r.type === ResourceType.SQL_WAREHOUSE);\n    await ServiceContext.initialize(\n      {\n        warehouseId:\n          getConfiguredWarehouseId(registry.getRequired()) ?? needsWarehouse,\n      },\n      config?.client,\n    );\n\n    // Validate env vars\n    registry.enforceValidation();\n\n    const preparedPlugins = AppKit.preparePlugins(rawPlugins);\n    const mergedConfig = {\n      plugins: preparedPlugins,\n    };\n\n    const instance = new AppKit(mergedConfig);\n\n    await Promise.all(instance.#setupPromises);\n\n    // Build the global tracer provider now that every plugin's setup() has run\n    // and contributed any span processors. Deferred to here so a single provider\n    // carries all processors (OTLP + plugin-contributed); see TelemetryManager.\n    TelemetryManager.start();\n\n    await instance.#context.emitLifecycle(\"setup:complete\");\n\n    const app = instance as unknown as PluginMap<T>;\n\n    if (config.onPluginsReady) {\n      logger.debug(\"Running onPluginsReady hook\");\n      await config.onPluginsReady(app);\n      logger.debug(\"onPluginsReady hook completed\");\n    }\n\n    if (isInternalTelemetryEnabled(config)) {\n      AppKit.bootstrapInternalTelemetry();\n    }\n\n    const serverPlugin = instance.#pluginInstances.server;\n    if (serverPlugin && typeof (serverPlugin as any).start === \"function\") {\n      await (serverPlugin as any).start();\n    }\n\n    // Core owns graceful shutdown: install the signal handlers once every\n    // plugin has started. Applies uniformly whether or not a server plugin\n    // is present — server-less apps still get their telemetry flushed and\n    // plugin shutdown() hooks run.\n    instance.#lifecycle = new LifecycleManager(instance.#context);\n    if (config.installSignalHandlers !== false) {\n      instance.#lifecycle.installSignalHandlers();\n    }\n\n    return app;\n  }\n\n  /**\n   * Internal teardown entry point for the test harness: delegates to the\n   * lifecycle's non-exiting `shutdown({ exit: false })` (the phases are\n   * canonical there). Not public API — AppKit does not support re-booting or\n   * embedding, so real apps tear down only through the signal path. The harness\n   * drops the core singletons and restores env after this resolves.\n   * @internal\n   */\n  async [disposeApp](): Promise<void> {\n    await this.#lifecycle?.shutdown({ exit: false });\n  }\n\n  private static bootstrapInternalTelemetry(): void {\n    const serviceCtx = ServiceContext.get();\n    const reporter = TelemetryReporter.initialize({\n      workspaceId: serviceCtx.workspaceId,\n      client: serviceCtx.client,\n      appId: process.env.DATABRICKS_CLIENT_ID || \"\",\n      appkitVersion: productVersion,\n    });\n    reporter.start();\n    reporter.sendStartup().catch(() => {});\n  }\n\n  /**\n   * Injects framework-owned default plugins the app author shouldn't have to\n   * register by hand. Runs before {@link filterDevOnlyPlugins}, so a default\n   * that is itself `devOnly` (like `ui-variants`) is present in dev and stripped\n   * in prod through the exact same guard as any user plugin — never alive in a\n   * deployed app.\n   *\n   * Currently injects the dev-only `ui-variants` recorder that backs the\n   * `<Variants>` UI picker, so neither the developer nor their coding agent has\n   * to remember to add it. If the app already registered it explicitly, that\n   * entry wins and no duplicate is added.\n   */\n  private static withDefaultPlugins<\n    T extends PluginData<PluginConstructor, unknown, string>[],\n  >(plugins: T): T {\n    const list = (plugins ?? []) as PluginData<\n      PluginConstructor,\n      unknown,\n      string\n    >[];\n\n    const defaults: PluginData<PluginConstructor, unknown, string>[] = [\n      uiVariants(),\n    ];\n\n    const missing = defaults.filter(\n      (def) => !list.some((p) => p?.name === def.name),\n    );\n\n    return [...list, ...missing] as T;\n  }\n\n  /**\n   * Drops plugins whose manifest declares `devOnly: true` unless\n   * `NODE_ENV === \"development\"`. Runs before resource collection so a skipped\n   * plugin is never constructed, never injects routes, and has its resource\n   * requirements ignored — the framework, not the app author, enforces that\n   * dev-only tooling can never run in a deployed app.\n   *\n   * This is the primary guard; plugins that expose a mutating dev endpoint\n   * should still keep an in-handler `NODE_ENV` check as fail-safe defense\n   * against being mounted through a path that bypasses this filter.\n   */\n  private static filterDevOnlyPlugins<\n    T extends PluginData<PluginConstructor, unknown, string>[],\n  >(plugins: T): T {\n    if (!plugins || process.env.NODE_ENV === \"development\") return plugins;\n\n    return plugins.filter((pluginData) => {\n      const isDevOnly = pluginData?.plugin?.manifest?.devOnly === true;\n      if (isDevOnly) {\n        logger.debug(\n          \"Skipping dev-only plugin %s (NODE_ENV=%s)\",\n          pluginData?.name ?? \"unknown\",\n          process.env.NODE_ENV ?? \"<unset>\",\n        );\n      }\n      return !isDevOnly;\n    }) as T;\n  }\n\n  private static preparePlugins(\n    plugins: PluginData<PluginConstructor, unknown, string>[],\n  ) {\n    const result: InputPluginMap = {};\n    for (const currentPlugin of plugins) {\n      result[currentPlugin.name] = {\n        plugin: currentPlugin.plugin,\n        config: currentPlugin.config as Record<string, unknown>,\n      };\n    }\n    return result;\n  }\n}\n\n/**\n * Bootstraps AppKit with the provided configuration.\n *\n * Initializes telemetry, cache, and service context, then registers plugins\n * in phase order (core, normal, deferred) and awaits their setup.\n * If a `onPluginsReady` callback is provided it runs after plugin setup but\n * before the server starts, giving you access to the full appkit handle\n * for registering custom routes or performing async setup.\n * The returned object maps each plugin name to its `exports()` API,\n * with an `asUser(req)` method for user-scoped execution.\n *\n * @returns A `PluginMap` keyed by plugin name with typed exports\n *\n * @example Minimal server\n * ```ts\n * import { createApp, server } from \"@databricks/appkit\";\n *\n * await createApp({\n *   plugins: [server()],\n * });\n * ```\n *\n * @example Server with custom routes via onPluginsReady\n * ```ts\n * import { createApp, server, analytics } from \"@databricks/appkit\";\n *\n * await createApp({\n *   plugins: [server(), analytics({})],\n *   onPluginsReady(appkit) {\n *     appkit.server.extend((app) => {\n *       app.get(\"/custom\", (_req, res) => res.json({ ok: true }));\n *     });\n *   },\n * });\n * ```\n */\nexport async function createApp<\n  T extends PluginData<PluginConstructor, unknown, string>[],\n>(\n  config: {\n    plugins?: T;\n    telemetry?: TelemetryConfig;\n    cache?: CacheConfig;\n    client?: WorkspaceClient;\n    /** Runs after plugin setup but **before** the server starts. */\n    onPluginsReady?: (appkit: PluginMap<T>) => void | Promise<void>;\n    disableInternalTelemetry?: boolean;\n  } = {},\n): Promise<PluginMap<T>> {\n  return AppKit._createApp(config);\n}\n"],"mappings":"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"}
+{"version":3,"file":"appkit.js","names":["#pluginInstances","#context","#setupPromises","#lifecycle","productVersion"],"sources":["../../src/core/appkit.ts"],"sourcesContent":["import type {\n  AppKitApi,\n  BasePlugin,\n  CacheConfig,\n  InputPluginMap,\n  OptionalConfigPluginDef,\n  PluginConstructor,\n  PluginData,\n} from \"shared\";\n\nimport { version as productVersion } from \"../../package.json\";\nimport { CacheManager } from \"../cache\";\nimport { ServiceContext } from \"../context\";\nimport { createRequestScope } from \"../context/request-scope\";\nimport {\n  assertPluginExecution,\n  getPluginResourceTypes,\n  guardPluginApi,\n} from \"../context/resource-capabilities\";\nimport { scopeApi } from \"../context/scoped-api\";\nimport {\n  isInternalTelemetryEnabled,\n  TelemetryReporter,\n} from \"../internal-telemetry\";\nimport { createLogger } from \"../logging/logger\";\nimport { uiVariants } from \"../plugins/ui-variants\";\nimport { ResourceRegistry, ResourceType } from \"../registry\";\nimport { getConfiguredWarehouseId } from \"../resources/warehouse\";\nimport type { TelemetryConfig } from \"../telemetry\";\nimport { TelemetryManager } from \"../telemetry\";\nimport { isPlainObject } from \"../utils/is-plain-object\";\nimport type { WorkspaceClient } from \"../workspace-client\";\nimport { LifecycleManager } from \"./lifecycle-manager\";\nimport { isToolProvider, PluginContext } from \"./plugin-context\";\n\nconst logger = createLogger(\"appkit\");\n\n/**\n * Internal teardown entry for the test harness (see `createTestApp`).\n * Symbol-keyed so it cannot collide with — or be shadowed by — a plugin\n * manifest name, and so it stays off the public `PluginMap` surface.\n * @internal\n */\nexport const disposeApp = Symbol(\"appkit.internal.dispose\");\n\nexport class AppKit<TPlugins extends InputPluginMap> {\n  #pluginInstances: Record<string, BasePlugin> = {};\n  #setupPromises: Promise<void>[] = [];\n  #context: PluginContext;\n  /** Owns the shutdown sequence; assigned once every plugin has started. */\n  #lifecycle: LifecycleManager | undefined;\n\n  /** Execute a block or a single plugin call as the requesting user. */\n  asUser(req: import(\"express\").Request) {\n    const scope = createRequestScope(\n      req,\n      Object.values(this.#pluginInstances).flatMap(getPluginResourceTypes),\n    );\n    const kit: Record<string, unknown> = Object.create(null);\n    // Memoize each plugin's scoped export for the life of THIS handle only.\n    // The map is created per asUser(req) call and captured solely by this\n    // handle's getters, so it dies with the request and never crosses\n    // principals. Repeated access (e.g. kit.analytics twice) reuses the same\n    // wrapper instead of rebuilding the proxy on every read.\n    const scopedExports = new Map<string, unknown>();\n    for (const [name, plugin] of Object.entries(this.#pluginInstances)) {\n      Object.defineProperty(kit, name, {\n        enumerable: true,\n        get: () => {\n          if (!scopedExports.has(name)) {\n            // The app-only guard runs on first access; it is deterministic per\n            // (plugin, scope), so caching the result after it passes is safe,\n            // and if it throws nothing is cached (stays fail-closed).\n            scopedExports.set(\n              name,\n              scopeApi(\n                scope.run(() => {\n                  assertPluginExecution(plugin, true);\n                  return plugin.exports?.() ?? {};\n                }),\n                scope,\n                plugin,\n              ),\n            );\n          }\n          return scopedExports.get(name);\n        },\n      });\n    }\n    Object.defineProperty(kit, \"run\", {\n      value: async <T>(\n        fn: (kit: Record<string, unknown>) => T | Promise<T>,\n      ): Promise<T> => scope.run(() => fn(kit)),\n    });\n    return Object.freeze(kit);\n  }\n\n  private constructor(config: { plugins: TPlugins }) {\n    const { plugins, ...globalConfig } = config;\n\n    this.#context = new PluginContext();\n\n    const pluginEntries = Object.entries(plugins);\n\n    const corePlugins = pluginEntries.filter(([_, p]) => {\n      return (p?.plugin?.phase ?? \"normal\") === \"core\";\n    });\n    const normalPlugins = pluginEntries.filter(\n      ([_, p]) => (p?.plugin?.phase ?? \"normal\") === \"normal\",\n    );\n    const deferredPlugins = pluginEntries.filter(\n      ([_, p]) => (p?.plugin?.phase ?? \"normal\") === \"deferred\",\n    );\n\n    for (const [name, pluginData] of corePlugins) {\n      if (pluginData) {\n        this.createAndRegisterPlugin(globalConfig, name, pluginData, {\n          context: this.#context,\n        });\n      }\n    }\n\n    for (const [name, pluginData] of normalPlugins) {\n      if (pluginData) {\n        this.createAndRegisterPlugin(globalConfig, name, pluginData, {\n          context: this.#context,\n        });\n      }\n    }\n\n    for (const [name, pluginData] of deferredPlugins) {\n      if (pluginData) {\n        this.createAndRegisterPlugin(globalConfig, name, pluginData, {\n          context: this.#context,\n        });\n      }\n    }\n  }\n\n  private createAndRegisterPlugin<T extends PluginConstructor>(\n    config: Omit<{ plugins: TPlugins }, \"plugins\">,\n    name: string,\n    pluginData: OptionalConfigPluginDef<T>,\n    extraData?: Record<string, unknown>,\n  ) {\n    if (name === \"run\" || /^as[A-Z]/.test(name)) {\n      throw new Error(\n        `Plugin name \"${name}\" is reserved for execution scoping`,\n      );\n    }\n    const { plugin: Plugin, config: pluginConfig } = pluginData;\n    const baseConfig = {\n      ...config,\n      ...Plugin.DEFAULT_CONFIG,\n      ...pluginConfig,\n      name,\n      ...extraData,\n    };\n    const pluginInstance = new Plugin(baseConfig);\n\n    if (typeof pluginInstance.attachContext === \"function\") {\n      pluginInstance.attachContext({\n        context: this.#context,\n        telemetryConfig: baseConfig.telemetry,\n      });\n    }\n\n    this.#pluginInstances[name] = pluginInstance;\n\n    this.#context.registerPlugin(name, pluginInstance);\n    if (isToolProvider(pluginInstance)) {\n      this.#context.registerToolProvider(name, pluginInstance);\n    }\n\n    this.#setupPromises.push(pluginInstance.setup());\n\n    const self = this;\n\n    // The manifest `name` is camelCase, so it doubles as the public handle key\n    // (`appkit.aiSearch`). The kebab HTTP route is derived separately.\n    Object.defineProperty(this, name, {\n      get() {\n        const plugin = self.#pluginInstances[name];\n        return self.wrapWithAsUser(plugin);\n      },\n      enumerable: true,\n    });\n  }\n\n  /**\n   * Binds all function properties in an exports object to the given context.\n   * Recurses into plain objects to handle nested APIs (e.g., volume APIs).\n   */\n  private bindExportMethods(\n    exports: Record<string, unknown>,\n    context: BasePlugin,\n  ) {\n    for (const key in exports) {\n      if (!Object.hasOwn(exports, key)) continue;\n      const val = exports[key];\n      if (typeof val === \"function\") {\n        exports[key] = (val as (...args: unknown[]) => unknown).bind(context);\n      } else if (isPlainObject(val)) {\n        this.bindExportMethods(val as Record<string, unknown>, context);\n      }\n    }\n  }\n\n  /**\n   * Wraps a plugin's exports with an `asUser` method that returns\n   * a user-scoped version of the exports.\n   *\n   * When `exports()` returns a callable (function), it is returned as-is\n   * since the plugin manages its own `asUser` per-call (e.g. files plugin).\n   * When it returns a plain object, the standard `asUser` wrapper is added.\n   *\n   * This preserves the deprecated per-plugin API. Both entry points delegate\n   * to the shared request scope; new code should use the app-level API.\n   */\n  private wrapWithAsUser<T extends BasePlugin>(plugin: T) {\n    assertPluginExecution(plugin);\n    // If plugin doesn't implement exports(), return empty object\n    const pluginExports = plugin.exports?.() ?? {};\n\n    // If exports is a function, the plugin manages its own asUser pattern\n    if (typeof pluginExports === \"function\") {\n      return guardPluginApi(plugin, pluginExports);\n    }\n\n    const objExports = pluginExports as Record<string, unknown>;\n    this.bindExportMethods(objExports, plugin);\n\n    // If plugin doesn't support asUser (no asUser method), return exports as-is\n    if (typeof (plugin as any).asUser !== \"function\") {\n      return guardPluginApi(plugin, objExports);\n    }\n\n    return guardPluginApi(plugin, {\n      ...objExports,\n      /**\n       * @deprecated Use appkit.asUser(req) instead.\n       * Execute operations using the user's identity from the request.\n       * Returns user-scoped exports where all methods execute with the\n       * user's Databricks credentials instead of the service principal.\n       */\n      asUser: (req: import(\"express\").Request) =>\n        (plugin as any).asUser(req).exports() as Record<string, unknown>,\n    });\n  }\n\n  static async _createApp<\n    T extends PluginData<PluginConstructor, unknown, string>[],\n  >(\n    config: {\n      plugins?: T;\n      telemetry?: TelemetryConfig;\n      cache?: CacheConfig;\n      client?: WorkspaceClient;\n      onPluginsReady?: (appkit: AppKitApi<T>) => void | Promise<void>;\n      disableInternalTelemetry?: boolean;\n      /**\n       * Skip installing the SIGTERM/SIGINT handlers. Internal, and not exposed\n       * on {@link createApp}: only the test harness sets it, because it boots\n       * repeatedly in one process and manages its own teardown, so\n       * accumulating signal handlers would be a leak.\n       */\n      installSignalHandlers?: boolean;\n    } = {},\n  ): Promise<AppKitApi<T>> {\n    // Initialize core services\n    TelemetryManager.initialize(config?.telemetry);\n    await CacheManager.getInstance(config?.cache);\n\n    const withDefaults = AppKit.withDefaultPlugins(config.plugins as T);\n    const rawPlugins = AppKit.filterDevOnlyPlugins(withDefaults);\n\n    // Collect manifest resources via registry\n    const registry = new ResourceRegistry();\n    registry.collectResources(rawPlugins);\n    registry.validate();\n\n    // Derive ServiceContext needs from what manifests declared\n    const needsWarehouse = registry\n      .getRequired()\n      .some((r) => r.type === ResourceType.SQL_WAREHOUSE);\n    await ServiceContext.initialize(\n      {\n        warehouseId:\n          getConfiguredWarehouseId(registry.getRequired()) ?? needsWarehouse,\n      },\n      config?.client,\n    );\n\n    // Validate env vars\n    registry.enforceValidation();\n\n    const preparedPlugins = AppKit.preparePlugins(rawPlugins);\n    const mergedConfig = {\n      plugins: preparedPlugins,\n    };\n\n    const instance = new AppKit(mergedConfig);\n\n    await Promise.all(instance.#setupPromises);\n\n    // Build the global tracer provider now that every plugin's setup() has run\n    // and contributed any span processors. Deferred to here so a single provider\n    // carries all processors (OTLP + plugin-contributed); see TelemetryManager.\n    TelemetryManager.start();\n\n    await instance.#context.emitLifecycle(\"setup:complete\");\n\n    const app = instance as typeof instance & AppKitApi<T>;\n\n    if (config.onPluginsReady) {\n      logger.debug(\"Running onPluginsReady hook\");\n      await config.onPluginsReady(app);\n      logger.debug(\"onPluginsReady hook completed\");\n    }\n\n    if (isInternalTelemetryEnabled(config)) {\n      AppKit.bootstrapInternalTelemetry();\n    }\n\n    const serverPlugin = instance.#pluginInstances.server;\n    if (serverPlugin && typeof (serverPlugin as any).start === \"function\") {\n      await (serverPlugin as any).start();\n    }\n\n    // Core owns graceful shutdown: install the signal handlers once every\n    // plugin has started. Applies uniformly whether or not a server plugin\n    // is present — server-less apps still get their telemetry flushed and\n    // plugin shutdown() hooks run.\n    instance.#lifecycle = new LifecycleManager(instance.#context);\n    if (config.installSignalHandlers !== false) {\n      instance.#lifecycle.installSignalHandlers();\n    }\n\n    return app;\n  }\n\n  /**\n   * Internal teardown entry point for the test harness: delegates to the\n   * lifecycle's non-exiting `shutdown({ exit: false })` (the phases are\n   * canonical there). Not public API — AppKit does not support re-booting or\n   * embedding, so real apps tear down only through the signal path. The harness\n   * drops the core singletons and restores env after this resolves.\n   * @internal\n   */\n  async [disposeApp](): Promise<void> {\n    await this.#lifecycle?.shutdown({ exit: false });\n  }\n\n  private static bootstrapInternalTelemetry(): void {\n    const serviceCtx = ServiceContext.get();\n    const reporter = TelemetryReporter.initialize({\n      workspaceId: serviceCtx.workspaceId,\n      client: serviceCtx.client,\n      appId: process.env.DATABRICKS_CLIENT_ID || \"\",\n      appkitVersion: productVersion,\n    });\n    reporter.start();\n    reporter.sendStartup().catch(() => {});\n  }\n\n  /**\n   * Injects framework-owned default plugins the app author shouldn't have to\n   * register by hand. Runs before {@link filterDevOnlyPlugins}, so a default\n   * that is itself `devOnly` (like `ui-variants`) is present in dev and stripped\n   * in prod through the exact same guard as any user plugin — never alive in a\n   * deployed app.\n   *\n   * Currently injects the dev-only `ui-variants` recorder that backs the\n   * `<Variants>` UI picker, so neither the developer nor their coding agent has\n   * to remember to add it. If the app already registered it explicitly, that\n   * entry wins and no duplicate is added.\n   */\n  private static withDefaultPlugins<\n    T extends PluginData<PluginConstructor, unknown, string>[],\n  >(plugins: T): T {\n    const list = (plugins ?? []) as PluginData<\n      PluginConstructor,\n      unknown,\n      string\n    >[];\n\n    const defaults: PluginData<PluginConstructor, unknown, string>[] = [\n      uiVariants(),\n    ];\n\n    const missing = defaults.filter(\n      (def) => !list.some((p) => p?.name === def.name),\n    );\n\n    return [...list, ...missing] as T;\n  }\n\n  /**\n   * Drops plugins whose manifest declares `devOnly: true` unless\n   * `NODE_ENV === \"development\"`. Runs before resource collection so a skipped\n   * plugin is never constructed, never injects routes, and has its resource\n   * requirements ignored — the framework, not the app author, enforces that\n   * dev-only tooling can never run in a deployed app.\n   *\n   * This is the primary guard; plugins that expose a mutating dev endpoint\n   * should still keep an in-handler `NODE_ENV` check as fail-safe defense\n   * against being mounted through a path that bypasses this filter.\n   */\n  private static filterDevOnlyPlugins<\n    T extends PluginData<PluginConstructor, unknown, string>[],\n  >(plugins: T): T {\n    if (!plugins || process.env.NODE_ENV === \"development\") return plugins;\n\n    return plugins.filter((pluginData) => {\n      const isDevOnly = pluginData?.plugin?.manifest?.devOnly === true;\n      if (isDevOnly) {\n        logger.debug(\n          \"Skipping dev-only plugin %s (NODE_ENV=%s)\",\n          pluginData?.name ?? \"unknown\",\n          process.env.NODE_ENV ?? \"<unset>\",\n        );\n      }\n      return !isDevOnly;\n    }) as T;\n  }\n\n  private static preparePlugins(\n    plugins: PluginData<PluginConstructor, unknown, string>[],\n  ) {\n    const result: InputPluginMap = {};\n    for (const currentPlugin of plugins) {\n      result[currentPlugin.name] = {\n        plugin: currentPlugin.plugin,\n        config: currentPlugin.config as Record<string, unknown>,\n      };\n    }\n    return result;\n  }\n}\n\n/**\n * Bootstraps AppKit with the provided configuration.\n *\n * Initializes telemetry, cache, and service context, then registers plugins\n * in phase order (core, normal, deferred) and awaits their setup.\n * If a `onPluginsReady` callback is provided it runs after plugin setup but\n * before the server starts, giving you access to the full appkit handle\n * for registering custom routes or performing async setup.\n * The returned object maps each plugin name to its `exports()` API,\n * with an `asUser(req)` method for user-scoped execution.\n *\n * @returns A `PluginMap` keyed by plugin name with typed exports\n *\n * @example Minimal server\n * ```ts\n * import { createApp, server } from \"@databricks/appkit\";\n *\n * await createApp({\n *   plugins: [server()],\n * });\n * ```\n *\n * @example Server with custom routes via onPluginsReady\n * ```ts\n * import { createApp, server, analytics } from \"@databricks/appkit\";\n *\n * await createApp({\n *   plugins: [server(), analytics({})],\n *   onPluginsReady(appkit) {\n *     appkit.server.extend((app) => {\n *       app.get(\"/custom\", (_req, res) => res.json({ ok: true }));\n *     });\n *   },\n * });\n * ```\n */\nexport async function createApp<\n  T extends PluginData<PluginConstructor, unknown, string>[],\n>(\n  config: {\n    plugins?: T;\n    telemetry?: TelemetryConfig;\n    cache?: CacheConfig;\n    client?: WorkspaceClient;\n    /** Runs after plugin setup but **before** the server starts. */\n    onPluginsReady?: (appkit: AppKitApi<T>) => void | Promise<void>;\n    disableInternalTelemetry?: boolean;\n  } = {},\n): Promise<AppKitApi<T>> {\n  return AppKit._createApp(config);\n}\n"],"mappings":"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"}

package/dist/core/plugin-context.d.ts

@@ -1,6 +1,7 @@
 import { ToolProvider } from "../shared/src/agent.js";
-import { BasePlugin, IAppRequest } from "../shared/src/plugin.js";
+import { BasePlugin } from "../shared/src/plugin.js";
 import "../shared/src/index.js";
+import { ServiceContext } from "../context/service-context.js";
 import { ITelemetry } from "../telemetry/types.js";
 import "../telemetry/index.js";
 import express from "express";
@@ -10,14 +11,9 @@ interface RouteTarget {
   addExtension(fn: (app: express.Application) => void): void;
 }
 /**
- * A tool-provider plugin that also exposes user-scoped execution. Plugins
- * derived from {@link Plugin} satisfy this implicitly because `asUser` lives
- * on the base class. {@link isToolProvider} narrows to this shape so
- * `executeTool` can call `asUser` without an unsafe cast.
+ * Tool execution inherits the caller scope established by the entry point.
  */
-type ToolProviderPlugin = BasePlugin & ToolProvider & {
-  asUser: (req: IAppRequest) => ToolProvider;
-};
+type ToolProviderPlugin = BasePlugin & ToolProvider;
 /**
  * Lifecycle events emitted through {@link PluginContext.emitLifecycle}.
  *
@@ -52,16 +48,19 @@ declare class PluginContext {
   private plugins;
   private lifecycleHooks;
   private telemetry;
+  private createCallerContext;
   /**
    * @param deps.telemetry - Telemetry provider used for `executeTool` spans.
-   *   Defaults to the shared `"plugin-context"` provider — the production
+   *   Defaults to the shared `"plugin-context"` provider, the production
    *   path. Injectable so the testing kit can pass a mock provider and run
-   *   `executeTool` without a live OpenTelemetry pipeline. This is the only
-   *   seam the mock context needs; route buffering and the tool registry are
+   *   `executeTool` without a live OpenTelemetry pipeline.
+   * @param deps.createCallerContext - Offline credential factory for tests.
+   *   Header validation and ALS remain real; route buffering and the registry are
    *   exercised through the existing public API.
    */
   constructor(deps?: {
-    telemetry?: ITelemetry;
+    telemetry?: ITelemetry; /** @internal Credential factory seam for offline testing. */
+    createCallerContext?: typeof ServiceContext.createCallerContext;
   });
   /**
    * Register a route on the root Express application.
@@ -117,15 +116,15 @@ declare class PluginContext {
     provider: ToolProvider;
   }>;
   /**
-   * Execute a tool on a ToolProvider plugin with automatic user scoping
+   * Execute a tool on a ToolProvider plugin with the ambient principal
    * and telemetry.
    *
    * The context:
    * 1. Resolves the plugin by name
-   * 2. Calls `asUser(req)` for user-scoped execution
+   * 2. Inherits the caller, or establishes user scope from the request
    * 3. Wraps the call in a telemetry span with a configurable timeout
    *
-   * @param timeoutMs Per-call timeout. Defaults to 5 minutes — the floor
+   * @param timeoutMs Per-call timeout. Defaults to 5 minutes, the floor
    *   for cold SQL Warehouse round-trips, long Genie conversations, and
    *   busy serverless Lakebase queries. The agents plugin overrides this
    *   per-app via `agents({ limits: { toolCallTimeoutMs } })`.

package/dist/core/plugin-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin-context.d.ts","names":[],"sources":["../../src/core/plugin-context.ts"],"mappings":";;;;;;;;UAmBU,WAAA;EACR,YAAA,CAAa,EAAA,GAAK,GAAA,EAAK,OAAA,CAAQ,WAAA;AAAA;;;AAZX;;;;KAqBjB,kBAAA,GAAqB,UAAA,GACxB,YAAA;EAAiB,MAAA,GAAS,GAAA,EAAK,WAAA,KAAgB,YAAA;AAAA;;;;;AAVI;;;;;;;;;KAyBhD,cAAA;;;;;;;;AAfwD;;;;;AA8B7D;cAAa,aAAA;EAAA,QACH,WAAA;EAAA,QACA,WAAA;EAAA,QACA,aAAA;EAAA,QACA,OAAA;EAAA,QACA,cAAA;EAAA,QAIA,SAAA;EAiG+B;;;;;;;;cAvF3B,IAAA;IAAQ,SAAA,GAAY,UAAA;EAAA;EAuMY;;;;;;;EA3L5C,QAAA,CACE,MAAA,UACA,IAAA,aACG,QAAA,EAAU,OAAA,CAAQ,cAAA;EAzBf;;;;;EAuCR,aAAA,CAAc,IAAA,aAAiB,QAAA,EAAU,OAAA,CAAQ,cAAA;EAhB/C;;;;;;;;;EAiCF,qBAAA,CAAsB,MAAA,EAAQ,WAAA;EAA9B;;;;;;;;EA2BA,oBAAA,CAAqB,IAAA,UAAc,MAAA,EAAQ,kBAAA;EAcJ;;;;EAAvC,cAAA,CAAe,IAAA,UAAc,QAAA,EAAU,UAAA;EAkBvC;;;;;;EARA,UAAA,CAAA,GAAc,WAAA,SAAoB,UAAA;EA8BnB;;;;EAtBf,gBAAA,CAAA,GAAoB,KAAA;IAAQ,IAAA;IAAc,QAAA,EAAU,YAAA;EAAA;EA4BjD;;;;;;;;;;;;;;EAPG,WAAA,CACJ,GAAA,EAAK,OAAA,CAAQ,OAAA,EACb,UAAA,UACA,QAAA,UACA,IAAA,WACA,MAAA,GAAS,WAAA,EACT,SAAA,YACC,OAAA;EAwHoB;;;;;;;EAvEvB,WAAA,CAAY,KAAA,EAAO,cAAA,EAAgB,EAAA,eAAiB,OAAA;;;;;;;;;EAiB9C,aAAA,CAAc,KAAA,EAAO,cAAA,GAAiB,OAAA;;;;EA8B5C,cAAA,CAAA;;;;EAOA,SAAA,CAAU,IAAA;EAAA,QAIF,UAAA;EAAA,QAaA,eAAA;AAAA"}
+{"version":3,"file":"plugin-context.d.ts","names":[],"sources":["../../src/core/plugin-context.ts"],"mappings":";;;;;;;;;UA6BU,WAAA;EACR,YAAA,CAAa,EAAA,GAAK,GAAA,EAAK,OAAA,CAAQ,WAAA;AAAA;;;AAZX;KAkBjB,kBAAA,GAAqB,UAAA,GAAa,YAAA;;;;;;;;;;AANc;;;;KAqBhD,cAAA;AAf8C;;;;;AA8BnD;;;;;;;;AA9BmD,cA8BtC,aAAA;EAAA,QACH,WAAA;EAAA,QACA,WAAA;EAAA,QACA,aAAA;EAAA,QACA,OAAA;EAAA,QACA,cAAA;EAAA,QAIA,SAAA;EAAA,QACA,mBAAA;EAyJL;;;;;;;;;cA7ID,IAAA;IACE,SAAA,GAAY,UAAA,EAlBR;IAoBJ,mBAAA,UAA6B,cAAA,CAAe,mBAAA;EAAA;;;;;;;;EAiBhD,QAAA,CACE,MAAA,UACA,IAAA,aACG,QAAA,EAAU,OAAA,CAAQ,cAAA;EAFrB;;;;;EAgBF,aAAA,CAAc,IAAA,aAAiB,QAAA,EAAU,OAAA,CAAQ,cAAA;EAAnC;;;;;;;;;EAiBd,qBAAA,CAAsB,MAAA,EAAQ,WAAA;EA2BK;;;;;;;;EAAnC,oBAAA,CAAqB,IAAA,UAAc,MAAA,EAAQ,kBAAA;EAgCvB;;;;EAlBpB,cAAA,CAAe,IAAA,UAAc,QAAA,EAAU,UAAA;EAwChC;;;;;;EA9BP,UAAA,CAAA,GAAc,WAAA,SAAoB,UAAA;EAkChC;;;;EA1BF,gBAAA,CAAA,GAAoB,KAAA;IAAQ,IAAA;IAAc,QAAA,EAAU,YAAA;EAAA;EAwG9C;;;;;;;;;;;;;;EAnFA,WAAA,CACJ,GAAA,EAAK,OAAA,CAAQ,OAAA,EACb,UAAA,UACA,QAAA,UACA,IAAA,WACA,MAAA,GAAS,WAAA,EACT,SAAA,YACC,OAAA;;;;;;;;EA2DH,WAAA,CAAY,KAAA,EAAO,cAAA,EAAgB,EAAA,eAAiB,OAAA;;;;;;;;;EAiB9C,aAAA,CAAc,KAAA,EAAO,cAAA,GAAiB,OAAA;;;;EA8B5C,cAAA,CAAA;;;;EAOA,SAAA,CAAU,IAAA;EAAA,QAIF,UAAA;EAAA,QAaA,eAAA;AAAA"}

package/dist/core/plugin-context.js

@@ -1,6 +1,10 @@
 import { createLogger } from "../logging/logger.js";
+import { ServiceContext } from "../context/service-context.js";
+import { getCallerContext, normalizeIdentityError } from "../context/execution-context.js";
+import { assertPluginExecution, getPluginResourceTypes } from "../context/resource-capabilities.js";
 import { TelemetryManager } from "../telemetry/telemetry-manager.js";
 import { SpanStatusCode } from "../telemetry/index.js";
+import { createRequestScope } from "../context/request-scope.js";
 import { forwardAsyncErrors } from "../utils/safe-handler.js";
 
 //#region src/core/plugin-context.ts
@@ -25,16 +29,19 @@ var PluginContext = class {
 	plugins = /* @__PURE__ */ new Map();
 	lifecycleHooks = /* @__PURE__ */ new Map();
 	telemetry;
+	createCallerContext;
 	/**
 	* @param deps.telemetry - Telemetry provider used for `executeTool` spans.
-	*   Defaults to the shared `"plugin-context"` provider — the production
+	*   Defaults to the shared `"plugin-context"` provider, the production
 	*   path. Injectable so the testing kit can pass a mock provider and run
-	*   `executeTool` without a live OpenTelemetry pipeline. This is the only
-	*   seam the mock context needs; route buffering and the tool registry are
+	*   `executeTool` without a live OpenTelemetry pipeline.
+	* @param deps.createCallerContext - Offline credential factory for tests.
+	*   Header validation and ALS remain real; route buffering and the registry are
 	*   exercised through the existing public API.
 	*/
 	constructor(deps = {}) {
 		this.telemetry = deps.telemetry ?? TelemetryManager.getProvider("plugin-context");
+		this.createCallerContext = deps.createCallerContext ?? ((...args) => ServiceContext.createCallerContext(...args));
 	}
 	/**
 	* Register a route on the root Express application.
@@ -126,15 +133,15 @@ var PluginContext = class {
 		}));
 	}
 	/**
-	* Execute a tool on a ToolProvider plugin with automatic user scoping
+	* Execute a tool on a ToolProvider plugin with the ambient principal
 	* and telemetry.
 	*
 	* The context:
 	* 1. Resolves the plugin by name
-	* 2. Calls `asUser(req)` for user-scoped execution
+	* 2. Inherits the caller, or establishes user scope from the request
 	* 3. Wraps the call in a telemetry span with a configurable timeout
 	*
-	* @param timeoutMs Per-call timeout. Defaults to 5 minutes — the floor
+	* @param timeoutMs Per-call timeout. Defaults to 5 minutes, the floor
 	*   for cold SQL Warehouse round-trips, long Genie conversations, and
 	*   busy serverless Lakebase queries. The agents plugin overrides this
 	*   per-app via `agents({ limits: { toolCallTimeoutMs } })`.
@@ -144,14 +151,16 @@ var PluginContext = class {
 		if (!provider) throw new Error(`PluginContext: unknown plugin "${pluginName}". Available: ${Array.from(this.toolProviders.keys()).join(", ")}`);
 		const tracer = this.telemetry.getTracer();
 		const operationName = `executeTool:${pluginName}.${toolName}`;
-		return tracer.startActiveSpan(operationName, async (span) => {
+		const executeInCurrentScope = () => tracer.startActiveSpan(operationName, async (span) => {
 			const timeoutSignal = AbortSignal.timeout(timeoutMs);
 			const combinedSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
 			try {
-				const result = await provider.asUser(req).executeAgentTool(toolName, args, combinedSignal);
+				assertPluginExecution(provider);
+				const result = await provider.executeAgentTool(toolName, args, combinedSignal);
 				span.setStatus({ code: SpanStatusCode.OK });
 				return result;
-			} catch (error) {
+			} catch (caught) {
+				const error = normalizeIdentityError(caught);
 				span.setStatus({
 					code: SpanStatusCode.ERROR,
 					message: error instanceof Error ? error.message : "Tool execution failed"
@@ -162,6 +171,10 @@ var PluginContext = class {
 				span.end();
 			}
 		});
+		return getCallerContext() ? executeInCurrentScope() : createRequestScope(req, getPluginResourceTypes(provider), {
+			createCaller: this.createCallerContext,
+			legacy: true
+		}).run(executeInCurrentScope);
 	}
 	/**
 	* Register a lifecycle hook callback.
@@ -223,13 +236,10 @@ var PluginContext = class {
 	}
 };
 /**
-* Type guard: checks whether a plugin implements the ToolProvider interface
-* and exposes the user-scoped `asUser` helper that the {@link Plugin} base
-* class provides. Narrowing to {@link ToolProviderPlugin} lets `executeTool`
-* call `asUser` without an unsafe cast.
+* Type guard for the tool-provider methods. Identity comes from the ALS scope.
 */
 function isToolProvider(plugin) {
-	return typeof plugin === "object" && plugin !== null && "getAgentTools" in plugin && typeof plugin.getAgentTools === "function" && "executeAgentTool" in plugin && typeof plugin.executeAgentTool === "function" && "asUser" in plugin && typeof plugin.asUser === "function";
+	return typeof plugin === "object" && plugin !== null && "getAgentTools" in plugin && typeof plugin.getAgentTools === "function" && "executeAgentTool" in plugin && typeof plugin.executeAgentTool === "function";
 }
 
 //#endregion

package/dist/core/plugin-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"plugin-context.js","names":[],"sources":["../../src/core/plugin-context.ts"],"sourcesContent":["import type express from \"express\";\nimport type { BasePlugin, IAppRequest, ToolProvider } from \"shared\";\n\nimport { createLogger } from \"../logging/logger\";\nimport {\n  type ITelemetry,\n  SpanStatusCode,\n  TelemetryManager,\n} from \"../telemetry\";\nimport { forwardAsyncErrors } from \"../utils/safe-handler\";\n\nconst logger = createLogger(\"plugin-context\");\n\ninterface BufferedRoute {\n  method: string;\n  path: string;\n  handlers: express.RequestHandler[];\n}\n\ninterface RouteTarget {\n  addExtension(fn: (app: express.Application) => void): void;\n}\n\n/**\n * A tool-provider plugin that also exposes user-scoped execution. Plugins\n * derived from {@link Plugin} satisfy this implicitly because `asUser` lives\n * on the base class. {@link isToolProvider} narrows to this shape so\n * `executeTool` can call `asUser` without an unsafe cast.\n */\ntype ToolProviderPlugin = BasePlugin &\n  ToolProvider & { asUser: (req: IAppRequest) => ToolProvider };\n\n/**\n * Lifecycle events emitted through {@link PluginContext.emitLifecycle}.\n *\n * - `\"setup:complete\"` — emitted by AppKit core after every plugin's\n *   `setup()` has finished.\n * - `\"server:ready\"` — emitted when the HTTP server is listening.\n * - `\"shutdown\"` — emitted by the core lifecycle manager during graceful\n *   shutdown, AFTER all plugin `shutdown()` hooks have completed. The emit is\n *   bounded by a short timeout (see the lifecycle manager's shutdown budget),\n *   so subscribers must not start long-running async work — finish quickly or\n *   be cut off. (The server plugin subscribes here to force-close its\n *   remaining sockets once peers have drained.)\n */\ntype LifecycleEvent = \"setup:complete\" | \"server:ready\" | \"shutdown\";\n\n/**\n * Mediator for inter-plugin communication.\n *\n * Created by AppKit core and passed to every plugin. Plugins request\n * capabilities from the context instead of holding direct references\n * to sibling plugin instances.\n *\n * Capabilities:\n * - Route mounting with buffering (order-independent)\n * - Typed ToolProvider registry (live, not snapshot-based)\n * - User-scoped tool execution with automatic telemetry\n * - Lifecycle hooks for plugin coordination\n */\nexport class PluginContext {\n  private routeBuffer: BufferedRoute[] = [];\n  private routeTarget: RouteTarget | null = null;\n  private toolProviders = new Map<string, ToolProviderPlugin>();\n  private plugins = new Map<string, BasePlugin>();\n  private lifecycleHooks = new Map<\n    LifecycleEvent,\n    Set<() => void | Promise<void>>\n  >();\n  private telemetry: ITelemetry;\n\n  /**\n   * @param deps.telemetry - Telemetry provider used for `executeTool` spans.\n   *   Defaults to the shared `\"plugin-context\"` provider — the production\n   *   path. Injectable so the testing kit can pass a mock provider and run\n   *   `executeTool` without a live OpenTelemetry pipeline. This is the only\n   *   seam the mock context needs; route buffering and the tool registry are\n   *   exercised through the existing public API.\n   */\n  constructor(deps: { telemetry?: ITelemetry } = {}) {\n    this.telemetry =\n      deps.telemetry ?? TelemetryManager.getProvider(\"plugin-context\");\n  }\n\n  /**\n   * Register a route on the root Express application.\n   *\n   * If a route target (server plugin) has registered, the route is applied\n   * immediately. Otherwise it is buffered and flushed when a route target\n   * becomes available.\n   */\n  addRoute(\n    method: string,\n    path: string,\n    ...handlers: express.RequestHandler[]\n  ): void {\n    if (this.routeTarget) {\n      this.applyRoute({ method, path, handlers });\n    } else {\n      this.routeBuffer.push({ method, path, handlers });\n    }\n  }\n\n  /**\n   * Register middleware on the root Express application.\n   *\n   * Same buffering semantics as `addRoute`.\n   */\n  addMiddleware(path: string, ...handlers: express.RequestHandler[]): void {\n    if (this.routeTarget) {\n      this.applyMiddleware(path, handlers);\n    } else {\n      this.routeBuffer.push({ method: \"use\", path, handlers });\n    }\n  }\n\n  /**\n   * Called by the server plugin to opt in as the route target.\n   * Flushes all buffered routes via the server's `addExtension`.\n   *\n   * Only the first caller wins — subsequent calls are ignored with a warning.\n   * In practice only the server plugin registers, but a misconfigured app\n   * (two server plugins, or duplicate AppKit setup in tests) would otherwise\n   * silently drop the first target's later extensions.\n   */\n  registerAsRouteTarget(target: RouteTarget): void {\n    if (this.routeTarget) {\n      logger.warn(\n        \"registerAsRouteTarget called more than once; ignoring duplicate registration\",\n      );\n      return;\n    }\n    this.routeTarget = target;\n\n    for (const route of this.routeBuffer) {\n      if (route.method === \"use\") {\n        this.applyMiddleware(route.path, route.handlers);\n      } else {\n        this.applyRoute(route);\n      }\n    }\n    this.routeBuffer = [];\n  }\n\n  /**\n   * Register a plugin that implements the ToolProvider interface.\n   * Called by AppKit core after constructing each plugin.\n   *\n   * Plugin names should be unique (they are derived from `manifest.name`).\n   * A duplicate registration overwrites the previous entry and emits a\n   * warning so the misconfiguration is visible in startup logs.\n   */\n  registerToolProvider(name: string, plugin: ToolProviderPlugin): void {\n    if (this.toolProviders.has(name)) {\n      logger.warn(\n        'Tool provider \"%s\" registered more than once; the previous registration is being overwritten',\n        name,\n      );\n    }\n    this.toolProviders.set(name, plugin);\n  }\n\n  /**\n   * Register a plugin instance.\n   * Called by AppKit core after constructing each plugin.\n   */\n  registerPlugin(name: string, instance: BasePlugin): void {\n    this.plugins.set(name, instance);\n  }\n\n  /**\n   * Returns all registered plugin instances keyed by name.\n   * Used by the server plugin for route injection, client config,\n   * and shutdown coordination. The returned map is read-only at the\n   * type level — callers must not mutate the live registry.\n   */\n  getPlugins(): ReadonlyMap<string, BasePlugin> {\n    return this.plugins;\n  }\n\n  /**\n   * Returns all registered ToolProvider plugins.\n   * Always returns the current set — not a frozen snapshot.\n   */\n  getToolProviders(): Array<{ name: string; provider: ToolProvider }> {\n    return Array.from(this.toolProviders.entries()).map(([name, provider]) => ({\n      name,\n      provider,\n    }));\n  }\n\n  /**\n   * Execute a tool on a ToolProvider plugin with automatic user scoping\n   * and telemetry.\n   *\n   * The context:\n   * 1. Resolves the plugin by name\n   * 2. Calls `asUser(req)` for user-scoped execution\n   * 3. Wraps the call in a telemetry span with a configurable timeout\n   *\n   * @param timeoutMs Per-call timeout. Defaults to 5 minutes — the floor\n   *   for cold SQL Warehouse round-trips, long Genie conversations, and\n   *   busy serverless Lakebase queries. The agents plugin overrides this\n   *   per-app via `agents({ limits: { toolCallTimeoutMs } })`.\n   */\n  async executeTool(\n    req: express.Request,\n    pluginName: string,\n    toolName: string,\n    args: unknown,\n    signal?: AbortSignal,\n    timeoutMs: number = 300_000,\n  ): Promise<unknown> {\n    const provider = this.toolProviders.get(pluginName);\n    if (!provider) {\n      throw new Error(\n        `PluginContext: unknown plugin \"${pluginName}\". Available: ${Array.from(this.toolProviders.keys()).join(\", \")}`,\n      );\n    }\n\n    const tracer = this.telemetry.getTracer();\n    const operationName = `executeTool:${pluginName}.${toolName}`;\n\n    return tracer.startActiveSpan(operationName, async (span) => {\n      const timeoutSignal = AbortSignal.timeout(timeoutMs);\n      const combinedSignal = signal\n        ? AbortSignal.any([signal, timeoutSignal])\n        : timeoutSignal;\n\n      try {\n        const userScoped = provider.asUser(req);\n        const result = await userScoped.executeAgentTool(\n          toolName,\n          args,\n          combinedSignal,\n        );\n        span.setStatus({ code: SpanStatusCode.OK });\n        return result;\n      } catch (error) {\n        span.setStatus({\n          code: SpanStatusCode.ERROR,\n          message:\n            error instanceof Error ? error.message : \"Tool execution failed\",\n        });\n        span.recordException(\n          error instanceof Error ? error : new Error(String(error)),\n        );\n        throw error;\n      } finally {\n        span.end();\n      }\n    });\n  }\n\n  /**\n   * Register a lifecycle hook callback.\n   *\n   * See {@link LifecycleEvent} for event semantics. In particular,\n   * `\"shutdown\"` subscribers run inside a bounded shutdown phase and must\n   * not start long-running async work.\n   */\n  onLifecycle(event: LifecycleEvent, fn: () => void | Promise<void>): void {\n    let hooks = this.lifecycleHooks.get(event);\n    if (!hooks) {\n      hooks = new Set();\n      this.lifecycleHooks.set(event, hooks);\n    }\n    hooks.add(fn);\n  }\n\n  /**\n   * Emit a lifecycle event, calling all registered callbacks.\n   * Errors in individual callbacks are logged but do not prevent\n   * other callbacks from running.\n   *\n   * @internal Called by AppKit core: `setup:complete` after plugin setup,\n   * and `shutdown` by the lifecycle manager during graceful shutdown.\n   */\n  async emitLifecycle(event: LifecycleEvent): Promise<void> {\n    const hooks = this.lifecycleHooks.get(event);\n    if (!hooks) return;\n\n    if (\n      event === \"setup:complete\" &&\n      this.routeBuffer.length > 0 &&\n      !this.routeTarget\n    ) {\n      logger.warn(\n        \"%d buffered routes were never applied — no server plugin registered as route target\",\n        this.routeBuffer.length,\n      );\n    }\n\n    // Snapshot before iterating so a callback that registers a new hook for\n    // the same event does not mutate the loop. ECMAScript Set iteration would\n    // otherwise visit late-added entries, risking unexpected re-entry.\n    for (const fn of [...hooks]) {\n      try {\n        await fn();\n      } catch (error) {\n        logger.error(\"Lifecycle hook '%s' failed: %O\", event, error);\n      }\n    }\n  }\n\n  /**\n   * Returns all registered plugin names.\n   */\n  getPluginNames(): string[] {\n    return Array.from(this.plugins.keys());\n  }\n\n  /**\n   * Check if a plugin with the given name is registered.\n   */\n  hasPlugin(name: string): boolean {\n    return this.plugins.has(name);\n  }\n\n  private applyRoute(route: BufferedRoute): void {\n    if (!this.routeTarget) return;\n    this.routeTarget.addExtension((app) => {\n      const method = route.method.toLowerCase() as keyof express.Application;\n      if (typeof app[method] === \"function\") {\n        (app[method] as (...a: unknown[]) => void)(\n          route.path,\n          ...route.handlers.map(forwardAsyncErrors),\n        );\n      }\n    });\n  }\n\n  private applyMiddleware(\n    path: string,\n    handlers: express.RequestHandler[],\n  ): void {\n    if (!this.routeTarget) return;\n    this.routeTarget.addExtension((app) => {\n      app.use(path, ...handlers.map(forwardAsyncErrors));\n    });\n  }\n}\n\n/**\n * Type guard: checks whether a plugin implements the ToolProvider interface\n * and exposes the user-scoped `asUser` helper that the {@link Plugin} base\n * class provides. Narrowing to {@link ToolProviderPlugin} lets `executeTool`\n * call `asUser` without an unsafe cast.\n */\nexport function isToolProvider(plugin: unknown): plugin is ToolProviderPlugin {\n  return (\n    typeof plugin === \"object\" &&\n    plugin !== null &&\n    \"getAgentTools\" in plugin &&\n    typeof (plugin as ToolProvider).getAgentTools === \"function\" &&\n    \"executeAgentTool\" in plugin &&\n    typeof (plugin as ToolProvider).executeAgentTool === \"function\" &&\n    \"asUser\" in plugin &&\n    typeof (plugin as { asUser?: unknown }).asUser === \"function\"\n  );\n}\n"],"mappings":"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"}
+{"version":3,"file":"plugin-context.js","names":[],"sources":["../../src/core/plugin-context.ts"],"sourcesContent":["import type express from \"express\";\nimport type { BasePlugin, ToolProvider } from \"shared\";\n\nimport {\n  getCallerContext,\n  normalizeIdentityError,\n} from \"../context/execution-context\";\nimport { createRequestScope } from \"../context/request-scope\";\nimport {\n  assertPluginExecution,\n  getPluginResourceTypes,\n} from \"../context/resource-capabilities\";\nimport { ServiceContext } from \"../context/service-context\";\nimport { createLogger } from \"../logging/logger\";\nimport {\n  type ITelemetry,\n  SpanStatusCode,\n  TelemetryManager,\n} from \"../telemetry\";\nimport { forwardAsyncErrors } from \"../utils/safe-handler\";\n\nconst logger = createLogger(\"plugin-context\");\n\ninterface BufferedRoute {\n  method: string;\n  path: string;\n  handlers: express.RequestHandler[];\n}\n\ninterface RouteTarget {\n  addExtension(fn: (app: express.Application) => void): void;\n}\n\n/**\n * Tool execution inherits the caller scope established by the entry point.\n */\ntype ToolProviderPlugin = BasePlugin & ToolProvider;\n\n/**\n * Lifecycle events emitted through {@link PluginContext.emitLifecycle}.\n *\n * - `\"setup:complete\"` — emitted by AppKit core after every plugin's\n *   `setup()` has finished.\n * - `\"server:ready\"` — emitted when the HTTP server is listening.\n * - `\"shutdown\"` — emitted by the core lifecycle manager during graceful\n *   shutdown, AFTER all plugin `shutdown()` hooks have completed. The emit is\n *   bounded by a short timeout (see the lifecycle manager's shutdown budget),\n *   so subscribers must not start long-running async work — finish quickly or\n *   be cut off. (The server plugin subscribes here to force-close its\n *   remaining sockets once peers have drained.)\n */\ntype LifecycleEvent = \"setup:complete\" | \"server:ready\" | \"shutdown\";\n\n/**\n * Mediator for inter-plugin communication.\n *\n * Created by AppKit core and passed to every plugin. Plugins request\n * capabilities from the context instead of holding direct references\n * to sibling plugin instances.\n *\n * Capabilities:\n * - Route mounting with buffering (order-independent)\n * - Typed ToolProvider registry (live, not snapshot-based)\n * - User-scoped tool execution with automatic telemetry\n * - Lifecycle hooks for plugin coordination\n */\nexport class PluginContext {\n  private routeBuffer: BufferedRoute[] = [];\n  private routeTarget: RouteTarget | null = null;\n  private toolProviders = new Map<string, ToolProviderPlugin>();\n  private plugins = new Map<string, BasePlugin>();\n  private lifecycleHooks = new Map<\n    LifecycleEvent,\n    Set<() => void | Promise<void>>\n  >();\n  private telemetry: ITelemetry;\n  private createCallerContext: typeof ServiceContext.createCallerContext;\n\n  /**\n   * @param deps.telemetry - Telemetry provider used for `executeTool` spans.\n   *   Defaults to the shared `\"plugin-context\"` provider, the production\n   *   path. Injectable so the testing kit can pass a mock provider and run\n   *   `executeTool` without a live OpenTelemetry pipeline.\n   * @param deps.createCallerContext - Offline credential factory for tests.\n   *   Header validation and ALS remain real; route buffering and the registry are\n   *   exercised through the existing public API.\n   */\n  constructor(\n    deps: {\n      telemetry?: ITelemetry;\n      /** @internal Credential factory seam for offline testing. */\n      createCallerContext?: typeof ServiceContext.createCallerContext;\n    } = {},\n  ) {\n    this.telemetry =\n      deps.telemetry ?? TelemetryManager.getProvider(\"plugin-context\");\n    this.createCallerContext =\n      deps.createCallerContext ??\n      ((...args) => ServiceContext.createCallerContext(...args));\n  }\n\n  /**\n   * Register a route on the root Express application.\n   *\n   * If a route target (server plugin) has registered, the route is applied\n   * immediately. Otherwise it is buffered and flushed when a route target\n   * becomes available.\n   */\n  addRoute(\n    method: string,\n    path: string,\n    ...handlers: express.RequestHandler[]\n  ): void {\n    if (this.routeTarget) {\n      this.applyRoute({ method, path, handlers });\n    } else {\n      this.routeBuffer.push({ method, path, handlers });\n    }\n  }\n\n  /**\n   * Register middleware on the root Express application.\n   *\n   * Same buffering semantics as `addRoute`.\n   */\n  addMiddleware(path: string, ...handlers: express.RequestHandler[]): void {\n    if (this.routeTarget) {\n      this.applyMiddleware(path, handlers);\n    } else {\n      this.routeBuffer.push({ method: \"use\", path, handlers });\n    }\n  }\n\n  /**\n   * Called by the server plugin to opt in as the route target.\n   * Flushes all buffered routes via the server's `addExtension`.\n   *\n   * Only the first caller wins — subsequent calls are ignored with a warning.\n   * In practice only the server plugin registers, but a misconfigured app\n   * (two server plugins, or duplicate AppKit setup in tests) would otherwise\n   * silently drop the first target's later extensions.\n   */\n  registerAsRouteTarget(target: RouteTarget): void {\n    if (this.routeTarget) {\n      logger.warn(\n        \"registerAsRouteTarget called more than once; ignoring duplicate registration\",\n      );\n      return;\n    }\n    this.routeTarget = target;\n\n    for (const route of this.routeBuffer) {\n      if (route.method === \"use\") {\n        this.applyMiddleware(route.path, route.handlers);\n      } else {\n        this.applyRoute(route);\n      }\n    }\n    this.routeBuffer = [];\n  }\n\n  /**\n   * Register a plugin that implements the ToolProvider interface.\n   * Called by AppKit core after constructing each plugin.\n   *\n   * Plugin names should be unique (they are derived from `manifest.name`).\n   * A duplicate registration overwrites the previous entry and emits a\n   * warning so the misconfiguration is visible in startup logs.\n   */\n  registerToolProvider(name: string, plugin: ToolProviderPlugin): void {\n    if (this.toolProviders.has(name)) {\n      logger.warn(\n        'Tool provider \"%s\" registered more than once; the previous registration is being overwritten',\n        name,\n      );\n    }\n    this.toolProviders.set(name, plugin);\n  }\n\n  /**\n   * Register a plugin instance.\n   * Called by AppKit core after constructing each plugin.\n   */\n  registerPlugin(name: string, instance: BasePlugin): void {\n    this.plugins.set(name, instance);\n  }\n\n  /**\n   * Returns all registered plugin instances keyed by name.\n   * Used by the server plugin for route injection, client config,\n   * and shutdown coordination. The returned map is read-only at the\n   * type level — callers must not mutate the live registry.\n   */\n  getPlugins(): ReadonlyMap<string, BasePlugin> {\n    return this.plugins;\n  }\n\n  /**\n   * Returns all registered ToolProvider plugins.\n   * Always returns the current set — not a frozen snapshot.\n   */\n  getToolProviders(): Array<{ name: string; provider: ToolProvider }> {\n    return Array.from(this.toolProviders.entries()).map(([name, provider]) => ({\n      name,\n      provider,\n    }));\n  }\n\n  /**\n   * Execute a tool on a ToolProvider plugin with the ambient principal\n   * and telemetry.\n   *\n   * The context:\n   * 1. Resolves the plugin by name\n   * 2. Inherits the caller, or establishes user scope from the request\n   * 3. Wraps the call in a telemetry span with a configurable timeout\n   *\n   * @param timeoutMs Per-call timeout. Defaults to 5 minutes, the floor\n   *   for cold SQL Warehouse round-trips, long Genie conversations, and\n   *   busy serverless Lakebase queries. The agents plugin overrides this\n   *   per-app via `agents({ limits: { toolCallTimeoutMs } })`.\n   */\n  async executeTool(\n    req: express.Request,\n    pluginName: string,\n    toolName: string,\n    args: unknown,\n    signal?: AbortSignal,\n    timeoutMs: number = 300_000,\n  ): Promise<unknown> {\n    const provider = this.toolProviders.get(pluginName);\n    if (!provider) {\n      throw new Error(\n        `PluginContext: unknown plugin \"${pluginName}\". Available: ${Array.from(this.toolProviders.keys()).join(\", \")}`,\n      );\n    }\n\n    const tracer = this.telemetry.getTracer();\n    const operationName = `executeTool:${pluginName}.${toolName}`;\n\n    const executeInCurrentScope = () =>\n      tracer.startActiveSpan(operationName, async (span) => {\n        const timeoutSignal = AbortSignal.timeout(timeoutMs);\n        const combinedSignal = signal\n          ? AbortSignal.any([signal, timeoutSignal])\n          : timeoutSignal;\n\n        try {\n          assertPluginExecution(provider);\n          const result = await provider.executeAgentTool(\n            toolName,\n            args,\n            combinedSignal,\n          );\n          span.setStatus({ code: SpanStatusCode.OK });\n          return result;\n        } catch (caught) {\n          const error = normalizeIdentityError(caught);\n          span.setStatus({\n            code: SpanStatusCode.ERROR,\n            message:\n              error instanceof Error ? error.message : \"Tool execution failed\",\n          });\n          span.recordException(\n            error instanceof Error ? error : new Error(String(error)),\n          );\n          throw error;\n        } finally {\n          span.end();\n        }\n      });\n\n    // Inherit the caller or establish request user scope before the span and tool run.\n    return getCallerContext()\n      ? executeInCurrentScope()\n      : createRequestScope(req, getPluginResourceTypes(provider), {\n          createCaller: this.createCallerContext,\n          legacy: true,\n        }).run(executeInCurrentScope);\n  }\n\n  /**\n   * Register a lifecycle hook callback.\n   *\n   * See {@link LifecycleEvent} for event semantics. In particular,\n   * `\"shutdown\"` subscribers run inside a bounded shutdown phase and must\n   * not start long-running async work.\n   */\n  onLifecycle(event: LifecycleEvent, fn: () => void | Promise<void>): void {\n    let hooks = this.lifecycleHooks.get(event);\n    if (!hooks) {\n      hooks = new Set();\n      this.lifecycleHooks.set(event, hooks);\n    }\n    hooks.add(fn);\n  }\n\n  /**\n   * Emit a lifecycle event, calling all registered callbacks.\n   * Errors in individual callbacks are logged but do not prevent\n   * other callbacks from running.\n   *\n   * @internal Called by AppKit core: `setup:complete` after plugin setup,\n   * and `shutdown` by the lifecycle manager during graceful shutdown.\n   */\n  async emitLifecycle(event: LifecycleEvent): Promise<void> {\n    const hooks = this.lifecycleHooks.get(event);\n    if (!hooks) return;\n\n    if (\n      event === \"setup:complete\" &&\n      this.routeBuffer.length > 0 &&\n      !this.routeTarget\n    ) {\n      logger.warn(\n        \"%d buffered routes were never applied — no server plugin registered as route target\",\n        this.routeBuffer.length,\n      );\n    }\n\n    // Snapshot before iterating so a callback that registers a new hook for\n    // the same event does not mutate the loop. ECMAScript Set iteration would\n    // otherwise visit late-added entries, risking unexpected re-entry.\n    for (const fn of [...hooks]) {\n      try {\n        await fn();\n      } catch (error) {\n        logger.error(\"Lifecycle hook '%s' failed: %O\", event, error);\n      }\n    }\n  }\n\n  /**\n   * Returns all registered plugin names.\n   */\n  getPluginNames(): string[] {\n    return Array.from(this.plugins.keys());\n  }\n\n  /**\n   * Check if a plugin with the given name is registered.\n   */\n  hasPlugin(name: string): boolean {\n    return this.plugins.has(name);\n  }\n\n  private applyRoute(route: BufferedRoute): void {\n    if (!this.routeTarget) return;\n    this.routeTarget.addExtension((app) => {\n      const method = route.method.toLowerCase() as keyof express.Application;\n      if (typeof app[method] === \"function\") {\n        (app[method] as (...a: unknown[]) => void)(\n          route.path,\n          ...route.handlers.map(forwardAsyncErrors),\n        );\n      }\n    });\n  }\n\n  private applyMiddleware(\n    path: string,\n    handlers: express.RequestHandler[],\n  ): void {\n    if (!this.routeTarget) return;\n    this.routeTarget.addExtension((app) => {\n      app.use(path, ...handlers.map(forwardAsyncErrors));\n    });\n  }\n}\n\n/**\n * Type guard for the tool-provider methods. Identity comes from the ALS scope.\n */\nexport function isToolProvider(plugin: unknown): plugin is ToolProviderPlugin {\n  return (\n    typeof plugin === \"object\" &&\n    plugin !== null &&\n    \"getAgentTools\" in plugin &&\n    typeof (plugin as ToolProvider).getAgentTools === \"function\" &&\n    \"executeAgentTool\" in plugin &&\n    typeof (plugin as ToolProvider).executeAgentTool === \"function\"\n  );\n}\n"],"mappings":";;;;;;;;;;AAqBA,MAAM,SAAS,aAAa,iBAAiB;;;;;;;;;;;;;;AA6C7C,IAAa,gBAAb,MAA2B;CACzB,AAAQ,cAA+B,EAAE;CACzC,AAAQ,cAAkC;CAC1C,AAAQ,gCAAgB,IAAI,KAAiC;CAC7D,AAAQ,0BAAU,IAAI,KAAyB;CAC/C,AAAQ,iCAAiB,IAAI,KAG1B;CACH,AAAQ;CACR,AAAQ;;;;;;;;;;CAWR,YACE,OAII,EAAE,EACN;AACA,OAAK,YACH,KAAK,aAAa,iBAAiB,YAAY,iBAAiB;AAClE,OAAK,sBACH,KAAK,yBACH,GAAG,SAAS,eAAe,oBAAoB,GAAG,KAAK;;;;;;;;;CAU7D,SACE,QACA,MACA,GAAG,UACG;AACN,MAAI,KAAK,YACP,MAAK,WAAW;GAAE;GAAQ;GAAM;GAAU,CAAC;MAE3C,MAAK,YAAY,KAAK;GAAE;GAAQ;GAAM;GAAU,CAAC;;;;;;;CASrD,cAAc,MAAc,GAAG,UAA0C;AACvE,MAAI,KAAK,YACP,MAAK,gBAAgB,MAAM,SAAS;MAEpC,MAAK,YAAY,KAAK;GAAE,QAAQ;GAAO;GAAM;GAAU,CAAC;;;;;;;;;;;CAa5D,sBAAsB,QAA2B;AAC/C,MAAI,KAAK,aAAa;AACpB,UAAO,KACL,+EACD;AACD;;AAEF,OAAK,cAAc;AAEnB,OAAK,MAAM,SAAS,KAAK,YACvB,KAAI,MAAM,WAAW,MACnB,MAAK,gBAAgB,MAAM,MAAM,MAAM,SAAS;MAEhD,MAAK,WAAW,MAAM;AAG1B,OAAK,cAAc,EAAE;;;;;;;;;;CAWvB,qBAAqB,MAAc,QAAkC;AACnE,MAAI,KAAK,cAAc,IAAI,KAAK,CAC9B,QAAO,KACL,kGACA,KACD;AAEH,OAAK,cAAc,IAAI,MAAM,OAAO;;;;;;CAOtC,eAAe,MAAc,UAA4B;AACvD,OAAK,QAAQ,IAAI,MAAM,SAAS;;;;;;;;CASlC,aAA8C;AAC5C,SAAO,KAAK;;;;;;CAOd,mBAAoE;AAClE,SAAO,MAAM,KAAK,KAAK,cAAc,SAAS,CAAC,CAAC,KAAK,CAAC,MAAM,eAAe;GACzE;GACA;GACD,EAAE;;;;;;;;;;;;;;;;CAiBL,MAAM,YACJ,KACA,YACA,UACA,MACA,QACA,YAAoB,KACF;EAClB,MAAM,WAAW,KAAK,cAAc,IAAI,WAAW;AACnD,MAAI,CAAC,SACH,OAAM,IAAI,MACR,kCAAkC,WAAW,gBAAgB,MAAM,KAAK,KAAK,cAAc,MAAM,CAAC,CAAC,KAAK,KAAK,GAC9G;EAGH,MAAM,SAAS,KAAK,UAAU,WAAW;EACzC,MAAM,gBAAgB,eAAe,WAAW,GAAG;EAEnD,MAAM,8BACJ,OAAO,gBAAgB,eAAe,OAAO,SAAS;GACpD,MAAM,gBAAgB,YAAY,QAAQ,UAAU;GACpD,MAAM,iBAAiB,SACnB,YAAY,IAAI,CAAC,QAAQ,cAAc,CAAC,GACxC;AAEJ,OAAI;AACF,0BAAsB,SAAS;IAC/B,MAAM,SAAS,MAAM,SAAS,iBAC5B,UACA,MACA,eACD;AACD,SAAK,UAAU,EAAE,MAAM,eAAe,IAAI,CAAC;AAC3C,WAAO;YACA,QAAQ;IACf,MAAM,QAAQ,uBAAuB,OAAO;AAC5C,SAAK,UAAU;KACb,MAAM,eAAe;KACrB,SACE,iBAAiB,QAAQ,MAAM,UAAU;KAC5C,CAAC;AACF,SAAK,gBACH,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,MAAM,CAAC,CAC1D;AACD,UAAM;aACE;AACR,SAAK,KAAK;;IAEZ;AAGJ,SAAO,kBAAkB,GACrB,uBAAuB,GACvB,mBAAmB,KAAK,uBAAuB,SAAS,EAAE;GACxD,cAAc,KAAK;GACnB,QAAQ;GACT,CAAC,CAAC,IAAI,sBAAsB;;;;;;;;;CAUnC,YAAY,OAAuB,IAAsC;EACvE,IAAI,QAAQ,KAAK,eAAe,IAAI,MAAM;AAC1C,MAAI,CAAC,OAAO;AACV,2BAAQ,IAAI,KAAK;AACjB,QAAK,eAAe,IAAI,OAAO,MAAM;;AAEvC,QAAM,IAAI,GAAG;;;;;;;;;;CAWf,MAAM,cAAc,OAAsC;EACxD,MAAM,QAAQ,KAAK,eAAe,IAAI,MAAM;AAC5C,MAAI,CAAC,MAAO;AAEZ,MACE,UAAU,oBACV,KAAK,YAAY,SAAS,KAC1B,CAAC,KAAK,YAEN,QAAO,KACL,uFACA,KAAK,YAAY,OAClB;AAMH,OAAK,MAAM,MAAM,CAAC,GAAG,MAAM,CACzB,KAAI;AACF,SAAM,IAAI;WACH,OAAO;AACd,UAAO,MAAM,kCAAkC,OAAO,MAAM;;;;;;CAQlE,iBAA2B;AACzB,SAAO,MAAM,KAAK,KAAK,QAAQ,MAAM,CAAC;;;;;CAMxC,UAAU,MAAuB;AAC/B,SAAO,KAAK,QAAQ,IAAI,KAAK;;CAG/B,AAAQ,WAAW,OAA4B;AAC7C,MAAI,CAAC,KAAK,YAAa;AACvB,OAAK,YAAY,cAAc,QAAQ;GACrC,MAAM,SAAS,MAAM,OAAO,aAAa;AACzC,OAAI,OAAO,IAAI,YAAY,WACzB,CAAC,IAAI,QACH,MAAM,MACN,GAAG,MAAM,SAAS,IAAI,mBAAmB,CAC1C;IAEH;;CAGJ,AAAQ,gBACN,MACA,UACM;AACN,MAAI,CAAC,KAAK,YAAa;AACvB,OAAK,YAAY,cAAc,QAAQ;AACrC,OAAI,IAAI,MAAM,GAAG,SAAS,IAAI,mBAAmB,CAAC;IAClD;;;;;;AAON,SAAgB,eAAe,QAA+C;AAC5E,QACE,OAAO,WAAW,YAClB,WAAW,QACX,mBAAmB,UACnB,OAAQ,OAAwB,kBAAkB,cAClD,sBAAsB,UACtB,OAAQ,OAAwB,qBAAqB"}

package/dist/errors/base.d.ts

@@ -33,8 +33,8 @@ declare abstract class AppKitError extends Error {
   readonly context?: Record<string, unknown>;
   /**
    * Client-safe error message. When set, callers serializing the error to
-   * a client (SSE, HTTP body) MUST prefer `clientMessage` over `message`
-   * — `message` may contain raw upstream / SDK text including statement
+   * a client (SSE, HTTP body) MUST prefer `clientMessage` over `message`.
+   * `message` may contain raw upstream / SDK text including statement
    * fragments, internal object names, and correlation IDs.
    *
    * Subclasses can set this in their constructor for a fixed sanitized

package/dist/errors/base.js

@@ -37,8 +37,8 @@ var AppKitError = class extends Error {
 	context;
 	/**
 	* Client-safe error message. When set, callers serializing the error to
-	* a client (SSE, HTTP body) MUST prefer `clientMessage` over `message`
-	* — `message` may contain raw upstream / SDK text including statement
+	* a client (SSE, HTTP body) MUST prefer `clientMessage` over `message`.
+	* `message` may contain raw upstream / SDK text including statement
 	* fragments, internal object names, and correlation IDs.
 	*
 	* Subclasses can set this in their constructor for a fixed sanitized

package/dist/errors/base.js.map

@@ -1 +1 @@
-{"version":3,"file":"base.js","names":[],"sources":["../../src/errors/base.ts"],"sourcesContent":["/** Fields that should be redacted in logs/serialization for security */\nconst SENSITIVE_FIELD_PATTERNS = [\n  /token/i,\n  /password/i,\n  /secret/i,\n  /credential/i,\n  /auth/i,\n  /key$/i,\n  /apikey/i,\n];\n\n/**\n * Base error class for all AppKit errors.\n * Provides a consistent structure for error handling across the framework.\n *\n * @example\n * ```typescript\n * // Catching errors by type\n * try {\n *   await lakebase.query(\"...\");\n * } catch (e) {\n *   if (e instanceof AuthenticationError) {\n *     // Re-authenticate\n *   } else if (e instanceof ConnectionError && e.isRetryable) {\n *     // Retry with backoff\n *   }\n * }\n *\n * // Logging errors\n * console.error(error.toJSON()); // Safe for logging, sensitive values redacted\n * ```\n */\nexport abstract class AppKitError extends Error {\n  /** Error code for programmatic error handling */\n  abstract readonly code: string;\n\n  /** HTTP status code suggestion (can be overridden) */\n  abstract readonly statusCode: number;\n\n  /** Whether this error type is generally safe to retry */\n  abstract readonly isRetryable: boolean;\n\n  /** Optional cause of the error */\n  readonly cause?: Error;\n\n  /** Additional context for the error */\n  readonly context?: Record<string, unknown>;\n\n  /**\n   * Client-safe error message. When set, callers serializing the error to\n   * a client (SSE, HTTP body) MUST prefer `clientMessage` over `message`\n   * — `message` may contain raw upstream / SDK text including statement\n   * fragments, internal object names, and correlation IDs.\n   *\n   * Subclasses can set this in their constructor for a fixed sanitized\n   * string. When unset, `clientMessage` defaults to a generic per-code\n   * string (see the getter), and the raw `message` is kept server-side\n   * only.\n   */\n  protected readonly _clientMessage?: string;\n\n  constructor(\n    message: string,\n    options?: {\n      cause?: Error;\n      context?: Record<string, unknown>;\n      clientMessage?: string;\n    },\n  ) {\n    super(message);\n    this.name = this.constructor.name;\n    this.cause = options?.cause;\n    this.context = options?.context;\n    this._clientMessage = options?.clientMessage;\n\n    // Maintains proper stack trace for where the error was thrown\n    if (Error.captureStackTrace) {\n      Error.captureStackTrace(this, this.constructor);\n    }\n  }\n\n  /**\n   * Sanitized message safe to forward to clients. Override in subclasses\n   * if a more specific default is appropriate.\n   */\n  get clientMessage(): string {\n    return this._clientMessage ?? \"An internal error occurred\";\n  }\n\n  /**\n   * Convert error to JSON for logging/serialization.\n   * Sensitive values in context are automatically redacted.\n   */\n  toJSON(): Record<string, unknown> {\n    return {\n      name: this.name,\n      code: this.code,\n      message: this.message,\n      statusCode: this.statusCode,\n      isRetryable: this.isRetryable,\n      context: this.sanitizeContext(this.context),\n      cause: this.cause?.message,\n      stack: this.stack,\n    };\n  }\n\n  /**\n   * Create a human-readable string representation\n   */\n  toString(): string {\n    let str = `${this.name} [${this.code}]: ${this.message}`;\n    if (this.cause) {\n      str += ` (caused by: ${this.cause.message})`;\n    }\n    return str;\n  }\n\n  /**\n   * Sanitize context by redacting sensitive field values\n   */\n  private sanitizeContext(\n    context?: Record<string, unknown>,\n  ): Record<string, unknown> | undefined {\n    if (!context) return undefined;\n\n    const sanitized: Record<string, unknown> = {};\n    for (const [key, value] of Object.entries(context)) {\n      if (this.isSensitiveField(key)) {\n        sanitized[key] = \"[REDACTED]\";\n      } else if (typeof value === \"object\" && value !== null) {\n        // Don't deep-sanitize nested objects, just indicate their type\n        sanitized[key] = Array.isArray(value)\n          ? `[Array(${value.length})]`\n          : \"[Object]\";\n      } else {\n        sanitized[key] = value;\n      }\n    }\n    return sanitized;\n  }\n\n  /**\n   * Check if a field name matches sensitive patterns\n   */\n  private isSensitiveField(fieldName: string): boolean {\n    return SENSITIVE_FIELD_PATTERNS.some((pattern) => pattern.test(fieldName));\n  }\n}\n"],"mappings":";;AACA,MAAM,2BAA2B;CAC/B;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;;;;;;;;;;;;;;;;;;AAuBD,IAAsB,cAAtB,cAA0C,MAAM;;CAW9C,AAAS;;CAGT,AAAS;;;;;;;;;;;;CAaT,AAAmB;CAEnB,YACE,SACA,SAKA;AACA,QAAM,QAAQ;AACd,OAAK,OAAO,KAAK,YAAY;AAC7B,OAAK,QAAQ,SAAS;AACtB,OAAK,UAAU,SAAS;AACxB,OAAK,iBAAiB,SAAS;AAG/B,MAAI,MAAM,kBACR,OAAM,kBAAkB,MAAM,KAAK,YAAY;;;;;;CAQnD,IAAI,gBAAwB;AAC1B,SAAO,KAAK,kBAAkB;;;;;;CAOhC,SAAkC;AAChC,SAAO;GACL,MAAM,KAAK;GACX,MAAM,KAAK;GACX,SAAS,KAAK;GACd,YAAY,KAAK;GACjB,aAAa,KAAK;GAClB,SAAS,KAAK,gBAAgB,KAAK,QAAQ;GAC3C,OAAO,KAAK,OAAO;GACnB,OAAO,KAAK;GACb;;;;;CAMH,WAAmB;EACjB,IAAI,MAAM,GAAG,KAAK,KAAK,IAAI,KAAK,KAAK,KAAK,KAAK;AAC/C,MAAI,KAAK,MACP,QAAO,gBAAgB,KAAK,MAAM,QAAQ;AAE5C,SAAO;;;;;CAMT,AAAQ,gBACN,SACqC;AACrC,MAAI,CAAC,QAAS,QAAO;EAErB,MAAM,YAAqC,EAAE;AAC7C,OAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,QAAQ,CAChD,KAAI,KAAK,iBAAiB,IAAI,CAC5B,WAAU,OAAO;WACR,OAAO,UAAU,YAAY,UAAU,KAEhD,WAAU,OAAO,MAAM,QAAQ,MAAM,GACjC,UAAU,MAAM,OAAO,MACvB;MAEJ,WAAU,OAAO;AAGrB,SAAO;;;;;CAMT,AAAQ,iBAAiB,WAA4B;AACnD,SAAO,yBAAyB,MAAM,YAAY,QAAQ,KAAK,UAAU,CAAC"}
+{"version":3,"file":"base.js","names":[],"sources":["../../src/errors/base.ts"],"sourcesContent":["/** Fields that should be redacted in logs/serialization for security */\nconst SENSITIVE_FIELD_PATTERNS = [\n  /token/i,\n  /password/i,\n  /secret/i,\n  /credential/i,\n  /auth/i,\n  /key$/i,\n  /apikey/i,\n];\n\n/**\n * Base error class for all AppKit errors.\n * Provides a consistent structure for error handling across the framework.\n *\n * @example\n * ```typescript\n * // Catching errors by type\n * try {\n *   await lakebase.query(\"...\");\n * } catch (e) {\n *   if (e instanceof AuthenticationError) {\n *     // Re-authenticate\n *   } else if (e instanceof ConnectionError && e.isRetryable) {\n *     // Retry with backoff\n *   }\n * }\n *\n * // Logging errors\n * console.error(error.toJSON()); // Safe for logging, sensitive values redacted\n * ```\n */\nexport abstract class AppKitError extends Error {\n  /** Error code for programmatic error handling */\n  abstract readonly code: string;\n\n  /** HTTP status code suggestion (can be overridden) */\n  abstract readonly statusCode: number;\n\n  /** Whether this error type is generally safe to retry */\n  abstract readonly isRetryable: boolean;\n\n  /** Optional cause of the error */\n  readonly cause?: Error;\n\n  /** Additional context for the error */\n  readonly context?: Record<string, unknown>;\n\n  /**\n   * Client-safe error message. When set, callers serializing the error to\n   * a client (SSE, HTTP body) MUST prefer `clientMessage` over `message`.\n   * `message` may contain raw upstream / SDK text including statement\n   * fragments, internal object names, and correlation IDs.\n   *\n   * Subclasses can set this in their constructor for a fixed sanitized\n   * string. When unset, `clientMessage` defaults to a generic per-code\n   * string (see the getter), and the raw `message` is kept server-side\n   * only.\n   */\n  protected readonly _clientMessage?: string;\n\n  constructor(\n    message: string,\n    options?: {\n      cause?: Error;\n      context?: Record<string, unknown>;\n      clientMessage?: string;\n    },\n  ) {\n    super(message);\n    this.name = this.constructor.name;\n    this.cause = options?.cause;\n    this.context = options?.context;\n    this._clientMessage = options?.clientMessage;\n\n    // Maintains proper stack trace for where the error was thrown\n    if (Error.captureStackTrace) {\n      Error.captureStackTrace(this, this.constructor);\n    }\n  }\n\n  /**\n   * Sanitized message safe to forward to clients. Override in subclasses\n   * if a more specific default is appropriate.\n   */\n  get clientMessage(): string {\n    return this._clientMessage ?? \"An internal error occurred\";\n  }\n\n  /**\n   * Convert error to JSON for logging/serialization.\n   * Sensitive values in context are automatically redacted.\n   */\n  toJSON(): Record<string, unknown> {\n    return {\n      name: this.name,\n      code: this.code,\n      message: this.message,\n      statusCode: this.statusCode,\n      isRetryable: this.isRetryable,\n      context: this.sanitizeContext(this.context),\n      cause: this.cause?.message,\n      stack: this.stack,\n    };\n  }\n\n  /**\n   * Create a human-readable string representation\n   */\n  toString(): string {\n    let str = `${this.name} [${this.code}]: ${this.message}`;\n    if (this.cause) {\n      str += ` (caused by: ${this.cause.message})`;\n    }\n    return str;\n  }\n\n  /**\n   * Sanitize context by redacting sensitive field values\n   */\n  private sanitizeContext(\n    context?: Record<string, unknown>,\n  ): Record<string, unknown> | undefined {\n    if (!context) return undefined;\n\n    const sanitized: Record<string, unknown> = {};\n    for (const [key, value] of Object.entries(context)) {\n      if (this.isSensitiveField(key)) {\n        sanitized[key] = \"[REDACTED]\";\n      } else if (typeof value === \"object\" && value !== null) {\n        // Don't deep-sanitize nested objects, just indicate their type\n        sanitized[key] = Array.isArray(value)\n          ? `[Array(${value.length})]`\n          : \"[Object]\";\n      } else {\n        sanitized[key] = value;\n      }\n    }\n    return sanitized;\n  }\n\n  /**\n   * Check if a field name matches sensitive patterns\n   */\n  private isSensitiveField(fieldName: string): boolean {\n    return SENSITIVE_FIELD_PATTERNS.some((pattern) => pattern.test(fieldName));\n  }\n}\n"],"mappings":";;AACA,MAAM,2BAA2B;CAC/B;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;;;;;;;;;;;;;;;;;;AAuBD,IAAsB,cAAtB,cAA0C,MAAM;;CAW9C,AAAS;;CAGT,AAAS;;;;;;;;;;;;CAaT,AAAmB;CAEnB,YACE,SACA,SAKA;AACA,QAAM,QAAQ;AACd,OAAK,OAAO,KAAK,YAAY;AAC7B,OAAK,QAAQ,SAAS;AACtB,OAAK,UAAU,SAAS;AACxB,OAAK,iBAAiB,SAAS;AAG/B,MAAI,MAAM,kBACR,OAAM,kBAAkB,MAAM,KAAK,YAAY;;;;;;CAQnD,IAAI,gBAAwB;AAC1B,SAAO,KAAK,kBAAkB;;;;;;CAOhC,SAAkC;AAChC,SAAO;GACL,MAAM,KAAK;GACX,MAAM,KAAK;GACX,SAAS,KAAK;GACd,YAAY,KAAK;GACjB,aAAa,KAAK;GAClB,SAAS,KAAK,gBAAgB,KAAK,QAAQ;GAC3C,OAAO,KAAK,OAAO;GACnB,OAAO,KAAK;GACb;;;;;CAMH,WAAmB;EACjB,IAAI,MAAM,GAAG,KAAK,KAAK,IAAI,KAAK,KAAK,KAAK,KAAK;AAC/C,MAAI,KAAK,MACP,QAAO,gBAAgB,KAAK,MAAM,QAAQ;AAE5C,SAAO;;;;;CAMT,AAAQ,gBACN,SACqC;AACrC,MAAI,CAAC,QAAS,QAAO;EAErB,MAAM,YAAqC,EAAE;AAC7C,OAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,QAAQ,CAChD,KAAI,KAAK,iBAAiB,IAAI,CAC5B,WAAU,OAAO;WACR,OAAO,UAAU,YAAY,UAAU,KAEhD,WAAU,OAAO,MAAM,QAAQ,MAAM,GACjC,UAAU,MAAM,OAAO,MACvB;MAEJ,WAAU,OAAO;AAGrB,SAAO;;;;;CAMT,AAAQ,iBAAiB,WAA4B;AACnD,SAAO,yBAAyB,MAAM,YAAY,QAAQ,KAAK,UAAU,CAAC"}

package/dist/errors/identity-expired.d.ts

@@ -0,0 +1,14 @@
+import { AppKitError } from "./base.js";
+
+//#region src/errors/identity-expired.d.ts
+/** The downstream service rejected the active caller's credentials. */
+declare class IdentityExpiredError extends AppKitError {
+  readonly tokenFingerprint?: string | undefined;
+  readonly code = "IDENTITY_EXPIRED";
+  readonly statusCode = 401;
+  readonly isRetryable = false;
+  constructor(tokenFingerprint?: string | undefined);
+}
+//#endregion
+export { IdentityExpiredError };
+//# sourceMappingURL=identity-expired.d.ts.map

package/dist/errors/identity-expired.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-expired.d.ts","names":[],"sources":["../../src/errors/identity-expired.ts"],"mappings":";;;;cAGa,oBAAA,SAA6B,WAAA;EAAA,SAKnB,gBAAA;EAAA,SAJZ,IAAA;EAAA,SACA,UAAA;EAAA,SACA,WAAA;cAEY,gBAAA;AAAA"}

package/dist/errors/identity-expired.js

@@ -0,0 +1,33 @@
+import { AppKitError } from "./base.js";
+
+//#region src/errors/identity-expired.ts
+/** The downstream service rejected the active caller's credentials. */
+var IdentityExpiredError = class extends AppKitError {
+	code = "IDENTITY_EXPIRED";
+	statusCode = 401;
+	isRetryable = false;
+	constructor(tokenFingerprint) {
+		const message = "Caller credentials were rejected or expired. Reauthenticate and retry with a fresh user token.";
+		super(message, {
+			clientMessage: message,
+			context: { fingerprint: tokenFingerprint }
+		});
+		this.tokenFingerprint = tokenFingerprint;
+	}
+};
+/** Recognize structured HTTP failures, including connector cause wrappers. */
+function isUnauthorized(error) {
+	const seen = /* @__PURE__ */ new Set();
+	let current = error;
+	while (current && typeof current === "object" && !seen.has(current)) {
+		seen.add(current);
+		const value = current;
+		if (!(current instanceof AppKitError) && (value.status === 401 || value.statusCode === 401 || value.response?.status === 401)) return true;
+		current = value.cause;
+	}
+	return false;
+}
+
+//#endregion
+export { IdentityExpiredError, isUnauthorized };
+//# sourceMappingURL=identity-expired.js.map

package/dist/errors/identity-expired.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-expired.js","names":[],"sources":["../../src/errors/identity-expired.ts"],"sourcesContent":["import { AppKitError } from \"./base\";\n\n/** The downstream service rejected the active caller's credentials. */\nexport class IdentityExpiredError extends AppKitError {\n  readonly code = \"IDENTITY_EXPIRED\";\n  readonly statusCode = 401;\n  readonly isRetryable = false;\n\n  constructor(readonly tokenFingerprint?: string) {\n    const message =\n      \"Caller credentials were rejected or expired. Reauthenticate and retry with a fresh user token.\";\n    // Do not retain upstream errors: SDK errors may contain authorization headers.\n    super(message, {\n      clientMessage: message,\n      context: { fingerprint: tokenFingerprint },\n    });\n  }\n}\n\n/** Recognize structured HTTP failures, including connector cause wrappers. */\nexport function isUnauthorized(error: unknown): boolean {\n  const seen = new Set<object>();\n  let current = error;\n  while (current && typeof current === \"object\" && !seen.has(current)) {\n    seen.add(current);\n    const value = current as {\n      status?: unknown;\n      statusCode?: unknown;\n      response?: { status?: unknown };\n      cause?: unknown;\n    };\n    if (\n      !(current instanceof AppKitError) &&\n      (value.status === 401 ||\n        value.statusCode === 401 ||\n        value.response?.status === 401)\n    )\n      return true;\n    current = value.cause;\n  }\n  return false;\n}\n"],"mappings":";;;;AAGA,IAAa,uBAAb,cAA0C,YAAY;CACpD,AAAS,OAAO;CAChB,AAAS,aAAa;CACtB,AAAS,cAAc;CAEvB,YAAY,AAAS,kBAA2B;EAC9C,MAAM,UACJ;AAEF,QAAM,SAAS;GACb,eAAe;GACf,SAAS,EAAE,aAAa,kBAAkB;GAC3C,CAAC;EAPiB;;;;AAYvB,SAAgB,eAAe,OAAyB;CACtD,MAAM,uBAAO,IAAI,KAAa;CAC9B,IAAI,UAAU;AACd,QAAO,WAAW,OAAO,YAAY,YAAY,CAAC,KAAK,IAAI,QAAQ,EAAE;AACnE,OAAK,IAAI,QAAQ;EACjB,MAAM,QAAQ;AAMd,MACE,EAAE,mBAAmB,iBACpB,MAAM,WAAW,OAChB,MAAM,eAAe,OACrB,MAAM,UAAU,WAAW,KAE7B,QAAO;AACT,YAAU,MAAM;;AAElB,QAAO"}

package/dist/errors/index.js

@@ -1,5 +1,6 @@
 import { AppKitError } from "./base.js";
 import { AuthenticationError } from "./authentication.js";
+import { IdentityExpiredError } from "./identity-expired.js";
 import { ConfigurationError } from "./configuration.js";
 import { ConnectionError } from "./connection.js";
 import { DatabaseValidationError } from "./database-validation.js";

package/dist/index.d.ts

@@ -1,22 +1,24 @@
 import { StreamExecutionSettings } from "./shared/src/execute.js";
 import { ResourceFieldEntry } from "./shared/src/schemas/manifest.js";
-import { BasePluginConfig, IAppRouter, PluginData, ToPlugin } from "./shared/src/plugin.js";
+import { AppKitApi, BasePluginConfig, IAppRouter, PluginData, ScopedPluginMap, ToPlugin, UserScopedApp } from "./shared/src/plugin.js";
 import { CacheConfig } from "./shared/src/cache.js";
 import { isSQLTypeMarker, sql } from "./shared/src/sql/helpers.js";
 import { ApiError } from "./shared/src/workspace-client/errors.js";
 import { createWorkspaceClient } from "./shared/src/workspace-client/factory.js";
 import "./shared/src/index.js";
 import { WorkspaceClient, WorkspaceClientOptions } from "./workspace-client/index.js";
+import { UserContext, isUserContext } from "./context/user-context.js";
+import { ServiceContext } from "./context/service-context.js";
+import { CallerContext, CallerPrincipal, ExecutionContext } from "./context/caller-context.js";
+import { getCallerContext, getCurrentActorId, getCurrentPrincipalKey, getCurrentUserId, getExecutionContext, getUserContext, isInUserContext, runInCallerContext, runInUserContext } from "./context/execution-context.js";
+import "./context/index.js";
 import { DatabaseRegistry } from "./database/contract/registry.js";
 import { CacheManager } from "./cache/index.js";
 import { JobsConnectorConfig } from "./connectors/jobs/types.js";
 import "./connectors/jobs/index.js";
 import { LakebasePoolManager, createLakebasePoolManager } from "./connectors/lakebase/pool-manager.js";
-import { CallerContext, CallerPrincipal, ExecutionContext } from "./context/caller-context.js";
 import { LakebasePool } from "./connectors/lakebase/routing-pool.js";
 import { DatabaseCredential, GenerateDatabaseCredentialRequest, LakebasePoolConfig, RequestedClaims, RequestedClaimsPermissionSet, RequestedResource, createLakebasePool, generateDatabaseCredential, getLakebaseOrmConfig, getLakebasePgConfig, getUsernameWithApiLookup, getWorkspaceClient } from "./connectors/lakebase/index.js";
-import { getCurrentActorId, getCurrentPrincipalKey, getExecutionContext } from "./context/execution-context.js";
-import "./context/index.js";
 import { ITelemetry, TelemetryConfig } from "./telemetry/types.js";
 import { Counter, Histogram, SeverityNumber, Span, SpanStatusCode } from "./telemetry/index.js";
 import { createApp } from "./core/appkit.js";
@@ -27,6 +29,7 @@ import { getWarehouseId } from "./resources/warehouse.js";
 import "./resources/index.js";
 import { AppKitError } from "./errors/base.js";
 import { AuthenticationError } from "./errors/authentication.js";
+import { IdentityExpiredError } from "./errors/identity-expired.js";
 import { ConfigurationError } from "./errors/configuration.js";
 import { ConnectionError } from "./errors/connection.js";
 import { DatabaseValidationError, DatabaseValidationIssue } from "./errors/database-validation.js";
@@ -57,4 +60,4 @@ import "./plugins/ga-exports.generated.js";
 import { extractServingEndpoints, findServerFile } from "./type-generator/serving/server-file-extractor.js";
 import { appKitServingTypesPlugin } from "./type-generator/serving/vite-plugin.js";
 import { appKitTypesPlugin } from "./type-generator/vite-plugin.js";
-export { ApiError, AppKitError, AuthenticationError, type BasePluginConfig, type CacheConfig, CacheManager, type CallerContext, type CallerPrincipal, type ConfigSchema, ConfigurationError, ConnectionError, type Counter, type DatabaseCredential, type DatabaseRegistry, DatabaseValidationError, type DatabaseValidationIssue, type EndpointConfig, type ExecutionContext, ExecutionError, type ExecutionResult, type FileAction, type FilePolicy, type FilePolicyUser, type FileResource, type GenerateDatabaseCredentialRequest, type Histogram, type IAppRouter, type IJobsConfig, type ITelemetry, InitializationError, type JobAPI, type JobConfig, type JobsConnectorConfig, type JobsExport, type LakebasePool, type LakebasePoolConfig, type LakebasePoolManager, Plugin, type PluginData, type PluginManifest, PolicyDeniedError, READ_ACTIONS, type RequestedClaims, RequestedClaimsPermissionSet, type RequestedResource, type ResourceEntry, type ResourceFieldEntry, type ResourcePermission, ResourceRegistry, type ResourceRequirement, ResourceType, ServerError, type ServingEndpointEntry, type ServingEndpointRegistry, type ServingFactory, SeverityNumber, type Span, SpanStatusCode, type StreamExecutionSettings, type TelemetryConfig, type ToPlugin, TunnelError, ValidationError, type ValidationResult, WRITE_ACTIONS, type WorkspaceClient, type WorkspaceClientOptions, analytics, appKitServingTypesPlugin, appKitTypesPlugin, createApp, createLakebasePool, createLakebasePoolManager, createWorkspaceClient, defineManifest, extractServingEndpoints, files, findServerFile, generateDatabaseCredential, genie, getCurrentActorId, getCurrentPrincipalKey, getExecutionContext, getLakebaseOrmConfig, getLakebasePgConfig, getPluginManifest, getResourceRequirements, getUsernameWithApiLookup, getWarehouseId, getWorkspaceClient, isSQLTypeMarker, jobs, lakebase, server, serving, sql, toPlugin };
+export { ApiError, type AppKitApi, AppKitError, AuthenticationError, type BasePluginConfig, type CacheConfig, CacheManager, type CallerContext, type CallerPrincipal, type ConfigSchema, ConfigurationError, ConnectionError, type Counter, type DatabaseCredential, type DatabaseRegistry, DatabaseValidationError, type DatabaseValidationIssue, type EndpointConfig, type ExecutionContext, ExecutionError, type ExecutionResult, type FileAction, type FilePolicy, type FilePolicyUser, type FileResource, type GenerateDatabaseCredentialRequest, type Histogram, type IAppRouter, type IJobsConfig, type ITelemetry, IdentityExpiredError, InitializationError, type JobAPI, type JobConfig, type JobsConnectorConfig, type JobsExport, type LakebasePool, type LakebasePoolConfig, type LakebasePoolManager, Plugin, type PluginData, type PluginManifest, PolicyDeniedError, READ_ACTIONS, type RequestedClaims, RequestedClaimsPermissionSet, type RequestedResource, type ResourceEntry, type ResourceFieldEntry, type ResourcePermission, ResourceRegistry, type ResourceRequirement, ResourceType, type ScopedPluginMap, ServerError, ServiceContext, type ServingEndpointEntry, type ServingEndpointRegistry, type ServingFactory, SeverityNumber, type Span, SpanStatusCode, type StreamExecutionSettings, type TelemetryConfig, type ToPlugin, TunnelError, type UserContext, type UserScopedApp, ValidationError, type ValidationResult, WRITE_ACTIONS, type WorkspaceClient, type WorkspaceClientOptions, analytics, appKitServingTypesPlugin, appKitTypesPlugin, createApp, createLakebasePool, createLakebasePoolManager, createWorkspaceClient, defineManifest, extractServingEndpoints, files, findServerFile, generateDatabaseCredential, genie, getCallerContext, getCurrentActorId, getCurrentPrincipalKey, getCurrentUserId, getExecutionContext, getLakebaseOrmConfig, getLakebasePgConfig, getPluginManifest, getResourceRequirements, getUserContext, getUsernameWithApiLookup, getWarehouseId, getWorkspaceClient, isInUserContext, isSQLTypeMarker, isUserContext, jobs, lakebase, runInCallerContext, runInUserContext, server, serving, sql, toPlugin };

package/dist/index.js

@@ -3,6 +3,7 @@ import { ApiError } from "./shared/src/workspace-client/errors.js";
 import { createWorkspaceClient } from "./shared/src/workspace-client/factory.js";
 import { AppKitError } from "./errors/base.js";
 import { AuthenticationError } from "./errors/authentication.js";
+import { IdentityExpiredError } from "./errors/identity-expired.js";
 import { ConfigurationError } from "./errors/configuration.js";
 import { ConnectionError } from "./errors/connection.js";
 import { DatabaseValidationError } from "./errors/database-validation.js";
@@ -13,8 +14,10 @@ import { TunnelError } from "./errors/tunnel.js";
 import { ValidationError } from "./errors/validation.js";
 import "./errors/index.js";
 import { getWarehouseId } from "./resources/warehouse.js";
+import { isUserContext } from "./context/user-context.js";
+import { ServiceContext } from "./context/service-context.js";
 import { createLakebasePoolManager } from "./connectors/lakebase/pool-manager.js";
-import { getCurrentActorId, getCurrentPrincipalKey, getExecutionContext } from "./context/execution-context.js";
+import { getCallerContext, getCurrentActorId, getCurrentPrincipalKey, getCurrentUserId, getExecutionContext, getUserContext, isInUserContext, runInCallerContext, runInUserContext } from "./context/execution-context.js";
 import { RequestedClaimsPermissionSet, createLakebasePool, generateDatabaseCredential, getLakebaseOrmConfig, getLakebasePgConfig, getUsernameWithApiLookup, getWorkspaceClient } from "./connectors/lakebase/index.js";
 import { SeverityNumber, SpanStatusCode } from "./telemetry/index.js";
 import { CacheManager } from "./cache/index.js";
@@ -42,4 +45,4 @@ import { server } from "./plugins/server/index.js";
 import { serving } from "./plugins/serving/serving.js";
 import "./plugins/ga-exports.generated.js";
 
-export { ApiError, AppKitError, AuthenticationError, CacheManager, ConfigurationError, ConnectionError, DatabaseValidationError, ExecutionError, InitializationError, Plugin, PolicyDeniedError, READ_ACTIONS, RequestedClaimsPermissionSet, ResourceRegistry, ResourceType, ServerError, SeverityNumber, SpanStatusCode, TunnelError, ValidationError, WRITE_ACTIONS, analytics, appKitServingTypesPlugin, appKitTypesPlugin, createApp, createLakebasePool, createLakebasePoolManager, createWorkspaceClient, defineManifest, extractServingEndpoints, files, findServerFile, generateDatabaseCredential, genie, getCurrentActorId, getCurrentPrincipalKey, getExecutionContext, getLakebaseOrmConfig, getLakebasePgConfig, getPluginManifest, getResourceRequirements, getUsernameWithApiLookup, getWarehouseId, getWorkspaceClient, isSQLTypeMarker, jobs, lakebase, server, serving, sql, toPlugin };
+export { ApiError, AppKitError, AuthenticationError, CacheManager, ConfigurationError, ConnectionError, DatabaseValidationError, ExecutionError, IdentityExpiredError, InitializationError, Plugin, PolicyDeniedError, READ_ACTIONS, RequestedClaimsPermissionSet, ResourceRegistry, ResourceType, ServerError, ServiceContext, SeverityNumber, SpanStatusCode, TunnelError, ValidationError, WRITE_ACTIONS, analytics, appKitServingTypesPlugin, appKitTypesPlugin, createApp, createLakebasePool, createLakebasePoolManager, createWorkspaceClient, defineManifest, extractServingEndpoints, files, findServerFile, generateDatabaseCredential, genie, getCallerContext, getCurrentActorId, getCurrentPrincipalKey, getCurrentUserId, getExecutionContext, getLakebaseOrmConfig, getLakebasePgConfig, getPluginManifest, getResourceRequirements, getUserContext, getUsernameWithApiLookup, getWarehouseId, getWorkspaceClient, isInUserContext, isSQLTypeMarker, isUserContext, jobs, lakebase, runInCallerContext, runInUserContext, server, serving, sql, toPlugin };

package/dist/logging/logger.js

@@ -1,8 +1,8 @@
 import { DEFAULT_SAMPLING_CONFIG, shouldSample } from "./sampling.js";
 import { WideEvent } from "./wide-event.js";
 import { WideEventEmitter } from "./wide-event-emitter.js";
-import { AsyncLocalStorage } from "node:async_hooks";
 import { format } from "node:util";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { trace } from "@opentelemetry/api";
 import { createDebug } from "obug";
 

package/dist/plugin/execution-result.d.ts

@@ -1,3 +1,5 @@
+import { IdentityExpiredError } from "../errors/identity-expired.js";
+
 //#region src/plugin/execution-result.d.ts
 /**
  * Discriminated union for plugin execution results.
@@ -19,7 +21,8 @@ type ExecutionResult<T> = {
 } | {
   ok: false;
   status: number;
-  message: string;
+  message: string; /** Typed credential expiry without changing the existing failure envelope. */
+  error?: IdentityExpiredError;
 };
 //#endregion
 export { ExecutionResult };

package/dist/plugin/execution-result.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execution-result.d.ts","names":[],"sources":["../../src/plugin/execution-result.ts"],"mappings":";;AAcA;;;;;;;;;;;;;KAAY,eAAA;EACN,EAAA;EAAU,IAAA,EAAM,CAAA;AAAA;EAChB,EAAA;EAAW,MAAA;EAAgB,OAAA;AAAA"}
+{"version":3,"file":"execution-result.d.ts","names":[],"sources":["../../src/plugin/execution-result.ts"],"mappings":";;;;;AAgBA;;;;;;;;;;;;KAAY,eAAA;EACN,EAAA;EAAU,IAAA,EAAM,CAAA;AAAA;EAEhB,EAAA;EACA,MAAA;EACA,OAAA;EAEA,KAAA,GAAQ,oBAAA;AAAA"}