@databricks/appkit 0.48.0 → 0.49.0

package/dist/agents/supervisor-api.d.ts

@@ -0,0 +1,362 @@
+import { AgentAdapter, AgentEvent, AgentInput, AgentRunContext } from "../shared/src/agent.js";
+import "../shared/src/index.js";
+import { ApiClientLike, StreamBody } from "../connectors/serving/client.js";
+
+//#region src/agents/supervisor-api.d.ts
+/**
+ * Structural shape of a Databricks SDK client used by {@link fromSupervisorApi}.
+ * Only what we need: `apiClient.request` for streaming and
+ * `config.ensureResolved` to materialise the host/credentials.
+ *
+ * Exported because {@link SupervisorApiAdapterOptions.workspaceClient} (a
+ * public type) references it — callers passing their own client can name
+ * the shape they need to satisfy.
+ */
+interface WorkspaceClientLike extends ApiClientLike {
+  config: {
+    ensureResolved(): Promise<void>;
+  };
+}
+/**
+ * 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.
+ *
+ * This is an adapter-internal wire type. Application code authors tools via
+ * the {@link supervisorTools} factories, which return tagged
+ * {@link HostedSupervisorTool} records — the agents plugin then unwraps
+ * the `.spec` when routing through {@link AgentInput.extensions}.
+ */
+type SupervisorTool = {
+  type: "genie_space";
+  genie_space: {
+    id: string;
+    description: string;
+  };
+} | {
+  type: "uc_function";
+  uc_function: {
+    name: string;
+    description: string;
+  };
+} | {
+  type: "knowledge_assistant";
+  knowledge_assistant: {
+    knowledge_assistant_id: string;
+    description: string;
+  };
+} | {
+  type: "app";
+  app: {
+    name: string;
+    description: string;
+  };
+} | {
+  type: "uc_connection";
+  uc_connection: {
+    name: string;
+    description: string;
+  };
+};
+/**
+ * Tagged record returned by every {@link supervisorTools} 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).
+ */
+interface HostedSupervisorTool {
+  readonly __kind: "hosted-supervisor";
+  readonly spec: SupervisorTool;
+}
+/**
+ * Type guard for {@link HostedSupervisorTool}. 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.
+ */
+declare function isSupervisorTool(value: unknown): value is HostedSupervisorTool;
+/**
+ * Concise factories for declaring Supervisor API tools.
+ *
+ * Each factory accepts a single named-options object: routing-critical
+ * strings (`id`, `name`, `description`) get labels at the call site so
+ * "we swapped the args and didn't notice for two weeks" bugs are
+ * impossible.
+ *
+ * `description` is required: SA's protobuf validation rejects `null`/`""`,
+ * AND the LLM running on SA reads this string to decide when to route to
+ * the tool. Two genie spaces both labelled "Genie space" give the model
+ * nothing to discriminate on, so callers always own the routing hint.
+ *
+ * ⚠ The `description` is read by the LLM at routing time — it is a
+ * prompt-injection sink. Do **not** derive it from untrusted input (user
+ * messages, request bodies, external systems). Treat it as application
+ * configuration. (CWE-1427)
+ *
+ * @example
+ * ```ts
+ * import { createAgent } from "@databricks/appkit";
+ * import {
+ *   agents,
+ *   DatabricksAdapter,
+ *   supervisorTools,
+ * } from "@databricks/appkit/beta";
+ *
+ * const 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",
+ *     }),
+ *     add: supervisorTools.ucFunction({
+ *       name: "main.default.add",
+ *       description: "Adds two integers and returns the sum.",
+ *     }),
+ *   }),
+ * });
+ * ```
+ */
+declare const supervisorTools: {
+  genieSpace: ({
+    id,
+    description
+  }: {
+    id: string;
+    description: string;
+  }) => HostedSupervisorTool;
+  ucFunction: ({
+    name,
+    description
+  }: {
+    name: string;
+    description: string;
+  }) => HostedSupervisorTool;
+  knowledgeAssistant: ({
+    knowledgeAssistantId,
+    description
+  }: {
+    knowledgeAssistantId: string;
+    description: string;
+  }) => HostedSupervisorTool;
+  app: ({
+    name,
+    description
+  }: {
+    name: string;
+    description: string;
+  }) => HostedSupervisorTool;
+  ucConnection: ({
+    name,
+    description
+  }: {
+    name: string;
+    description: string;
+  }) => HostedSupervisorTool;
+};
+/**
+ * Namespace key under which the adapter reads its hosted-tool payload
+ * from {@link AgentInput.extensions}. Exported so the agents plugin and
+ * standalone `runAgent` (the producers) can write under the same key the
+ * adapter reads.
+ */
+declare const SUPERVISOR_EXTENSION_KEY: "databricks.supervisor";
+/**
+ * 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.
+ */
+interface SupervisorExtension {
+  hostedTools?: SupervisorTool[];
+}
+interface SupervisorApiAdapterOptions {
+  /**
+   * Model identifier to pass in the request body
+   * (e.g. "databricks-claude-sonnet-4").
+   */
+  model: string;
+  /**
+   * 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)
+   */
+  workspaceClient?: WorkspaceClientLike;
+  /**
+   * 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.
+   */
+  timeoutMs?: number;
+}
+interface SupervisorApiAdapterCtorOptions {
+  streamBody: StreamBody;
+  model: string;
+  timeoutMs?: number;
+}
+/**
+ * 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 {@link SupervisorApiAdapterCtorOptions.streamBody}; the
+ * {@link fromSupervisorApi} 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
+ * ```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",
+ *             }),
+ *           }),
+ *         }),
+ *       },
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare class SupervisorApiAdapter implements AgentAdapter {
+  private streamBody;
+  private model;
+  private timeoutMs;
+  /**
+   * Capability negotiation: the adapter reads its hosted-tool payload
+   * from {@link AgentInput.extensions} under {@link SUPERVISOR_EXTENSION_KEY}.
+   * The agents plugin uses this list to warn at registration when the tool
+   * index produces extensions the adapter wouldn't consume.
+   */
+  readonly acceptsExtensions: readonly ["databricks.supervisor"];
+  /**
+   * 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.
+   */
+  readonly consumesInputTools = false;
+  constructor(options: SupervisorApiAdapterCtorOptions);
+  run(input: AgentInput, context: AgentRunContext): AsyncGenerator<AgentEvent, void, unknown>;
+  private streamResponse;
+  /**
+   * Splits the agent's message list into a Responses-API payload. System
+   * messages are concatenated (in order) into the top-level `instructions`
+   * field; user/assistant turns become `input` (as a plain string for the
+   * common single-user-turn case, otherwise as `{role,content}[]`). Tool-role
+   * messages are skipped — SA owns its own tool history server-side, so
+   * re-feeding our tool-result records would only confuse it.
+   */
+  private buildInput;
+}
+/**
+ * Creates an {@link AgentAdapter} 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
+ * {@link DatabricksAdapter.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 {@link DatabricksAdapter}.
+ *
+ * @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
+ * ⚠ When passing your own `workspaceClient`, see the warning on
+ * {@link SupervisorApiAdapterOptions.workspaceClient} — the client is
+ * captured once and reused, so per-request OBO clients would leak
+ * identity across requests.
+ *
+ * @see {@link DatabricksAdapter.fromSupervisorApi} — the recommended
+ * application-facing entry point.
+ */
+declare function fromSupervisorApi(options: SupervisorApiAdapterOptions): Promise<AgentAdapter>;
+//#endregion
+export { HostedSupervisorTool, SUPERVISOR_EXTENSION_KEY, SupervisorApiAdapter, SupervisorApiAdapterOptions, SupervisorExtension, SupervisorTool, WorkspaceClientLike, fromSupervisorApi, isSupervisorTool, supervisorTools };
+//# sourceMappingURL=supervisor-api.d.ts.map

