refactor(appkit): restructure supervisor-api adapter per PR #345 review

Address structural feedback from Mario Cadenas' review of PR #345 (sections
1-8). Stacked on top of the §9 defensive fixes commit.

API changes (BETA surface only):
- Add `DatabricksAdapter.fromSupervisorApi` static factory for discoverability
  alongside `.fromChatCompletions`.
- Shrink `SupervisorApiAdapterOptions` to `{ model, workspaceClient? }`; tools
  no longer live on the adapter.
- Hosted tools (`supervisorTools.*`) now return tagged `HostedSupervisorTool`
  records and accept named options instead of positional args.
- Declare hosted tools on the agent's `tools` map (same place as function
  tools / sub-agents); the agents plugin and `runAgent` route them to the
  adapter via the new `AgentInput.extensions[SUPERVISOR_EXTENSION_KEY]`.
- Add capability-negotiation fields to `AgentAdapter`:
  `acceptsExtensions?` + `consumesInputTools?`. The agents plugin and
  `runAgent` warn at registration when adapter capabilities don't match
  declared tools.

Internals:
- Extend `ResolvedToolEntry` / `StandaloneEntry` with a `hosted-supervisor`
  branch; `classifyTool` matches it before MCP hosted-tool rejection so
  standalone `runAgent` supports supervisor tools.
- Defense-in-depth: both indexers throw if a `hosted-supervisor` entry is
  ever dispatched as a callable function.
- `DatabricksAdapter.fromSupervisorApi` uses a dynamic import to avoid
  load-time cycles.

Docs:
- Rewrite supervisor-API section in docs/plugins/agents.md for the new shape.
- Add cross-adapter sub-agent composition note (one-directional: chat
  parents can call supervisor children, not vice-versa, until SA's
  function-call events are routed back through `context.executeTool`).

Playground:
- Update dev-playground supervisor agent to the new shape
  (`DatabricksAdapter.fromSupervisorApi(...)` + tools on `createAgent`).

Tests:
- Rewrite supervisor-api.test.ts factory + adapter tests for the new shape.
- Add `isSupervisorTool` and `DatabricksAdapter.fromSupervisorApi` tests.
- New regression tests in `run-agent.test.ts` covering the
  hosted-supervisor extension-routing path and both capability-mismatch
  warnings.
- New agents-plugin tests covering the same warning paths and the new
  `hosted-supervisor` tool-index branch.

Signed-off-by: Hubert Zub <hubert.zub@databricks.com>

Author: hubertzub-db

apps/dev-playground/server/index.ts

@@ -14,7 +14,7 @@ import {
 import {
   agents,
   createAgent,
-  fromSupervisorApi,
+  DatabricksAdapter,
   tool,
 } from "@databricks/appkit/beta";
 import { WorkspaceClient } from "@databricks/sdk-experimental";
@@ -73,10 +73,12 @@ const helper = createAgent({
   },
 });
 
-// Supervisor API demo agent. Tools are configured on the adapter (the SA
-// endpoint executes them server-side), not on the createAgent definition.
-// Uncomment a `supervisorTools.*` entry (and import 'supervisorTools' from
-// '@databricks/appkit/beta') to give the model real powers.
+// Supervisor API demo agent. The Databricks AI Gateway executes hosted
+// tools server-side; declare them via `createAgent({ tools })` like any
+// other agent tool — the agents plugin classifies the tagged record and
+// routes it to the adapter via AgentInput.extensions. Import
+// `supervisorTools` from '@databricks/appkit/beta' and uncomment an
+// entry below to give the model real powers.
 //
 // `createAgent({ model })` accepts an adapter promise, so the factory's
 // host/credential resolution is awaited lazily on first dispatch (via
