@dbx-tools/shared-model 0.3.21 → 0.3.23

package/README.md

@@ -14,9 +14,12 @@ Key features:
 - Browser-safe zod schemas for lookup requests, endpoint summaries, ranked
   results, and profile metadata.
 - Endpoint classifier that groups serving endpoints by score profile and family
-  naming conventions.
+  naming conventions, plus `classify.endpointCapabilities` for chat / embedding
+  / tool-calling capability flags.
 - Version/family parsing helpers for model catalogues and tests.
 - Human-readable endpoint display names via `display.toModelDisplayName`.
+- OpenAI wire contracts: chat message/tool-call types plus a Responses API
+  translator, so a proxy, a route, and a UI all speak the same payload shapes.
 - Types that match the server selection API without depending on the Databricks
   SDK.
 
@@ -89,12 +92,66 @@ const version = classify.versionTuple("llama-3-1-70b");
 Family parsing helps callers bucket custom lists or explain why an endpoint
 landed in a class before the live workspace scores are available.
 
+## Ask What An Endpoint Can Do
+
+```ts
+const caps = classify.endpointCapabilities(endpoint);
+if (caps.chat) offerInChatPicker(endpoint);
+```
+
+Capability comes from the Databricks task hint (`llm/v1/chat` /
+`llm/v1/embeddings`) with the classified class as the fallback for endpoints
+Databricks left untagged. Filter on this rather than comparing raw `task`
+strings, so every picker, CLI, and route agrees on what "chat-capable" means.
+
+## Translate The OpenAI Responses API
+
+```ts
+import { openaiResponses } from "@dbx-tools/shared-model";
+
+const { chat, stream } = openaiResponses.responsesToChat(requestBody);
+// ... POST `chat` to the endpoint's invocations URL ...
+const response = openaiResponses.chatToResponse(completion, modelId);
+```
+
+Databricks serving endpoints speak Chat Completions; some clients (the Codex
+CLI, for one) speak only the Responses API. `openaiResponses` bridges the two in
+both directions, including a streaming translator
+(`createResponsesStreamTranslator`) that lifts `chat.completion.chunk` SSE into
+the Responses event stream, and `readResponsesOutput` for pulling the answer and
+its citations back out of a native Responses reply. Pure functions over plain
+JSON, so the same translation runs in a proxy, a server route, or a test.
+
+## Strip Fields Databricks Rejects
+
+```ts
+import { openaiChat } from "@dbx-tools/shared-model";
+
+const dropped = openaiChat.stripUnsupportedChatFields(body); // mutates `body`
+```
+
+Databricks Model Serving validates the chat body strictly: one unrecognized
+top-level key fails the entire turn rather than being ignored. An OpenAI client
+that sends `parallel_tool_calls` gets back
+`parallel_tool_calls: Extra inputs are not permitted` and no completion at all.
+
+`stripUnsupportedChatFields` deletes the known offenders in place and returns
+what it removed, so a caller can log the difference. Reach for it on any path
+that forwards a client body largely as-is; a translator that copies fields
+one-by-one (`openaiResponses.responsesToChat`) already can't leak them. Pass
+`extra` names to cover a workspace that rejects something not yet in
+`openaiChat.UNSUPPORTED_CHAT_FIELDS`.
+
 ## Modules
 
 - `model` - `ModelClass`, zod schemas, and inferred types for profiles,
   endpoint summaries, lookup requests, and ranked results.
-- `classify` - family parsing, version tuple parsing, and endpoint
-  classification.
+- `classify` - family parsing, version tuple parsing, endpoint classification,
+  and capability flags.
+- `display` - human-readable endpoint labels.
+- `openaiChat` - Chat Completions message / tool-call types,
+  `chatContentToText`, and `stripUnsupportedChatFields`.
+- `openaiResponses` - Responses API translation, in both directions.
 
 Server-side selection, cache, and fuzzy endpoint matching are in
 [`@dbx-tools/model`](../../node/model).

package/index.ts

@@ -5,5 +5,9 @@
 export * as classify from "./src/classify";
 export * as display from "./src/display";
 export * as model from "./src/model";
-export type { FamilyClass } from "./src/classify";
+export * as openaiChat from "./src/openai-chat";
+export * as openaiResponses from "./src/openai-responses";
+export type { EndpointCapabilities, FamilyClass } from "./src/classify";
 export type { ModelProfile, ServingEndpointSummary, ModelQuery, RankedModel } from "./src/model";
+export type { ChatRole, ChatContentPart, ChatToolCallFunction, ChatToolCall, ChatMessage, ChatContentToTextOptions } from "./src/openai-chat";
+export type { ResponsesStreamTranslator, ResponsesCitation, ResponsesOutput } from "./src/openai-responses";

package/package.json

