@databricks/appkit 0.83.0 → 0.84.0

package/docs/api/appkit.md

@@ -21,12 +21,14 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
 | [DatabaseValidationError](./docs/api/appkit/Class.DatabaseValidationError.md) | Deliberate validation failure raised by a database mutation hook. Generated routes answer `422` and echo only the issues naming a public column; every other failure raised inside a hook stays an opaque server error.                                        |
 | [DatabricksAdapter](./docs/api/appkit/Class.DatabricksAdapter.md)             | Adapter that talks directly to Databricks Model Serving `/invocations` endpoint.                                                                                                                                                                               |
 | [ExecutionError](./docs/api/appkit/Class.ExecutionError.md)                   | Error thrown when an operation execution fails. Use for statement failures, canceled operations, or unexpected states.                                                                                                                                         |
+| [IdentityExpiredError](./docs/api/appkit/Class.IdentityExpiredError.md)       | The downstream service rejected the active caller's credentials.                                                                                                                                                                                               |
 | [InitializationError](./docs/api/appkit/Class.InitializationError.md)         | Error thrown when a service or component is not properly initialized. Use when accessing services before they are ready.                                                                                                                                       |
 | [MlflowClient](./docs/api/appkit/Class.MlflowClient.md)                       | A thin client over the Databricks workspace REST API, owning the host + bearer token so callers (eval-run creation, assessment writes, the judge's serving endpoint) don't each re-derive URLs or re-attach auth. The host is normalized once at construction. |
 | [Plugin](./docs/api/appkit/Class.Plugin.md)                                   | Base abstract class for creating AppKit plugins.                                                                                                                                                                                                               |
 | [PolicyDeniedError](./docs/api/appkit/Class.PolicyDeniedError.md)             | Thrown when a policy denies an action.                                                                                                                                                                                                                         |
 | [ResourceRegistry](./docs/api/appkit/Class.ResourceRegistry.md)               | Central registry for tracking plugin resource requirements. Deduplication uses type + resourceKey (machine-stable); alias is for display only.                                                                                                                 |
 | [ServerError](./docs/api/appkit/Class.ServerError.md)                         | Error thrown when server lifecycle operations fail. Use for server start/stop issues, configuration conflicts, etc.                                                                                                                                            |
+| [ServiceContext](./docs/api/appkit/Class.ServiceContext.md)                   | ServiceContext is a singleton that manages the service principal's WorkspaceClient and workspace ID. WarehouseResource owns warehouse bindings.                                                                                                                |
 | [SupervisorApiAdapter](./docs/api/appkit/Class.SupervisorApiAdapter.md)       | Adapter that calls the Databricks AI Gateway Responses API (`/ai-gateway/mlflow/v1/responses`).                                                                                                                                                                |
 | [TunnelError](./docs/api/appkit/Class.TunnelError.md)                         | Error thrown when remote tunnel operations fail. Use for tunnel connection issues, message parsing failures, etc.                                                                                                                                              |
 | [ValidationError](./docs/api/appkit/Class.ValidationError.md)                 | Error thrown when input validation fails. Use for invalid parameters, missing required fields, or type mismatches.                                                                                                                                             |
@@ -135,10 +137,12 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
 
 | Type Alias                                                                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [AgentAuth](./docs/api/appkit/TypeAlias.AgentAuth.md)                                 | Identity an agent runs under. The only value is on-behalf-of-user.                                                                                                                                                                                                                                                                                                                                                                                         |
 | [AgentEvent](./docs/api/appkit/TypeAlias.AgentEvent.md)                               | -                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | [AgentTool](./docs/api/appkit/TypeAlias.AgentTool.md)                                 | Any tool an agent can invoke: inline function tools (`tool()`), hosted MCP tools (`mcpServer()` / raw hosted), toolkit references from plugins (`analytics().toolkit()`), or adapter-hosted Supervisor-API tools (`supervisorTools.*`).                                                                                                                                                                                                                    |
 | [AgentTools](./docs/api/appkit/TypeAlias.AgentTools.md)                               | Per-agent tool record. String keys map to inline tools, toolkit entries, hosted tools, etc.                                                                                                                                                                                                                                                                                                                                                                |
 | [AgentToolsFn](./docs/api/appkit/TypeAlias.AgentToolsFn.md)                           | Function form of `AgentDefinition.tools`. Receives the typed [Plugins](./docs/api/appkit/TypeAlias.Plugins.md) map and returns a tool record. Invoked exactly once at setup (or once per `runAgent` call in standalone mode); the result is cached as the agent's resolved tool record.                                                                                                                                                              |
+| [AppKitApi](./docs/api/appkit/TypeAlias.AppKitApi.md)                                 | App instance with plugin exports and an explicit caller-scoped entry point.                                                                                                                                                                                                                                                                                                                                                                                |
 | [BaseSystemPromptOption](./docs/api/appkit/TypeAlias.BaseSystemPromptOption.md)       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | [CallerPrincipal](./docs/api/appkit/TypeAlias.CallerPrincipal.md)                     | The caller identity whose permissions authorize execution, not its resources.                                                                                                                                                                                                                                                                                                                                                                              |
 | [ConfigSchema](./docs/api/appkit/TypeAlias.ConfigSchema.md)                           | Configuration schema definition for plugin config. Re-exported from the standard JSON Schema Draft 7 types.                                                                                                                                                                                                                                                                                                                                                |
@@ -163,6 +167,7 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
 | [ResolvedToolEntry](./docs/api/appkit/TypeAlias.ResolvedToolEntry.md)                 | Internal tool-index entry after a tool record has been resolved to a dispatchable form.                                                                                                                                                                                                                                                                                                                                                                    |
 | [ResourceFieldEntry](./docs/api/appkit/TypeAlias.ResourceFieldEntry.md)               | -                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | [ResourcePermission](./docs/api/appkit/TypeAlias.ResourcePermission.md)               | Union of all possible permission levels across all resource types.                                                                                                                                                                                                                                                                                                                                                                                         |
+| [ScopedPluginMap](./docs/api/appkit/TypeAlias.ScopedPluginMap.md)                     | -                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | [SearchFilters](./docs/api/appkit/TypeAlias.SearchFilters.md)                         | -                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | [ServingFactory](./docs/api/appkit/TypeAlias.ServingFactory.md)                       | Factory function returned by `AppKit.serving`.                                                                                                                                                                                                                                                                                                                                                                                                             |
 | [Severity](./docs/api/appkit/TypeAlias.Severity.md)                                   | Whether an assertion fails the eval (`gate`) or is tracked only (`soft`).                                                                                                                                                                                                                                                                                                                                                                                  |
@@ -170,6 +175,8 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
 | [ToolRegistry](./docs/api/appkit/TypeAlias.ToolRegistry.md)                           | -                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | [ToPlugin](./docs/api/appkit/TypeAlias.ToPlugin.md)                                   | Factory function type returned by `toPlugin()`. Accepts optional config and returns a PluginData tuple.                                                                                                                                                                                                                                                                                                                                                    |
 | [TransactionClient](./docs/api/appkit/TypeAlias.TransactionClient.md)                 | Entity and SQL capabilities bound to one transaction.                                                                                                                                                                                                                                                                                                                                                                                                      |
+| [~~UserContext~~](./docs/api/appkit/TypeAlias.UserContext.md)                         | -                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| [UserScopedApp](./docs/api/appkit/TypeAlias.UserScopedApp.md)                         | -                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 
 ## Variables[​](#variables "Direct link to Variables")
 
@@ -226,13 +233,16 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
 | [fromSupervisorApi](./docs/api/appkit/Function.fromSupervisorApi.md)                   | Creates an [AgentAdapter](./docs/api/appkit/Interface.AgentAdapter.md) backed by the Databricks AI Gateway Responses API (`/ai-gateway/mlflow/v1/responses`).                                                                                                                                                                                                                                        |
 | [functionToolToDefinition](./docs/api/appkit/Function.functionToolToDefinition.md)     | -                                                                                                                                                                                                                                                                                                                                                                                                          |
 | [generateDatabaseCredential](./docs/api/appkit/Function.generateDatabaseCredential.md) | Generate OAuth credentials for Postgres database connection using the proper Postgres API.                                                                                                                                                                                                                                                                                                                 |
+| [getCallerContext](./docs/api/appkit/Function.getCallerContext.md)                     | Get the caller context if one is active, otherwise `undefined`. Unlike `getExecutionContext()`, this does not require `ServiceContext` to be initialized and never throws.                                                                                                                                                                                                                                 |
 | [getCurrentActorId](./docs/api/appkit/Function.getCurrentActorId.md)                   | The initiating user in a caller scope; no user actor exists in service scope.                                                                                                                                                                                                                                                                                                                              |
 | [getCurrentPrincipalKey](./docs/api/appkit/Function.getCurrentPrincipalKey.md)         | Get the principal key for future cache keying: `app` or `user:<id>`.                                                                                                                                                                                                                                                                                                                                       |
+| [~~getCurrentUserId~~](./docs/api/appkit/Function.getCurrentUserId.md)                 | -                                                                                                                                                                                                                                                                                                                                                                                                          |
 | [getExecutionContext](./docs/api/appkit/Function.getExecutionContext.md)               | Get the current execution context.                                                                                                                                                                                                                                                                                                                                                                         |
 | [getLakebaseOrmConfig](./docs/api/appkit/Function.getLakebaseOrmConfig.md)             | Get Lakebase connection configuration for ORMs that don't accept pg.Pool directly.                                                                                                                                                                                                                                                                                                                         |
 | [getLakebasePgConfig](./docs/api/appkit/Function.getLakebasePgConfig.md)               | Get Lakebase connection configuration for PostgreSQL clients.                                                                                                                                                                                                                                                                                                                                              |
 | [getPluginManifest](./docs/api/appkit/Function.getPluginManifest.md)                   | Loads and validates the manifest from a plugin constructor. Normalizes string type/permission to strict ResourceType/ResourcePermission.                                                                                                                                                                                                                                                                   |
 | [getResourceRequirements](./docs/api/appkit/Function.getResourceRequirements.md)       | Gets the resource requirements from a plugin's manifest.                                                                                                                                                                                                                                                                                                                                                   |
+| [~~getUserContext~~](./docs/api/appkit/Function.getUserContext.md)                     | -                                                                                                                                                                                                                                                                                                                                                                                                          |
 | [getUsernameWithApiLookup](./docs/api/appkit/Function.getUsernameWithApiLookup.md)     | Resolves the PostgreSQL username for a Lakebase connection.                                                                                                                                                                                                                                                                                                                                                |
 | [getWarehouseId](./docs/api/appkit/Function.getWarehouseId.md)                         | Get the configured SQL warehouse ID after app initialization. The warehouse is an app resource; SP and caller executions use the same binding. Deprecated user-context scopes retain support for explicit warehouse overrides.                                                                                                                                                                             |
 | [getWorkspaceClient](./docs/api/appkit/Function.getWorkspaceClient.md)                 | Get workspace client from config or SDK default auth chain                                                                                                                                                                                                                                                                                                                                                 |
@@ -241,10 +251,12 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
 | [integer](./docs/api/appkit/Function.integer.md)                                       | -                                                                                                                                                                                                                                                                                                                                                                                                          |
 | [isFunctionTool](./docs/api/appkit/Function.isFunctionTool.md)                         | -                                                                                                                                                                                                                                                                                                                                                                                                          |
 | [isHostedTool](./docs/api/appkit/Function.isHostedTool.md)                             | -                                                                                                                                                                                                                                                                                                                                                                                                          |
+| [isInUserContext](./docs/api/appkit/Function.isInUserContext.md)                       | Check if currently running in a user context.                                                                                                                                                                                                                                                                                                                                                              |
 | [isJudgeConfigured](./docs/api/appkit/Function.isJudgeConfigured.md)                   | -                                                                                                                                                                                                                                                                                                                                                                                                          |
 | [isSQLTypeMarker](./docs/api/appkit/Function.isSQLTypeMarker.md)                       | Type guard to check if a value is a SQL type marker                                                                                                                                                                                                                                                                                                                                                        |
 | [isSupervisorTool](./docs/api/appkit/Function.isSupervisorTool.md)                     | Type guard for [HostedSupervisorTool](./docs/api/appkit/Interface.HostedSupervisorTool.md). Used by the agents plugin (`buildToolIndex`) and standalone `runAgent` (`classifyTool`) to route supervisor-hosted tools to the extensions payload rather than the adapter's `tools` array.                                                                                                              |
 | [isToolkitEntry](./docs/api/appkit/Function.isToolkitEntry.md)                         | Type guard for `ToolkitEntry` — used by the agents plugin to differentiate toolkit references from inline tools in a mixed `tools` record.                                                                                                                                                                                                                                                                 |
+| [~~isUserContext~~](./docs/api/appkit/Function.isUserContext.md)                       | -                                                                                                                                                                                                                                                                                                                                                                                                          |
 | [jsonb](./docs/api/appkit/Function.jsonb.md)                                           | -                                                                                                                                                                                                                                                                                                                                                                                                          |
 | [loadAgentFromFile](./docs/api/appkit/Function.loadAgentFromFile.md)                   | Loads a single markdown agent file and resolves its frontmatter against registered plugin toolkits + ambient tool library.                                                                                                                                                                                                                                                                                 |
 | [loadAgentsFromDir](./docs/api/appkit/Function.loadAgentsFromDir.md)                   | Scans a directory for one subdirectory per agent, each containing `agent.md` (frontmatter + body). Produces an `AgentDefinition` record keyed by agent id (folder name). Throws on frontmatter errors or unresolved references. Returns an empty map if the directory does not exist.                                                                                                                      |
@@ -261,6 +273,8 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
 | [runAgent](./docs/api/appkit/Function.runAgent.md)                                     | Standalone agent execution without `createApp`. Resolves the adapter, binds inline tools, and drives the adapter's `run()` loop to completion.                                                                                                                                                                                                                                                             |
 | [runEval](./docs/api/appkit/Function.runEval.md)                                       | Run a single eval against a driver. Never throws for assertion or agent failures — those become a non-passing [EvalResult](./docs/api/appkit/Interface.EvalResult.md). Only a malformed eval definition surfaces as `result.error`.                                                                                                                                                                  |
 | [runEvalsInDir](./docs/api/appkit/Function.runEvalsInDir.md)                           | Discover, load, and run every eval under each agent's `evals/` dir, driving the agents on a running app. Never throws for an individual eval — load/run failures become non-passing [EvalResult](./docs/api/appkit/Interface.EvalResult.md)s.                                                                                                                                                        |
+| [runInCallerContext](./docs/api/appkit/Function.runInCallerContext.md)                 | Run a function with an immutable snapshot of the caller context. Nested and concurrent scopes keep their own identities.                                                                                                                                                                                                                                                                                   |
+| [~~runInUserContext~~](./docs/api/appkit/Function.runInUserContext.md)                 | -                                                                                                                                                                                                                                                                                                                                                                                                          |
 | [runWithRetries](./docs/api/appkit/Function.runWithRetries.md)                         | Run `attempt` up to `1 + retries` times, stopping as soon as it returns a result that is neither a thrown error / per-eval timeout (`error`) nor a transport/agent turn failure (`infraFailure`). Assertion failures set neither, so a failed-but-completed eval is returned on the first try and never retried. Returns the last result when every attempt failed on infra.                               |
 | [summarize](./docs/api/appkit/Function.summarize.md)                                   | -                                                                                                                                                                                                                                                                                                                                                                                                          |
 | [text](./docs/api/appkit/Function.text.md)                                             | -                                                                                                                                                                                                                                                                                                                                                                                                          |

package/docs/plugins/agents.md

@@ -326,6 +326,49 @@ const result = await runAgent(classifier, {
 
 MCP hosted tools (`mcpServer(...)`) still require `agents()` (they need a live MCP client). Supervisor-API hosted tools (`supervisorTools.*`), by contrast, **work in standalone `runAgent`** — the adapter has everything it needs to execute them server-side. This makes batch-eval / CI use of supervisor agents possible without `createApp`. Plugin tool dispatch in standalone mode runs as the service principal (no OBO) and **bypasses the agents-plugin approval gate** — treat standalone runAgent as a trusted-prompt environment (CI, batch eval, internal scripts), not as an exposed user-facing surface.
 
+## Execution identity[​](#execution-identity "Direct link to Execution identity")
+
+By default an agent runs **mixed**: the model call and hand-rolled `tool({ execute })` tools run as the app's service principal, and plugin-toolkit tools run as the requesting user. Set `auth: "on-behalf-of-user"` to run the whole agent as the user:
+
+```ts
+agents({ auth: "on-behalf-of-user" });                      // default for every agent
+createAgent({ instructions: "...", auth: "on-behalf-of-user" }); // one agent
+
+```
+
+In markdown, set `auth: on-behalf-of-user` in the frontmatter. A per-agent value overrides the plugin default. Omitting `auth` keeps the mixed behavior; there is no all-service-principal mode.
+
+| Piece                           | Default (mixed)                                             | `on-behalf-of-user`                                                   |
+| ------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------- |
+| Model call                      | service principal                                           | user                                                                  |
+| Plugin-toolkit tools            | user                                                        | user                                                                  |
+| Hand-rolled `tool({ execute })` | service principal                                           | user                                                                  |
+| Sub-agents                      | own mode                                                    | own mode, never service principal                                     |
+| Standalone `runAgent`           | service principal, or user tools with `caller`              | requires `caller` (or an ambient user scope); model and tools as user |
+| MLflow tracing                  | service principal                                           | service principal (exception)                                         |
+| Thread store                    | service principal                                           | service principal (exception)                                         |
+| Catalog skills volume           | service principal                                           | service principal (exception)                                         |
+| Missing user token              | plugin tools reject; the rest runs as the service principal | the request is rejected with 401 before any model or tool call        |
+
+An on-behalf-of-user agent fails closed:
+
+* No forwarded user token: `401` before any model or tool call, in production and in development. There is no service-principal fallback.
+* A `401` from the model mid-run becomes an `IDENTITY_EXPIRED` error event and the stream ends. The run is not retried as the service principal.
+* A sub-agent never widens: under an on-behalf-of-user parent, a mixed sub-agent also runs as the user.
+
+**Exceptions.** MLflow tracing, the thread store, and catalog skills (see [Catalog skills](#catalog-skills-unity-catalog-volume)) are app-owned and stay service principal in every mode. Thread rows are keyed by the user id.
+
+**Pre-built adapters.** The user's client is applied when AppKit builds the adapter from a model string (`model: "my-endpoint"`, `defaultModel`, or `DATABRICKS_SERVING_ENDPOINT_NAME`). If you build a `DatabricksAdapter` yourself with a fixed `workspaceClient`, an on-behalf-of-user agent throws at boot instead of running the model as the service principal. Pass a provider so the client resolves per call, or use a model string. Mixed agents accept fixed-client adapters as before:
+
+```ts
+DatabricksAdapter.fromModelServing("my-endpoint", {
+  workspaceClient: () => getWorkspaceClient(),
+});
+
+```
+
+**Provisioning.** Each user needs the `model-serving` user API scope on the app, and `CAN_QUERY` on any custom serving endpoint the agent calls. Plugin tools still need their own scopes and grants as in mixed mode.
+
 ## Adding agents to an existing app[​](#adding-agents-to-an-existing-app "Direct link to Adding agents to an existing app")
 
 Already have an app and want to add agents? What you touch depends on the kind:
@@ -492,6 +535,7 @@ agents({
   agents?: Record<string, AgentDefinition>,  // DEPRECATED — use server/agents/<id>/ discovery
   defaultAgent?: string,
   defaultModel?: AgentAdapter | Promise<AgentAdapter> | string,
+  auth?: "on-behalf-of-user",  // default: mixed (see Execution identity)
   tools?: Record<string, AgentTool>,
   autoInheritTools?: boolean | { file?: boolean, code?: boolean },
   autoInheritSkills?: boolean | { file?: boolean, code?: boolean }, // default off
@@ -956,6 +1000,7 @@ Skip `--experiment` (and `MLFLOW_EXPERIMENT_ID`) to run evals purely locally wit
 | `maxTokens`        | number          | Adapter max-token hint.                                                                                                                                                                                                                                                                         |
 | `generationParams` | object          | Adapter generation params (e.g. `temperature`, `top_p`) passed through when AppKit builds the adapter.                                                                                                                                                                                          |
 | `baseSystemPrompt` | false \| string | Per-agent override. `false` disables the AppKit base prompt.                                                                                                                                                                                                                                    |
+| `auth`             | string          | `on-behalf-of-user` runs this agent as the user. Any other value throws at boot. See [Execution identity](#execution-identity).                                                                                                                                                                 |
 | `ephemeral`        | boolean         | If `true`, the thread created for a chat request against this agent is deleted from `ThreadStore` after the stream finishes. Use for stateless one-shot agents (e.g. autocomplete) so history does not accumulate or contaminate future calls. Defaults to `false`.                             |
 
 Unknown keys are logged and ignored. Invalid YAML and missing plugin/tool references throw at boot.

package/docs/plugins/execution-context.md

@@ -1,78 +1,129 @@
 # Execution context
 
-AppKit manages Databricks authentication via two contexts:
+AppKit uses the service principal by default. Open a caller scope when an operation should use the requesting user's Databricks permissions.
 
-* **ServiceContext** (singleton): Initialized at app startup with service principal credentials
-* **ExecutionContext**: Determined at runtime - either service principal or user context
+## User-scoped operations[​](#user-scoped-operations "Direct link to User-scoped operations")
 
-## Headers for user context[​](#headers-for-user-context "Direct link to Headers for user context")
+Prefer a scope block for handlers that perform multiple operations:
 
-* `x-forwarded-user`: required in production; identifies the user
-* `x-forwarded-access-token`: required for user token passthrough
+```ts
+const result = await appkit.asUser(req).run(async (kit) => {
+  const orders = await kit.analytics.query("orders");
+  return orders;
+});
 
-## Using `asUser(req)` for user-scoped operations[​](#using-asuserreq-for-user-scoped-operations "Direct link to using-asuserreq-for-user-scoped-operations")
+// Shorthand for one operation:
+await appkit.asUser(req).analytics.query("orders");
 
-The `asUser(req)` pattern allows plugins to execute operations using the requesting user's credentials:
+// With no caller scope, a plain call uses the service principal:
+await appkit.analytics.query("metrics");
 
-```ts
-// In a custom plugin route handler
-router.post("/users/me/data", async (req, res) => {
-  // Execute as the user (uses their Databricks permissions)
-  const result = await this.asUser(req).query("SELECT ...");
-  res.json(result);
-});
+```
+
+One immutable caller context is shared by the block and its plugin handles. Nested operations, tools, and plain app handles used inside the block inherit that context. Async work and lazy stream consumption preserve the caller. There is no public `asApp()` and scoped handles cannot chain another `asUser()`. Group principals are deferred.
+
+The Apps proxy supplies `x-forwarded-access-token` and `x-forwarded-user`, both required in production. `x-forwarded-email` is optional. Only trust these headers behind the authenticated Apps proxy or your own trusted authentication boundary.
+
+`plugin.asUser(req)` remains available with a one-time deprecation warning. New code should use `appkit.asUser(req)`.
+
+## Tools and agents[​](#tools-and-agents "Direct link to Tools and agents")
+
+`PluginContext.executeTool` inherits an existing caller scope. Without one, it establishes user scope from the request, preserving the original fail-closed OBO default. Missing credentials reject before the provider executes. An existing caller takes precedence over conflicting or absent request credentials.
+
+On the agents HTTP execution routes (`/invocations`, `/responses`, and `/api/agents/chat`), each plugin-toolkit tool call runs in user scope through `executeTool`, including tool calls made by sub-agents. A plugin tool call without usable user credentials rejects; it never runs as the service principal. The marked development fallback below is the only missing-token exception. The agent's model call and hand-rolled tools are not wrapped in user scope.
+
+## Which built-in surfaces run as the user[​](#which-built-in-surfaces-run-as-the-user "Direct link to Which built-in surfaces run as the user")
+
+The default is the **service principal**. Work runs on behalf of the user only inside a caller scope: `appkit.asUser(req)`, a route that opens one, or a query file that selects the user lane. There is no global "OBO everywhere" mode, so identity is decided per surface:
+
+| Surface                                                         | Runs as                          | Why                                                                                                          |
+| --------------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Genie routes                                                    | signed-in user (OBO)             | the built-in route runs every call in user scope                                                             |
+| Serving plugin (deprecated) routes                              | signed-in user (OBO)             | the built-in route runs every call in user scope; prefer the agents plugin                                   |
+| Analytics `.obo.sql` queries                                    | signed-in user (OBO)             | the `.obo.sql` file name selects the user lane                                                               |
+| Analytics `.sql` queries, Files, and other plugin calls         | app service principal            | user only inside `appkit.asUser(req)`, or for Files volumes configured with `auth: "on-behalf-of-user"`      |
+| Agents HTTP routes: the model (LLM) call                        | app service principal            | the model adapter builds its own service-principal client, and the route does not open user scope            |
+| Agents HTTP routes: plugin-toolkit tool calls (`plugin:<name>`) | signed-in user (OBO)             | `executeTool` opens user scope for each call; without user credentials the call rejects                      |
+| Agents HTTP routes: hand-rolled `tool({ execute })`             | app service principal            | `execute` receives only the validated arguments and runs in the app context, as before                       |
+| Standalone `runAgent` (no HTTP request)                         | app service principal by default | there is no request, so no user scope unless you pass `caller` (see [Standalone agents](#standalone-agents)) |
+
+So an agent's **model inference runs as the service principal**, while the tools it calls over the built-in HTTP routes run on behalf of the user. See the [agents plugin](./docs/plugins/agents.md) for the tool-level detail.
+
+## Context helpers and cache isolation[​](#context-helpers-and-cache-isolation "Direct link to Context helpers and cache isolation")
+
+Exported from `@databricks/appkit`:
+
+* `getCurrentPrincipalKey()`: `app` or `user:<id>`, used to partition cache entries.
+* `getCurrentActorId()`: initiating user ID, when available, for audit and telemetry.
+* `getWorkspaceClient()`: workspace client for the current execution.
+* `getWarehouseId()`: resource configuration, separate from execution identity.
+* `getWorkspaceId()`: workspace ID as a promise.
+
+The old context helpers remain as deprecated compatibility aliases. Cache keys now include the principal namespace even when an explicit legacy user key is supplied. Existing stored entries will have a cold miss after upgrading; users and SP continue to have separate cache entries and in-flight work.
+
+## Standalone agents[​](#standalone-agents "Direct link to Standalone agents")
+
+Standalone `runAgent` can opt into user execution without an HTTP request:
 
-// Service principal execution (default)
-router.post("/system/data", async (req, res) => {
-  const result = await this.query("SELECT ...");
-  res.json(result);
+```ts
+await runAgent(agent, {
+  messages: "Summarize my data",
+  caller: {
+    token: userToken,
+    principal: { type: "user", userId },
+    host: "https://your-workspace.cloud.databricks.com",
+    workspaceId,
+  },
 });
 
 ```
 
-## Which built-in surfaces run OBO vs service principal[​](#which-built-in-surfaces-run-obo-vs-service-principal "Direct link to Which built-in surfaces run OBO vs service principal")
+Get credentials through a trusted authentication flow, never from model output. The caller applies to plugin initialization, model adapters, tools, and nested agents. Omitting it inherits an existing caller scope or defaults to SP. Invalid explicit credentials reject even in development. No service context or CLI profile is initialized implicitly. Standalone execution still has no approval gate and is intended for trusted scripts and evaluations.
 
-The default is the **service principal**: an operation runs on behalf of the user only when it goes through `asUser(req)`, which needs the forwarded user token. There is no global "OBO everywhere" mode, so identity is decided per surface:
+## Development fallback[​](#development-fallback "Direct link to Development fallback")
 
-| Surface                                                     | Runs as               | Why                                                                                                                |
-| ----------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| Genie routes                                                | signed-in user (OBO)  | the built-in route calls `asUser(req)` automatically                                                               |
-| Files / Analytics ops via `asUser(req)`                     | signed-in user (OBO)  | service principal by default; OBO only when you wrap the call in `asUser(req)`                                     |
-| Agents plugin `/chat` — the model (LLM) call                | app service principal | the chat route does not call `asUser`, and the model adapter is built at startup with the service-principal client |
-| Agents plugin — plugin-toolkit tool calls (`plugin:<name>`) | signed-in user (OBO)  | dispatched through `asUser(req)` per call                                                                          |
-| Agents plugin — hand-rolled `tool({ execute })`             | app service principal | receives only tool arguments, no `req`, so it can't opt into OBO                                                   |
-| Standalone `runAgent` (no HTTP request)                     | app service principal | no request context, so neither the model nor any tool runs OBO                                                     |
-| Serving plugin (deprecated) routes                          | signed-in user (OBO)  | the built-in route calls `asUser(req)`; prefer the agents plugin                                                   |
+With `NODE_ENV=development`, `asUser(req)` without a token logs a warning and runs with default app credentials, marked `DEV_OBO_FALLBACK`. If a caller scope is already open, fallback retains it instead of widening to SP. The marker does not leak outside the scope. Production never falls back when credentials are missing.
 
-So an agent's **model inference runs as the service principal**; only the plugin tools it calls over the built-in HTTP routes run on behalf of the user. See the [agents plugin](./docs/plugins/agents.md) for the tool-level detail.
+## App-only resources and missing credentials[​](#app-only-resources-and-missing-credentials "Direct link to App-only resources and missing credentials")
 
-## Context helper functions[​](#context-helper-functions "Direct link to Context helper functions")
+The manifest capability contract keeps `secret`, `database`, and `postgres` app-only for the new `appkit.asUser` and `runInCallerContext` APIs. Accessing those resources through these caller-scoped plugin APIs or tools raises a clear error identifying the resource by its manifest alias, or its type when no alias is available. The message states that the resource is app-only in this version of AppKit and does not support OBO execution through these APIs. The check applies when using cached handles inside a later user scope too. It does not reject unrelated plugins merely because an app-only plugin is installed. Required resources, runtime requirements, and configured optional resources determine the plugin's resource capability.
 
-Exported from `@databricks/appkit`:
+Deprecated `plugin.asUser` and `runInUserContext`, direct request-based tool dispatch, and the existing agents HTTP routes retain their established resource behavior, including Lakebase per-user routing. They still establish user identity and reject missing production credentials; they never fall back to SP by omission. Using a deprecated entry point inside a new guarded scope cannot disable its guards.
 
-* `getCurrentUserId()`: Returns user ID in user context, service user ID otherwise
-* `getWorkspaceClient()`: Returns the appropriate WorkspaceClient for current context
-* `getWarehouseId()`: `Promise<string>` (from `DATABRICKS_WAREHOUSE_ID` or auto-selected in dev)
-* `getWorkspaceId()`: `Promise<string>` (from `DATABRICKS_WORKSPACE_ID` or fetched)
+Missing-token messages distinguish OBO-capable resources from generic operations. For an OBO-capable resource, the message explains that no user token was forwarded and the app may be deployed service-principal-only. Otherwise the generic missing user token error remains. The app-level check uses the registered plugins' active resource metadata because no individual plugin has been selected yet.
 
-## Telemetry span attributes[​](#telemetry-span-attributes "Direct link to Telemetry span attributes")
+## Credential expiration and telemetry[​](#credential-expiration-and-telemetry "Direct link to Credential expiration and telemetry")
 
-The `plugin.execute` span created by the execution interceptor chain includes these attributes:
+A structured downstream HTTP 401 inside a caller scope throws `IdentityExpiredError` with code `IDENTITY_EXPIRED`. It includes the existing token fingerprint, not the token or upstream credential-bearing error. Obtain fresh user credentials before retrying. Non-401 failures and SP execution keep their existing behavior. Plugin `execute()` preserves its failed-result envelope and adds the typed error in the optional `error` field; SSE streams expose `IDENTITY_EXPIRED` in the error payload's `errorCode` field.
 
-| Attribute                    | Type                    | Description                                                                        |
-| ---------------------------- | ----------------------- | ---------------------------------------------------------------------------------- |
-| `execution.context`          | `"user"` \| `"service"` | Whether the operation runs as a user (OBO) or service principal                    |
-| `caller.id`                  | `string`                | The user ID (OBO) or service principal ID                                          |
-| `execution.obo_dev_fallback` | `boolean`               | Set to `true` when an OBO call falls back to service principal in development mode |
+AppKit-managed spans include `appkit.execution.principal` (`app` or `user`) and `appkit.execution.principal_id` (user or SP ID, or `app` before initialization). `appkit.execution.actor_id` is present when an initiating user exists. Tokens are never attached to these attributes.
 
-These attributes are automatically added when your plugin uses `execute()` or `executeStream()`. All built-in plugins use these methods for their OBO operations. Custom plugins should do the same to get automatic telemetry instrumentation.
+## Real user execution locally[​](#real-user-execution-locally "Direct link to Real user execution locally")
 
-## Lakebase per-user connections[​](#lakebase-per-user-connections "Direct link to Lakebase per-user connections")
+Set `DATABRICKS_TOKEN` and `DATABRICKS_HOST` in the app's `.env` to use a user token directly:
 
-The Lakebase plugin uses a different mechanism for `asUser(req)`: instead of swapping the `WorkspaceClient` via AsyncLocalStorage, it creates a **separate `pg.Pool` per user**, each with its own OAuth token refresh. This is necessary because PostgreSQL connections are authenticated at connection time — the pool itself is the authentication boundary.
+```dotenv
+DATABRICKS_HOST=https://your-workspace.cloud.databricks.com
+DATABRICKS_TOKEN=your-user-token
+
+```
+
+When `DATABRICKS_TOKEN` is present, it takes precedence. AppKit uses it directly and resolves the user ID from the configured host. Otherwise, set `DATABRICKS_CONFIG_PROFILE` to an authenticated user profile for the same workspace as the app. The generated template already sets the profile when you choose one during scaffolding:
+
+```dotenv
+DATABRICKS_CONFIG_PROFILE=your-user-profile
+
+```
+
+Then run your usual command:
+
+```sh
+npm run dev
+
+```
 
-See [Lakebase plugin — per-user connections](./docs/plugins/lakebase.md#on-behalf-of-obo--per-user-connections) for details.
+Open the app's normal localhost URL. In development, the server automatically adds `x-forwarded-access-token`, `x-forwarded-user`, and optional email headers before plugin routes and custom routes run. No separate proxy, target, or port is needed. `asUser(req)` uses that user identity. Unscoped operations still use the app's configured credentials; injecting headers does not open a caller scope. For a genuine SP-versus-user comparison, the app credentials must belong to an SP, not the same user profile.
 
-## Development mode behavior[​](#development-mode-behavior "Direct link to Development mode behavior")
+Credentials stay in memory and refresh after 30 seconds of use. Initial auth and refresh failures return 401, never a silent SP fallback. Existing forwarded user tokens are preserved. Automatic injection runs only in `NODE_ENV=development` and only for same-origin loopback requests, including `localhost`. Use it only with a trusted local app. It emulates user credentials, not platform consent, scope enforcement, or resource provisioning.
 
-In local development (`NODE_ENV=development`), if `asUser(req)` is called without a user token, it logs a warning and skips user impersonation — the operation runs with the default credentials configured for the app instead. The telemetry span will show `execution.context: "service"` with `execution.obo_dev_fallback: true` to distinguish these from regular service principal calls.
+Set `APPKIT_DEV_OBO=false` in `.env` to disable automatic injection. Without a configured token or profile, injection is also disabled. Tokenless `asUser(req)` then keeps the existing `DEV_OBO_FALLBACK` behavior in development.

package/docs/plugins/lakebase.md

@@ -115,94 +115,18 @@ await createApp({
 
 ```
 
-## On-Behalf-Of (OBO) — per-user connections[​](#on-behalf-of-obo--per-user-connections "Direct link to On-Behalf-Of (OBO) — per-user connections")
+## On-Behalf-Of (OBO)[​](#on-behalf-of-obo--per-user-connections "Direct link to On-Behalf-Of (OBO)")
 
-When your app needs Row-Level Security (RLS) or per-user data isolation, use `asUser(req)` to execute queries using a per-user Lakebase connection pool. Each user's pool is authenticated with their Databricks identity, so PostgreSQL's `current_user` reflects the actual user.
+Lakebase is app-only through the new `appkit.asUser` and `runInCallerContext` APIs. Operations in those scopes fail with a clear error. For a connector call without a manifest alias:
 
-### Prerequisites[​](#prerequisites-1 "Direct link to Prerequisites")
-
-1. **Enable user authorization** in your Databricks App with the **`postgres`** scope. See [User authorization](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/auth#user-authorization) for setup instructions. In your `databricks.yml`:
-
-   ```yaml
-   resources:
-     apps:
-       app:
-         user_api_scopes:
-           - postgres
-
-   ```
-
-   Apps scaffolded with `databricks apps init` and the Lakebase plugin include this automatically.
-
-2. Each app user needs a **Postgres role** in Lakebase. Create one with the Databricks CLI:
-
-   ```bash
-   databricks postgres create-role "projects/{project_id}/branches/{branch_id}" \
-     --json '{"spec": {"identity_type": "USER", "postgres_role": "user@example.com"}}'
-
-   ```
-
-   Alternatively, create roles in the Lakebase UI under **Branch Overview** → **Add role**.
-
-   note
-
-   Do not grant `databricks_superuser` to OBO users — superusers bypass RLS. Use [fine-grained grants](#fine-grained-permissions) instead.
-
-### Usage[​](#usage "Direct link to Usage")
-
-No configuration needed — just call `asUser(req)`:
-
-```ts
-const AppKit = await createApp({
-  plugins: [server(), lakebase()],
-});
-
-// Service principal query (default — bypasses RLS as table owner)
-const all = await AppKit.lakebase.query("SELECT * FROM app.orders");
-
-// User-scoped query (per-user pool, RLS enforced)
-app.get("/api/my-orders", async (req, res) => {
-  const result = await AppKit.lakebase
-    .asUser(req)
-    .query("SELECT * FROM app.orders ORDER BY created_at DESC");
-  res.json(result.rows);
-});
+```text
+Resource "postgres" is app-only in this version of AppKit and does not support OBO (on-behalf-of-user) execution. It runs as the service principal. Resource type: postgres.
 
 ```
 
-When `asUser(req)` is called:
-
-1. The user's token and identity are extracted from `x-forwarded-access-token` and `x-forwarded-email` headers (set automatically by Databricks Apps).
-2. A per-user `pg.Pool` is created (or reused) with the user's OAuth credentials.
-3. `query()` and `pool` use the user's pool — `current_user` in PostgreSQL reflects the user's identity.
-
-### Row-Level Security example[​](#row-level-security-example "Direct link to Row-Level Security example")
-
-```sql
--- As the service principal (during app setup):
-ALTER TABLE app.orders ENABLE ROW LEVEL SECURITY;
-
-CREATE POLICY user_orders ON app.orders
-  FOR ALL TO PUBLIC
-  USING (owner = current_user);
-
--- Grant access so OBO users can query
-GRANT USAGE ON SCHEMA app TO PUBLIC;
-GRANT SELECT, INSERT ON ALL TABLES IN SCHEMA app TO PUBLIC;
-
-```
-
-### How it works[​](#how-it-works "Direct link to How it works")
-
-* The **service principal pool** (`AppKit.lakebase.pool`) is always created and used for DDL operations, seeding, and admin queries.
-* **Per-user pools** are created on the first `asUser(req)` call and cached by user identity. Each pool has its own OAuth token refresh cycle.
-* Idle connections within per-user pools close automatically (30s idle timeout). Empty pool objects are cleaned up periodically.
-* On shutdown, all pools (SP + user) are closed gracefully.
-* In development mode (`NODE_ENV=development`), if no user token is available, `asUser(req)` falls back to the SP pool with a warning.
-
-RLS and superusers
+Use a plain Lakebase call outside a caller scope for SP execution. There is no `asApp()` escape from a caller scope. The guard also applies to agent tools, ORM configuration, and pool handles obtained before entering a new caller scope.
 
-PostgreSQL superusers bypass Row-Level Security entirely. Users with the `databricks_superuser` role will see all rows regardless of RLS policies. For RLS enforcement, use [fine-grained grants](#fine-grained-permissions) instead of the superuser role.
+The platform has a `postgres` user API scope, but AppKit does not enable that capability in the new v1 execution API. For backward compatibility, deprecated `plugin.asUser(req)` and `runInUserContext` retain the existing per-user pool routing, as do direct request-based tool dispatch and existing agents routes. These paths keep the user's identity and do not silently use the SP. They cannot disable an enclosing new caller scope's guard. Existing applications can upgrade without migrating their Lakebase OBO calls, then adopt the new execution API explicitly. Database permissions and row-level policies still govern data access.
 
 ## Database Permissions[​](#database-permissions "Direct link to Database Permissions")