@databricks/appkit-ui 0.82.0 → 0.84.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. package/CLAUDE.md +21 -1
  2. package/dist/cli/commands/agent/eval.js +1 -1
  3. package/dist/cli/commands/generate-types.js +1 -1
  4. package/dist/cli/commands/plugin/sync/sync.js +28 -15
  5. package/dist/cli/commands/plugin/sync/sync.js.map +1 -1
  6. package/dist/cli/commands/registry/add.js +3 -11
  7. package/dist/cli/commands/registry/add.js.map +1 -1
  8. package/dist/cli/commands/registry/config-writer.js +1 -1
  9. package/dist/schemas/manifest.d.ts +44 -1
  10. package/dist/schemas/manifest.d.ts.map +1 -1
  11. package/dist/schemas/manifest.js +122 -3
  12. package/dist/schemas/manifest.js.map +1 -1
  13. package/dist/shared/src/plugin.d.ts.map +1 -1
  14. package/docs/api/appkit/Class.AppKitError.md +2 -1
  15. package/docs/api/appkit/Class.AuthenticationError.md +1 -1
  16. package/docs/api/appkit/Class.ConfigurationError.md +1 -1
  17. package/docs/api/appkit/Class.ConnectionError.md +1 -1
  18. package/docs/api/appkit/Class.DatabaseValidationError.md +1 -1
  19. package/docs/api/appkit/Class.ExecutionError.md +1 -1
  20. package/docs/api/appkit/Class.IdentityExpiredError.md +190 -0
  21. package/docs/api/appkit/Class.InitializationError.md +1 -1
  22. package/docs/api/appkit/Class.Plugin.md +9 -13
  23. package/docs/api/appkit/Class.ServerError.md +1 -1
  24. package/docs/api/appkit/Class.ServiceContext.md +169 -0
  25. package/docs/api/appkit/Class.TunnelError.md +1 -1
  26. package/docs/api/appkit/Class.ValidationError.md +1 -1
  27. package/docs/api/appkit/Function.createApp.md +12 -12
  28. package/docs/api/appkit/Function.getCallerContext.md +12 -0
  29. package/docs/api/appkit/Function.getCurrentActorId.md +12 -0
  30. package/docs/api/appkit/Function.getCurrentPrincipalKey.md +12 -0
  31. package/docs/api/appkit/Function.getCurrentUserId.md +14 -0
  32. package/docs/api/appkit/Function.getExecutionContext.md +5 -3
  33. package/docs/api/appkit/Function.getUserContext.md +16 -0
  34. package/docs/api/appkit/Function.getWarehouseId.md +20 -0
  35. package/docs/api/appkit/Function.isInUserContext.md +12 -0
  36. package/docs/api/appkit/Function.isUserContext.md +20 -0
  37. package/docs/api/appkit/Function.runAgent.md +1 -1
  38. package/docs/api/appkit/Function.runInCallerContext.md +27 -0
  39. package/docs/api/appkit/Function.runInUserContext.md +29 -0
  40. package/docs/api/appkit/Interface.AgentDefinition.md +11 -0
  41. package/docs/api/appkit/Interface.AgentsPluginConfig.md +11 -0
  42. package/docs/api/appkit/Interface.CallerContext.md +54 -0
  43. package/docs/api/appkit/Interface.IndexConfig.md +1 -1
  44. package/docs/api/appkit/Interface.PluginManifest.md +33 -2
  45. package/docs/api/appkit/Interface.RegisteredAgent.md +11 -0
  46. package/docs/api/appkit/Interface.RunAgentInput.md +45 -1
  47. package/docs/api/appkit/TypeAlias.AgentAuth.md +8 -0
  48. package/docs/api/appkit/TypeAlias.AppKitApi.md +35 -0
  49. package/docs/api/appkit/TypeAlias.CallerPrincipal.md +13 -0
  50. package/docs/api/appkit/TypeAlias.ExecutionContext.md +9 -0
  51. package/docs/api/appkit/TypeAlias.ExecutionResult.md +65 -0
  52. package/docs/api/appkit/TypeAlias.ScopedPluginMap.md +12 -0
  53. package/docs/api/appkit/TypeAlias.UserContext.md +109 -0
  54. package/docs/api/appkit/TypeAlias.UserScopedApp.md +39 -0
  55. package/docs/api/appkit.md +20 -0
  56. package/docs/plugins/agents.md +45 -0
  57. package/docs/plugins/analytics.md +8 -0
  58. package/docs/plugins/execution-context.md +101 -50
  59. package/docs/plugins/lakebase.md +6 -82
  60. package/llms.txt +21 -1
  61. package/package.json +1 -1
  62. package/sbom.cdx.json +1 -1
