@databricks/appkit 0.82.0 → 0.84.0

package/docs/api/appkit/Function.isUserContext.md

@@ -0,0 +1,20 @@
+# ~~Function: isUserContext()~~
+
+```ts
+function isUserContext(ctx: ExecutionContext): ctx is UserContext & Partial<CallerContext>;
+
+```
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                                                                        |
+| --------- | --------------------------------------------------------------------------- |
+| `ctx`     | [`ExecutionContext`](./docs/api/appkit/TypeAlias.ExecutionContext.md) |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`ctx is UserContext & Partial<CallerContext>`
+
+## Deprecated[​](#deprecated "Direct link to Deprecated")
+
+Use isCallerContext. Active caller contexts retain the legacy identity accessors for callers narrowed by this guard.

package/docs/api/appkit/Function.runAgent.md

@@ -9,7 +9,7 @@ Standalone agent execution without `createApp`. Resolves the adapter, binds inli
 
 Limitations vs. running through the agents() plugin:
 
-* **No OBO and no approval gate** — there is no HTTP request, so plugin tools run as the service principal. The agents-plugin approval gate that prompts for human confirmation on `effect: "write" | "update" | "destructive"` tools is also absent. LLM-controlled tool arguments flow straight through to the SP. Treat standalone runAgent as a trusted-prompt environment (CI, batch eval, internal scripts) — not as an exposed user-facing surface.
+* **No approval gate**: tools inherit the run's principal, SP by default. Explicit caller credentials enable user execution. The agents-plugin gate that prompts for human confirmation on `effect: "write" | "update" | "destructive"` tools is also absent. LLM-controlled tool arguments flow straight through to the tools. Treat standalone runAgent as a trusted-prompt environment (CI, batch eval, internal scripts), not as an exposed user-facing surface.
 * **Hosted tools (MCP) are not supported** — they require a live MCP client that only exists inside the agents plugin's lifecycle. `runAgent` rejects them at index-build time with a clear error.
 * **Sub-agents** (`agents: { ... }` on the def) are executed as nested `runAgent` calls with no shared thread state. Plugin instances ARE shared across the recursion (same cache as the parent).
 * **Plugin tools** (used inside the function form via `plugins.<name>.toolkit(...)`) require passing `plugins: [...]` via `RunAgentInput`. Each plugin in that array is constructed once, `attachContext({})` and `await setup()` are called eagerly, and the resulting instance is shared across the top-level run and all sub-agent recursions. Plugins whose `setup()` requires runtime that only `createApp` provides (e.g. `WorkspaceClient`, `ServiceContext`, `PluginContext`) throw at standalone-init time with a clear "use createApp instead" message — not mid-stream.

package/docs/api/appkit/Function.runInCallerContext.md

@@ -0,0 +1,27 @@
+# Function: runInCallerContext()
+
+```ts
+function runInCallerContext<T>(callerContext: CallerContext, fn: () => T): T;
+
+```
+
+Run a function with an immutable snapshot of the caller context. Nested and concurrent scopes keep their own identities.
+
+## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter       | Type                                                                  | Description               |
+| --------------- | --------------------------------------------------------------------- | ------------------------- |
+| `callerContext` | [`CallerContext`](./docs/api/appkit/Interface.CallerContext.md) | The caller context to use |
+| `fn`            | () => `T`                                                             | The function to run       |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`T`
+
+The result of the function

package/docs/api/appkit/Function.runInUserContext.md

@@ -0,0 +1,29 @@
+# ~~Function: runInUserContext()~~
+
+```ts
+function runInUserContext<T>(userContext: 
+  | UserContext
+  | CallerContext & Pick<UserContext, "warehouseId">, fn: () => T): T;
+
+```
+
+## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter     | Type                                                                                                                                                                                                                                       |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `userContext` | \| [`UserContext`](./docs/api/appkit/TypeAlias.UserContext.md) \| [`CallerContext`](./docs/api/appkit/Interface.CallerContext.md) & `Pick`<[`UserContext`](./docs/api/appkit/TypeAlias.UserContext.md), `"warehouseId"`> |
+| `fn`          | () => `T`                                                                                                                                                                                                                                  |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`T`
+
+## Deprecated[​](#deprecated "Direct link to Deprecated")
+
+Use runInCallerContext.

package/docs/api/appkit/Interface.AgentDefinition.md

@@ -13,6 +13,17 @@ Sub-agents, exposed as `agent-<key>` tools on this agent.
 
 ***
 
