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

Address structural feedback from Mario Cadenas' review of PR databricks#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.",
+    // }),
   }),
 });