package/dist/agents/supervisor-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor-api.d.ts","names":[],"sources":["../../src/agents/supervisor-api.ts"],"mappings":";;;;;;;;AAiGA;;;;;;UAAiB,mBAAA,SAA4B,aAAA;EAC3C,MAAA;IAAU,cAAA,IAAkB,OAAA;EAAA;AAAA;;;;;;;;;;;KAiBlB,cAAA;EACN,IAAA;EAAqB,WAAA;IAAe,EAAA;IAAY,WAAA;EAAA;AAAA;EAChD,IAAA;EAAqB,WAAA;IAAe,IAAA;IAAc,WAAA;EAAA;AAAA;EAElD,IAAA;EACA,mBAAA;IACE,sBAAA;IACA,WAAA;EAAA;AAAA;EAGF,IAAA;EAAa,GAAA;IAAO,IAAA;IAAc,WAAA;EAAA;AAAA;EAElC,IAAA;EACA,aAAA;IAAiB,IAAA;IAAc,WAAA;EAAA;AAAA;;;AA6ErC;;;;;;UAlEiB,oBAAA;EAAA,SACN,MAAA;EAAA,SACA,IAAA,EAAM,cAAA;AAAA;;;;;;;iBASD,gBAAA,CACd,KAAA,YACC,KAAA,IAAS,oBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAqDC,eAAA;;;;;IAKT,EAAA;IACA,WAAA;EAAA,MACE,oBAAA;;;;;IAQF,IAAA;IACA,WAAA;EAAA,MACE,oBAAA;;;;;IAQF,oBAAA;IACA,WAAA;EAAA,MACE,oBAAA;;;;;IAcF,IAAA;IACA,WAAA;EAAA,MACE,oBAAA;;;;;IAQF,IAAA;IACA,WAAA;EAAA,MACE,oBAAA;AAAA;;;;;;;cAgBO,wBAAA;;AAyHb;;;;UAlHiB,mBAAA;EACf,WAAA,GAAc,cAAA;AAAA;AAAA,UAgBC,2BAAA;EAiG4B;;;;EA5F3C,KAAA;EA8FQ;;;;;;;;;;;;EAjFR,eAAA,GAAkB,mBAAA;EA8GA;;;;;AAgcpB;;;;EApiBE,SAAA;AAAA;AAAA,UAGQ,+BAAA;EACR,UAAA,EAAY,UAAA;EACZ,KAAA;EACA,SAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA+DW,oBAAA,YAAgC,YAAA;EAAA,QACnC,UAAA;EAAA,QACA,KAAA;EAAA,QACA,SAAA;;;;;;;WAQC,iBAAA;;;;;;;;WASA,kBAAA;cAEG,OAAA,EAAS,+BAAA;EAMd,GAAA,CACL,KAAA,EAAO,UAAA,EACP,OAAA,EAAS,eAAA,GACR,cAAA,CAAe,UAAA;EAAA,QAiBH,cAAA;;;;;;;;;UA+NP,UAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgNY,iBAAA,CACpB,OAAA,EAAS,2BAAA,GACR,OAAA,CAAQ,YAAA"}