+### auth?[​](#auth "Direct link to auth?")
+
+```ts
+optional auth: "on-behalf-of-user";
+
+```
+
+Run this agent on behalf of the signed-in user: the model call, plugin tools, hand-rolled tools, and sub-agents all use the user's credentials. Overrides `agents({ auth })` for this agent. Omit for the default, where the model and hand-rolled tools run as the app service principal and plugin tools run as the user.
+
+***
+
 ### baseSystemPrompt?[​](#basesystemprompt "Direct link to baseSystemPrompt?")
 
 ```ts

package/docs/api/appkit/Interface.AgentsPluginConfig.md

@@ -60,6 +60,17 @@ Milliseconds to wait before auto-denying. Default: 60\_000.
 
 ***
 
+### auth?[​](#auth "Direct link to auth?")
+
+```ts
+optional auth: "on-behalf-of-user";
+
+```
+
+Default identity for agents that don't set their own `auth`. `"on-behalf-of-user"` runs the whole agent as the signed-in user.
+
+***
+
 ### autoInheritSkills?[​](#autoinheritskills "Direct link to autoInheritSkills?")
 
 ```ts

package/docs/api/appkit/Interface.CallerContext.md

@@ -0,0 +1,54 @@
+# Interface: CallerContext
+
+Caller identity and workspace for one immutable execution scope.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### client[​](#client "Direct link to client")
+
+```ts
+readonly client: WorkspaceClient;
+
+```
+
+***
+
+### principal[​](#principal "Direct link to principal")
+
+```ts
+readonly principal: CallerPrincipal;
+
+```
+
+***
+
+### tokenFingerprint?[​](#tokenfingerprint "Direct link to tokenFingerprint?")
+
+```ts
+readonly optional tokenFingerprint: string;
+
+```
+
+Truncated SHA-256 hash of the caller token, used to detect rotation.
+
+***
+
+### ~~warehouseId?~~[​](#warehouseid "Direct link to warehouseid")
+
+```ts
+readonly optional warehouseId: Promise<string>;
+
+```
+
+#### Deprecated[​](#deprecated "Direct link to Deprecated")
+
+Use getWarehouseId(). Only legacy context access exposes this field.
+
+***
+
+### workspaceId[​](#workspaceid "Direct link to workspaceId")
+
+```ts
+readonly workspaceId: Promise<string>;
+
+```

package/docs/api/appkit/Interface.IndexConfig.md

@@ -5,7 +5,7 @@
 ### auth?[​](#auth "Direct link to auth?")
 
 ```ts
-optional auth: "service-principal" | "on-behalf-of-user";
+optional auth: "on-behalf-of-user" | "service-principal";
 
 ```
 

package/docs/api/appkit/Interface.PluginManifest.md

@@ -323,6 +323,37 @@ Omit.scaffolding
 
 ***
 
+### scopes?[​](#scopes "Direct link to scopes?")
+
+```ts
+optional scopes: (
+  | "postgres"
+  | "sql"
+  | "model-serving"
+  | "genie"
+  | "files"
+  | "vector-search"
+  | "catalog.connections"
+  | "ai-gateway"
+  | "mcp.external"
+  | "mcp.functions"
+  | "workspace.workspace"
+  | "catalog.catalogs:read"
+  | "catalog.schemas:read"
+  | "catalog.tables:read"
+  | "sql:restricted-query")[];
+
+```
+
+#### Inherited from[​](#inherited-from-11 "Direct link to Inherited from")
+
+```ts
+Omit.scopes
+
+```
+
+***
+
 ### stability?[​](#stability "Direct link to stability?")
 
 ```ts
@@ -332,7 +363,7 @@ optional stability: "beta" | "ga";
 
 Plugin stability level. Beta plugins may have breaking API changes between minor releases but are on a path to GA. GA (general availability) plugins follow semver strictly.
 
-#### Inherited from[​](#inherited-from-11 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-12 "Direct link to Inherited from")
 
 ```ts
 Omit.stability
@@ -350,7 +381,7 @@ optional version: string;
 
 Plugin version (semver format)
 
-#### Inherited from[​](#inherited-from-12 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-13 "Direct link to Inherited from")
 
 ```ts
 Omit.version

package/docs/api/appkit/Interface.RegisteredAgent.md

@@ -11,6 +11,17 @@ adapter: AgentAdapter;
 
 ***
 
+### auth?[​](#auth "Direct link to auth?")
+
+```ts
+optional auth: "on-behalf-of-user";
+
+```
+
+Effective identity: the agent's `auth`, else the plugin default.
+
+***
+
 ### baseSystemPrompt?[​](#basesystemprompt "Direct link to baseSystemPrompt?")
 
 ```ts

package/docs/api/appkit/Interface.RunAgentInput.md

@@ -2,6 +2,50 @@
 
 ## Properties[​](#properties "Direct link to Properties")
 
