@databricks/appkit 0.47.1 → 0.49.0

package/dist/stream/sse-reader.js

@@ -0,0 +1,86 @@
+//#region src/stream/sse-reader.ts
+const DEFAULT_MAX_SSE_LINE_CHARS = 1024 * 1024;
+const DEFAULT_MAX_SSE_BUFFER_CHARS = 8 * 1024 * 1024;
+/**
+* Async-iterates Server-Sent Events from a UTF-8 byte stream.
+*
+* Block-oriented parser: events are delimited by blank lines (`\n\n` after
+* CRLF normalization), so an `event:` line in chunk N pairs correctly with a
+* `data:` line in chunk N+1 — no hoisted state needed.
+*
+* The reader passes through the sentinel string `[DONE]` as `event=""`,
+* `data="[DONE]"`. Callers that care about it should match `data === "[DONE]"`
+* after destructuring.
+*
+* Terminates when the stream closes or `signal` aborts; releases the reader
+* lock in either case. Throws when {@link ReadSseEventsOptions.maxLineChars}
+* or {@link ReadSseEventsOptions.maxBufferChars} are exceeded.
+*/
+async function* readSseEvents(stream, signal, options) {
+	const maxLineChars = options?.maxLineChars ?? DEFAULT_MAX_SSE_LINE_CHARS;
+	const maxBufferChars = options?.maxBufferChars ?? DEFAULT_MAX_SSE_BUFFER_CHARS;
+	const reader = stream.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	const onAbort = () => {
+		reader.cancel().catch(() => {});
+	};
+	if (signal) if (signal.aborted) onAbort();
+	else signal.addEventListener("abort", onAbort, { once: true });
+	try {
+		while (true) {
+			if (signal?.aborted) break;
+			const { done, value } = await reader.read();
+			if (done) {
+				if (buffer.length > maxLineChars) throw new Error(`readSseEvents: trailing SSE block exceeds maxLineChars (${maxLineChars} UTF-16 code units)`);
+				const tail = parseSseBlock(buffer);
+				if (tail) yield tail;
+				break;
+			}
+			buffer += decoder.decode(value, { stream: true });
+			const blocks = (buffer.indexOf("\r") !== -1 ? buffer.replace(/\r\n/g, "\n") : buffer).split("\n\n");
+			buffer = blocks.pop() ?? "";
+			if (buffer.length > maxBufferChars) throw new Error(`readSseEvents: incomplete SSE block exceeds maxBufferChars (${maxBufferChars} UTF-16 code units) without a terminator`);
+			for (const block of blocks) {
+				if (block.length > maxLineChars) throw new Error(`readSseEvents: SSE block exceeds maxLineChars (${maxLineChars} UTF-16 code units)`);
+				const event = parseSseBlock(block);
+				if (event) yield event;
+			}
+		}
+	} finally {
+		if (signal) signal.removeEventListener("abort", onAbort);
+		reader.releaseLock();
+	}
+}
+/**
+* Per the SSE spec, only a single leading `U+0020` is stripped from a field
+* value — not arbitrary whitespace. `trimStart()` would also strip tabs,
+* NBSP, etc.; for callers that feed binary or whitespace-prefixed payloads
+* this is a footgun.
+*/
+function stripOneLeadingSpace(s) {
+	return s.startsWith(" ") ? s.slice(1) : s;
+}
+function parseSseBlock(block) {
+	if (block.length === 0) return null;
+	const lines = block.split("\n");
+	let eventName = "";
+	let id;
+	const dataLines = [];
+	for (const line of lines) {
+		if (line === "" || line.startsWith(":")) continue;
+		if (line.startsWith("event:")) eventName = stripOneLeadingSpace(line.slice(6));
+		else if (line.startsWith("data:")) dataLines.push(stripOneLeadingSpace(line.slice(5)));
+		else if (line.startsWith("id:")) id = stripOneLeadingSpace(line.slice(3));
+	}
+	if (dataLines.length === 0) return null;
+	return {
+		event: eventName,
+		data: dataLines.join("\n"),
+		id
+	};
+}
+
+//#endregion
+export { readSseEvents };
+//# sourceMappingURL=sse-reader.js.map

