@databricks/appkit-ui 0.83.0 → 0.84.0

package/docs/api/appkit/Class.Plugin.md

@@ -239,30 +239,26 @@ BasePlugin.abortActiveOperations
 
 ***
 
-### asUser()[​](#asuser "Direct link to asUser()")
+### ~~asUser()~~[​](#asuser "Direct link to asuser")
 
 ```ts
 asUser(req: Request): this;
 
 ```
 
-Execute operations using the user's identity from the request. Returns a proxy of this plugin where all method calls execute with the user's Databricks credentials instead of the service principal.
-
 #### Parameters[​](#parameters-1 "Direct link to Parameters")
 
-| Parameter | Type      | Description                                              |
-| --------- | --------- | -------------------------------------------------------- |
-| `req`     | `Request` | The Express request containing the user token in headers |
+| Parameter | Type      |
+| --------- | --------- |
+| `req`     | `Request` |
 
 #### Returns[​](#returns-2 "Direct link to Returns")
 
 `this`
 
-A proxied plugin instance that executes as the user
+#### Deprecated[​](#deprecated "Direct link to Deprecated")
 
-#### Throws[​](#throws "Direct link to Throws")
-
-AuthenticationError if user token is not available in request headers (production only). In development mode (`NODE_ENV=development`), skips user impersonation instead of throwing.
+Use appkit.asUser(req) to scope the whole app.
 
 ***
 
@@ -374,7 +370,7 @@ Returns an [ExecutionResult](./docs/api/appkit/TypeAlias.ExecutionResult.md) dis
 * `{ ok: true, data: T }` on success
 * `{ ok: false, status: number, message: string }` on failure
 
-Errors are never thrown — the method is production-safe.
+Caller credential expiration retains the failure result and additionally exposes a typed error, preserving existing result-based callers.
 
 #### Type Parameters[​](#type-parameters-1 "Direct link to Type Parameters")
 
