@databricks/appkit-ui 0.48.0 → 0.49.0

package/CLAUDE.md

@@ -74,6 +74,7 @@ npx @databricks/appkit docs <query>
 - [Class: PolicyDeniedError](./docs/api/appkit/Class.PolicyDeniedError.md): Thrown when a policy denies an action.
 - [Class: ResourceRegistry](./docs/api/appkit/Class.ResourceRegistry.md): Central registry for tracking plugin resource requirements.
 - [Class: ServerError](./docs/api/appkit/Class.ServerError.md): Error thrown when server lifecycle operations fail.
+- [Class: SupervisorApiAdapter](./docs/api/appkit/Class.SupervisorApiAdapter.md): Adapter that calls the Databricks AI Gateway Responses API
 - [Class: TunnelError](./docs/api/appkit/Class.TunnelError.md): Error thrown when remote tunnel operations fail.
 - [Class: ValidationError](./docs/api/appkit/Class.ValidationError.md): Error thrown when input validation fails.
 - [Enumeration: RequestedClaimsPermissionSet](./docs/api/appkit/Enumeration.RequestedClaimsPermissionSet.md): Permission set for Unity Catalog table access
@@ -89,6 +90,7 @@ npx @databricks/appkit docs <query>
 - [Function: executeFromRegistry()](./docs/api/appkit/Function.executeFromRegistry.md): Validates tool-call arguments against the entry's schema and invokes its
 - [Function: extractServingEndpoints()](./docs/api/appkit/Function.extractServingEndpoints.md): Extract serving endpoint config from a server file by AST-parsing it.
 - [Function: findServerFile()](./docs/api/appkit/Function.findServerFile.md): Find the server entry file by checking candidate paths in order.
+- [Function: fromSupervisorApi()](./docs/api/appkit/Function.fromSupervisorApi.md): Creates an AgentAdapter backed by the Databricks AI Gateway
 - [Function: functionToolToDefinition()](./docs/api/appkit/Function.functionToolToDefinition.md): Parameters
 - [Function: generateDatabaseCredential()](./docs/api/appkit/Function.generateDatabaseCredential.md): Generate OAuth credentials for Postgres database connection using the proper Postgres API.
 - [Function: getExecutionContext()](./docs/api/appkit/Function.getExecutionContext.md): Get the current execution context.
@@ -101,6 +103,7 @@ npx @databricks/appkit docs <query>
 - [Function: isFunctionTool()](./docs/api/appkit/Function.isFunctionTool.md): Parameters
 - [Function: isHostedTool()](./docs/api/appkit/Function.isHostedTool.md): Parameters
 - [Function: isSQLTypeMarker()](./docs/api/appkit/Function.isSQLTypeMarker.md): Type guard to check if a value is a SQL type marker
+- [Function: isSupervisorTool()](./docs/api/appkit/Function.isSupervisorTool.md): Type guard for HostedSupervisorTool. Used by the agents plugin
 - [Function: isToolkitEntry()](./docs/api/appkit/Function.isToolkitEntry.md): Type guard for ToolkitEntry — used by the agents plugin to differentiate
 - [Function: loadAgentFromFile()](./docs/api/appkit/Function.loadAgentFromFile.md): Loads a single markdown agent file and resolves its frontmatter against
 - [Function: loadAgentsFromDir()](./docs/api/appkit/Function.loadAgentsFromDir.md): Scans a directory for one subdirectory per agent, each containing
@@ -110,7 +113,7 @@ npx @databricks/appkit docs <query>
 - [Function: runAgent()](./docs/api/appkit/Function.runAgent.md): Standalone agent execution without createApp. Resolves the adapter, binds
 - [Function: tool()](./docs/api/appkit/Function.tool.md): Factory for defining function tools with Zod schemas.
 - [Function: toolsFromRegistry()](./docs/api/appkit/Function.toolsFromRegistry.md): Produces the AgentToolDefinition[] a ToolProvider exposes to the LLM,
-- [Interface: AgentAdapter](./docs/api/appkit/Interface.AgentAdapter.md): Methods
+- [Interface: AgentAdapter](./docs/api/appkit/Interface.AgentAdapter.md): Properties
 - [Interface: AgentDefinition](./docs/api/appkit/Interface.AgentDefinition.md): Properties
 - [Interface: AgentInput](./docs/api/appkit/Interface.AgentInput.md): Properties
 - [Interface: AgentRunContext](./docs/api/appkit/Interface.AgentRunContext.md): Properties
@@ -126,6 +129,7 @@ npx @databricks/appkit docs <query>
 - [Interface: FunctionTool](./docs/api/appkit/Interface.FunctionTool.md): Properties
 - [Interface: GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md): Request parameters for generating database OAuth credentials
 - [Interface: GenerationParams](./docs/api/appkit/Interface.GenerationParams.md): Optional generation parameters forwarded to the OpenAI-compatible serving