package/dist/stream/sse-reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-reader.js","names":[],"sources":["../../src/stream/sse-reader.ts"],"sourcesContent":["/**\n * One parsed Server-Sent Event. Field names follow the spec:\n * https://html.spec.whatwg.org/multipage/server-sent-events.html\n *\n * The reader does not interpret `data` (no JSON parsing), so callers control\n * the wire shape they expect.\n */\nexport interface SseEvent {\n  /** Value of the most recent `event:` field, or `\"\"` for an unnamed event. */\n  event: string;\n  /** Joined `data:` lines for the event (empty string when no data was set). */\n  data: string;\n  /** Value of the most recent `id:` field, or `undefined` if none. */\n  id?: string;\n}\n\n/**\n * Configuration for {@link readSseEvents}. All limits are in UTF-16 code\n * units (JS string `.length`) and exist as a DoS guard (CWE-770) for\n * untrusted upstreams that might stream arbitrarily large lines or never\n * emit a block terminator.\n */\ninterface ReadSseEventsOptions {\n  /**\n   * Maximum length of any single SSE event block (i.e. the text between\n   * two `\\n\\n` separators). Exceeding this throws.\n   *\n   * @default 1 MiB (1_048_576)\n   */\n  maxLineChars?: number;\n  /**\n   * Maximum length of the rolling input buffer when no block terminator\n   * has been seen yet. Exceeding this throws — protects against an\n   * upstream that streams indefinitely without ever sending `\\n\\n`.\n   *\n   * @default 8 MiB (8_388_608)\n   */\n  maxBufferChars?: number;\n}\n\nconst DEFAULT_MAX_SSE_LINE_CHARS = 1024 * 1024;\nconst DEFAULT_MAX_SSE_BUFFER_CHARS = 8 * 1024 * 1024;\n\n/**\n * Async-iterates Server-Sent Events from a UTF-8 byte stream.\n *\n * Block-oriented parser: events are delimited by blank lines (`\\n\\n` after\n * CRLF normalization), so an `event:` line in chunk N pairs correctly with a\n * `data:` line in chunk N+1 — no hoisted state needed.\n *\n * The reader passes through the sentinel string `[DONE]` as `event=\"\"`,\n * `data=\"[DONE]\"`. Callers that care about it should match `data === \"[DONE]\"`\n * after destructuring.\n *\n * Terminates when the stream closes or `signal` aborts; releases the reader\n * lock in either case. Throws when {@link ReadSseEventsOptions.maxLineChars}\n * or {@link ReadSseEventsOptions.maxBufferChars} are exceeded.\n */\nexport async function* readSseEvents(\n  stream: ReadableStream<Uint8Array>,\n  signal?: AbortSignal,\n  options?: ReadSseEventsOptions,\n): AsyncGenerator<SseEvent, void, unknown> {\n  const maxLineChars = options?.maxLineChars ?? DEFAULT_MAX_SSE_LINE_CHARS;\n  const maxBufferChars =\n    options?.maxBufferChars ?? DEFAULT_MAX_SSE_BUFFER_CHARS;\n\n  const reader = stream.getReader();\n  const decoder = new TextDecoder();\n  let buffer = \"\";\n\n  // Cancel the reader on abort so an in-flight `reader.read()` returns\n  // immediately instead of waiting for the next chunk. Without this, an\n  // aborted consumer would only notice between reads — fine for chatty\n  // streams, but unbounded for an idle/heartbeat-less upstream.\n  const onAbort = () => {\n    reader.cancel().catch(() => {\n      // `cancel()` rejects if the stream is already errored/closed; ignore.\n    });\n  };\n  if (signal) {\n    if (signal.aborted) onAbort();\n    else signal.addEventListener(\"abort\", onAbort, { once: true });\n  }\n\n  try {\n    while (true) {\n      if (signal?.aborted) break;\n      const { done, value } = await reader.read();\n      if (done) {\n        if (buffer.length > maxLineChars) {\n          throw new Error(\n            `readSseEvents: trailing SSE block exceeds maxLineChars (${maxLineChars} UTF-16 code units)`,\n          );\n        }\n        const tail = parseSseBlock(buffer);\n        if (tail) yield tail;\n        break;\n      }\n\n      buffer += decoder.decode(value, { stream: true });\n\n      // Gate the CRLF normalize on `\\r` presence — saves a full-buffer\n      // regex scan on every chunk for the common LF-only steady state.\n      const normalized =\n        buffer.indexOf(\"\\r\") !== -1 ? buffer.replace(/\\r\\n/g, \"\\n\") : buffer;\n      const blocks = normalized.split(\"\\n\\n\");\n      // Last entry is either an incomplete block or \"\" (when the chunk ended\n      // exactly on a boundary). Either way, keep it for the next iteration.\n      buffer = blocks.pop() ?? \"\";\n\n      if (buffer.length > maxBufferChars) {\n        throw new Error(\n          `readSseEvents: incomplete SSE block exceeds maxBufferChars (${maxBufferChars} UTF-16 code units) without a terminator`,\n        );\n      }\n\n      for (const block of blocks) {\n        if (block.length > maxLineChars) {\n          throw new Error(\n            `readSseEvents: SSE block exceeds maxLineChars (${maxLineChars} UTF-16 code units)`,\n          );\n        }\n        const event = parseSseBlock(block);\n        if (event) yield event;\n      }\n    }\n  } finally {\n    if (signal) signal.removeEventListener(\"abort\", onAbort);\n    reader.releaseLock();\n  }\n}\n\n/**\n * Per the SSE spec, only a single leading `U+0020` is stripped from a field\n * value — not arbitrary whitespace. `trimStart()` would also strip tabs,\n * NBSP, etc.; for callers that feed binary or whitespace-prefixed payloads\n * this is a footgun.\n */\nfunction stripOneLeadingSpace(s: string): string {\n  return s.startsWith(\" \") ? s.slice(1) : s;\n}\n\nfunction parseSseBlock(block: string): SseEvent | null {\n  if (block.length === 0) return null;\n  // CRLF was already normalised at the buffer level, so each `line` here is\n  // already free of trailing `\\r` — no per-line strip needed.\n  const lines = block.split(\"\\n\");\n\n  let eventName = \"\";\n  let id: string | undefined;\n  const dataLines: string[] = [];\n\n  for (const line of lines) {\n    if (line === \"\" || line.startsWith(\":\")) continue;\n\n    if (line.startsWith(\"event:\")) {\n      eventName = stripOneLeadingSpace(line.slice(6));\n    } else if (line.startsWith(\"data:\")) {\n      dataLines.push(stripOneLeadingSpace(line.slice(5)));\n    } else if (line.startsWith(\"id:\")) {\n      id = stripOneLeadingSpace(line.slice(3));\n    }\n    // Other fields (`retry:`, custom) are ignored by design.\n  }\n\n  // Per the SSE spec, a block is only dispatched when the data buffer is\n  // non-empty. Blocks containing only `event:`/`id:` (or comments) do not\n  // surface as events.\n  if (dataLines.length === 0) return null;\n\n  return {\n    event: eventName,\n    data: dataLines.join(\"\\n\"),\n    id,\n  };\n}\n"],"mappings":";AAwCA,MAAM,6BAA6B,OAAO;AAC1C,MAAM,+BAA+B,IAAI,OAAO;;;;;;;;;;;;;;;;AAiBhD,gBAAuB,cACrB,QACA,QACA,SACyC;CACzC,MAAM,eAAe,SAAS,gBAAgB;CAC9C,MAAM,iBACJ,SAAS,kBAAkB;CAE7B,MAAM,SAAS,OAAO,WAAW;CACjC,MAAM,UAAU,IAAI,aAAa;CACjC,IAAI,SAAS;CAMb,MAAM,gBAAgB;AACpB,SAAO,QAAQ,CAAC,YAAY,GAE1B;;AAEJ,KAAI,OACF,KAAI,OAAO,QAAS,UAAS;KACxB,QAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,MAAM,CAAC;AAGhE,KAAI;AACF,SAAO,MAAM;AACX,OAAI,QAAQ,QAAS;GACrB,MAAM,EAAE,MAAM,UAAU,MAAM,OAAO,MAAM;AAC3C,OAAI,MAAM;AACR,QAAI,OAAO,SAAS,aAClB,OAAM,IAAI,MACR,2DAA2D,aAAa,qBACzE;IAEH,MAAM,OAAO,cAAc,OAAO;AAClC,QAAI,KAAM,OAAM;AAChB;;AAGF,aAAU,QAAQ,OAAO,OAAO,EAAE,QAAQ,MAAM,CAAC;GAMjD,MAAM,UADJ,OAAO,QAAQ,KAAK,KAAK,KAAK,OAAO,QAAQ,SAAS,KAAK,GAAG,QACtC,MAAM,OAAO;AAGvC,YAAS,OAAO,KAAK,IAAI;AAEzB,OAAI,OAAO,SAAS,eAClB,OAAM,IAAI,MACR,+DAA+D,eAAe,0CAC/E;AAGH,QAAK,MAAM,SAAS,QAAQ;AAC1B,QAAI,MAAM,SAAS,aACjB,OAAM,IAAI,MACR,kDAAkD,aAAa,qBAChE;IAEH,MAAM,QAAQ,cAAc,MAAM;AAClC,QAAI,MAAO,OAAM;;;WAGb;AACR,MAAI,OAAQ,QAAO,oBAAoB,SAAS,QAAQ;AACxD,SAAO,aAAa;;;;;;;;;AAUxB,SAAS,qBAAqB,GAAmB;AAC/C,QAAO,EAAE,WAAW,IAAI,GAAG,EAAE,MAAM,EAAE,GAAG;;AAG1C,SAAS,cAAc,OAAgC;AACrD,KAAI,MAAM,WAAW,EAAG,QAAO;CAG/B,MAAM,QAAQ,MAAM,MAAM,KAAK;CAE/B,IAAI,YAAY;CAChB,IAAI;CACJ,MAAM,YAAsB,EAAE;AAE9B,MAAK,MAAM,QAAQ,OAAO;AACxB,MAAI,SAAS,MAAM,KAAK,WAAW,IAAI,CAAE;AAEzC,MAAI,KAAK,WAAW,SAAS,CAC3B,aAAY,qBAAqB,KAAK,MAAM,EAAE,CAAC;WACtC,KAAK,WAAW,QAAQ,CACjC,WAAU,KAAK,qBAAqB,KAAK,MAAM,EAAE,CAAC,CAAC;WAC1C,KAAK,WAAW,MAAM,CAC/B,MAAK,qBAAqB,KAAK,MAAM,EAAE,CAAC;;AAQ5C,KAAI,UAAU,WAAW,EAAG,QAAO;AAEnC,QAAO;EACL,OAAO;EACP,MAAM,UAAU,KAAK,KAAK;EAC1B;EACD"}

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.PluginManifest.md