@@ -576,7 +572,7 @@ Returns the `x-forwarded-user` header when present. In development mode (`NODE_E
 
 `string`
 
-#### Throws[​](#throws-1 "Direct link to Throws")
+#### Throws[​](#throws "Direct link to Throws")
 
 AuthenticationError in production when no user header is present.
 

package/docs/api/appkit/Class.ServerError.md

@@ -53,7 +53,7 @@ protected readonly optional _clientMessage: string;
 
 ```
 
-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 fragments, internal object names, and correlation IDs.
+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 fragments, internal object names, and correlation IDs.
 
 Subclasses can set this in their constructor for a fixed sanitized string. When unset, `clientMessage` defaults to a generic per-code string (see the getter), and the raw `message` is kept server-side only.
 

package/docs/api/appkit/Class.ServiceContext.md

@@ -0,0 +1,169 @@
+# Class: ServiceContext
+
+ServiceContext is a singleton that manages the service principal's WorkspaceClient and workspace ID. WarehouseResource owns warehouse bindings.
+
+It's initialized once at app startup and provides the foundation for both service principal and user context execution.
+
+## Constructors[​](#constructors "Direct link to Constructors")
+
+### Constructor[​](#constructor "Direct link to Constructor")
+
+```ts
+new ServiceContext(): ServiceContext;
+
+```
+
+#### Returns[​](#returns "Direct link to Returns")
+
+`ServiceContext`
+
+## Methods[​](#methods "Direct link to Methods")
+
+### createCallerContext()[​](#createcallercontext "Direct link to createCallerContext()")
+
+```ts
+static createCallerContext(
+   token: string, 
+   userId: string, 
+   userName?: string, 
+   userEmail?: string): CallerContext;
+
+```
+
+Create an immutable caller context from the existing user request headers.
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter    | Type     | Description                                                  |
+| ------------ | -------- | ------------------------------------------------------------ |
+| `token`      | `string` | The user's access token from x-forwarded-access-token header |
+| `userId`     | `string` | The user's ID from x-forwarded-user header                   |
+| `userName?`  | `string` | Optional user name                                           |
+| `userEmail?` | `string` | Optional email from x-forwarded-email                        |
+
+#### Returns[​](#returns-1 "Direct link to Returns")
+
+[`CallerContext`](./docs/api/appkit/Interface.CallerContext.md)
+
+#### Throws[​](#throws "Direct link to Throws")
+
+Error if token is not provided
+
+***
+
+### ~~createUserContext()~~[​](#createusercontext "Direct link to createusercontext")
+
+```ts
+static createUserContext(
+   token: string, 
+   userId: string, 
+   userName?: string, 
+   userEmail?: string): CallerContext & UserContext;
+
+```
+
+#### Parameters[​](#parameters-1 "Direct link to Parameters")
+
+| Parameter    | Type     |
+| ------------ | -------- |
+| `token`      | `string` |
+| `userId`     | `string` |
+| `userName?`  | `string` |
+| `userEmail?` | `string` |
+
+#### Returns[​](#returns-2 "Direct link to Returns")
+
+[`CallerContext`](./docs/api/appkit/Interface.CallerContext.md) & [`UserContext`](./docs/api/appkit/TypeAlias.UserContext.md)
+
+#### Deprecated[​](#deprecated "Direct link to Deprecated")
+
+Use ServiceContext.createCallerContext.
+
+***
+
+### get()[​](#get "Direct link to get()")
+
+```ts
+static get(): ServiceContextState;
+
+```
+
+Get the initialized service context.
+
+#### Returns[​](#returns-3 "Direct link to Returns")
+
+`ServiceContextState`
+
+#### Throws[​](#throws-1 "Direct link to Throws")
+
+Error if not initialized
+
+***
+
+### getClientOptions()[​](#getclientoptions "Direct link to getClientOptions()")
+
+```ts
+static getClientOptions(): ClientOptions;
+
+```
+
+Get the client options for WorkspaceClient. Exposed for testing purposes.
+
+#### Returns[​](#returns-4 "Direct link to Returns")
+
+`ClientOptions`
+
+***
+
+### initialize()[​](#initialize "Direct link to initialize()")
+
+```ts
+static initialize(options?: {
+  warehouseId?: string | boolean;
+}, client?: WorkspaceClient): Promise<ServiceContextState>;
+
+```
+
+Initialize the service context. Should be called once at app startup. Safe to call multiple times - will return the same instance.
+
+#### Parameters[​](#parameters-2 "Direct link to Parameters")
+
+| Parameter              | Type                                                                      | Description                                                                                          |
+| ---------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `options?`             | { `warehouseId?`: `string` \| `boolean`; }                                | A resolved warehouse ID, or a boolean enabling discovery.                                            |
+| `options.warehouseId?` | `string` \| `boolean`                                                     | -                                                                                                    |
+| `client?`              | [`WorkspaceClient`](./docs/api/appkit/Interface.WorkspaceClient.md) | Optional pre-configured WorkspaceClient to use instead of creating one from environment credentials. |
+
+#### Returns[​](#returns-5 "Direct link to Returns")
+
+`Promise`<`ServiceContextState`>
+
+***
+
+### isInitialized()[​](#isinitialized "Direct link to isInitialized()")
+
+```ts
+static isInitialized(): boolean;
+
+```
+
+Check if the service context has been initialized.
+
+#### Returns[​](#returns-6 "Direct link to Returns")
+
+`boolean`
+
+***
+
+### reset()[​](#reset "Direct link to reset()")
+
+```ts
+static reset(): void;
+
+```
+
+Reset the service context. Only for testing purposes.
+
+#### Returns[​](#returns-7 "Direct link to Returns")
+
+`void`

package/docs/api/appkit/Class.TunnelError.md

@@ -54,7 +54,7 @@ protected readonly optional _clientMessage: string;
 
 ```
 
-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 fragments, internal object names, and correlation IDs.
+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 fragments, internal object names, and correlation IDs.
 
 Subclasses can set this in their constructor for a fixed sanitized string. When unset, `clientMessage` defaults to a generic per-code string (see the getter), and the raw `message` is kept server-side only.
 

package/docs/api/appkit/Class.ValidationError.md

@@ -54,7 +54,7 @@ protected readonly optional _clientMessage: string;
 
 ```
 
-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 fragments, internal object names, and correlation IDs.
+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 fragments, internal object names, and correlation IDs.
 
 Subclasses can set this in their constructor for a fixed sanitized string. When unset, `clientMessage` defaults to a generic per-code string (see the getter), and the raw `message` is kept server-side only.
 

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

@@ -5,10 +5,10 @@ function createApp<T>(config: {
   cache?: CacheConfig;
   client?: WorkspaceClient;
   disableInternalTelemetry?: boolean;
-  onPluginsReady?: (appkit: PluginMap<T>) => void | Promise<void>;
+  onPluginsReady?: (appkit: AppKitApi<T>) => void | Promise<void>;
   plugins?: T;
   telemetry?: TelemetryConfig;
-}): Promise<PluginMap<T>>;
+}): Promise<AppKitApi<T>>;
 
 ```
 
@@ -24,19 +24,19 @@ Initializes telemetry, cache, and service context, then registers plugins in pha
 
 ## Parameters[​](#parameters "Direct link to Parameters")
 
-| Parameter                          | Type                                                                                                                                                                                                                                                                                                                                                                                                     | Description                                               |
-| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
-| `config`                           | { `cache?`: [`CacheConfig`](./docs/api/appkit/Interface.CacheConfig.md); `client?`: [`WorkspaceClient`](./docs/api/appkit/Interface.WorkspaceClient.md); `disableInternalTelemetry?`: `boolean`; `onPluginsReady?`: (`appkit`: `PluginMap`<`T`>) => `void` \| `Promise`<`void`>; `plugins?`: `T`; `telemetry?`: [`TelemetryConfig`](./docs/api/appkit/Interface.TelemetryConfig.md); } | -                                                         |
-| `config.cache?`                    | [`CacheConfig`](./docs/api/appkit/Interface.CacheConfig.md)                                                                                                                                                                                                                                                                                                                                        | -                                                         |
-| `config.client?`                   | [`WorkspaceClient`](./docs/api/appkit/Interface.WorkspaceClient.md)                                                                                                                                                                                                                                                                                                                                | -                                                         |
-| `config.disableInternalTelemetry?` | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                | -                                                         |
-| `config.onPluginsReady?`           | (`appkit`: `PluginMap`<`T`>) => `void` \| `Promise`<`void`>                                                                                                                                                                                                                                                                                                                                              | Runs after plugin setup but **before** the server starts. |
-| `config.plugins?`                  | `T`                                                                                                                                                                                                                                                                                                                                                                                                      | -                                                         |
-| `config.telemetry?`                | [`TelemetryConfig`](./docs/api/appkit/Interface.TelemetryConfig.md)                                                                                                                                                                                                                                                                                                                                | -                                                         |
+| Parameter                          | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Description                                               |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| `config`                           | { `cache?`: [`CacheConfig`](./docs/api/appkit/Interface.CacheConfig.md); `client?`: [`WorkspaceClient`](./docs/api/appkit/Interface.WorkspaceClient.md); `disableInternalTelemetry?`: `boolean`; `onPluginsReady?`: (`appkit`: [`AppKitApi`](./docs/api/appkit/TypeAlias.AppKitApi.md)<`T`>) => `void` \| `Promise`<`void`>; `plugins?`: `T`; `telemetry?`: [`TelemetryConfig`](./docs/api/appkit/Interface.TelemetryConfig.md); } | -                                                         |
+| `config.cache?`                    | [`CacheConfig`](./docs/api/appkit/Interface.CacheConfig.md)                                                                                                                                                                                                                                                                                                                                                                                          | -                                                         |
+| `config.client?`                   | [`WorkspaceClient`](./docs/api/appkit/Interface.WorkspaceClient.md)                                                                                                                                                                                                                                                                                                                                                                                  | -                                                         |
+| `config.disableInternalTelemetry?` | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                  | -                                                         |
+| `config.onPluginsReady?`           | (`appkit`: [`AppKitApi`](./docs/api/appkit/TypeAlias.AppKitApi.md)<`T`>) => `void` \| `Promise`<`void`>                                                                                                                                                                                                                                                                                                                                              | Runs after plugin setup but **before** the server starts. |
+| `config.plugins?`                  | `T`                                                                                                                                                                                                                                                                                                                                                                                                                                                        | -                                                         |
+| `config.telemetry?`                | [`TelemetryConfig`](./docs/api/appkit/Interface.TelemetryConfig.md)                                                                                                                                                                                                                                                                                                                                                                                  | -                                                         |
 
 ## Returns[​](#returns "Direct link to Returns")
 
-`Promise`<`PluginMap`<`T`>>
+`Promise`<[`AppKitApi`](./docs/api/appkit/TypeAlias.AppKitApi.md)<`T`>>
 
 A `PluginMap` keyed by plugin name with typed exports
 

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

@@ -0,0 +1,12 @@
+# Function: getCallerContext()
+
+```ts
+function getCallerContext(): CallerContext | undefined;
+
+```
+
+Get the caller context if one is active, otherwise `undefined`. Unlike `getExecutionContext()`, this does not require `ServiceContext` to be initialized and never throws.
+
+## Returns[​](#returns "Direct link to Returns")
+
+[`CallerContext`](./docs/api/appkit/Interface.CallerContext.md) | `undefined`

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

@@ -0,0 +1,14 @@
+# ~~Function: getCurrentUserId()~~
+
+```ts
+function getCurrentUserId(): string;
+
+```
+
+## Returns[​](#returns "Direct link to Returns")
+
+`string`
+
+## Deprecated[​](#deprecated "Direct link to Deprecated")
+
+Use getCurrentPrincipalKey for new cache keys or getCurrentActorId for audit. Preserves the bare user or service ID for existing callers.

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

@@ -14,7 +14,7 @@ Get the current execution context.
 
 ## Returns[​](#returns "Direct link to Returns")
 
-\| `ServiceContextState` | [`CallerContext`](./docs/api/appkit/Interface.CallerContext.md) & `UserContext`
+\| `ServiceContextState` | [`CallerContext`](./docs/api/appkit/Interface.CallerContext.md) & [`UserContext`](./docs/api/appkit/TypeAlias.UserContext.md)
 
 ## Throws[​](#throws "Direct link to Throws")
 

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

@@ -0,0 +1,16 @@
+# ~~Function: getUserContext()~~
+
+```ts
+function getUserContext(): 
+  | CallerContext & UserContext
+  | undefined;
+
+```
+
+## Returns[​](#returns "Direct link to Returns")
+
+\| [`CallerContext`](./docs/api/appkit/Interface.CallerContext.md) & [`UserContext`](./docs/api/appkit/TypeAlias.UserContext.md) | `undefined`
+
+## Deprecated[​](#deprecated "Direct link to Deprecated")
+
+Use getCallerContext and its principal field.

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

@@ -0,0 +1,12 @@
+# Function: isInUserContext()
+
+```ts
+function isInUserContext(): boolean;
+
+```
+
+Check if currently running in a user context.
+
+## Returns[​](#returns "Direct link to Returns")
+
+`boolean`

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

@@ -33,6 +33,19 @@ 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

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

@@ -327,13 +327,21 @@ Omit.scaffolding
 
 ```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")[];
+  | "catalog.tables:read"
+  | "sql:restricted-query")[];
 
 ```
 

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.