package/docs/api/appkit/Interface.PluginManifest.md CHANGED
@@ -323,6 +323,37 @@ Omit.scaffolding
323
323
 
324
324
  ***
325
325
 
326
+ ### scopes?[​](#scopes "Direct link to scopes?")
327
+
328
+ ```ts
329
+ optional scopes: (
330
+ | "postgres"
331
+ | "sql"
332
+ | "model-serving"
333
+ | "genie"
334
+ | "files"
335
+ | "vector-search"
336
+ | "catalog.connections"
337
+ | "ai-gateway"
338
+ | "mcp.external"
339
+ | "mcp.functions"
340
+ | "workspace.workspace"
341
+ | "catalog.catalogs:read"
342
+ | "catalog.schemas:read"
343
+ | "catalog.tables:read"
344
+ | "sql:restricted-query")[];
345
+
346
+ ```
347
+
348
+ #### Inherited from[​](#inherited-from-11 "Direct link to Inherited from")
349
+
350
+ ```ts
351
+ Omit.scopes
352
+
353
+ ```
354
+
355
+ ***
356
+
326
357
  ### stability?[​](#stability "Direct link to stability?")
327
358
 
328
359
  ```ts
@@ -332,7 +363,7 @@ optional stability: "beta" | "ga";
332
363
 
333
364
  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.
334
365
 
335
- #### Inherited from[​](#inherited-from-11 "Direct link to Inherited from")
366
+ #### Inherited from[​](#inherited-from-12 "Direct link to Inherited from")
336
367
 
337
368
  ```ts
338
369
  Omit.stability
@@ -350,7 +381,7 @@ optional version: string;
350
381
 
351
382
  Plugin version (semver format)
352
383
 
353
- #### Inherited from[​](#inherited-from-12 "Direct link to Inherited from")
384
+ #### Inherited from[​](#inherited-from-13 "Direct link to Inherited from")
354
385
 
355
386
  ```ts
356
387
  Omit.version
package/docs/api/appkit/Interface.RegisteredAgent.md CHANGED
@@ -11,6 +11,17 @@ adapter: AgentAdapter;
11
11
 
12
12
  ***
13
13
 
14
+ ### auth?[​](#auth "Direct link to auth?")
15
+
16
+ ```ts
17
+ optional auth: "on-behalf-of-user";
18
+
19
+ ```
20
+
21
+ Effective identity: the agent's `auth`, else the plugin default.
22
+
23
+ ***
24
+
14
25
  ### baseSystemPrompt?[​](#basesystemprompt "Direct link to baseSystemPrompt?")
15
26
 
16
27
  ```ts
package/docs/api/appkit/Interface.RunAgentInput.md CHANGED
@@ -2,6 +2,50 @@
2
2
 
3
3
  ## Properties[​](#properties "Direct link to Properties")
4
4
 