+### caller?[​](#caller "Direct link to caller?")
+
+```ts
+optional caller: {
+  host: string;
+  principal: CallerPrincipal;
+  token: string;
+  workspaceId: string;
+};
+
+```
+
+Explicit user credentials for standalone execution. Host and workspace ID are required, so no CLI profile or service-principal identity is selected. Omit to inherit the ambient scope, or use SP when no caller scope is open. Obtain the token through a trusted authentication flow, not model input.
+
+#### host[​](#host "Direct link to host")
+
+```ts
+readonly host: string;
+
+```
+
+#### principal[​](#principal "Direct link to principal")
+
+```ts
+readonly principal: CallerPrincipal;
+
+```
+
+#### token[​](#token "Direct link to token")
+
+```ts
+readonly token: string;
+
+```
+
+#### workspaceId[​](#workspaceid "Direct link to workspaceId")
+
+```ts
+readonly workspaceId: string;
+
+```
+
+***
+
 ### messages[​](#messages "Direct link to messages")
 
 ```ts
@@ -20,7 +64,7 @@ optional plugins: PluginData<PluginConstructor, unknown, string>[];
 
 ```
 
-Optional plugin list. Required when `def.tools` is the function form `(plugins) => Record<string, AgentTool>` and the function dereferences any plugins. `runAgent` constructs a fresh instance per plugin and dispatches tool calls against it as the service principal (no OBO — there is no HTTP request in standalone mode).
+Optional plugin list. Required when `def.tools` is the function form `(plugins) => Record<string, AgentTool>` and the function dereferences any plugins. `runAgent` constructs a fresh instance per plugin and dispatches tool calls with the run's ambient principal.
 
 ***
 

package/docs/api/appkit/TypeAlias.AgentAuth.md

@@ -0,0 +1,8 @@
+# Type Alias: AgentAuth
+
+```ts
+type AgentAuth = "on-behalf-of-user";
+
+```
+
+Identity an agent runs under. The only value is on-behalf-of-user.

package/docs/api/appkit/TypeAlias.AppKitApi.md

@@ -0,0 +1,35 @@
+# Type Alias: AppKitApi\<U>
+
+```ts
+type AppKitApi<U> = PluginMap<U> & {
+  asUser: UserScopedApp<U>;
+};
+
+```
+
+App instance with plugin exports and an explicit caller-scoped entry point.
+
+## Type Declaration[​](#type-declaration "Direct link to Type Declaration")
+
+### asUser()[​](#asuser "Direct link to asUser()")
+
+```ts
+asUser(req: IAppRequest): UserScopedApp<U>;
+
+```
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type          |
+| --------- | ------------- |
+| `req`     | `IAppRequest` |
+
+#### Returns[​](#returns "Direct link to Returns")
+
+[`UserScopedApp`](./docs/api/appkit/TypeAlias.UserScopedApp.md)<`U`>
+
+## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
+
+| Type Parameter                                                                                                                      |
+| ----------------------------------------------------------------------------------------------------------------------------------- |
+| `U` *extends* readonly [`PluginData`](./docs/api/appkit/TypeAlias.PluginData.md)<`PluginConstructor`, `unknown`, `string`>\[] |

package/docs/api/appkit/TypeAlias.CallerPrincipal.md

@@ -0,0 +1,13 @@
+# Type Alias: CallerPrincipal
+
+```ts
+type CallerPrincipal = Readonly<{
+  type: "user";
+  userEmail?: string;
+  userId: string;
+  userName?: string;
+}>;
+
+```
+
+The caller identity whose permissions authorize execution, not its resources.

package/docs/api/appkit/TypeAlias.ExecutionContext.md

@@ -0,0 +1,9 @@
+# Type Alias: ExecutionContext
+
+```ts
+type ExecutionContext = 
+  | ServiceContextState
+  | CallerContext
+  | UserContext;
+
+```

package/docs/api/appkit/TypeAlias.ExecutionResult.md