@@ -75,6 +75,24 @@ Omit.description
 
 ***
 
+### devOnly?[​](#devonly "Direct link to devOnly?")
+
+```ts
+optional devOnly: boolean;
+
+```
+
+When true, this plugin is only registered when NODE\_ENV === "development". In any other environment createApp skips it entirely (not constructed, no routes, resources not validated). Use for dev-only tooling that must never run in a deployed app.
+
+#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")
+
+```ts
+Omit.devOnly
+
+```
+
+***
+
 ### displayName[​](#displayname "Direct link to displayName")
 
 ```ts
@@ -84,7 +102,7 @@ displayName: string;
 
 Human-readable display name for UI and CLI
 
-#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")
 
 ```ts
 Omit.displayName
@@ -102,7 +120,7 @@ optional hidden: boolean;
 
 When true, this plugin is excluded from the template plugins manifest (appkit.plugins.json) during sync.
 
-#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-4 "Direct link to Inherited from")
 
 ```ts
 Omit.hidden
@@ -120,7 +138,7 @@ optional keywords: string[];
 
 Keywords for plugin discovery
 
-#### Inherited from[​](#inherited-from-4 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-5 "Direct link to Inherited from")
 
 ```ts
 Omit.keywords
@@ -138,7 +156,7 @@ optional license: string;
 
 SPDX license identifier
 
