@databricks/appkit-ui 0.47.1 → 0.49.0

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

@@ -75,6 +75,24 @@ Omit.description
 
 ***
 
+### devOnly?[​](#devonly "Direct link to devOnly?")
+
+```ts
+optional devOnly: boolean;
+
+```
+
+When true, this plugin is only registered when NODE\_ENV === "development". In any other environment createApp skips it entirely (not constructed, no routes, resources not validated). Use for dev-only tooling that must never run in a deployed app.
+
+#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")
+
+```ts
+Omit.devOnly
+
+```
+
+***
+
 ### displayName[​](#displayname "Direct link to displayName")
 
 ```ts
@@ -84,7 +102,7 @@ displayName: string;
 
 Human-readable display name for UI and CLI
 
-#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")
 
 ```ts
 Omit.displayName
@@ -102,7 +120,7 @@ optional hidden: boolean;
 
 When true, this plugin is excluded from the template plugins manifest (appkit.plugins.json) during sync.
 
-#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-4 "Direct link to Inherited from")
 
 ```ts
 Omit.hidden
@@ -120,7 +138,7 @@ optional keywords: string[];
 
 Keywords for plugin discovery
 
-#### Inherited from[​](#inherited-from-4 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-5 "Direct link to Inherited from")
 
 ```ts
 Omit.keywords
@@ -138,7 +156,7 @@ optional license: string;
 
 SPDX license identifier
 
-#### Inherited from[​](#inherited-from-5 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-6 "Direct link to Inherited from")
 
 ```ts
 Omit.license
@@ -174,7 +192,7 @@ optional onSetupMessage: string;
 
 Message displayed to the user after project initialization. Use this to inform about manual setup steps (e.g. environment variables, resource provisioning).
 
-#### Inherited from[​](#inherited-from-6 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-7 "Direct link to Inherited from")
 
 ```ts
 Omit.onSetupMessage
@@ -192,7 +210,7 @@ optional repository: string;
 
 URL to the plugin's source repository
 
-#### Inherited from[​](#inherited-from-7 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-8 "Direct link to Inherited from")
 
 ```ts
 Omit.repository
@@ -278,7 +296,7 @@ optional should: string[];
 
 ```
 
-#### Inherited from[​](#inherited-from-8 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-9 "Direct link to Inherited from")
 
 ```ts
 Omit.scaffolding
@@ -296,7 +314,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-9 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-10 "Direct link to Inherited from")
 
 ```ts
 Omit.stability
@@ -314,7 +332,7 @@ optional version: string;
 
 Plugin version (semver format)
 
