@databricks/appkit 0.48.0 → 0.50.0

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

@@ -149,3 +149,37 @@ Routes through the shared `connectors/serving/stream` helper, which delegates to
 #### Returns[​](#returns-3 "Direct link to Returns")
 
 `Promise`<`DatabricksAdapter`>
+
+***
+
+### fromSupervisorApi()[​](#fromsupervisorapi "Direct link to fromSupervisorApi()")
+
+```ts
+static fromSupervisorApi(options: SupervisorApiAdapterOptions): Promise<AgentAdapter>;
+
+```
+
+Discoverability shim for the Supervisor API adapter. Returns an [AgentAdapter](./docs/api/appkit/Interface.AgentAdapter.md) (a `SupervisorApiAdapter` at runtime), NOT a DatabricksAdapter — the two are separate classes (different wire formats, different lifecycle). The return type is the [AgentAdapter](./docs/api/appkit/Interface.AgentAdapter.md) interface so callers aren't bound to the concrete class. Surfaced here so application developers see a single `DatabricksAdapter.from*` autocomplete root.
+
+Dynamic-imports `./supervisor-api` to avoid forming a load-time cycle: both files share `connectors/serving/client.ts`.
+
+#### Parameters[​](#parameters-4 "Direct link to Parameters")
+
+| Parameter | Type                                                                                              |
+| --------- | ------------------------------------------------------------------------------------------------- |
+| `options` | [`SupervisorApiAdapterOptions`](./docs/api/appkit/Interface.SupervisorApiAdapterOptions.md) |
+
+#### Returns[​](#returns-4 "Direct link to Returns")
+
+`Promise`<[`AgentAdapter`](./docs/api/appkit/Interface.AgentAdapter.md)>
+
+#### Example[​](#example-1 "Direct link to Example")
+
+```ts
+import { DatabricksAdapter } from "@databricks/appkit/beta";
+
+const model = await DatabricksAdapter.fromSupervisorApi({
+  model: "databricks-claude-sonnet-4-5",
+});
+
+```

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