5
+ ### caller?[​](#caller "Direct link to caller?")
6
+
7
+ ```ts
8
+ optional caller: {
9
+ host: string;
10
+ principal: CallerPrincipal;
11
+ token: string;
12
+ workspaceId: string;
13
+ };
14
+
15
+ ```
16
+
17
+ 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.
18
+
19
+ #### host[​](#host "Direct link to host")
20
+
21
+ ```ts
22
+ readonly host: string;
23
+
24
+ ```
25
+
26
+ #### principal[​](#principal "Direct link to principal")
27
+
28
+ ```ts
29
+ readonly principal: CallerPrincipal;
30
+
31
+ ```
32
+
33
+ #### token[​](#token "Direct link to token")
34
+
35
+ ```ts
36
+ readonly token: string;
37
+
38
+ ```
39
+
40
+ #### workspaceId[​](#workspaceid "Direct link to workspaceId")
41
+
42
+ ```ts
43
+ readonly workspaceId: string;
44
+
45
+ ```
46
+
47
+ ***
48
+
5
49
  ### messages[​](#messages "Direct link to messages")
6
50
 
7
51
  ```ts
@@ -20,7 +64,7 @@ optional plugins: PluginData<PluginConstructor, unknown, string>[];
20
64
 
21
65
  ```
22
66
 
23
- 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).
67
+ 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.
24
68
 
25
69
  ***
26
70
 
package/docs/api/appkit/TypeAlias.AgentAuth.md ADDED
@@ -0,0 +1,8 @@
1
+ # Type Alias: AgentAuth
2
+
3
+ ```ts
4
+ type AgentAuth = "on-behalf-of-user";
5
+
6
+ ```
7
+
8
+ Identity an agent runs under. The only value is on-behalf-of-user.
package/docs/api/appkit/TypeAlias.AppKitApi.md ADDED
@@ -0,0 +1,35 @@
1
+ # Type Alias: AppKitApi\<U>
2
+
3
+ ```ts
4
+ type AppKitApi<U> = PluginMap<U> & {
5
+ asUser: UserScopedApp<U>;
6
+ };
7
+
8
+ ```
9
+
10
+ App instance with plugin exports and an explicit caller-scoped entry point.
11
+
12
+ ## Type Declaration[​](#type-declaration "Direct link to Type Declaration")
13
+
14
+ ### asUser()[​](#asuser "Direct link to asUser()")
15
+
16
+ ```ts
17
+ asUser(req: IAppRequest): UserScopedApp<U>;
18
+
19
+ ```
20
+
21
+ #### Parameters[​](#parameters "Direct link to Parameters")
22
+
23
+ | Parameter | Type |
24
+ | --------- | ------------- |
25
+ | `req` | `IAppRequest` |
26
+
27
+ #### Returns[​](#returns "Direct link to Returns")
28
+
29
+ [`UserScopedApp`](./docs/api/appkit/TypeAlias.UserScopedApp.md)<`U`>
30
+
31
+ ## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
32
+
33
+ | Type Parameter |
34
+ | ----------------------------------------------------------------------------------------------------------------------------------- |
35
+ | `U` *extends* readonly [`PluginData`](./docs/api/appkit/TypeAlias.PluginData.md)<`PluginConstructor`, `unknown`, `string`>\[] |
package/docs/api/appkit/TypeAlias.CallerPrincipal.md ADDED
@@ -0,0 +1,13 @@
1
+ # Type Alias: CallerPrincipal
2
+
3
+ ```ts
4
+ type CallerPrincipal = Readonly<{
5
+ type: "user";
6
+ userEmail?: string;
7
+ userId: string;
8
+ userName?: string;
9
+ }>;
10
+
11
+ ```
12
+
13
+ The caller identity whose permissions authorize execution, not its resources.
package/docs/api/appkit/TypeAlias.ExecutionContext.md ADDED
@@ -0,0 +1,9 @@
1
+ # Type Alias: ExecutionContext
2
+
3
+ ```ts
4
+ type ExecutionContext =
5
+ | ServiceContextState
6
+ | CallerContext
7
+ | UserContext;
8
+
9
+ ```
package/docs/api/appkit/TypeAlias.ExecutionResult.md CHANGED
@@ -7,6 +7,7 @@ type ExecutionResult<T> =
7
7
  ok: true;
8
8
  }