-#### Inherited from[​](#inherited-from-10 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-11 "Direct link to Inherited from")
 
 ```ts
 Omit.version

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

@@ -0,0 +1,38 @@
+# Interface: SupervisorApiAdapterOptions
+
+## Properties[​](#properties "Direct link to Properties")
+
+### model[​](#model "Direct link to model")
+
+```ts
+model: string;
+
+```
+
+Model identifier to pass in the request body (e.g. "databricks-claude-sonnet-4").
+
+***
+
+### timeoutMs?[​](#timeoutms "Direct link to timeoutMs?")
+
+```ts
+optional timeoutMs: number;
+
+```
+
+Total wall-clock budget (ms) for a single `run()`. When the SSE stream runs longer than this — e.g. an upstream that stalls without closing — the adapter aborts it and emits a terminal `transport` error rather than hanging the request indefinitely.
+
+This is a total-duration cap, not an idle cap. Defaults to 5 minutes, generous enough for multi-tool server-side orchestration.
+
+***
+
+### workspaceClient?[​](#workspaceclient "Direct link to workspaceClient?")
+
+```ts
+optional workspaceClient: WorkspaceClientLike;
+
+```
+
+A WorkspaceClient (or structural equivalent) used for host resolution and per-request authentication. When omitted, a `WorkspaceClient({})` is created internally using the default SDK credential chain (`DATABRICKS_HOST`, OAuth, PAT, etc.).
+
+⚠ The `workspaceClient` is captured at construction and reused across every request. Passing a per-request OBO (On-Behalf-Of) client here would silently leak the first request's identity into all subsequent requests served by this adapter instance. Use the default credential chain or pass a service-principal client. (CWE-664)

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

@@ -0,0 +1,12 @@
+# Interface: SupervisorExtension
+
+Shape of the value at `AgentInput.extensions[SUPERVISOR_EXTENSION_KEY]`. The agents plugin / `runAgent` build this from the tool index; advanced callers invoking `adapter.run(...)` directly populate it themselves.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### hostedTools?[​](#hostedtools "Direct link to hostedTools?")
+
+```ts
+optional hostedTools: SupervisorTool[];
+
+```

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

@@ -0,0 +1,67 @@
+# Interface: WorkspaceClientLike
+
+Structural shape of a Databricks SDK client used by [fromSupervisorApi](./docs/api/appkit/Function.fromSupervisorApi.md). Only what we need: `apiClient.request` for streaming and `config.ensureResolved` to materialise the host/credentials.
+
+Exported because [SupervisorApiAdapterOptions.workspaceClient](./docs/api/appkit/Interface.SupervisorApiAdapterOptions.md#workspaceclient) (a public type) references it — callers passing their own client can name the shape they need to satisfy.
+
+## Extends[​](#extends "Direct link to Extends")
+
+* `ApiClientLike`
+
+## Properties[​](#properties "Direct link to Properties")
+
+### apiClient[​](#apiclient "Direct link to apiClient")
+
+```ts
+apiClient: {
+  request: Promise<unknown>;
+};
+
+```
+
+#### request()[​](#request "Direct link to request()")
+
+```ts
+request(options: Record<string, unknown>, context?: unknown): Promise<unknown>;
+
+```
+
+##### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter  | Type                          |
+| ---------- | ----------------------------- |
+| `options`  | `Record`<`string`, `unknown`> |
+| `context?` | `unknown`                     |
+
+##### Returns[​](#returns "Direct link to Returns")
+
+`Promise`<`unknown`>
+
+#### Inherited from[​](#inherited-from "Direct link to Inherited from")
+
+```ts
+ApiClientLike.apiClient
+
+```
+
+***
+
+### config[​](#config "Direct link to config")
+
+```ts
+config: {
+  ensureResolved: Promise<void>;
+};
+
+```
+
+#### ensureResolved()[​](#ensureresolved "Direct link to ensureResolved()")
+
+```ts
+ensureResolved(): Promise<void>;
+
+```
+
+##### Returns[​](#returns-1 "Direct link to Returns")
+
+`Promise`<`void`>

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

@@ -4,8 +4,9 @@
 type AgentTool = 
   | FunctionTool
   | HostedTool
-  | ToolkitEntry;
+  | ToolkitEntry
+  | HostedSupervisorTool;
 
 ```
 
-Any tool an agent can invoke: inline function tools (`tool()`), hosted MCP tools (`mcpServer()` / raw hosted), or toolkit references from plugins (`analytics().toolkit()`).
+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.*`).

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

@@ -22,8 +22,175 @@ type ResolvedToolEntry =
   agentName: string;
   def: AgentToolDefinition;
   source: "subagent";
+}
+  | {
+  def: AgentToolDefinition;
+  source: "hosted-supervisor";
+  spec: SupervisorTool;
 };
 
 ```
 
 Internal tool-index entry after a tool record has been resolved to a dispatchable form.
+
+## Type Declaration[​](#type-declaration "Direct link to Type Declaration")
+
+```ts
+{
+  def: AgentToolDefinition;
+  localName: string;
+  pluginName: string;
+  source: "toolkit";
+}
+
+```
+
+### def[​](#def "Direct link to def")
+
+```ts
+def: AgentToolDefinition;
+
+```
+
+### localName[​](#localname "Direct link to localName")
+
+```ts
+localName: string;
+
+```
+
+### pluginName[​](#pluginname "Direct link to pluginName")
+
+```ts
+pluginName: string;
+
+```
+
+### source[​](#source "Direct link to source")
+
+```ts
+source: "toolkit";
+
+```
+
+```ts
+{
+  def: AgentToolDefinition;
+  functionTool: FunctionTool;
+  source: "function";
+}
+
+```
+
+### def[​](#def-1 "Direct link to def")
+
+```ts
+def: AgentToolDefinition;
+
+```
+
+### functionTool[​](#functiontool "Direct link to functionTool")
+
+```ts
+functionTool: FunctionTool;
+
+```
+
+### source[​](#source-1 "Direct link to source")
+
+```ts
+source: "function";
+
+```
+
+```ts
+{
+  def: AgentToolDefinition;
+  mcpToolName: string;
+  source: "mcp";
+}
+
+```
+
+### def[​](#def-2 "Direct link to def")
+
+```ts
+def: AgentToolDefinition;
+
+```
+
+### mcpToolName[​](#mcptoolname "Direct link to mcpToolName")
+
+```ts
+mcpToolName: string;
+
+```
+
+### source[​](#source-2 "Direct link to source")
+
+```ts
+source: "mcp";
+
+```
+
+```ts
+{
+  agentName: string;
+  def: AgentToolDefinition;
+  source: "subagent";
+}
+
+```
+
+### agentName[​](#agentname "Direct link to agentName")
+
+```ts
+agentName: string;
+
+```
+
+### def[​](#def-3 "Direct link to def")
+
+```ts
+def: AgentToolDefinition;
+
+```
+
+### source[​](#source-3 "Direct link to source")
+
+```ts
+source: "subagent";
+
+```
+
+```ts
+{
+  def: AgentToolDefinition;
+  source: "hosted-supervisor";
+  spec: SupervisorTool;
+}
+
+```
+
+### def[​](#def-4 "Direct link to def")
+
+```ts
+def: AgentToolDefinition;
+
+```
+
+### source[​](#source-4 "Direct link to source")
+
+```ts
+source: "hosted-supervisor";
+
+```
+
+Adapter-side hosted tool (executed by the model-host, not by the Node process). Today: Supervisor API hosted tools (Genie spaces, UC functions, etc.). The `spec` is opaque to the agents plugin — it routes the entry into `AgentInput.extensions` for the adapter that declared the matching `acceptsExtensions` key. `def` is a synthetic placeholder kept so the index has a uniform shape; it is intentionally NOT included in the `tools` array passed to `adapter.run()` (those entries are not callable functions).
+
+### spec[​](#spec "Direct link to spec")
+
+```ts
+spec: SupervisorTool;
+
+```

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