-#### Inherited from[​](#inherited-from-5 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-6 "Direct link to Inherited from")
 
 ```ts
 Omit.license
@@ -174,7 +192,7 @@ optional onSetupMessage: string;
 
 Message displayed to the user after project initialization. Use this to inform about manual setup steps (e.g. environment variables, resource provisioning).
 
-#### Inherited from[​](#inherited-from-6 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-7 "Direct link to Inherited from")
 
 ```ts
 Omit.onSetupMessage
@@ -192,7 +210,7 @@ optional repository: string;
 
 URL to the plugin's source repository
 
-#### Inherited from[​](#inherited-from-7 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-8 "Direct link to Inherited from")
 
 ```ts
 Omit.repository
@@ -278,7 +296,7 @@ optional should: string[];
 
 ```
 
-#### Inherited from[​](#inherited-from-8 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-9 "Direct link to Inherited from")
 
 ```ts
 Omit.scaffolding
@@ -296,7 +314,7 @@ optional stability: "beta" | "ga";
 
 Plugin stability level. Beta plugins may have breaking API changes between minor releases but are on a path to GA. GA (general availability) plugins follow semver strictly.
 
-#### Inherited from[​](#inherited-from-9 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-10 "Direct link to Inherited from")
 
 ```ts
 Omit.stability
@@ -314,7 +332,7 @@ optional version: string;
 
 Plugin version (semver format)
 
-#### Inherited from[​](#inherited-from-10 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-11 "Direct link to Inherited from")
 
 ```ts
 Omit.version

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