@@ -85,18 +87,18 @@ const helper = createAgent({
 const supervisor = createAgent({
   instructions:
     "You are an assistant powered by the Databricks Supervisor API.",
-  model: fromSupervisorApi({
+  model: DatabricksAdapter.fromSupervisorApi({
     model: "databricks-claude-sonnet-4-5",
-    tools: [
-      // supervisorTools.genieSpace(
-      //   "01ABCDEF12345678",
-      //   "NYC taxi trip records and zones",
-      // ),
-      // supervisorTools.ucFunction(
-      //   "main.default.add",
-      //   "Adds two integers and returns the sum.",
-      // ),
-    ],
+  }),
+  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.",
+    // }),
   }),
 });
 

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

@@ -0,0 +1,100 @@
+# 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](Interface.SupervisorApiAdapterCtorOptions.md#streambody); the
+[fromSupervisorApi](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.
+
+## Example
+
+```ts
+import { createApp, createAgent } from "@databricks/appkit";
+import {
+  agents,
+  fromSupervisorApi,
+  supervisorTools,
+} from "@databricks/appkit/beta";
+
+const adapter = await fromSupervisorApi({
+  model: "databricks-claude-sonnet-4",
+  tools: [
+    supervisorTools.genieSpace(
+      "01ABCDEF12345678",
+      "NYC taxi trip records and zones",
+    ),
+  ],
+});
+
+await createApp({
+  plugins: [
+    agents({
+      agents: {
+        assistant: createAgent({
+          instructions: "You are a helpful assistant.",
+          model: adapter,
+        }),
+      },
+    }),
+  ],
+});
+```
+
+## Implements
+
+- [`AgentAdapter`](Interface.AgentAdapter.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new SupervisorApiAdapter(options: SupervisorApiAdapterCtorOptions): SupervisorApiAdapter;
+```
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `options` | [`SupervisorApiAdapterCtorOptions`](Interface.SupervisorApiAdapterCtorOptions.md) |
+
+#### Returns
+
+`SupervisorApiAdapter`
+
+## Methods
+
+### run()
+
+```ts
+run(input: AgentInput, context: AgentRunContext): AsyncGenerator<AgentEvent, void, unknown>;
+```
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `input` | [`AgentInput`](Interface.AgentInput.md) |
+| `context` | [`AgentRunContext`](Interface.AgentRunContext.md) |
+
+#### Returns
+
+`AsyncGenerator`\<[`AgentEvent`](TypeAlias.AgentEvent.md), `void`, `unknown`\>
+
+#### Implementation of
+
+[`AgentAdapter`](Interface.AgentAdapter.md).[`run`](Interface.AgentAdapter.md#run)

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

@@ -0,0 +1,47 @@
+# Function: fromSupervisorApi()
+
+```ts
+function fromSupervisorApi(options: SupervisorApiAdapterOptions): Promise<SupervisorApiAdapter>;
+```
+
+Creates an [AgentAdapter](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.).
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `options` | [`SupervisorApiAdapterOptions`](Interface.SupervisorApiAdapterOptions.md) |
+
+## Returns
+
+`Promise`\<[`SupervisorApiAdapter`](Class.SupervisorApiAdapter.md)\>
+
+## Example
+
+```ts
+import {
+  fromSupervisorApi,
+  supervisorTools,
+} from "@databricks/appkit/beta";
+
+const adapter = await fromSupervisorApi({
+  model: "databricks-claude-sonnet-4",
+  tools: [
+    supervisorTools.genieSpace(
+      "01ABCDEF12345678",
+      "NYC taxi trip records and zones",
+    ),
+  ],
+});
+```
+
+## Remarks
+
+⚠ When passing your own `workspaceClient`, see the warning on
+[SupervisorApiAdapterOptions.workspaceClient](Interface.SupervisorApiAdapterOptions.md#workspaceclient) — the client is
+captured once and reused, so per-request OBO clients would leak
+identity across requests.

docs/docs/api/appkit/Interface.SupervisorApiAdapterCtorOptions.md

@@ -0,0 +1,25 @@
+# Interface: SupervisorApiAdapterCtorOptions
+
+## Properties
+
+### model
+
+```ts
+model: string;
+```
+
+***
+
+### streamBody
+
+```ts
+streamBody: StreamBody;
+```
+
+***
+
+### tools?
+
+```ts
+optional tools: SupervisorTool[];
+```

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

@@ -0,0 +1,42 @@
+# Interface: SupervisorApiAdapterOptions
+
+## Properties
+
+### model
+
+```ts
+model: string;
+```
+
+Model identifier to pass in the request body
+(e.g. "databricks-claude-sonnet-4").
+
+***
+
+### tools?
+
+```ts
+optional tools: SupervisorTool[];
+```
+
+Hosted tools the SA endpoint should expose to the model. Use the
+[supervisorTools](Variable.supervisorTools.md) factories for the most common shapes.
+
+***
+
+### 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)

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

@@ -0,0 +1,47 @@
+# 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.
+
+Prefer the [supervisorTools](Variable.supervisorTools.md) factories — they fill in the
+SA-validation-bug workaround for `description` (must be non-empty).