@@ -0,0 +1,45 @@
+# Type Alias: SupervisorTool
+
+```ts
+type SupervisorTool = 
+  | {
+  genie_space: {
+     description: string;
+     id: string;
+  };
+  type: "genie_space";
+}
+  | {
+  type: "uc_function";
+  uc_function: {
+     description: string;
+     name: string;
+  };
+}
+  | {
+  knowledge_assistant: {
+     description: string;
+     knowledge_assistant_id: string;
+  };
+  type: "knowledge_assistant";
+}
+  | {
+  app: {
+     description: string;
+     name: string;
+  };
+  type: "app";
+}
+  | {
+  type: "uc_connection";
+  uc_connection: {
+     description: string;
+     name: string;
+  };
+};
+
+```
+
+Tools supported by the Databricks AI Gateway Responses API. The shapes match the wire format the endpoint expects, so the adapter passes the array straight into the request body.
+
+This is an adapter-internal wire type. Application code authors tools via the [supervisorTools](./docs/api/appkit/Variable.supervisorTools.md) factories, which return tagged [HostedSupervisorTool](./docs/api/appkit/Interface.HostedSupervisorTool.md) records — the agents plugin then unwraps the `.spec` when routing through [AgentInput.extensions](./docs/api/appkit/Interface.AgentInput.md#extensions).

package/docs/api/appkit/Variable.SUPERVISOR_EXTENSION_KEY.md

@@ -0,0 +1,8 @@
+# Variable: SUPERVISOR\_EXTENSION\_KEY
+
+```ts
+const SUPERVISOR_EXTENSION_KEY: "databricks.supervisor";
+
+```
+
+Namespace key under which the adapter reads its hosted-tool payload from [AgentInput.extensions](./docs/api/appkit/Interface.AgentInput.md#extensions). Exported so the agents plugin and standalone `runAgent` (the producers) can write under the same key the adapter reads.

package/docs/api/appkit/Variable.supervisorTools.md

@@ -0,0 +1,176 @@
+# Variable: supervisorTools
+
+```ts
+const supervisorTools: {
+  app: (__namedParameters: {
+     description: string;
+     name: string;
+  }) => HostedSupervisorTool;
+  genieSpace: (__namedParameters: {
+     description: string;
+     id: string;
+  }) => HostedSupervisorTool;
+  knowledgeAssistant: (__namedParameters: {
+     description: string;
+     knowledgeAssistantId: string;
+  }) => HostedSupervisorTool;
+  ucConnection: (__namedParameters: {
+     description: string;
+     name: string;
+  }) => HostedSupervisorTool;
+  ucFunction: (__namedParameters: {
+     description: string;
+     name: string;
+  }) => HostedSupervisorTool;
+};
+
+```
+
+Concise factories for declaring Supervisor API tools.
+
+Each factory accepts a single named-options object: routing-critical strings (`id`, `name`, `description`) get labels at the call site so "we swapped the args and didn't notice for two weeks" bugs are impossible.
+
+`description` is required: SA's protobuf validation rejects `null`/`""`, AND the LLM running on SA reads this string to decide when to route to the tool. Two genie spaces both labelled "Genie space" give the model nothing to discriminate on, so callers always own the routing hint.
+
+⚠ The `description` is read by the LLM at routing time — it is a prompt-injection sink. Do **not** derive it from untrusted input (user messages, request bodies, external systems). Treat it as application configuration. (CWE-1427)
+
+## Type Declaration[​](#type-declaration "Direct link to Type Declaration")
+
+### app()[​](#app "Direct link to app()")
+
+```ts
+app: (__namedParameters: {
+  description: string;
+  name: string;
+}) => HostedSupervisorTool;
+
+```
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter                       | Type                                           |
+| ------------------------------- | ---------------------------------------------- |
+| `__namedParameters`             | { `description`: `string`; `name`: `string`; } |
+| `__namedParameters.description` | `string`                                       |
+| `__namedParameters.name`        | `string`                                       |
+
+#### Returns[​](#returns "Direct link to Returns")
+
+[`HostedSupervisorTool`](./docs/api/appkit/Interface.HostedSupervisorTool.md)
+
+### genieSpace()[​](#geniespace "Direct link to genieSpace()")
+
+```ts
+genieSpace: (__namedParameters: {
+  description: string;
+  id: string;
+}) => HostedSupervisorTool;
+
+```
+
+#### Parameters[​](#parameters-1 "Direct link to Parameters")
+
+| Parameter                       | Type                                         |
+| ------------------------------- | -------------------------------------------- |
+| `__namedParameters`             | { `description`: `string`; `id`: `string`; } |
+| `__namedParameters.description` | `string`                                     |
+| `__namedParameters.id`          | `string`                                     |
+
+#### Returns[​](#returns-1 "Direct link to Returns")
+
+[`HostedSupervisorTool`](./docs/api/appkit/Interface.HostedSupervisorTool.md)
+
+### knowledgeAssistant()[​](#knowledgeassistant "Direct link to knowledgeAssistant()")
+
+```ts
+knowledgeAssistant: (__namedParameters: {
+  description: string;
+  knowledgeAssistantId: string;
+}) => HostedSupervisorTool;
+
+```
+
+#### Parameters[​](#parameters-2 "Direct link to Parameters")
+
+| Parameter                                | Type                                                           |
+| ---------------------------------------- | -------------------------------------------------------------- |
+| `__namedParameters`                      | { `description`: `string`; `knowledgeAssistantId`: `string`; } |
+| `__namedParameters.description`          | `string`                                                       |
+| `__namedParameters.knowledgeAssistantId` | `string`                                                       |
+
+#### Returns[​](#returns-2 "Direct link to Returns")
+
+[`HostedSupervisorTool`](./docs/api/appkit/Interface.HostedSupervisorTool.md)
+
+### ucConnection()[​](#ucconnection "Direct link to ucConnection()")
+
+```ts
+ucConnection: (__namedParameters: {
+  description: string;
+  name: string;
+}) => HostedSupervisorTool;
+
+```
+
+#### Parameters[​](#parameters-3 "Direct link to Parameters")
+
+| Parameter                       | Type                                           |
+| ------------------------------- | ---------------------------------------------- |
+| `__namedParameters`             | { `description`: `string`; `name`: `string`; } |
+| `__namedParameters.description` | `string`                                       |
+| `__namedParameters.name`        | `string`                                       |
+
+#### Returns[​](#returns-3 "Direct link to Returns")
+
+[`HostedSupervisorTool`](./docs/api/appkit/Interface.HostedSupervisorTool.md)
+
+### ucFunction()[​](#ucfunction "Direct link to ucFunction()")
+
+```ts
+ucFunction: (__namedParameters: {
+  description: string;
+  name: string;
+}) => HostedSupervisorTool;
+
+```
+
+#### Parameters[​](#parameters-4 "Direct link to Parameters")
+
+| Parameter                       | Type                                           |
+| ------------------------------- | ---------------------------------------------- |
+| `__namedParameters`             | { `description`: `string`; `name`: `string`; } |
+| `__namedParameters.description` | `string`                                       |
+| `__namedParameters.name`        | `string`                                       |
+
+#### Returns[​](#returns-4 "Direct link to Returns")
+
+[`HostedSupervisorTool`](./docs/api/appkit/Interface.HostedSupervisorTool.md)
+
+## Example[​](#example "Direct link to Example")
+
+```ts
+import { createAgent } from "@databricks/appkit";
+import {
+  agents,
+  DatabricksAdapter,
+  supervisorTools,
+} from "@databricks/appkit/beta";
+
+const assistant = createAgent({
+  instructions: "You are a helpful assistant.",
+  model: DatabricksAdapter.fromSupervisorApi({
+    model: "databricks-claude-sonnet-4",
+  }),
+  tools: () => ({
+    nyc: supervisorTools.genieSpace({
+      id: "01ABCDEF12345678",
+      description: "NYC taxi trip records and zones",
+    }),
+    add: supervisorTools.ucFunction({
+      name: "main.default.add",
+      description: "Adds two integers and returns the sum.",
+    }),
+  }),
+});
+
+```