9
9
  | {
10
+ error?: IdentityExpiredError;
10
11
  message: string;
11
12
  ok: false;
12
13
  status: number;
@@ -34,3 +35,67 @@ In production, error messages from non-AppKitError sources are handled as:
34
35
  | Type Parameter |
35
36
  | -------------- |
36
37
  | `T` |
38
+
39
+ ## Type Declaration[​](#type-declaration "Direct link to Type Declaration")
40
+
41
+ ```ts
42
+ {
43
+ data: T;
44
+ ok: true;
45
+ }
46
+
47
+ ```
48
+
49
+ ### data[​](#data "Direct link to data")
50
+
51
+ ```ts
52
+ data: T;
53
+
54
+ ```
55
+
56
+ ### ok[​](#ok "Direct link to ok")
57
+
58
+ ```ts
59
+ ok: true;
60
+
61
+ ```
62
+
63
+ ```ts
64
+ {
65
+ error?: IdentityExpiredError;
66
+ message: string;
67
+ ok: false;
68
+ status: number;
69
+ }
70
+
71
+ ```
72
+
73
+ ### error?[​](#error "Direct link to error?")
74
+
75
+ ```ts
76
+ optional error: IdentityExpiredError;
77
+
78
+ ```
79
+
80
+ Typed credential expiry without changing the existing failure envelope.
81
+
82
+ ### message[​](#message "Direct link to message")
83
+
84
+ ```ts
85
+ message: string;
86
+
87
+ ```
88
+
89
+ ### ok[​](#ok-1 "Direct link to ok")
90
+
91
+ ```ts
92
+ ok: false;
93
+
94
+ ```
95
+
96
+ ### status[​](#status "Direct link to status")
97
+
98
+ ```ts
99
+ status: number;
100
+
101
+ ```
package/docs/api/appkit/TypeAlias.ScopedPluginMap.md ADDED
@@ -0,0 +1,12 @@
1
+ # Type Alias: ScopedPluginMap\<U>
2
+
3
+ ```ts
4
+ type ScopedPluginMap<U> = { [P in U[number] as P["name"]]: ScopedExports<PluginExports<InstanceType<P["plugin"]>>> };
5
+
6
+ ```
7
+
8
+ ## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
9
+
10
+ | Type Parameter |
11
+ | ----------------------------------------------------------------------------------------------------------------------------------- |
12
+ | `U` *extends* readonly [`PluginData`](./docs/api/appkit/TypeAlias.PluginData.md)<`PluginConstructor`, `unknown`, `string`>\[] |
package/docs/api/appkit/TypeAlias.UserContext.md ADDED
@@ -0,0 +1,109 @@
1
+ # ~~Type Alias: UserContext~~
2
+
3
+ ```ts
4
+ type UserContext = {
5
+ client: ServiceContextState["client"];
6
+ isUserContext: true;
7
+ tokenFingerprint?: string;
8
+ userEmail?: string;
9
+ userId: string;
10
+ userName?: string;
11
+ warehouseId?: Promise<string>;
12
+ workspaceId: Promise<string>;
13
+ };
14
+
15
+ ```
16
+
17
+ ## Deprecated[​](#deprecated "Direct link to Deprecated")
18
+
19
+ Use CallerContext and its principal field. Kept for callers that construct the legacy shape or read its flat identity fields.
20
+
21
+ ## Properties[​](#properties "Direct link to Properties")
22
+
23
+ ### ~~client~~[​](#client "Direct link to client")
24
+
25
+ ```ts
26
+ client: ServiceContextState["client"];
27
+
28
+ ```
29
+
30
+ WorkspaceClient authenticated as the user
31
+
32
+ ***
33
+
34
+ ### ~~isUserContext~~[​](#isusercontext "Direct link to isusercontext")
35
+
36
+ ```ts
37
+ isUserContext: true;
38
+
39
+ ```
40
+
41
+ Flag indicating this is a user context
42
+
43
+ ***
44
+
45
+ ### ~~tokenFingerprint?~~[​](#tokenfingerprint "Direct link to tokenfingerprint")
46
+
47
+ ```ts
48
+ optional tokenFingerprint: string;
49
+
50
+ ```
51
+
52
+ Truncated SHA-256 hash of the user's OBO token, used to detect token rotation
53
+
54
+ ***
55
+
56
+ ### ~~userEmail?~~[​](#useremail "Direct link to useremail")
57
+
58
+ ```ts
59
+ optional userEmail: string;
60
+
61
+ ```
62
+
63
+ The user's email (from `x-forwarded-email` header)
64
+
65
+ ***
66
+
67
+ ### ~~userId~~[​](#userid "Direct link to userid")
68
+
69
+ ```ts
70
+ userId: string;
71
+
72
+ ```
73
+
74
+ The user's ID (from request headers)
75
+
76
+ ***
77
+
78
+ ### ~~userName?~~[​](#username "Direct link to username")
79
+
80
+ ```ts
81
+ optional userName: string;
82
+
83
+ ```
84
+
85
+ The user's name (from request headers)
86
+
87
+ ***
88
+
89
+ ### ~~warehouseId?~~[​](#warehouseid "Direct link to warehouseid")
90
+
91
+ ```ts
92
+ optional warehouseId: Promise<string>;
93
+
94
+ ```
95
+
96
+ #### Deprecated[​](#deprecated-1 "Direct link to Deprecated")
97
+
98
+ Use getWarehouseId() from @databricks/appkit.
99
+
100
+ ***
101
+
102
+ ### ~~workspaceId~~[​](#workspaceid "Direct link to workspaceid")
103
+
104
+ ```ts
105
+ workspaceId: Promise<string>;
106
+
107
+ ```
108
+
109
+ Promise that resolves to the workspace ID (inherited from service context)
package/docs/api/appkit/TypeAlias.UserScopedApp.md ADDED
@@ -0,0 +1,39 @@
1
+ # Type Alias: UserScopedApp\<U>
2
+
3
+ ```ts
4
+ type UserScopedApp<U> = ScopedPluginMap<U> & {
5
+ run: Promise<T>;
6
+ };
7
+
8
+ ```
9
+
10
+ ## Type Declaration[​](#type-declaration "Direct link to Type Declaration")
11
+
12
+ ### run()[​](#run "Direct link to run()")
13
+
14
+ ```ts
15
+ run<T>(fn: (kit: ScopedPluginMap<U>) => T | Promise<T>): Promise<T>;
16
+
17
+ ```
18
+
19
+ #### Type Parameters[​](#type-parameters "Direct link to Type Parameters")
20
+
21
+ | Type Parameter |
22
+ | -------------- |
23
+ | `T` |
24
+
25
+ #### Parameters[​](#parameters "Direct link to Parameters")
26
+
27
+ | Parameter | Type |
28
+ | --------- | ---------------------------------------------------------------------------------------------------------------- |
29
+ | `fn` | (`kit`: [`ScopedPluginMap`](./docs/api/appkit/TypeAlias.ScopedPluginMap.md)<`U`>) => `T` \| `Promise`<`T`> |
30
+
31
+ #### Returns[​](#returns "Direct link to Returns")
32
+
33
+ `Promise`<`T`>
34
+
35
+ ## Type Parameters[​](#type-parameters-1 "Direct link to Type Parameters")
36
+
37
+ | Type Parameter |
38
+ | ----------------------------------------------------------------------------------------------------------------------------------- |
39
+ | `U` *extends* readonly [`PluginData`](./docs/api/appkit/TypeAlias.PluginData.md)<`PluginConstructor`, `unknown`, `string`>\[] |
package/docs/api/appkit.md CHANGED
@@ -21,12 +21,14 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
21
21
  | [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. |
22
22
  | [DatabricksAdapter](./docs/api/appkit/Class.DatabricksAdapter.md) | Adapter that talks directly to Databricks Model Serving `/invocations` endpoint. |
23
23
  | [ExecutionError](./docs/api/appkit/Class.ExecutionError.md) | Error thrown when an operation execution fails. Use for statement failures, canceled operations, or unexpected states. |
24
+ | [IdentityExpiredError](./docs/api/appkit/Class.IdentityExpiredError.md) | The downstream service rejected the active caller's credentials. |
24
25
  | [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. |
25
26
  | [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. |
26
27
  | [Plugin](./docs/api/appkit/Class.Plugin.md) | Base abstract class for creating AppKit plugins. |
27
28
  | [PolicyDeniedError](./docs/api/appkit/Class.PolicyDeniedError.md) | Thrown when a policy denies an action. |
28
29
  | [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. |
29
30
  | [ServerError](./docs/api/appkit/Class.ServerError.md) | Error thrown when server lifecycle operations fail. Use for server start/stop issues, configuration conflicts, etc. |
31
+ | [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. |
30
32
  | [SupervisorApiAdapter](./docs/api/appkit/Class.SupervisorApiAdapter.md) | Adapter that calls the Databricks AI Gateway Responses API (`/ai-gateway/mlflow/v1/responses`). |
31
33
  | [TunnelError](./docs/api/appkit/Class.TunnelError.md) | Error thrown when remote tunnel operations fail. Use for tunnel connection issues, message parsing failures, etc. |
32
34
  | [ValidationError](./docs/api/appkit/Class.ValidationError.md) | Error thrown when input validation fails. Use for invalid parameters, missing required fields, or type mismatches. |
@@ -47,6 +49,7 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
47
49
  | [AutoInheritToolsConfig](./docs/api/appkit/Interface.AutoInheritToolsConfig.md) | Auto-inherit configuration. When enabled for a given agent origin, agents with no explicit `tools:` declaration receive every registered ToolProvider plugin tool whose author marked `autoInheritable: true`. Tools without that flag — destructive, state-mutating, or privilege-sensitive — never spread automatically and must be wired via `tools:` (object or function form in code, `plugin:NAME` entries in markdown frontmatter). |
48
50
  | [BasePluginConfig](./docs/api/appkit/Interface.BasePluginConfig.md) | Base configuration interface for AppKit plugins |
49
51
  | [CacheConfig](./docs/api/appkit/Interface.CacheConfig.md) | Configuration for the CacheInterceptor. Controls TTL, size limits, storage backend, and probabilistic cleanup. |
52
+ | [CallerContext](./docs/api/appkit/Interface.CallerContext.md) | Caller identity and workspace for one immutable execution scope. |
50
53
  | [CustomJudgeSpec](./docs/api/appkit/Interface.CustomJudgeSpec.md) | A custom LLM-judge definition: a prompt template and choice→score mapping. |
51
54
  | [DatabaseCredential](./docs/api/appkit/Interface.DatabaseCredential.md) | Database credentials with OAuth token for Postgres connection |
52
55
  | [DatabaseRegistry](./docs/api/appkit/Interface.DatabaseRegistry.md) | CANONICAL augmentation target. Empty by default; the generated `database.d.ts` augments it via `declare module "@databricks/appkit" { interface DatabaseRegistry { ... } }`. |
@@ -134,11 +137,14 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
134
137
 
135
138
  | Type Alias | Description |
136
139
  | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
140
+ | [AgentAuth](./docs/api/appkit/TypeAlias.AgentAuth.md) | Identity an agent runs under. The only value is on-behalf-of-user. |
137
141
  | [AgentEvent](./docs/api/appkit/TypeAlias.AgentEvent.md) | - |
138
142
  | [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.*`). |
139
143
  | [AgentTools](./docs/api/appkit/TypeAlias.AgentTools.md) | Per-agent tool record. String keys map to inline tools, toolkit entries, hosted tools, etc. |
140
144
  | [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. |
145
+ | [AppKitApi](./docs/api/appkit/TypeAlias.AppKitApi.md) | App instance with plugin exports and an explicit caller-scoped entry point. |
141
146
  | [BaseSystemPromptOption](./docs/api/appkit/TypeAlias.BaseSystemPromptOption.md) | - |
147
+ | [CallerPrincipal](./docs/api/appkit/TypeAlias.CallerPrincipal.md) | The caller identity whose permissions authorize execution, not its resources. |
142
148
  | [ConfigSchema](./docs/api/appkit/TypeAlias.ConfigSchema.md) | Configuration schema definition for plugin config. Re-exported from the standard JSON Schema Draft 7 types. |
143
149
  | [DatabaseApiConfig](./docs/api/appkit/TypeAlias.DatabaseApiConfig.md) | Full generated CRUD for every declared table by default. Set false to disable all generated routes, or use an object to restrict tables and writes. Keyed routes require a public primary key; upsert stays programmatic. Route names must start with a letter, contain only letters, digits, `_`, or `-`, be at most 64 characters, and be unique ignoring case. Invalid names fail setup; exclude internal tables with `api.tables` or use `api: false`. |
144
150
  | [DatabaseApiWriteOperation](./docs/api/appkit/TypeAlias.DatabaseApiWriteOperation.md) | Generated HTTP write operations. |
@@ -146,6 +152,7 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
146
152
  | [DatabaseExports](./docs/api/appkit/TypeAlias.DatabaseExports.md) | Typed database API published by the plugin. |
147
153
  | [EntityHooks](./docs/api/appkit/TypeAlias.EntityHooks.md) | Response shaping and mutation lifecycle declared for one table. |
148
154
  | [EvalProgress](./docs/api/appkit/TypeAlias.EvalProgress.md) | - |
155
+ | [ExecutionContext](./docs/api/appkit/TypeAlias.ExecutionContext.md) | - |
149
156
  | [ExecutionResult](./docs/api/appkit/TypeAlias.ExecutionResult.md) | Discriminated union for plugin execution results. |
150
157
  | [FileAction](./docs/api/appkit/TypeAlias.FileAction.md) | Every action the files plugin can perform. |
151
158
  | [FilePolicy](./docs/api/appkit/TypeAlias.FilePolicy.md) | A policy function that decides whether `user` may perform `action` on `resource`. Return `true` to allow, `false` to deny. |
@@ -160,6 +167,7 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
160
167
  | [ResolvedToolEntry](./docs/api/appkit/TypeAlias.ResolvedToolEntry.md) | Internal tool-index entry after a tool record has been resolved to a dispatchable form. |
161
168
  | [ResourceFieldEntry](./docs/api/appkit/TypeAlias.ResourceFieldEntry.md) | - |
162
169
  | [ResourcePermission](./docs/api/appkit/TypeAlias.ResourcePermission.md) | Union of all possible permission levels across all resource types. |
170
+ | [ScopedPluginMap](./docs/api/appkit/TypeAlias.ScopedPluginMap.md) | - |
163
171
  | [SearchFilters](./docs/api/appkit/TypeAlias.SearchFilters.md) | - |
164
172
  | [ServingFactory](./docs/api/appkit/TypeAlias.ServingFactory.md) | Factory function returned by `AppKit.serving`. |
165
173
  | [Severity](./docs/api/appkit/TypeAlias.Severity.md) | Whether an assertion fails the eval (`gate`) or is tracked only (`soft`). |
@@ -167,6 +175,8 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
167
175
  | [ToolRegistry](./docs/api/appkit/TypeAlias.ToolRegistry.md) | - |
168
176
  | [ToPlugin](./docs/api/appkit/TypeAlias.ToPlugin.md) | Factory function type returned by `toPlugin()`. Accepts optional config and returns a PluginData tuple. |
169
177
  | [TransactionClient](./docs/api/appkit/TypeAlias.TransactionClient.md) | Entity and SQL capabilities bound to one transaction. |
178
+ | [~~UserContext~~](./docs/api/appkit/TypeAlias.UserContext.md) | - |
179
+ | [UserScopedApp](./docs/api/appkit/TypeAlias.UserScopedApp.md) | - |
170
180
 
171
181
  ## Variables[​](#variables "Direct link to Variables")
172
182
 
@@ -223,22 +233,30 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
223
233
  | [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`). |
224
234
  | [functionToolToDefinition](./docs/api/appkit/Function.functionToolToDefinition.md) | - |
225
235
  | [generateDatabaseCredential](./docs/api/appkit/Function.generateDatabaseCredential.md) | Generate OAuth credentials for Postgres database connection using the proper Postgres API. |
236
+ | [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. |
237
+ | [getCurrentActorId](./docs/api/appkit/Function.getCurrentActorId.md) | The initiating user in a caller scope; no user actor exists in service scope. |
238
+ | [getCurrentPrincipalKey](./docs/api/appkit/Function.getCurrentPrincipalKey.md) | Get the principal key for future cache keying: `app` or `user:<id>`. |
239
+ | [~~getCurrentUserId~~](./docs/api/appkit/Function.getCurrentUserId.md) | - |
226
240
  | [getExecutionContext](./docs/api/appkit/Function.getExecutionContext.md) | Get the current execution context. |
227
241
  | [getLakebaseOrmConfig](./docs/api/appkit/Function.getLakebaseOrmConfig.md) | Get Lakebase connection configuration for ORMs that don't accept pg.Pool directly. |
228
242
  | [getLakebasePgConfig](./docs/api/appkit/Function.getLakebasePgConfig.md) | Get Lakebase connection configuration for PostgreSQL clients. |
229
243
  | [getPluginManifest](./docs/api/appkit/Function.getPluginManifest.md) | Loads and validates the manifest from a plugin constructor. Normalizes string type/permission to strict ResourceType/ResourcePermission. |
230
244
  | [getResourceRequirements](./docs/api/appkit/Function.getResourceRequirements.md) | Gets the resource requirements from a plugin's manifest. |
245
+ | [~~getUserContext~~](./docs/api/appkit/Function.getUserContext.md) | - |
231
246
  | [getUsernameWithApiLookup](./docs/api/appkit/Function.getUsernameWithApiLookup.md) | Resolves the PostgreSQL username for a Lakebase connection. |
247
+ | [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. |
232
248
  | [getWorkspaceClient](./docs/api/appkit/Function.getWorkspaceClient.md) | Get workspace client from config or SDK default auth chain |
233
249
  | [id](./docs/api/appkit/Function.id.md) | - |
234
250
  | [includes](./docs/api/appkit/Function.includes.md) | Passes when the value contains `substring`. |
235
251
  | [integer](./docs/api/appkit/Function.integer.md) | - |
236
252
  | [isFunctionTool](./docs/api/appkit/Function.isFunctionTool.md) | - |
237
253
  | [isHostedTool](./docs/api/appkit/Function.isHostedTool.md) | - |
254
+ | [isInUserContext](./docs/api/appkit/Function.isInUserContext.md) | Check if currently running in a user context. |
238
255
  | [isJudgeConfigured](./docs/api/appkit/Function.isJudgeConfigured.md) | - |
239
256
  | [isSQLTypeMarker](./docs/api/appkit/Function.isSQLTypeMarker.md) | Type guard to check if a value is a SQL type marker |
240
257
  | [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. |
241
258
  | [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. |
259
+ | [~~isUserContext~~](./docs/api/appkit/Function.isUserContext.md) | - |
242
260
  | [jsonb](./docs/api/appkit/Function.jsonb.md) | - |
243
261
  | [loadAgentFromFile](./docs/api/appkit/Function.loadAgentFromFile.md) | Loads a single markdown agent file and resolves its frontmatter against registered plugin toolkits + ambient tool library. |
244
262
  | [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. |
@@ -255,6 +273,8 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
255
273
  | [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. |
256
274
  | [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`. |
257
275
  | [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. |
276
+ | [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. |
277
+ | [~~runInUserContext~~](./docs/api/appkit/Function.runInUserContext.md) | - |
258
278
  | [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. |
259
279
  | [summarize](./docs/api/appkit/Function.summarize.md) | - |
260
280
  | [text](./docs/api/appkit/Function.text.md) | - |