feat(appkit): supervisor API adapter for agents plugin (#400)

* feat(appkit): supervisor api adapter

* fix(appkit): address PR #345 review findings (section 9)

Apply Mario's defensive/correctness fixes from the supervisor API adapter
review without touching the public API shape (sections 1-8 will land in a
stacked branch). Highlights:

High
- Route the three SSE error-leak sites in supervisor-api.ts (streamBody
  catch, mapEvent "error", output_item.done with id="error") through a
  single emitError helper that returns a stable client-facing code
  (`Supervisor API error (transport|upstream_failed|upstream_tool|
  upstream_unknown)`) and logs the verbose detail server-side only.
  Addresses CWE-209 verbatim-upstream-error-text leak.

Medium
- Gate the terminal {status:"complete"} emission on lastCompleted.status
  / .error / .incomplete_details so a `response.completed` with a nested
  failed status no longer silently succeeds; surface as upstream_failed
  instead. Regression tests added.
- Skip the terminal error in the streamBody catch when signal.aborted —
  consumer-initiated aborts now end with a clean stop, not a contradictory
  terminal error event. Regression test added.
- Tighten the output_item.done error match: require item.type === "error"
  (or pair the reserved id="error" with a non-message type) so a stray
  assistant message with id="error" is not mis-classified.
- Add maxLineChars / maxBufferChars caps to readSseEvents with 1 MiB / 8
  MiB defaults; throw on overflow. Addresses CWE-770. Tests added.
- Docs: add a CWE-1427 callout warning that hosted-tool `description` is a
  prompt-injection sink — do not derive it from untrusted input.
- Redact the no-delta warning log: summariseErrorPayload extracts a short
  `type: message` line; full payload only via DEBUG. Addresses CWE-532.
- Gate the buffer-level CRLF normalize in sse-reader on `\r` presence to
  skip the regex on LF-only steady state.

Low
- mapEvent("error") fallback no longer wraps "Unknown error" with literal
  JSON quotes (uses string branch).
- Drop the misleading "we await the factory at module init" comment in
  dev-playground; the code never awaits.
- Fix @example imports in supervisor-api.ts JSDoc to use
  @databricks/appkit/beta (the actual public re-export).
- Replace trimStart() with single-U+0020 strip in sse-reader per the SSE
  spec; remove the now-dead per-line `\r$` strip after the buffer-level
  CRLF normalise.
- Flag streamPath as @internal in connectors/serving/client.ts noting the
  CWE-918 SSRF risk if it ever leaks to user-controlled input.
- Add JSDoc warning to workspaceClient on SupervisorApiAdapterOptions:
  passing a per-request OBO client would leak identity across requests
  (CWE-664).

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

* fix(appkit): address pkosiec feedback

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

* 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>

* fix(appkit): pkosiec's feedback

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

* fix(appkit): address supervisor adapter feedback 2026-07-28: first round

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

* fix(appkit): add agent selector to dev-playground

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

* Apply suggestions from code review

Co-authored-by: Pawel Kosiec <pawel.kosiec@gmail.com>

---------

Signed-off-by: Hubert Zub <hubert.zub@databricks.com>
Co-authored-by: Pawel Kosiec <pawel.kosiec@gmail.com>

Author: hubertzub-db

apps/dev-playground/.env.dist

@@ -8,7 +8,8 @@ OTEL_RESOURCE_ATTRIBUTES='service.sample_attribute=dev'
 OTEL_SERVICE_NAME='dev-playground'
 DATABRICKS_VOLUME_PLAYGROUND=
 DATABRICKS_VOLUME_OTHER=
-DATABRICKS_GENIE_SPACE_ID=
+DATABRICKS_GENIE_SPACE_ID='01f0b972bf391ccd8b60840332bb2e5b' # appkit NYC Taxi space
+DATABRICKS_UC_FUNCTION_NAME='system.ai.python_exec'
 DATABRICKS_JOB_ID=
 DATABRICKS_SERVING_ENDPOINT_NAME=
 LAKEBASE_ENDPOINT='' # Run: databricks postgres list-endpoints projects/{project-id}/branches/{branch-id} — use the `name` field from the output

apps/dev-playground/client/src/routes/agent.route.tsx

@@ -1,12 +1,25 @@
 import { getPluginClientConfig } from "@databricks/appkit-ui/js";
-import { Button } from "@databricks/appkit-ui/react";
+import {
+  Button,
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@databricks/appkit-ui/react";
 import { createFileRoute } from "@tanstack/react-router";
 import { useCallback, useEffect, useRef, useState } from "react";
 
 export const Route = createFileRoute("/agent")({
   component: AgentRoute,
 });
 
+const AGENT_OPTIONS = [
+  { value: "helper", label: "Helper — general assistant" },
+  { value: "sql_analyst", label: "SQL Analyst — NYC taxi queries" },
+  { value: "supervisor", label: "Supervisor — Databricks-hosted tools" },
+] as const;
+
 interface SSEEvent {
   type: string;
   delta?: string;
@@ -142,6 +155,7 @@ function AgentRoute() {
   const [input, setInput] = useState("");
   const [isLoading, setIsLoading] = useState(false);
   const [threadId, setThreadId] = useState<string | null>(null);
+  const [agent, setAgent] = useState<string>(AGENT_OPTIONS[0].value);
   const [pendingApprovals, setPendingApprovals] = useState<PendingApproval[]>(
     [],
   );
@@ -211,6 +225,7 @@ function AgentRoute() {
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
           message: userMessage,
+          agent,
           ...(threadId && { threadId }),
         }),
       });
@@ -310,7 +325,7 @@ function AgentRoute() {
     } finally {
       setIsLoading(false);
     }
-  }, [input, isLoading, threadId, clearSuggestion]);
+  }, [input, isLoading, threadId, agent, clearSuggestion]);
 
   const handleInputChange = (value: string) => {
     setInput(value);
@@ -328,23 +343,42 @@ function AgentRoute() {
   return (
     <div className="min-h-screen bg-background">
       <div className="max-w-7xl mx-auto px-6 py-12">
-        <div className="mb-8 flex items-end justify-between">
-          <div>
-            <h1 className="text-3xl font-bold mb-2">Agent Chat</h1>
-            <p className="text-base text-muted-foreground">
-              AI agent with auto-discovered tools from all AppKit plugins.
-              {threadId && (
-                <span className="ml-2 text-xs font-mono opacity-60">
-                  Thread: {threadId.slice(0, 8)}...
-                </span>
-              )}
-            </p>
+        <div className="flex items-center gap-6 justify-between">
+          <div className="mb-8 flex-1 flex items-end justify-between">
+            <div>
+              <h1 className="text-3xl font-bold mb-2">Agent Chat</h1>
+              <p className="text-base text-muted-foreground">
+                AI agent with auto-discovered tools from all AppKit plugins.
+                {threadId && (
+                  <span className="ml-2 text-xs font-mono opacity-60">
+                    Thread: {threadId.slice(0, 8)}...
+                  </span>
+                )}
+              </p>
+            </div>
+            {hasAutocomplete && (
+              <span className="text-xs text-muted-foreground bg-muted px-2 py-1 rounded">
+                Autocomplete enabled
+              </span>
+            )}
+          </div>
+          <div className="w-80 flex items-center gap-3">
+            <div className="flex flex-1 flex-col gap-1">
+              <span className="text-xs font-medium">Agent</span>
+              <Select value={agent} onValueChange={setAgent}>
+                <SelectTrigger className="w-80 h-8">
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  {AGENT_OPTIONS.map((option) => (
+                    <SelectItem key={option.value} value={option.value}>
+                      {option.label}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </div>
           </div>
-          {hasAutocomplete && (
-            <span className="text-xs text-muted-foreground bg-muted px-2 py-1 rounded">
-              Autocomplete enabled
-            </span>
-          )}
         </div>
 
         <div className="flex gap-6 h-[700px]">

apps/dev-playground/server/index.ts

@@ -11,7 +11,13 @@ import {
   serving,
   WRITE_ACTIONS,
 } from "@databricks/appkit";
-import { agents, createAgent, tool } from "@databricks/appkit/beta";
+import {
+  agents,
+  createAgent,
+  DatabricksAdapter,
+  supervisorTools,
+  tool,
+} from "@databricks/appkit/beta";
 import { WorkspaceClient } from "@databricks/sdk-experimental";
 import { z } from "zod";
 import { lakebaseExamples } from "./lakebase-examples-plugin";
@@ -68,6 +74,35 @@ const helper = createAgent({
   },
 });
 
+// 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
+// `resolveAdapter` in the agents plugin). A misconfigured workspace will
+// surface at first chat request, not at module init.
+const supervisor = createAgent({
+  instructions:
+    "You are an assistant powered by the Databricks Supervisor API.",
+  model: DatabricksAdapter.fromSupervisorApi({
+    model: "databricks-claude-sonnet-4-5",
+  }),
+  tools: () => ({
+    nyc: supervisorTools.genieSpace({
+      id: process.env.DATABRICKS_GENIE_SPACE_ID ?? "",
+      description: "NYC taxi trip records and zones",
+    }),
+    add: supervisorTools.ucFunction({
+      name: process.env.DATABRICKS_UC_FUNCTION_NAME ?? "",
+      description: "Adds two integers and returns the sum.",
+    }),
+  }),
+});
+
 /*
  * Smart-Dashboard agents.
  *
@@ -385,7 +420,7 @@ createApp({
     }),
     serving(),
     agents({
-      agents: { helper, sql_analyst, dashboard_pilot },
+      agents: { helper, sql_analyst, dashboard_pilot, supervisor },
       // `query` (markdown dispatcher) + `sql_analyst` + `dashboard_pilot`
       // wire the /smart-dashboard route. `insights` and `anomaly` are
       // ephemeral markdown agents auto-fired by the route's AgentSidebar.