@@ -7,6 +7,7 @@ type ExecutionResult<T> =
   ok: true;
 }
   | {
+  error?: IdentityExpiredError;
   message: string;
   ok: false;
   status: number;
@@ -34,3 +35,67 @@ In production, error messages from non-AppKitError sources are handled as:
 | Type Parameter |
 | -------------- |
 | `T`            |
+
+## Type Declaration[​](#type-declaration "Direct link to Type Declaration")
+
+```ts
+{
+  data: T;
+  ok: true;
+}
+
+```
+
+### data[​](#data "Direct link to data")
+
+```ts
+data: T;
+
+```
+
+### ok[​](#ok "Direct link to ok")
+
+```ts
+ok: true;
+
+```
+
+```ts
+{
+  error?: IdentityExpiredError;
+  message: string;
+  ok: false;
+  status: number;
+}
+
+```
+
+### error?[​](#error "Direct link to error?")
+
+```ts
+optional error: IdentityExpiredError;
+
+```
+
+Typed credential expiry without changing the existing failure envelope.
+
+### message[​](#message "Direct link to message")
+
+```ts
+message: string;
+
+```
+
+### ok[​](#ok-1 "Direct link to ok")
+
+```ts
+ok: false;
+
+```
+
+### status[​](#status "Direct link to status")
+
+```ts
+status: number;
+
+```

package/docs/api/appkit/TypeAlias.ScopedPluginMap.md

@@ -0,0 +1,12 @@
+# Type Alias: ScopedPluginMap\<U>
+
+```ts
+type ScopedPluginMap<U> = { [P in U[number] as P["name"]]: ScopedExports<PluginExports<InstanceType<P["plugin"]>>> };
+
+```
+
+## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
+
+| Type Parameter                                                                                                                      |
+| ----------------------------------------------------------------------------------------------------------------------------------- |
+| `U` *extends* readonly [`PluginData`](./docs/api/appkit/TypeAlias.PluginData.md)<`PluginConstructor`, `unknown`, `string`>\[] |

package/docs/api/appkit/TypeAlias.UserContext.md

@@ -0,0 +1,109 @@
+# ~~Type Alias: UserContext~~
+
+```ts
+type UserContext = {
+  client: ServiceContextState["client"];
+  isUserContext: true;
+  tokenFingerprint?: string;
+  userEmail?: string;
+  userId: string;
+  userName?: string;
+  warehouseId?: Promise<string>;
+  workspaceId: Promise<string>;
+};
+
+```
+
+## Deprecated[​](#deprecated "Direct link to Deprecated")
+
+Use CallerContext and its principal field. Kept for callers that construct the legacy shape or read its flat identity fields.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### ~~client~~[​](#client "Direct link to client")
+
+```ts
+client: ServiceContextState["client"];
+
+```
+
+WorkspaceClient authenticated as the user
+
+***
+
+### ~~isUserContext~~[​](#isusercontext "Direct link to isusercontext")
+
+```ts
+isUserContext: true;
+
+```
+
+Flag indicating this is a user context
+
+***
+
+### ~~tokenFingerprint?~~[​](#tokenfingerprint "Direct link to tokenfingerprint")
+
+```ts
+optional tokenFingerprint: string;
+
+```
+
+Truncated SHA-256 hash of the user's OBO token, used to detect token rotation
+
+***
+
+### ~~userEmail?~~[​](#useremail "Direct link to useremail")
+
+```ts
+optional userEmail: string;
+
+```
+
+The user's email (from `x-forwarded-email` header)
+
+***
+
+### ~~userId~~[​](#userid "Direct link to userid")
+
+```ts
+userId: string;
+
+```
+
+The user's ID (from request headers)
+
+***
+
+### ~~userName?~~[​](#username "Direct link to username")
+
+```ts
+optional userName: string;
+
+```
+
+The user's name (from request headers)
+
+***
+
+### ~~warehouseId?~~[​](#warehouseid "Direct link to warehouseid")
+
+```ts
+optional warehouseId: Promise<string>;
+
+```
+
+#### Deprecated[​](#deprecated-1 "Direct link to Deprecated")
+
+Use getWarehouseId() from @databricks/appkit.
+
+***
+
+### ~~workspaceId~~[​](#workspaceid "Direct link to workspaceid")
+
+```ts
+workspaceId: Promise<string>;
+
+```
+
+Promise that resolves to the workspace ID (inherited from service context)

package/docs/api/appkit/TypeAlias.UserScopedApp.md

@@ -0,0 +1,39 @@
+# Type Alias: UserScopedApp\<U>
+
+```ts
+type UserScopedApp<U> = ScopedPluginMap<U> & {
+  run: Promise<T>;
+};
+
+```
+
+## Type Declaration[​](#type-declaration "Direct link to Type Declaration")
+
+### run()[​](#run "Direct link to run()")
+
+```ts
+run<T>(fn: (kit: ScopedPluginMap<U>) => T | Promise<T>): Promise<T>;
+
+```
+
+#### Type Parameters[​](#type-parameters "Direct link to Type Parameters")
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                                                                                                             |
+| --------- | ---------------------------------------------------------------------------------------------------------------- |
+| `fn`      | (`kit`: [`ScopedPluginMap`](./docs/api/appkit/TypeAlias.ScopedPluginMap.md)<`U`>) => `T` \| `Promise`<`T`> |
+
+#### Returns[​](#returns "Direct link to Returns")
+
+`Promise`<`T`>
+
+## Type Parameters[​](#type-parameters-1 "Direct link to Type Parameters")
+
+| Type Parameter                                                                                                                      |
+| ----------------------------------------------------------------------------------------------------------------------------------- |
+| `U` *extends* readonly [`PluginData`](./docs/api/appkit/TypeAlias.PluginData.md)<`PluginConstructor`, `unknown`, `string`>\[] |