@@ -12,14 +12,14 @@
   },
   "dependencies": {
     "zod": "^4.3.6",
-    "@dbx-tools/shared-core": "0.3.21"
+    "@dbx-tools/shared-core": "0.3.23"
   },
   "main": "index.ts",
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.21",
+  "version": "0.3.23",
   "types": "index.ts",
   "type": "module",
   "exports": {

package/src/classify.ts

@@ -34,6 +34,34 @@ const CHAT_TASK = "llm/v1/chat";
 /** Task hint Databricks stamps on embedding endpoints. */
 const EMBEDDING_TASK = "llm/v1/embeddings";
 
+/** What an endpoint can be asked to do, as derived by {@link endpointCapabilities}. */
+export interface EndpointCapabilities {
+  /** OpenAI chat/completions + Responses: the surface a chat agent needs. */
+  chat: boolean;
+  /** Embedding (vector) endpoint. */
+  embedding: boolean;
+  /** Function / tool calling. Every chat endpoint on Databricks supports it. */
+  tools: boolean;
+}
+
+/**
+ * Derive an endpoint's capabilities from its Databricks task hint and its
+ * classified {@link ModelClass}, so consumers filter on capability instead of
+ * re-deriving it from raw `task` / `class` strings.
+ *
+ * Either signal alone is enough: the task hint is authoritative when present,
+ * and the class covers endpoints Databricks left untasked but the classifier
+ * recognized. Embedding wins over chat when both point at it, since the two are
+ * not interchangeable.
+ */
+export function endpointCapabilities(endpoint: ServingEndpointSummary): EndpointCapabilities {
+  const embedding = endpoint.task === EMBEDDING_TASK || endpoint.class === ModelClass.Embedding;
+  // Every non-embedding class is a chat band, so "classified but not embedding"
+  // is the class-side test for chat capability.
+  const chat = !embedding && (endpoint.task === CHAT_TASK || endpoint.class !== undefined);
+  return { chat, embedding, tools: chat };
+}
+
 /** Family-heuristic classification of a single endpoint name. */
 export interface FamilyClass {
   /** Chat capability band the family maps to (never embedding). */

package/src/display.ts

@@ -103,11 +103,7 @@ function renderSegment(segment: string): string {
     const token = tokens[i]!;
     const lower = token.toLowerCase();
     // Glue a size unit onto the preceding number: `120` + `b` -> `120B`.
-    if (
-      SIZE_UNITS.has(lower) &&
-      out.length > 0 &&
-      /^\d+$/.test(out[out.length - 1]!)
-    ) {
+    if (SIZE_UNITS.has(lower) && out.length > 0 && /^\d+$/.test(out[out.length - 1]!)) {
       out[out.length - 1] = `${out[out.length - 1]}${lower.toUpperCase()}`;
       continue;
     }

package/src/openai-chat.ts

@@ -0,0 +1,153 @@
+/**
+ * OpenAI Chat Completions wire shapes, as Databricks Model Serving speaks them.
+ *
+ * These are the request/reply payload types for `/chat/completions` and a
+ * serving endpoint's `invocations` URL. They are deliberately declared here
+ * rather than imported from the OpenAI or AI SDK packages: both keep these
+ * fields under internal namespaces that are not part of their public API,
+ * whereas the wire payload itself is the stable contract every caller in this
+ * repo actually codes against.
+ *
+ * Pure types plus one text-flattening helper - no zod, no runtime deps - so a
+ * browser client, a Node proxy, and an AppKit plugin can all agree on the shape
+ * without any of them pulling in the others' dependencies.
+ *
+ * @module
+ */
+
+/**
+ * The roles OpenAI defines for a chat turn. {@link ChatMessage.role} is typed as
+ * a plain string rather than this union, because providers add their own (for
+ * example Databricks-hosted Claude replays a `"reasoning"` turn); use this when
+ * you want the standard set named.
+ */
+export type ChatRole = "system" | "developer" | "user" | "assistant" | "tool";
+
+/**
+ * One entry of a structured `content` array. Only `type` and `text` are read
+ * here; the index signature keeps provider-specific parts (images, thinking
+ * blocks, cache markers) intact through a parse/serialize round trip.
+ */
+export interface ChatContentPart {
+  type?: string;
+  text?: string;
+  [key: string]: unknown;
+}
+
+/** The function a tool call invokes, with its arguments as a JSON string. */
+export interface ChatToolCallFunction {
+  name: string;
+  /** JSON-encoded argument object. Streamed in fragments, so assemble before parsing. */
+  arguments: string;
+}
+
+/** One tool call attached to an assistant turn. */
+export interface ChatToolCall {
+  id: string;
+  /** `"function"` in practice; widened so an unrecognized type round-trips. */
+  type: string;
+  function: ChatToolCallFunction;
+}
+
+/**
+ * A single chat message. `content` is nullable because an assistant turn that
+ * only calls tools carries `content: null`.
+ */
+export interface ChatMessage {
+  /** See {@link ChatRole} for the standard values; widened for provider extensions. */
+  role: string;
+  content?: string | ChatContentPart[] | null;
+  tool_calls?: ChatToolCall[];
+  /** Set on a `tool` turn, keying it back to the call it answers. */
+  tool_call_id?: string;
+  name?: string;
+}
+
+/**
+ * Top-level request fields an OpenAI client may send that Databricks Model
+ * Serving rejects outright, failing the whole turn rather than ignoring them.
+ *
+ * Databricks validates the chat body strictly, so an unrecognized key comes
+ * back as `parallel_tool_calls: Extra inputs are not permitted` (the
+ * gateway's pydantic validation) or `json: unknown field "parallel_tool_calls"`
+ * (its strict JSON decode), depending on the endpoint. Everything listed here
+ * is either OpenAI-platform bookkeeping with no bearing on the completion, or -
+ * in the case of `parallel_tool_calls` - a real setting Databricks has no way
+ * to accept, so dropping it is the only way the request can succeed at all.
+ *
+ * Callers that translate a request field-by-field (an allowlist, as
+ * `openaiResponses.responsesToChat` does) never need this; it exists for the
+ * paths that forward a client body largely as-is.
+ */
+export const UNSUPPORTED_CHAT_FIELDS: readonly string[] = [
+  // Tool-calling concurrency hint. Databricks rejects it; the upstream provider
+  // decides parallelism itself.
+  "parallel_tool_calls",
+  // Response-persistence and bookkeeping fields for OpenAI's own platform.
+  "store",
+  "metadata",
+  "service_tier",
+  "prompt_cache_key",
+  "safety_identifier",
+];
+
+/**
+ * Delete the fields Databricks rejects from a chat request body, in place.
+ * Returns the names actually removed so a caller can log what it dropped.
+ *
+ * @param body - Parsed chat request body. Mutated.
+ * @param extra - Additional field names to drop, for a workspace or endpoint
+ *   that rejects something not yet in {@link UNSUPPORTED_CHAT_FIELDS}.
+ */
+export function stripUnsupportedChatFields(
+  body: Record<string, unknown>,
+  extra: readonly string[] = [],
+): string[] {
+  const dropped: string[] = [];
+  for (const field of [...UNSUPPORTED_CHAT_FIELDS, ...extra]) {
+    if (!(field in body)) continue;
+    delete body[field];
+    dropped.push(field);
+  }
+  return dropped;
+}
+
+/** Options for {@link chatContentToText}. */
+export interface ChatContentToTextOptions {
+  /**
+   * Placed between parts. Defaults to `""`, which reassembles a message that was
+   * split purely for transport; pass `"\n\n"` when the parts are separate
+   * paragraphs that a human will read.
+   */
+  separator?: string;
+  /**
+   * Restrict to these `type` values. Defaults to accepting any part carrying
+   * `text`, which covers the `input_text` / `output_text` / `text` spellings
+   * different APIs use for the same thing.
+   */
+  types?: readonly string[];
+}
+
+/**
+ * Flatten a message `content` value to plain text. Accepts the string form and
+ * the structured-parts form ({@link ChatContentPart}), and yields `""` for
+ * anything else (null, a lone image part, a malformed payload). Typed as
+ * `unknown` because most callers are reading a just-parsed JSON body, and the
+ * point of this helper is that they do not have to pre-check it.
+ */
+export function chatContentToText(
+  content: unknown,
+  options: ChatContentToTextOptions = {},
+): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  const { separator = "", types } = options;
+  const parts: string[] = [];
+  for (const raw of content) {
+    if (!raw || typeof raw !== "object") continue;
+    const part = raw as ChatContentPart;
+    if (types && (typeof part.type !== "string" || !types.includes(part.type))) continue;
+    if (typeof part.text === "string") parts.push(part.text);
+  }
+  return parts.join(separator);
+}

package/src/openai-responses.ts

@@ -0,0 +1,446 @@
+/**
+ * OpenAI Responses API <-> Chat Completions translation.
+ *
+ * Some clients speak only the Responses API (`POST /v1/responses`) - the Codex
+ * CLI is the motivating one - while Databricks serving endpoints speak only
+ * Chat Completions (`messages`) at their `invocations` URL. This module bridges
+ * the two, in both directions:
+ *
+ *   - {@link responsesToChat} lowers a Responses request body to a chat
+ *     completions body (instructions -> system message, typed `input` items ->
+ *     `messages`, `tools`/`tool_choice` carried through, function-call outputs
+ *     folded back into the transcript).
+ *   - {@link chatToResponse} lifts a non-streaming chat completion back into a
+ *     Responses `response` object.
+ *   - {@link createResponsesStreamTranslator} lifts a streaming chat completion
+ *     (an OpenAI SSE `chat.completion.chunk` stream) into the Responses SSE
+ *     event stream those clients consume (`response.created`,
+ *     `response.output_text.delta`, function-call argument deltas,
+ *     `response.completed`).
+ *   - {@link readResponsesOutput} reads the other direction: pull the answer
+ *     text and citations out of a `response` object returned by an endpoint
+ *     that speaks Responses natively (the Databricks native web-search tool).
+ *
+ * Only the surface real clients exercise is translated; unknown fields are
+ * ignored rather than rejected, so a newer client degrades instead of breaking.
+ *
+ * Browser-safe: pure functions over plain JSON, no transport and no Node
+ * built-ins, so the same translation runs in a proxy, a server route, or a test.
+ *
+ * @module
+ */
+
+import { type ChatMessage, chatContentToText } from "./openai-chat";
+
+/**
+ * Lower a Responses request body to a chat-completions body. Returns the chat
+ * body plus whether the caller asked for streaming (the server needs it to pick
+ * the upstream `accept` header and the translation path).
+ */
+export function responsesToChat(body: Record<string, unknown>): {
+  chat: Record<string, unknown>;
+  stream: boolean;
+} {
+  const messages: ChatMessage[] = [];
+
+  // `instructions` becomes the leading system message.
+  if (typeof body.instructions === "string" && body.instructions.length > 0) {
+    messages.push({ role: "system", content: body.instructions });
+  }
+
+  // `input` is an array of typed items: messages, function_call, and
+  // function_call_output. Fold each into the chat transcript.
+  const input = Array.isArray(body.input) ? body.input : [];
+  for (const raw of input) {
+    if (!raw || typeof raw !== "object") continue;
+    const item = raw as Record<string, unknown>;
+    const type = item.type;
+
+    if (type === "function_call") {
+      // A prior tool call the model made; re-attach it to an assistant turn.
+      messages.push({
+        role: "assistant",
+        content: null,
+        tool_calls: [
+          {
+            id: String(item.call_id ?? item.id ?? ""),
+            type: "function",
+            function: {
+              name: String(item.name ?? ""),
+              arguments: typeof item.arguments === "string" ? item.arguments : "{}",
+            },
+          },
+        ],
+      });
+      continue;
+    }
+
+    if (type === "function_call_output") {
+      // The tool's result, keyed back to the call it answers.
+      messages.push({
+        role: "tool",
+        tool_call_id: String(item.call_id ?? item.id ?? ""),
+        content: typeof item.output === "string" ? item.output : chatContentToText(item.output),
+      });
+      continue;
+    }
+
+    // Default: a message item with a role and typed content.
+    const role = typeof item.role === "string" ? item.role : "user";
+    // Chat has no "developer" role; treat it as system (its intent here).
+    const chatRole = role === "developer" ? "system" : role;
+    messages.push({ role: chatRole, content: chatContentToText(item.content) });
+  }
+
+  const chat: Record<string, unknown> = {
+    model: body.model,
+    messages,
+    stream: body.stream === true,
+  };
+
+  // Carry through function-calling config when present. Responses function
+  // tools are FLAT (`{type:"function", name, description, parameters}`); chat
+  // wants them NESTED (`{type:"function", function:{name, …}}`). Clients also
+  // send built-in tool types (local_shell, web_search, …) that Databricks chat
+  // rejects ("Missing 'function' in the tool specification"), so we translate
+  // only function tools and drop the rest.
+  if (Array.isArray(body.tools) && body.tools.length > 0) {
+    const chatTools = body.tools
+      .map((t) => {
+        const tool = t as Record<string, unknown>;
+        // Already chat-nested (`function` object present): pass through.
+        if (tool.type === "function" && tool.function && typeof tool.function === "object") {
+          return tool;
+        }
+        // Flat Responses function tool: nest it.
+        if (tool.type === "function" && typeof tool.name === "string") {
+          return {
+            type: "function",
+            function: {
+              name: tool.name,
+              ...(tool.description ? { description: tool.description } : {}),
+              ...(tool.parameters ? { parameters: tool.parameters } : {}),
+            },
+          };
+        }
+        return undefined; // non-function built-in tool: unsupported upstream, drop
+      })
+      .filter((t): t is Record<string, unknown> => t !== undefined);
+    if (chatTools.length > 0) {
+      chat.tools = chatTools;
+      if (body.tool_choice !== undefined) chat.tool_choice = body.tool_choice;
+      // NOTE: do NOT forward `parallel_tool_calls`. Clients send it, but
+      // Databricks Model Serving's chat API rejects unknown fields
+      // ("parallel_tool_calls: Extra inputs are not permitted"), which would
+      // fail the whole turn. Drop it.
+    }
+  }
+
+  return { chat, stream: body.stream === true };
+}
+
+/** Lift a non-streaming chat completion JSON into a Responses `response` object. */
+export function chatToResponse(chat: Record<string, unknown>, model: string): unknown {
+  const choices = Array.isArray(chat.choices) ? chat.choices : [];
+  const first = (choices[0] ?? {}) as Record<string, unknown>;
+  const message = (first.message ?? {}) as Record<string, unknown>;
+  const output: unknown[] = [];
+
+  const text = typeof message.content === "string" ? message.content : "";
+  if (text) {
+    output.push({
+      type: "message",
+      role: "assistant",
+      content: [{ type: "output_text", text }],
+    });
+  }
+
+  // Surface any tool calls as Responses `function_call` output items.
+  const toolCalls = Array.isArray(message.tool_calls) ? message.tool_calls : [];
+  for (const raw of toolCalls) {
+    const call = raw as Record<string, unknown>;
+    const fn = (call.function ?? {}) as Record<string, unknown>;
+    output.push({
+      type: "function_call",
+      call_id: String(call.id ?? ""),
+      name: String(fn.name ?? ""),
+      arguments: typeof fn.arguments === "string" ? fn.arguments : "{}",
+    });
+  }
+
+  const usage = (chat.usage ?? {}) as Record<string, unknown>;
+  return {
+    id: String(chat.id ?? "resp"),
+    object: "response",
+    created_at: typeof chat.created === "number" ? chat.created : 0,
+    model,
+    status: "completed",
+    output,
+    usage: {
+      input_tokens: Number(usage.prompt_tokens ?? 0),
+      output_tokens: Number(usage.completion_tokens ?? 0),
+      total_tokens: Number(usage.total_tokens ?? 0),
+    },
+  };
+}
+
+/** One Server-Sent Event, ready to write to the client. */
+function sse(event: string, data: unknown): string {
+  return `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+}
+
+/**
+ * Incremental chat-chunk -> Responses-SSE translator. `feed` and `finish` both
+ * return the SSE bytes to forward, or `""` when a chunk produced no event.
+ */
+export interface ResponsesStreamTranslator {
+  /** Translate one upstream `chat.completion.chunk` object. */
+  feed(chunk: Record<string, unknown>): string;
+  /** Close any open items and emit `response.completed`. Call once, at end of stream. */
+  finish(): string;
+}
+
+/**
+ * Translate an upstream chat-completions SSE stream into the Responses SSE
+ * event stream a Responses client consumes.
+ *
+ * Upstream chunks are `chat.completion.chunk` objects whose `choices[0].delta`
+ * carries incremental `content` (assistant text) and/or `tool_calls` (function
+ * calls, streamed by `index` with partial `arguments`). We emit the Responses
+ * lifecycle around them:
+ *
+ *   response.created
+ *   -> per text run:  output_item.added → output_text.delta* → output_item.done
+ *   -> per tool call: output_item.added → function_call_arguments.delta*
+ *                       → function_call_arguments.done → output_item.done
+ *   response.completed   (with the assembled final `response` object)
+ *
+ * The translator is intentionally tolerant: malformed/keepalive lines yield
+ * nothing.
+ */
+export function createResponsesStreamTranslator(
+  model: string,
+  responseId: string,
+): ResponsesStreamTranslator {
+  let started = false;
+  let outputIndex = 0;
+
+  // Text run state: whether a message item is currently open, and its buffer.
+  let textOpen = false;
+  let textBuffer = "";
+  let textItemId = "";
+
+  // Tool-call state, keyed by the upstream `tool_calls[].index`.
+  interface ToolState {
+    outputIndex: number;
+    callId: string;
+    name: string;
+    args: string;
+  }
+  const tools = new Map<number, ToolState>();
+
+  const created = () =>
+    sse("response.created", {
+      type: "response.created",
+      response: { id: responseId, object: "response", status: "in_progress", model, output: [] },
+    });
+
+  function openText(): string {
+    textOpen = true;
+    textItemId = `${responseId}-msg-${outputIndex}`;
+    const ev = sse("response.output_item.added", {
+      type: "response.output_item.added",
+      output_index: outputIndex,
+      item: { id: textItemId, type: "message", role: "assistant", content: [] },
+    });
+    return ev;
+  }
+
+  function closeText(): string {
+    if (!textOpen) return "";
+    const item = {
+      id: textItemId,
+      type: "message",
+      role: "assistant",
+      content: [{ type: "output_text", text: textBuffer }],
+    };
+    const ev =
+      sse("response.output_text.done", {
+        type: "response.output_text.done",
+        item_id: textItemId,
+        output_index: outputIndex,
+        content_index: 0,
+        text: textBuffer,
+      }) +
+      sse("response.output_item.done", {
+        type: "response.output_item.done",
+        output_index: outputIndex,
+        item,
+      });
+    textOpen = false;
+    textBuffer = "";
+    outputIndex += 1;
+    return ev;
+  }
+
+  function feed(chunk: Record<string, unknown>): string {
+    let out = "";
+    if (!started) {
+      started = true;
+      out += created();
+    }
+    const choices = Array.isArray(chunk.choices) ? chunk.choices : [];
+    const choice = (choices[0] ?? {}) as Record<string, unknown>;
+    const delta = (choice.delta ?? {}) as Record<string, unknown>;
+
+    // Assistant text deltas.
+    if (typeof delta.content === "string" && delta.content.length > 0) {
+      if (!textOpen) out += openText();
+      textBuffer += delta.content;
+      out += sse("response.output_text.delta", {
+        type: "response.output_text.delta",
+        item_id: textItemId,
+        output_index: outputIndex,
+        content_index: 0,
+        delta: delta.content,
+      });
+    }
+
+    // Tool-call deltas: each is keyed by `index`; `arguments` arrives in pieces.
+    const toolDeltas = Array.isArray(delta.tool_calls) ? delta.tool_calls : [];
+    for (const rawTc of toolDeltas) {
+      const tc = rawTc as Record<string, unknown>;
+      const idx = Number(tc.index ?? 0);
+      const fn = (tc.function ?? {}) as Record<string, unknown>;
+      let state = tools.get(idx);
+      if (!state) {
+        // First fragment for this call: a text run (if open) must close first so
+        // output ordering stays monotonic, then we open a function_call item.
+        out += closeText();
+        state = {
+          outputIndex,
+          callId: String(tc.id ?? `${responseId}-call-${idx}`),
+          name: String(fn.name ?? ""),
+          args: "",
+        };
+        tools.set(idx, state);
+        out += sse("response.output_item.added", {
+          type: "response.output_item.added",
+          output_index: state.outputIndex,
+          item: {
+            id: state.callId,
+            type: "function_call",
+            call_id: state.callId,
+            name: state.name,
+            arguments: "",
+          },
+        });
+        outputIndex += 1;
+      }
+      if (typeof fn.name === "string" && fn.name && !state.name) state.name = fn.name;
+      if (typeof fn.arguments === "string" && fn.arguments.length > 0) {
+        state.args += fn.arguments;
+        out += sse("response.function_call_arguments.delta", {
+          type: "response.function_call_arguments.delta",
+          item_id: state.callId,
+          output_index: state.outputIndex,
+          delta: fn.arguments,
+        });
+      }
+    }
+    return out;
+  }
+
+  function finish(): string {
+    let out = closeText();
+    // Close any open tool calls, emitting their assembled arguments.
+    for (const state of tools.values()) {
+      out += sse("response.function_call_arguments.done", {
+        type: "response.function_call_arguments.done",
+        item_id: state.callId,
+        output_index: state.outputIndex,
+        arguments: state.args,
+      });
+      out += sse("response.output_item.done", {
+        type: "response.output_item.done",
+        output_index: state.outputIndex,
+        item: {
+          id: state.callId,
+          type: "function_call",
+          call_id: state.callId,
+          name: state.name,
+          arguments: state.args,
+        },
+      });
+    }
+    out += sse("response.completed", {
+      type: "response.completed",
+      response: { id: responseId, object: "response", status: "completed", model },
+    });
+    return out;
+  }
+
+  return { feed, finish };
+}
+
+/** A source the model cited, as carried by a Responses content-part annotation. */
+export interface ResponsesCitation {
+  url: string;
+  title?: string;
+}
+
+/** What {@link readResponsesOutput} pulls out of a `response` object. */
+export interface ResponsesOutput {
+  /** The assistant's answer, with the output items concatenated. */
+  text: string;
+  /** Cited sources in first-seen order, deduplicated by URL. */
+  citations: ResponsesCitation[];
+}
+
+/**
+ * Read the answer text and cited sources out of a Responses `response` payload.
+ *
+ * This is the inverse of {@link chatToResponse}: it consumes what an endpoint
+ * speaking Responses natively returns, rather than producing it. The Databricks
+ * native web-search tool answers this way, with each source attached as a
+ * `url_citation` annotation on the content part that used it.
+ *
+ * Prefers the flattened `output_text` when the payload carries it, and falls
+ * back to walking `output[].content[].text`. Every field is optional upstream,
+ * so a payload missing any of it yields empty results rather than throwing.
+ */
+export function readResponsesOutput(payload: Record<string, unknown>): ResponsesOutput {
+  const output = Array.isArray(payload.output) ? (payload.output as unknown[]) : [];
+  const texts: string[] = [];
+  const citations: ResponsesCitation[] = [];
+  const seen = new Set<string>();
+
+  for (const rawItem of output) {
+    if (!rawItem || typeof rawItem !== "object") continue;
+    const content = (rawItem as Record<string, unknown>).content;
+    if (!Array.isArray(content)) continue;
+    for (const rawPart of content) {
+      if (!rawPart || typeof rawPart !== "object") continue;
+      const part = rawPart as Record<string, unknown>;
+      const text = str(part.text);
+      if (text) texts.push(text);
+      const annotations = Array.isArray(part.annotations) ? part.annotations : [];
+      for (const rawAnn of annotations) {
+        if (!rawAnn || typeof rawAnn !== "object") continue;
+        const ann = rawAnn as Record<string, unknown>;
+        const url = str(ann.url);
+        if (!url || seen.has(url)) continue;
+        seen.add(url);
+        const title = str(ann.title);
+        citations.push({ url, ...(title ? { title } : {}) });
+      }
+    }
+  }
+
+  return { text: str(payload.output_text) || texts.join("\n").trim(), citations };
+}
+
+/** Coerce an unknown JSON value to a trimmed string, or `""` when it isn't one. */
+function str(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}

package/test/classify.test.ts

@@ -1,6 +1,11 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
-import { classifyByFamily, classifyEndpoints, versionTuple } from "../src/classify";
+import {
+  classifyByFamily,
+  classifyEndpoints,
+  endpointCapabilities,
+  versionTuple,
+} from "../src/classify";
 import { ModelClass, type ModelProfile, type ServingEndpointSummary } from "../src/model";
 
 const CHAT_TASK = "llm/v1/chat";
@@ -49,6 +54,53 @@ describe("versionTuple", () => {
   });
 });
 
+describe("endpointCapabilities", () => {
+  it("reads capability off the task hint", () => {
+    assert.deepEqual(endpointCapabilities(chat("databricks-gpt-5-5")), {
+      chat: true,
+      embedding: false,
+      tools: true,
+    });
+    assert.deepEqual(endpointCapabilities(embedding("databricks-gte-large-en")), {
+      chat: false,
+      embedding: true,
+      tools: false,
+    });
+  });
+
+  it("falls back to the classified class when the endpoint carries no task", () => {
+    assert.equal(
+      endpointCapabilities({ name: "custom", class: ModelClass.ChatFast }).chat,
+      true,
+    );
+    assert.equal(
+      endpointCapabilities({ name: "custom", class: ModelClass.Embedding }).embedding,
+      true,
+    );
+  });
+
+  it("keeps an unclassified, untasked endpoint out of both buckets", () => {
+    assert.deepEqual(endpointCapabilities({ name: "mystery" }), {
+      chat: false,
+      embedding: false,
+      tools: false,
+    });
+  });
+
+  it("lets embedding win when task and class disagree", () => {
+    const conflicted: ServingEndpointSummary = {
+      name: "databricks-gte-large-en",
+      task: EMBEDDING_TASK,
+      class: ModelClass.ChatFast,
+    };
+    assert.deepEqual(endpointCapabilities(conflicted), {
+      chat: false,
+      embedding: true,
+      tools: false,
+    });
+  });
+});
+
 describe("classifyEndpoints", () => {
   it("buckets scored models by quality quantiles, best-first", () => {
     // Three clear quality bands (gaps keep the 1/3 and 2/3 quantiles

package/test/display.test.ts

@@ -0,0 +1,45 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { toModelDisplayName } from "../src/display";
+
+describe("toModelDisplayName", () => {
+  it("strips a leading databricks prefix and dots the version", () => {
+    assert.equal(toModelDisplayName("databricks-claude-sonnet-4-6"), "Claude Sonnet 4.6");
+  });
+
+  it("strips the system.ai namespace and uppercases acronyms", () => {
+    assert.equal(toModelDisplayName("system.ai.bge_large_en"), "BGE Large En");
+  });
+
+  it("uppercases GPT/OSS and glues the size unit", () => {
+    assert.equal(toModelDisplayName("databricks-gpt-oss-120b"), "GPT OSS 120B");
+  });
+
+  it("restores AI casing", () => {
+    assert.equal(toModelDisplayName("databricks-ai-router"), "AI Router");
+  });
+
+  it("joins multi-part version runs with dots", () => {
+    assert.equal(
+      toModelDisplayName("databricks-meta-llama-3-3-70b-instruct"),
+      "Meta Llama 3.3 70B Instruct",
+    );
+  });
+
+  it("prefers a Databricks-provided name verbatim", () => {
+    assert.equal(
+      toModelDisplayName("databricks-claude-sonnet-4-6", "Claude Sonnet 4.6 (Preview)"),
+      "Claude Sonnet 4.6 (Preview)",
+    );
+  });
+
+  it("ignores a blank provided name and falls back to the derived label", () => {
+    assert.equal(toModelDisplayName("databricks-gpt-5-5", "   "), "GPT 5.5");
+  });
+
+  it("title-cases a bare vendor token when nothing else remains", () => {
+    // Only leading vendor prefixes are stripped, and never the last
+    // remaining token, so a name that is *only* a vendor word stays.
+    assert.equal(toModelDisplayName("databricks"), "Databricks");
+  });
+});

package/test/openai-chat.test.ts

@@ -0,0 +1,80 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  UNSUPPORTED_CHAT_FIELDS,
+  chatContentToText,
+  stripUnsupportedChatFields,
+} from "../src/openai-chat";
+
+describe("chatContentToText", () => {
+  it("passes a string through and flattens typed parts", () => {
+    assert.equal(chatContentToText("hello"), "hello");
+    assert.equal(
+      chatContentToText([{ type: "input_text", text: "a" }, { type: "output_text", text: "b" }]),
+      "ab",
+    );
+  });
+
+  it("honors a separator and a type filter", () => {
+    const content = [
+      { type: "text", text: "one" },
+      { type: "thinking", text: "hidden" },
+      { type: "text", text: "two" },
+    ];
+    assert.equal(chatContentToText(content, { separator: "\n\n", types: ["text"] }), "one\n\ntwo");
+  });
+
+  it("yields empty string for anything it can't read", () => {
+    assert.equal(chatContentToText(null), "");
+    assert.equal(chatContentToText(undefined), "");
+    assert.equal(chatContentToText([{ type: "image_url" }]), "");
+  });
+});
+
+describe("stripUnsupportedChatFields", () => {
+  it("drops parallel_tool_calls, the field Databricks rejects outright", () => {
+    const body: Record<string, unknown> = {
+      model: "databricks-claude-opus-4-8",
+      messages: [],
+      parallel_tool_calls: false,
+    };
+    assert.deepEqual(stripUnsupportedChatFields(body), ["parallel_tool_calls"]);
+    assert.deepEqual(body, { model: "databricks-claude-opus-4-8", messages: [] });
+  });
+
+  it("drops a field present with a falsy or null value", () => {
+    const body: Record<string, unknown> = { store: false, metadata: null };
+    assert.deepEqual(stripUnsupportedChatFields(body).sort(), ["metadata", "store"]);
+    assert.deepEqual(body, {});
+  });
+
+  it("leaves a supported body untouched and reports nothing dropped", () => {
+    const body: Record<string, unknown> = {
+      model: "m",
+      messages: [{ role: "user", content: "hi" }],
+      stream: true,
+      tools: [],
+      tool_choice: "auto",
+      temperature: 0.2,
+      max_tokens: 64,
+    };
+    const before = structuredClone(body);
+    assert.deepEqual(stripUnsupportedChatFields(body), []);
+    assert.deepEqual(body, before);
+  });
+
+  it("drops caller-supplied extra fields alongside the built-in list", () => {
+    const body: Record<string, unknown> = { store: true, future_field: 1, keep: 2 };
+    assert.deepEqual(stripUnsupportedChatFields(body, ["future_field"]), [
+      "store",
+      "future_field",
+    ]);
+    assert.deepEqual(body, { keep: 2 });
+  });
+
+  it("covers every name it advertises", () => {
+    const body = Object.fromEntries(UNSUPPORTED_CHAT_FIELDS.map((field) => [field, 1]));
+    assert.deepEqual(stripUnsupportedChatFields(body), [...UNSUPPORTED_CHAT_FIELDS]);
+    assert.deepEqual(body, {});
+  });
+});

package/test/openai-responses.test.ts

@@ -0,0 +1,242 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { ChatMessage } from "../src/openai-chat";
+import {
+  chatToResponse,
+  createResponsesStreamTranslator,
+  readResponsesOutput,
+  responsesToChat,
+} from "../src/openai-responses";
+
+/** The `messages` a lowered Responses body produced, typed for assertions. */
+function messagesOf(body: Record<string, unknown>): ChatMessage[] {
+  const { chat } = responsesToChat(body);
+  return chat.messages as ChatMessage[];
+}
+
+/** Event names, in order, from a block of SSE text. */
+function eventNames(sse: string): string[] {
+  return sse
+    .split("\n")
+    .filter((line) => line.startsWith("event: "))
+    .map((line) => line.slice("event: ".length));
+}
+
+/** Parsed `data:` payloads from a block of SSE text. */
+function eventData(sse: string): Record<string, unknown>[] {
+  return sse
+    .split("\n")
+    .filter((line) => line.startsWith("data: "))
+    .map((line) => JSON.parse(line.slice("data: ".length)) as Record<string, unknown>);
+}
+
+describe("responsesToChat", () => {
+  it("lowers instructions and message items into a chat transcript", () => {
+    const messages = messagesOf({
+      instructions: "be terse",
+      input: [{ type: "message", role: "user", content: [{ type: "input_text", text: "hi" }] }],
+    });
+    assert.deepEqual(messages, [
+      { role: "system", content: "be terse" },
+      { role: "user", content: "hi" },
+    ]);
+  });
+
+  it("maps the developer role to system (chat has no developer role)", () => {
+    const [first] = messagesOf({ input: [{ role: "developer", content: "policy" }] });
+    assert.equal(first?.role, "system");
+  });
+
+  it("re-attaches a prior function_call to an assistant turn", () => {
+    const [first] = messagesOf({
+      input: [{ type: "function_call", call_id: "c1", name: "lookup", arguments: '{"q":1}' }],
+    });
+    assert.equal(first?.role, "assistant");
+    assert.equal(first?.content, null);
+    assert.deepEqual(first?.tool_calls, [
+      { id: "c1", type: "function", function: { name: "lookup", arguments: '{"q":1}' } },
+    ]);
+  });
+
+  it("keys a function_call_output back to the call it answers", () => {
+    const [first] = messagesOf({
+      input: [{ type: "function_call_output", call_id: "c1", output: "42" }],
+    });
+    assert.deepEqual(first, { role: "tool", tool_call_id: "c1", content: "42" });
+  });
+
+  it("nests flat Responses function tools and drops built-in tool types", () => {
+    const { chat } = responsesToChat({
+      input: [],
+      tools: [
+        { type: "function", name: "lookup", description: "d", parameters: { type: "object" } },
+        { type: "local_shell" },
+        { type: "web_search" },
+      ],
+      tool_choice: "auto",
+    });
+    assert.deepEqual(chat.tools, [
+      {
+        type: "function",
+        function: { name: "lookup", description: "d", parameters: { type: "object" } },
+      },
+    ]);
+    assert.equal(chat.tool_choice, "auto");
+  });
+
+  it("never forwards parallel_tool_calls (Databricks rejects unknown fields)", () => {
+    const { chat } = responsesToChat({
+      input: [],
+      parallel_tool_calls: true,
+      tools: [{ type: "function", name: "lookup" }],
+    });
+    assert.ok(!("parallel_tool_calls" in chat));
+  });
+
+  it("reports the streaming flag", () => {
+    assert.equal(responsesToChat({ input: [] }).stream, false);
+    assert.equal(responsesToChat({ input: [], stream: true }).stream, true);
+  });
+});
+
+describe("chatToResponse", () => {
+  it("lifts assistant text, tool calls, and usage into a response object", () => {
+    const response = chatToResponse(
+      {
+        id: "chatcmpl-1",
+        created: 1700000000,
+        choices: [
+          {
+            message: {
+              content: "done",
+              tool_calls: [{ id: "c1", function: { name: "lookup", arguments: '{"q":1}' } }],
+            },
+          },
+        ],
+        usage: { prompt_tokens: 3, completion_tokens: 4, total_tokens: 7 },
+      },
+      "databricks-claude-opus-4-8",
+    ) as Record<string, unknown>;
+
+    assert.equal(response.id, "chatcmpl-1");
+    assert.equal(response.status, "completed");
+    assert.equal(response.model, "databricks-claude-opus-4-8");
+    assert.deepEqual(response.output, [
+      { type: "message", role: "assistant", content: [{ type: "output_text", text: "done" }] },
+      { type: "function_call", call_id: "c1", name: "lookup", arguments: '{"q":1}' },
+    ]);
+    assert.deepEqual(response.usage, { input_tokens: 3, output_tokens: 4, total_tokens: 7 });
+  });
+
+  it("omits the message item when the turn was tool calls only", () => {
+    const response = chatToResponse(
+      { choices: [{ message: { content: null, tool_calls: [] } }] },
+      "m",
+    ) as { output: unknown[] };
+    assert.deepEqual(response.output, []);
+  });
+});
+
+describe("createResponsesStreamTranslator", () => {
+  it("opens on the first chunk and closes the text run at finish", () => {
+    const translator = createResponsesStreamTranslator("m", "resp-1");
+    const first = translator.feed({ choices: [{ delta: { content: "he" } }] });
+    assert.deepEqual(eventNames(first), [
+      "response.created",
+      "response.output_item.added",
+      "response.output_text.delta",
+    ]);
+
+    const second = translator.feed({ choices: [{ delta: { content: "llo" } }] });
+    assert.deepEqual(eventNames(second), ["response.output_text.delta"]);
+
+    const done = translator.finish();
+    assert.deepEqual(eventNames(done), [
+      "response.output_text.done",
+      "response.output_item.done",
+      "response.completed",
+    ]);
+    // The buffered text is what the client renders as the final message.
+    assert.equal(eventData(done)[0]?.text, "hello");
+  });
+
+  it("assembles argument fragments into one function_call item", () => {
+    const translator = createResponsesStreamTranslator("m", "resp-1");
+    translator.feed({
+      choices: [
+        { delta: { tool_calls: [{ index: 0, id: "c1", function: { name: "lookup" } }] } },
+      ],
+    });
+    translator.feed({ choices: [{ delta: { tool_calls: [{ index: 0, function: { arguments: '{"q' } }] } }] });
+    translator.feed({ choices: [{ delta: { tool_calls: [{ index: 0, function: { arguments: '":1}' } }] } }] });
+
+    const done = translator.finish();
+    const [args] = eventData(done);
+    assert.equal(args?.arguments, '{"q":1}');
+    assert.ok(eventNames(done).includes("response.function_call_arguments.done"));
+  });
+
+  it("closes an open text run before opening a tool call so output stays ordered", () => {
+    const translator = createResponsesStreamTranslator("m", "resp-1");
+    translator.feed({ choices: [{ delta: { content: "thinking" } }] });
+    const withTool = translator.feed({
+      choices: [{ delta: { tool_calls: [{ index: 0, id: "c1", function: { name: "f" } }] } }],
+    });
+    assert.deepEqual(eventNames(withTool), [
+      "response.output_text.done",
+      "response.output_item.done",
+      "response.output_item.added",
+    ]);
+  });
+
+  it("emits nothing but the lifecycle for an empty chunk", () => {
+    const translator = createResponsesStreamTranslator("m", "resp-1");
+    assert.deepEqual(eventNames(translator.feed({})), ["response.created"]);
+    assert.deepEqual(eventNames(translator.finish()), ["response.completed"]);
+  });
+});
+
+describe("readResponsesOutput", () => {
+  it("prefers the flattened output_text", () => {
+    const { text } = readResponsesOutput({
+      output_text: "  the answer  ",
+      output: [{ content: [{ text: "ignored" }] }],
+    });
+    assert.equal(text, "the answer");
+  });
+
+  it("falls back to joining the output items", () => {
+    const { text } = readResponsesOutput({
+      output: [{ content: [{ text: "one" }, { text: "two" }] }],
+    });
+    assert.equal(text, "one\ntwo");
+  });
+
+  it("collects url_citation annotations, deduplicated by url", () => {
+    const { citations } = readResponsesOutput({
+      output: [
+        {
+          content: [
+            {
+              text: "answer",
+              annotations: [
+                { type: "url_citation", url: "https://a.example", title: "A" },
+                { type: "url_citation", url: "https://a.example", title: "A again" },
+                { type: "url_citation", url: "https://b.example" },
+                { type: "file_citation" },
+              ],
+            },
+          ],
+        },
+      ],
+    });
+    assert.deepEqual(citations, [
+      { url: "https://a.example", title: "A" },
+      { url: "https://b.example" },
+    ]);
+  });
+
+  it("returns empty results for a payload with no output", () => {
+    assert.deepEqual(readResponsesOutput({}), { text: "", citations: [] });
+  });
+});

package/test/tsconfig.json

@@ -0,0 +1,14 @@
+// ~~ Generated by projen. To modify, edit .projenrc.js and run "pnpm exec projen".
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": ".."
+  },
+  "include": [
+    "**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}