@dbx-tools/shared-model 0.3.22 → 0.3.24

package/package.json

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

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-responses.ts

@@ -2,16 +2,22 @@
  * 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:
+ * CLI is the motivating one. Databricks now also exposes native Responses
+ * surfaces (`/serving-endpoints/responses` and `/serving-endpoints/open-responses`),
+ * while most endpoints still speak Chat Completions at `/invocations`. 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 chatToResponsesRequest} raises a chat-completions request into a
+ *     Responses request (the inverse of {@link responsesToChat}), for routing a
+ *     chat client at a Responses-only model like Codex.
  *   - {@link chatToResponse} lifts a non-streaming chat completion back into a
  *     Responses `response` object.
+ *   - {@link responseToChatCompletion} lifts a native Responses `response`
+ *     back into a chat-completions body (the inverse of {@link chatToResponse}).
  *   - {@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`,
@@ -139,6 +145,110 @@ export function responsesToChat(body: Record<string, unknown>): {
   return { chat, stream: body.stream === true };
 }
 
+/**
+ * Raise a chat-completions request into a Responses request body. Inverse of
+ * {@link responsesToChat}: used when a chat client hits a Responses-only
+ * Databricks model (e.g. Codex) so the proxy can POST to
+ * `/serving-endpoints/responses` without the client knowing.
+ */
+export function chatToResponsesRequest(body: Record<string, unknown>): {
+  responses: Record<string, unknown>;
+  stream: boolean;
+} {
+  const messages = Array.isArray(body.messages) ? body.messages : [];
+  const input: unknown[] = [];
+  let instructions: string | undefined;
+
+  for (const raw of messages) {
+    if (!raw || typeof raw !== "object") continue;
+    const message = raw as Record<string, unknown>;
+    const role = typeof message.role === "string" ? message.role : "user";
+
+    // Leading system / developer messages become top-level `instructions`.
+    if ((role === "system" || role === "developer") && instructions === undefined && input.length === 0) {
+      const text = chatContentToText(message.content);
+      if (text) instructions = text;
+      continue;
+    }
+
+    if (role === "tool") {
+      input.push({
+        type: "function_call_output",
+        call_id: String(message.tool_call_id ?? ""),
+        output: chatContentToText(message.content),
+      });
+      continue;
+    }
+
+    if (role === "assistant" && Array.isArray(message.tool_calls) && message.tool_calls.length > 0) {
+      for (const rawCall of message.tool_calls) {
+        if (!rawCall || typeof rawCall !== "object") continue;
+        const call = rawCall as Record<string, unknown>;
+        const fn = (call.function ?? {}) as Record<string, unknown>;
+        input.push({
+          type: "function_call",
+          call_id: String(call.id ?? ""),
+          name: String(fn.name ?? ""),
+          arguments: typeof fn.arguments === "string" ? fn.arguments : "{}",
+        });
+      }
+      const text = chatContentToText(message.content);
+      if (text) {
+        input.push({ type: "message", role: "assistant", content: text });
+      }
+      continue;
+    }
+
+    input.push({
+      type: "message",
+      role,
+      content: chatContentToText(message.content),
+    });
+  }
+
+  const responses: Record<string, unknown> = {
+    model: body.model,
+    input,
+    stream: body.stream === true,
+  };
+  if (instructions) responses.instructions = instructions;
+
+  // Chat tools are nested (`function: { name, … }`); Responses wants them flat.
+  if (Array.isArray(body.tools) && body.tools.length > 0) {
+    const tools = body.tools
+      .map((t) => {
+        if (!t || typeof t !== "object") return undefined;
+        const tool = t as Record<string, unknown>;
+        if (tool.type !== "function") return undefined;
+        if (tool.function && typeof tool.function === "object") {
+          const fn = tool.function as Record<string, unknown>;
+          return {
+            type: "function",
+            name: fn.name,
+            ...(fn.description ? { description: fn.description } : {}),
+            ...(fn.parameters ? { parameters: fn.parameters } : {}),
+          };
+        }
+        if (typeof tool.name === "string") return tool;
+        return undefined;
+      })
+      .filter((t): t is Record<string, unknown> => t !== undefined);
+    if (tools.length > 0) {
+      responses.tools = tools;
+      if (body.tool_choice !== undefined) responses.tool_choice = body.tool_choice;
+    }
+  }
+
+  // Prefer Responses' max_output_tokens naming; fall back from chat max_tokens.
+  if (typeof body.max_output_tokens === "number") {
+    responses.max_output_tokens = body.max_output_tokens;
+  } else if (typeof body.max_tokens === "number") {
+    responses.max_output_tokens = body.max_tokens;
+  }
+
+  return { responses, 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 : [];
@@ -184,6 +294,59 @@ export function chatToResponse(chat: Record<string, unknown>, model: string): un
   };
 }
 
+/**
+ * Lift a native Responses `response` object into a chat-completions body.
+ * Inverse of {@link chatToResponse}: used after a Responses-only upstream call
+ * when the client spoke Chat Completions.
+ */
+export function responseToChatCompletion(
+  response: Record<string, unknown>,
+  model: string,
+): Record<string, unknown> {
+  const { text } = readResponsesOutput(response);
+  const toolCalls: unknown[] = [];
+  const output = Array.isArray(response.output) ? response.output : [];
+  for (const raw of output) {
+    if (!raw || typeof raw !== "object") continue;
+    const item = raw as Record<string, unknown>;
+    if (item.type !== "function_call") continue;
+    toolCalls.push({
+      id: String(item.call_id ?? item.id ?? ""),
+      type: "function",
+      function: {
+        name: String(item.name ?? ""),
+        arguments: typeof item.arguments === "string" ? item.arguments : "{}",
+      },
+    });
+  }
+
+  const message: Record<string, unknown> = {
+    role: "assistant",
+    content: text || null,
+  };
+  if (toolCalls.length > 0) message.tool_calls = toolCalls;
+
+  const usage = (response.usage ?? {}) as Record<string, unknown>;
+  return {
+    id: String(response.id ?? "chatcmpl"),
+    object: "chat.completion",
+    created: typeof response.created_at === "number" ? response.created_at : 0,
+    model,
+    choices: [
+      {
+        index: 0,
+        message,
+        finish_reason: toolCalls.length > 0 ? "tool_calls" : "stop",
+      },
+    ],
+    usage: {
+      prompt_tokens: Number(usage.input_tokens ?? 0),
+      completion_tokens: Number(usage.output_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`;

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"
+  ]
+}