@@ -0,0 +1,121 @@
+# Class: SupervisorApiAdapter
+
+Adapter that calls the Databricks AI Gateway Responses API (`/ai-gateway/mlflow/v1/responses`).
+
+Streams SSE events in the OpenAI Responses API wire format and maps them to the AppKit `AgentEvent` protocol. Tool execution is handled server-side, so the adapter ignores the agents-plugin tool index.
+
+Authentication is handled via the Databricks SDK credential chain — the same mechanism used by `DatabricksAdapter.fromModelServing`. The transport is injected via SupervisorApiAdapterCtorOptions.streamBody; the [fromSupervisorApi](./docs/api/appkit/Function.fromSupervisorApi.md) factory wires it through the SDK's `apiClient.request({ raw: true })`.
+
+Set `DEBUG=appkit:agents:supervisor-api` to log the outbound request shape (model, instructions length, input shape, tool count) and to be notified when the recovery path engages (no incremental deltas, text pulled from `response.completed.output[]`). The no-delta warning includes a per-turn event-type histogram and the SA-reported status/error/ incomplete\_details, so it's already actionable without DEBUG.
+
+Tools are not configured on the adapter. Declare them via `createAgent({ tools: () => ({ key: supervisorTools.genieSpace({...}) }) })` (or markdown frontmatter referencing an ambient `supervisorTools.*` entry); the agents plugin / standalone `runAgent` aggregates hosted-supervisor entries and routes them to the adapter via `AgentInput.extensions[SUPERVISOR_EXTENSION_KEY]`. Advanced callers invoking `adapter.run(...)` directly populate that key themselves.
+
+## Example[​](#example "Direct link to Example")
+
+```ts
+import { createApp, createAgent } from "@databricks/appkit";
+import {
+  agents,
+  DatabricksAdapter,
+  supervisorTools,
+} from "@databricks/appkit/beta";
+
+await createApp({
+  plugins: [
+    agents({
+      agents: {
+        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",
+            }),
+          }),
+        }),
+      },
+    }),
+  ],
+});
+
+```
+
+## Implements[​](#implements "Direct link to Implements")
+
+* [`AgentAdapter`](./docs/api/appkit/Interface.AgentAdapter.md)
+
+## Constructors[​](#constructors "Direct link to Constructors")
+
+### Constructor[​](#constructor "Direct link to Constructor")
+
+```ts
+new SupervisorApiAdapter(options: SupervisorApiAdapterCtorOptions): SupervisorApiAdapter;
+
+```
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                              |
+| --------- | --------------------------------- |
+| `options` | `SupervisorApiAdapterCtorOptions` |
+
+#### Returns[​](#returns "Direct link to Returns")
+
+`SupervisorApiAdapter`
+
+## Properties[​](#properties "Direct link to Properties")
+
+### acceptsExtensions[​](#acceptsextensions "Direct link to acceptsExtensions")
+
+```ts
+readonly acceptsExtensions: readonly ["databricks.supervisor"];
+
+```
+
+Capability negotiation: the adapter reads its hosted-tool payload from [AgentInput.extensions](./docs/api/appkit/Interface.AgentInput.md#extensions) under [SUPERVISOR\_EXTENSION\_KEY](./docs/api/appkit/Variable.SUPERVISOR_EXTENSION_KEY.md). The agents plugin uses this list to warn at registration when the tool index produces extensions the adapter wouldn't consume.
+
+#### Implementation of[​](#implementation-of "Direct link to Implementation of")
+
+[`AgentAdapter`](./docs/api/appkit/Interface.AgentAdapter.md).[`acceptsExtensions`](./docs/api/appkit/Interface.AgentAdapter.md#acceptsextensions)
+
+***
+
+### consumesInputTools[​](#consumesinputtools "Direct link to consumesInputTools")
+
+```ts
+readonly consumesInputTools: false = false;
+
+```
+
+Capability negotiation: the adapter does not consume `input.tools`. Tool execution is owned by the Databricks AI Gateway server-side, so any function tools or local sub-agents declared on this agent would be silently dropped — the agents plugin warns at registration when that combination is detected.
+
+#### Implementation of[​](#implementation-of-1 "Direct link to Implementation of")
+
+[`AgentAdapter`](./docs/api/appkit/Interface.AgentAdapter.md).[`consumesInputTools`](./docs/api/appkit/Interface.AgentAdapter.md#consumesinputtools)
+
+## Methods[​](#methods "Direct link to Methods")
+
+### run()[​](#run "Direct link to run()")
+
+```ts
+run(input: AgentInput, context: AgentRunContext): AsyncGenerator<AgentEvent, void, unknown>;
+
+```
+
+#### Parameters[​](#parameters-1 "Direct link to Parameters")
+
+| Parameter | Type                                                                      |
+| --------- | ------------------------------------------------------------------------- |
+| `input`   | [`AgentInput`](./docs/api/appkit/Interface.AgentInput.md)           |
+| `context` | [`AgentRunContext`](./docs/api/appkit/Interface.AgentRunContext.md) |
+
+#### Returns[​](#returns-1 "Direct link to Returns")
+
+`AsyncGenerator`<[`AgentEvent`](./docs/api/appkit/TypeAlias.AgentEvent.md), `void`, `unknown`>
+
+#### Implementation of[​](#implementation-of-2 "Direct link to Implementation of")
+
+[`AgentAdapter`](./docs/api/appkit/Interface.AgentAdapter.md).[`run`](./docs/api/appkit/Interface.AgentAdapter.md#run)

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

@@ -0,0 +1,63 @@
+# Function: fromSupervisorApi()
+
+```ts
+function fromSupervisorApi(options: SupervisorApiAdapterOptions): Promise<AgentAdapter>;
+
+```
+
+Creates an [AgentAdapter](./docs/api/appkit/Interface.AgentAdapter.md) backed by the Databricks AI Gateway Responses API (`/ai-gateway/mlflow/v1/responses`).
+
+Uses the SDK's default credential chain for auth (reads DATABRICKS\_HOST, DATABRICKS\_TOKEN, OAuth config, etc.). Tools are declared on the agent (via `createAgent({ tools })`), not on this factory.
+
+Application code should prefer the [DatabricksAdapter.fromSupervisorApi](./docs/api/appkit/Class.DatabricksAdapter.md#fromsupervisorapi) static — it delegates here and keeps a single `DatabricksAdapter.from*` autocomplete root for all Databricks-backed adapters. This free function is the implementation behind the static and remains exported for callers that want to import it directly without pulling in [DatabricksAdapter](./docs/api/appkit/Class.DatabricksAdapter.md).
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                                                                                              |
+| --------- | ------------------------------------------------------------------------------------------------- |
+| `options` | [`SupervisorApiAdapterOptions`](./docs/api/appkit/Interface.SupervisorApiAdapterOptions.md) |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`Promise`<[`AgentAdapter`](./docs/api/appkit/Interface.AgentAdapter.md)>
+
+## Example[​](#example "Direct link to Example")
+
+```ts
+import { createApp, createAgent } from "@databricks/appkit";
+import {
+  agents,
+  DatabricksAdapter,
+  supervisorTools,
+} from "@databricks/appkit/beta";
+
+await createApp({
+  plugins: [
+    agents({
+      agents: {
+        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",
+            }),
+          }),
+        }),
+      },
+    }),
+  ],
+});
+
+```
+
+## Remarks[​](#remarks "Direct link to Remarks")
+
+⚠ When passing your own `workspaceClient`, see the warning on [SupervisorApiAdapterOptions.workspaceClient](./docs/api/appkit/Interface.SupervisorApiAdapterOptions.md#workspaceclient) — the client is captured once and reused, so per-request OBO clients would leak identity across requests.
+
+## See[​](#see "Direct link to See")
+
+[DatabricksAdapter.fromSupervisorApi](./docs/api/appkit/Class.DatabricksAdapter.md#fromsupervisorapi) — the recommended application-facing entry point.

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

@@ -0,0 +1,18 @@
+# Function: isSupervisorTool()
+
+```ts
+function isSupervisorTool(value: unknown): value is HostedSupervisorTool;
+
+```
+
+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.
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type      |
+| --------- | --------- |
+| `value`   | `unknown` |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`value is HostedSupervisorTool`

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

@@ -1,5 +1,29 @@
 # Interface: AgentAdapter
 
+## Properties[​](#properties "Direct link to Properties")
+
+### acceptsExtensions?[​](#acceptsextensions "Direct link to acceptsExtensions?")
+
+```ts
+readonly optional acceptsExtensions: readonly string[];
+
+```
+
+Extension keys this adapter consumes from [AgentInput.extensions](./docs/api/appkit/Interface.AgentInput.md#extensions). The agents plugin (and standalone `runAgent`) warns at registration if the tool index produces extensions whose keys aren't listed here.
+
+Adapters that don't read extensions can omit this field.
+
+***
+
+### consumesInputTools?[​](#consumesinputtools "Direct link to consumesInputTools?")
+
+```ts
+readonly optional consumesInputTools: boolean;
+
+```
+
+Whether the adapter consumes tools from `input.tools`. Defaults to true. Adapters whose tool execution happens elsewhere (e.g. the Supervisor API, where SA owns the tool loop server-side) declare false; the agents plugin warns at registration if the agent declares function tools or local sub-agents alongside such an adapter, since those tools would never reach the model.
+
 ## Methods[​](#methods "Direct link to Methods")
 
 ### run()[​](#run "Direct link to run()")

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

@@ -2,6 +2,19 @@
 
 ## Properties[​](#properties "Direct link to Properties")
 
+### extensions?[​](#extensions "Direct link to extensions?")
+
+```ts
+optional extensions: Readonly<Record<string, unknown>>;
+
+```
+
+Adapter-specific opaque payloads, keyed by adapter namespace. The shared contract intentionally does not enumerate keys — see each adapter's docs for which keys it reads and the shape of each value.
+
+The agents plugin and standalone `runAgent` populate this from the agent's tool index when entries declare an adapter-side spec (e.g. Supervisor API hosted tools). Adapters that don't read extensions should leave it untouched.
+
+***
+
 ### messages[​](#messages "Direct link to messages")
 
 ```ts

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

@@ -0,0 +1,21 @@
+# Interface: HostedSupervisorTool
+
+Tagged record returned by every [supervisorTools](./docs/api/appkit/Variable.supervisorTools.md) factory. The `__kind` discriminator lets the agents plugin (and standalone `runAgent`) classify these tools without a structural match against the wire format — keeps the SA wire shape free to evolve and avoids namespace collisions with MCP hosted tools (which use `type: "genie-space"` hyphenated, vs SA's `type: "genie_space"` underscored).
+
+## Properties[​](#properties "Direct link to Properties")
+
+### \_\_kind[​](#__kind "Direct link to __kind")
+
+```ts
+readonly __kind: "hosted-supervisor";
+
+```
+
+***
+
+### spec[​](#spec "Direct link to spec")
+
+```ts
+readonly spec: SupervisorTool;
+
+```

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.