+- [Interface: HostedSupervisorTool](./docs/api/appkit/Interface.HostedSupervisorTool.md): Tagged record returned by every supervisorTools factory. The
 - [Interface: IJobsConfig](./docs/api/appkit/Interface.IJobsConfig.md): Configuration for the Jobs plugin.
 - [Interface: ITelemetry](./docs/api/appkit/Interface.ITelemetry.md): Plugin-facing interface for OpenTelemetry instrumentation.
 - [Interface: JobAPI](./docs/api/appkit/Interface.JobAPI.md): User-facing API for a single configured job.
@@ -149,6 +153,8 @@ npx @databricks/appkit docs <query>
 - [Interface: ServingEndpointEntry](./docs/api/appkit/Interface.ServingEndpointEntry.md): Shape of a single registry entry.
 - [Interface: ServingEndpointRegistry](./docs/api/appkit/Interface.ServingEndpointRegistry.md): Registry interface for serving endpoint type generation.
 - [Interface: StreamExecutionSettings](./docs/api/appkit/Interface.StreamExecutionSettings.md): Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration.
+- [Interface: SupervisorApiAdapterOptions](./docs/api/appkit/Interface.SupervisorApiAdapterOptions.md): Properties
+- [Interface: SupervisorExtension](./docs/api/appkit/Interface.SupervisorExtension.md): Shape of the value at AgentInput.extensions[SUPERVISOREXTENSIONKEY].
 - [Interface: TelemetryConfig](./docs/api/appkit/Interface.TelemetryConfig.md): OpenTelemetry configuration for AppKit applications
 - [Interface: Thread](./docs/api/appkit/Interface.Thread.md): Properties
 - [Interface: ThreadStore](./docs/api/appkit/Interface.ThreadStore.md): Methods
@@ -159,6 +165,7 @@ npx @databricks/appkit docs <query>
 - [Interface: ToolkitOptions](./docs/api/appkit/Interface.ToolkitOptions.md): Properties
 - [Interface: ToolProvider](./docs/api/appkit/Interface.ToolProvider.md): Methods
 - [Interface: ValidationResult](./docs/api/appkit/Interface.ValidationResult.md): Result of validating all registered resources against the environment.
+- [Interface: WorkspaceClientLike](./docs/api/appkit/Interface.WorkspaceClientLike.md): Structural shape of a Databricks SDK client used by fromSupervisorApi.
 - [Type Alias: AgentEvent](./docs/api/appkit/TypeAlias.AgentEvent.md): Type Declaration
 - [Type Alias: AgentTool](./docs/api/appkit/TypeAlias.AgentTool.md): Any tool an agent can invoke: inline function tools (tool()), hosted MCP
 - [Type Alias: AgentTools](./docs/api/appkit/TypeAlias.AgentTools.md): Per-agent tool record. String keys map to inline tools, toolkit entries,
@@ -178,11 +185,14 @@ npx @databricks/appkit docs <query>
 - [Type Alias: ResourceFieldEntry](./docs/api/appkit/TypeAlias.ResourceFieldEntry.md)
 - [Type Alias: ResourcePermission](./docs/api/appkit/TypeAlias.ResourcePermission.md): Union of all possible permission levels across all resource types.
 - [Type Alias: ServingFactory](./docs/api/appkit/TypeAlias.ServingFactory.md): Factory function returned by AppKit.serving.
+- [Type Alias: SupervisorTool](./docs/api/appkit/TypeAlias.SupervisorTool.md): Tools supported by the Databricks AI Gateway Responses API. The shapes match
 - [Type Alias: ToolRegistry](./docs/api/appkit/TypeAlias.ToolRegistry.md)
 - [Type Alias: ToPlugin()<T, U, N>](./docs/api/appkit/TypeAlias.ToPlugin.md): Factory function type returned by toPlugin(). Accepts optional config and returns a PluginData tuple.
 - [Variable: agents](./docs/api/appkit/Variable.agents.md): Plugin factory for the agents plugin. Reads config/agents/*.md by default,
 - [Variable: READ_ACTIONS](./docs/api/appkit/Variable.READ_ACTIONS.md): Actions that only read data.
 - [Variable: sql](./docs/api/appkit/Variable.sql.md): SQL helper namespace
+- [Variable: SUPERVISOR_EXTENSION_KEY](./docs/api/appkit/Variable.SUPERVISOR_EXTENSION_KEY.md): Namespace key under which the adapter reads its hosted-tool payload
+- [Variable: supervisorTools](./docs/api/appkit/Variable.supervisorTools.md): Concise factories for declaring Supervisor API tools.
 - [Variable: WRITE_ACTIONS](./docs/api/appkit/Variable.WRITE_ACTIONS.md): Actions that mutate data.
 
 ## appkit-ui API reference [collapsed]

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.*`).