@dbx-tools/cli-model-proxy 0.3.21 → 0.3.23

package/README.md

@@ -4,14 +4,18 @@ Local OpenAI-compatible proxy for Databricks Model Serving.
 
 Import this package or run its CLI when a tool expects the OpenAI API shape but
 you want Databricks Model Serving auth, endpoint discovery, and fuzzy model
-names. The proxy does not translate the OpenAI wire format; it resolves the
-requested model, mints/refreshes Databricks auth through the SDK, and streams the
-upstream response back to the caller.
+names. Chat/completions and embeddings bodies are forwarded verbatim: the proxy
+resolves the requested model, mints/refreshes Databricks auth through the SDK,
+and streams the upstream response back to the caller.
 
 Key features:
 
 - OpenAI-compatible `/v1/*` forwarding for local tools that already know how to
   call chat/completions endpoints.
+- `POST /v1/responses` support for clients that speak only the OpenAI Responses
+  API (the Codex CLI, for one), translated to and from Chat Completions -
+  streaming included - by
+  [`@dbx-tools/shared-model`](../../shared/model)'s `openaiResponses`.
 - Databricks SDK auth, including profile selection, token refresh, and workspace
   host resolution.
 - Fuzzy model names and model-class requests powered by
@@ -123,14 +127,40 @@ Use this when tests or local developer tools need a managed proxy lifecycle.
 
 1. `backend.DatabricksBackend` reads the OpenAI request body and resolves
    `body.model` through [`@dbx-tools/model`](../../node/model).
-2. The Databricks SDK supplies a fresh authorization header for the workspace.
-3. The proxy forwards the body to the resolved serving endpoint's
+2. Request fields Databricks refuses to parse are dropped (see below).
+3. The Databricks SDK supplies a fresh authorization header for the workspace.
+4. The proxy forwards the body to the resolved serving endpoint's
    `/invocations` route.
-4. JSON or SSE response bodies are piped back unchanged.
+5. JSON or SSE response bodies are piped back unchanged.
 
 This keeps the package small: Databricks already speaks the OpenAI schema, so
 the useful work is auth and endpoint resolution.
 
+## Unsupported Request Fields
+
+Databricks Model Serving validates the chat body strictly, so a single
+top-level key it doesn't recognize fails the whole turn:
+
+```json
+{ "error_code": "BAD_REQUEST", "message": "parallel_tool_calls: Extra inputs are not permitted" }
+```
+
+Because `/v1/chat/completions` forwards the client's body as-is, the proxy
+deletes the known offenders first - `parallel_tool_calls` plus OpenAI-platform
+bookkeeping like `store` and `metadata` - using
+`openaiChat.stripUnsupportedChatFields` from
+[`@dbx-tools/shared-model`](../../shared/model). Anything dropped is named in
+the `proxy` log line. `/v1/responses` is unaffected: it builds the chat body
+field-by-field and never copies these through.
+
+Set `PROXY_DROP_FIELDS` to a comma-separated list to drop more, when a
+workspace or a new client version trips a field this package doesn't know
+about yet:
+
+```sh
+PROXY_DROP_FIELDS=some_new_field,another dbx-tools-model-proxy
+```
+
 ## Modules
 
 - `cli` - Commander program and `runCli()`.

package/index.ts

@@ -5,7 +5,6 @@
 export * as backend from "./src/backend";
 export * as cli from "./src/cli";
 export * as defaults from "./src/defaults";
-export * as responses from "./src/responses";
 export * as server from "./src/server";
 export type { BackendOptions } from "./src/backend";
 export type { ProxyServerOptions, StartProxyOptions } from "./src/server";

package/package.json

@@ -18,16 +18,16 @@
     "@databricks/sdk-experimental": "^0.17.0",
     "commander": "^15.0.0",
     "tsx": "^4.23.0",
-    "@dbx-tools/model": "0.3.21",
-    "@dbx-tools/shared-core": "0.3.21",
-    "@dbx-tools/shared-model": "0.3.21"
+    "@dbx-tools/model": "0.3.23",
+    "@dbx-tools/shared-core": "0.3.23",
+    "@dbx-tools/shared-model": "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": {
@@ -35,7 +35,6 @@
     "./backend": "./src/backend.ts",
     "./cli": "./src/cli.ts",
     "./defaults": "./src/defaults.ts",
-    "./responses": "./src/responses.ts",
     "./server": "./src/server.ts",
     "./package.json": "./package.json"
   },

package/src/backend.ts

@@ -2,31 +2,25 @@
  * Databricks backend for the local model proxy.
  *
  * Wraps a single default-auth {@link WorkspaceClient} and exposes the three
- * things the proxy server needs: the workspace serving-endpoint list, fuzzy
- * name resolution (reusing `@dbx-tools/model`'s {@link resolve.rankModels} so a
- * loose `"opus"` / `"claude sonnet"` snaps to the best live endpoint id -
- * match score, then class, then within-class version), and a fresh set of auth
- * headers per upstream request.
+ * things the proxy server needs, each delegating to `@dbx-tools/model`: the
+ * workspace serving-endpoint list, fuzzy name resolution ({@link
+ * resolve.rankModelIdLive}, so a loose `"opus"` / `"claude sonnet"` snaps to
+ * the best live endpoint id - match score, then class, then within-class
+ * version), and a fresh set of auth headers per upstream request ({@link
+ * invoke.authHeaders}).
  *
- * Auth is delegated entirely to the Databricks SDK: `config.authenticate`
- * re-runs the configured credential provider on every call and refreshes the
- * underlying OAuth / PAT token when it is close to expiry, so the proxy never
- * manages token lifetimes itself - each request is signed with a
- * currently-valid bearer token.
- *
- * The endpoint catalogue is listed once and reused for the process, and
- * re-listed on a resolve miss so a model deployed after start-up still resolves
- * on first use - no cache layer, just one lazy load.
+ * What is left here is only the proxy's own policy: which client to construct,
+ * and holding the endpoint catalogue for the process lifetime. The catalogue is
+ * listed once and re-listed on a resolve miss, so a model deployed after
+ * start-up still resolves on first use - no cache layer, just one lazy load.
  *
  * @module
  */
 
+import { WorkspaceClient } from "@databricks/sdk-experimental";
+import { invoke, resolve, serving, type ResolvedModel } from "@dbx-tools/model";
 import { log } from "@dbx-tools/shared-core";
 import { type ServingEndpointSummary } from "@dbx-tools/shared-model";
-import { resolve, serving, type ResolvedModel } from "@dbx-tools/model";
-import { WorkspaceClient } from "@databricks/sdk-experimental";
-
-import { INVOCATIONS_SUFFIX } from "./defaults";
 
 const logger = log.logger("model-proxy/backend");
 
@@ -74,6 +68,9 @@ export class DatabricksBackend {
    * {@link ServingEndpointSummary} the resolver needs. Loaded lazily and
    * reused; pass `force` to re-list (used by `/v1/models` and the
    * resolve-on-miss path).
+   *
+   * Deliberately the uncached listing: the cached one runs through AppKit's
+   * `CacheManager`, which a plain CLI has no app to initialize.
    */
   async models(force = false): Promise<ServingEndpointSummary[]> {
     if (this.endpoints && !force) return this.endpoints;
@@ -85,40 +82,17 @@ export class DatabricksBackend {
 
   /**
    * Snap a (possibly loose) OpenAI-style model name to the best real serving
-   * endpoint via {@link resolve.rankModels} (the same ranking
-   * {@link resolve.resolveModel} uses): Fuse match (bucketed so version
-   * siblings tie), then class, then within-class version - so `"opus"` prefers
-   * `opus-5` over `opus-4-7`. On a miss the catalogue is re-listed once and
-   * retried, so a freshly deployed model resolves without a restart. Returns
-   * the input unchanged with `matched: false` when nothing scores within the
-   * threshold, so a deliberate endpoint id is never silently rewritten and
-   * Databricks surfaces a clean 404.
+   * endpoint. {@link resolve.rankModelIdLive} owns the policy: rank against the
+   * loaded catalogue, and on a miss re-list once and retry so a freshly
+   * deployed model resolves without a restart. An unmatched name comes back
+   * unchanged so a deliberate endpoint id is never silently rewritten.
    */
   async resolve(model: string): Promise<ResolvedModel> {
-    let resolved = this.resolveAgainst(model, await this.models());
-    if (!resolved.matched) {
-      resolved = this.resolveAgainst(model, await this.models(true));
-    }
-    return resolved;
-  }
-
-  /**
-   * Rank `model` against a catalogue snapshot and collapse to a single
-   * {@link ResolvedModel}. Uses {@link resolve.rankModels} with `limit: 1`
-   * rather than Fuse-only {@link serving.resolveModelId}, so equal-score
-   * siblings are broken by class / version.
-   */
-  private resolveAgainst(
-    model: string,
-    endpoints: readonly ServingEndpointSummary[],
-  ): ResolvedModel {
-    const [top] = resolve.rankModels(endpoints, {
-      search: model,
-      limit: 1,
-      ...(this.threshold !== undefined ? { threshold: this.threshold } : {}),
-    });
-    if (!top) return { modelId: model, matched: false };
-    return { modelId: top.endpoint.name, matched: true, score: top.score };
+    return resolve.rankModelIdLive(
+      (force) => this.models(force),
+      model,
+      this.threshold !== undefined ? { threshold: this.threshold } : {},
+    );
   }
 
   /**
@@ -127,20 +101,11 @@ export class DatabricksBackend {
    * header without the proxy tracking expiry.
    */
   async authHeaders(): Promise<Record<string, string>> {
-    const headers = new Headers();
-    await this.client.config.authenticate(headers);
-    const out: Record<string, string> = {};
-    headers.forEach((value, key) => {
-      out[key] = value;
-    });
-    return out;
+    return invoke.authHeaders(this.client);
   }
 
   /** OpenAI-compatible invocations URL for a resolved endpoint id. */
   invocationsUrl(endpoint: string): string {
-    return new URL(
-      `serving-endpoints/${encodeURIComponent(endpoint)}/${INVOCATIONS_SUFFIX}`,
-      this.host,
-    ).toString();
+    return invoke.invocationsUrl(this.host, endpoint);
   }
 }

package/src/cli.ts

@@ -8,45 +8,25 @@
  * fuzzy name snaps to. Auth comes from the standard Databricks SDK resolution
  * (env vars, `--profile`, or `databricks auth login`).
  *
+ * Shared flags (`--profile`, `--workspace-host`, `--threshold`, …) are declared
+ * on the root *and* redeclared on subcommands for help discoverability. Commander
+ * parks the values on the parent when both declare the same flag, so every
+ * subcommand action must read {@link Command.optsWithGlobals} - local `opts`
+ * alone misses `--profile` (env `DATABRICKS_CONFIG_PROFILE` still worked because
+ * the SDK reads that without the CLI flag).
+ *
  * @module
  */
 
 import { spawn } from "node:child_process";
 import type { Server } from "node:http";
+import { classify } from "@dbx-tools/shared-model";
 import { Command, CommanderError } from "commander";
 
-import { type ServingEndpointSummary } from "@dbx-tools/shared-model";
-
 import { DatabricksBackend, type BackendOptions } from "./backend";
 import { DEFAULT_BIND_HOST, DEFAULT_PORT } from "./defaults";
 import { startProxyServer } from "./server";
 
-/** Capability flags an endpoint advertises, derived from its task/class. */
-interface EndpointCapabilities {
-  /** OpenAI chat/completions + Responses (what a chat agent like Codex needs). */
-  chat: boolean;
-  /** Embedding (vector) endpoint. */
-  embedding: boolean;
-  /** Function / tool calling. Chat endpoints here support it. */
-  tools: boolean;
-}
-
-/**
- * Derive an endpoint's capabilities from its Databricks task hint and the
- * classifier's model class. `llm/v1/chat` (and chat-classed endpoints) are
- * chat- and tool-capable; `llm/v1/embeddings` (and embedding-classed) are
- * embedding-only. Keeps capability logic in one place so consumers don't
- * re-derive it from raw strings.
- */
-function capabilitiesFor(endpoint: ServingEndpointSummary): EndpointCapabilities {
-  const task = endpoint.task;
-  const cls = endpoint.class;
-  const embedding = task === "llm/v1/embeddings" || cls === "embedding";
-  const chat =
-    !embedding && (task === "llm/v1/chat" || (typeof cls === "string" && cls.startsWith("chat")));
-  return { chat, embedding, tools: chat };
-}
-
 /**
  * Default terminal client for `chat`, launched via `bunx`. OpenHarness is an
  * OpenAI-compatible TUI that reads the endpoint straight from the env we inject
@@ -78,6 +58,15 @@ function backendOptions(opts: CommonOpts): BackendOptions {
   };
 }
 
+/**
+ * Subcommand options merged with parent (root) options. Required for shared
+ * flags that are declared on both - Commander stores them on the parent, so
+ * the action's local `opts` alone omits `--profile` / `--workspace-host`.
+ */
+function globalOpts<T>(command: Command): T {
+  return command.optsWithGlobals() as T;
+}
+
 /** Create the backend and start the proxy from the shared listen flags. */
 async function startProxy(
   opts: ServeOpts,
@@ -92,102 +81,106 @@ async function startProxy(
   return { backend, server, url };
 }
 
+/** Shared auth / fuzzy-match flags added to the root and every subcommand. */
+function addAuthOptions(command: Command): Command {
+  return command
+    .option("--profile <profile>", "Databricks config profile")
+    .option("--workspace-host <url>", "override the Databricks workspace host")
+    .option("-t, --threshold <n>", "fuzzy match threshold (0..1)");
+}
+
 /** Build the `dbx-tools-model-proxy` commander program (no side effects until parsed). */
 export function buildProgram(): Command {
   // Serving is the root action, not a subcommand: the bare command runs the
   // proxy, and `chat`/`models`/`resolve` are the named detours off it.
-  const program = new Command()
-    .name("dbx-tools-model-proxy")
-    .description("Local OpenAI-compatible proxy to Databricks Model Serving.")
-    .option("-p, --port <port>", "port to listen on", String(DEFAULT_PORT))
-    .option("-H, --host <host>", "address to bind", DEFAULT_BIND_HOST)
-    .option("--profile <profile>", "Databricks config profile")
-    .option("--workspace-host <url>", "override the Databricks workspace host")
-    .option("-t, --threshold <n>", "fuzzy match threshold (0..1)")
-    .option("-k, --api-key <key>", "require this bearer token from local clients")
-    .action(async (opts: ServeOpts) => {
-      const { backend, url } = await startProxy(opts);
-      process.stderr.write(`model-proxy -> ${backend.host}\n`);
-      process.stderr.write(`  OpenAI base URL: ${url}/v1\n`);
-    });
+  const program = addAuthOptions(
+    new Command()
+      .name("dbx-tools-model-proxy")
+      .description("Local OpenAI-compatible proxy to Databricks Model Serving.")
+      .option("-p, --port <port>", "port to listen on", String(DEFAULT_PORT))
+      .option("-H, --host <host>", "address to bind", DEFAULT_BIND_HOST)
+      .option("-k, --api-key <key>", "require this bearer token from local clients"),
+  ).action(async (opts: ServeOpts) => {
+    const { backend, url } = await startProxy(opts);
+    process.stderr.write(`model-proxy -> ${backend.host}\n`);
+    process.stderr.write(`  OpenAI base URL: ${url}/v1\n`);
+  });
 
-  program
-    .command("chat")
-    .description("Start the proxy and launch a terminal chat client wired to it.")
-    .option("-p, --port <port>", "proxy port", String(DEFAULT_PORT))
-    .option("-H, --host <host>", "proxy bind host", DEFAULT_BIND_HOST)
-    .option("--profile <profile>", "Databricks config profile")
-    .option("--workspace-host <url>", "override the Databricks workspace host")
-    .option("-t, --threshold <n>", "fuzzy match threshold (0..1)")
-    .option("-m, --model <name>", "default model (fuzzy name ok)")
-    .option(
-      "--client <cmd>",
-      "terminal chat CLI to launch (run via your shell)",
-      process.env.PROXY_CHAT_CLIENT ?? DEFAULT_CHAT_CLIENT,
-    )
-    .action(async (opts: ServeOpts & { model?: string; client: string }) => {
-      const { backend, server, url } = await startProxy(opts);
-      const baseUrl = `${url}/v1`;
-      process.stderr.write(
-        `model-proxy -> ${backend.host}\n  OpenAI base URL: ${baseUrl}\n  launching: ${opts.client}\n`,
-      );
-      // Hand off to an off-the-shelf OpenAI-compatible client, pointing it at
-      // the proxy via the standard env vars (plus the provider switches a
-      // couple of popular CLIs read). `shell: true` lets `--client` carry its
-      // own args, e.g. `--client "bunx merlion"`.
-      const child = spawn(opts.client, {
-        stdio: "inherit",
-        shell: true,
-        env: {
-          ...process.env,
-          OPENAI_BASE_URL: baseUrl,
-          OPENAI_API_KEY: process.env.OPENAI_API_KEY ?? "model-proxy",
-          ...(opts.model ? { OPENAI_MODEL: opts.model } : {}),
-          LLM_PROVIDER: "openai-compat",
-          CLAUDE_CODE_USE_OPENAI: "1",
-        },
-      });
-      child.on("exit", (code) => {
-        server.close();
-        process.exit(code ?? 0);
-      });
-      process.on("SIGINT", () => child.kill("SIGINT"));
+  addAuthOptions(
+    program
+      .command("chat")
+      .description("Start the proxy and launch a terminal chat client wired to it.")
+      .option("-p, --port <port>", "proxy port", String(DEFAULT_PORT))
+      .option("-H, --host <host>", "proxy bind host", DEFAULT_BIND_HOST)
+      .option("-m, --model <name>", "default model (fuzzy name ok)")
+      .option(
+        "--client <cmd>",
+        "terminal chat CLI to launch (run via your shell)",
+        process.env.PROXY_CHAT_CLIENT ?? DEFAULT_CHAT_CLIENT,
+      ),
+  ).action(async (_local: ServeOpts & { model?: string; client: string }, command: Command) => {
+    const opts = globalOpts<ServeOpts & { model?: string; client: string }>(command);
+    const { backend, server, url } = await startProxy(opts);
+    const baseUrl = `${url}/v1`;
+    process.stderr.write(
+      `model-proxy -> ${backend.host}\n  OpenAI base URL: ${baseUrl}\n  launching: ${opts.client}\n`,
+    );
+    // Hand off to an off-the-shelf OpenAI-compatible client, pointing it at
+    // the proxy via the standard env vars (plus the provider switches a
+    // couple of popular CLIs read). `shell: true` lets `--client` carry its
+    // own args, e.g. `--client "bunx merlion"`.
+    const child = spawn(opts.client, {
+      stdio: "inherit",
+      shell: true,
+      env: {
+        ...process.env,
+        OPENAI_BASE_URL: baseUrl,
+        OPENAI_API_KEY: process.env.OPENAI_API_KEY ?? "model-proxy",
+        ...(opts.model ? { OPENAI_MODEL: opts.model } : {}),
+        LLM_PROVIDER: "openai-compat",
+        CLAUDE_CODE_USE_OPENAI: "1",
+      },
     });
-
-  program
-    .command("models")
-    .description("List resolvable Databricks serving endpoints (as JSON).")
-    .option("--profile <profile>", "Databricks config profile")
-    .option("--workspace-host <url>", "override the Databricks workspace host")
-    .option("--chat", "only list chat-capable endpoints")
-    .action(async (opts: CommonOpts & { chat?: boolean }) => {
-      const backend = await DatabricksBackend.create(backendOptions(opts));
-      const endpoints = await backend.models();
-      // Enrich each endpoint with a derived `capabilities` object so consumers
-      // filter on capability rather than re-deriving it from raw `task`/`class`
-      // strings. `chat` = OpenAI chat/completions + Responses (what an agent
-      // like Codex needs); `embedding` = vector endpoints; `tools` = whether the
-      // endpoint supports function/tool calls (all chat endpoints here do).
-      const enriched = endpoints.map((endpoint) => {
-        const caps = capabilitiesFor(endpoint);
-        return { ...endpoint, capabilities: caps };
-      });
-      const out = opts.chat ? enriched.filter((e) => e.capabilities.chat) : enriched;
-      process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+    child.on("exit", (code) => {
+      server.close();
+      process.exit(code ?? 0);
     });
+    process.on("SIGINT", () => child.kill("SIGINT"));
+  });
 
-  program
-    .command("resolve")
-    .description("Show what a fuzzy model name resolves to (as JSON).")
-    .argument("<query...>", "model name / fuzzy search terms")
-    .option("--profile <profile>", "Databricks config profile")
-    .option("--workspace-host <url>", "override the Databricks workspace host")
-    .option("-t, --threshold <n>", "fuzzy match threshold (0..1)")
-    .action(async (query: string[], opts: CommonOpts) => {
-      const backend = await DatabricksBackend.create(backendOptions(opts));
-      const resolved = await backend.resolve(query.join(" "));
-      process.stdout.write(`${JSON.stringify(resolved, null, 2)}\n`);
-    });
+  addAuthOptions(
+    program
+      .command("models")
+      .description("List resolvable Databricks serving endpoints (as JSON).")
+      .option("--chat", "only list chat-capable endpoints"),
+  ).action(async (_local: CommonOpts & { chat?: boolean }, command: Command) => {
+    const opts = globalOpts<CommonOpts & { chat?: boolean }>(command);
+    const backend = await DatabricksBackend.create(backendOptions(opts));
+    const endpoints = await backend.models();
+    // Enrich each endpoint with a derived `capabilities` object so consumers
+    // filter on capability rather than re-deriving it from raw `task`/`class`
+    // strings. `chat` = OpenAI chat/completions + Responses (what an agent
+    // like Codex needs); `embedding` = vector endpoints; `tools` = whether the
+    // endpoint supports function/tool calls (all chat endpoints here do).
+    const enriched = endpoints.map((endpoint) => ({
+      ...endpoint,
+      capabilities: classify.endpointCapabilities(endpoint),
+    }));
+    const out = opts.chat ? enriched.filter((e) => e.capabilities.chat) : enriched;
+    process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+  });
+
+  addAuthOptions(
+    program
+      .command("resolve")
+      .description("Show what a fuzzy model name resolves to (as JSON).")
+      .argument("<query...>", "model name / fuzzy search terms"),
+  ).action(async (query: string[], _local: CommonOpts, command: Command) => {
+    const opts = globalOpts<CommonOpts>(command);
+    const backend = await DatabricksBackend.create(backendOptions(opts));
+    const resolved = await backend.resolve(query.join(" "));
+    process.stdout.write(`${JSON.stringify(resolved, null, 2)}\n`);
+  });
 
   return program;
 }

package/src/defaults.ts

@@ -9,10 +9,3 @@ export const DEFAULT_BIND_HOST = "127.0.0.1";
 
 /** Default TCP port for the local proxy. */
 export const DEFAULT_PORT = 4000;
-
-/**
- * Path segment Databricks Model Serving exposes for OpenAI-compatible requests.
- * Every serving endpoint answers chat / completion / embedding payloads under
- * `serving-endpoints/<name>/invocations`.
- */
-export const INVOCATIONS_SUFFIX = "invocations";

package/src/server.ts

@@ -25,16 +25,14 @@
  * @module
  */
 
-import { error, log } from "@dbx-tools/shared-core";
 import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import { error, log } from "@dbx-tools/shared-core";
+import { classify, openaiChat, openaiResponses } from "@dbx-tools/shared-model";
 
 import type { DatabricksBackend } from "./backend";
 import { DEFAULT_BIND_HOST, DEFAULT_PORT } from "./defaults";
-import {
-  chatToResponse,
-  createResponsesStreamTranslator,
-  responsesToChat,
-} from "./responses";
+
+const { chatToResponse, createResponsesStreamTranslator, responsesToChat } = openaiResponses;
 
 const logger = log.logger("model-proxy/server");
 
@@ -54,6 +52,21 @@ const MODELS_PATHS = new Set(["/v1/models", "/models"]);
 /** POST routes that carry an OpenAI Responses API body (translated to chat). */
 const RESPONSES_PATHS = new Set(["/v1/responses", "/responses"]);
 
+/**
+ * Extra request fields to strip before forwarding, on top of
+ * `openaiChat.UNSUPPORTED_CHAT_FIELDS`. Comma-separated in `PROXY_DROP_FIELDS`.
+ *
+ * An escape hatch: when a workspace or a new client version trips a field
+ * Databricks rejects, an operator can unblock themselves immediately instead of
+ * waiting on a release of this package.
+ */
+function extraDropFields(): string[] {
+  return (process.env.PROXY_DROP_FIELDS ?? "")
+    .split(",")
+    .map((field) => field.trim())
+    .filter((field) => field.length > 0);
+}
+
 /** Options shared by {@link createProxyServer} and {@link startProxyServer}. */
 export interface ProxyServerOptions {
   /**
@@ -168,7 +181,7 @@ async function handleModels(
   const endpoints = await backend.models(true);
   if (codexShape) {
     const models = endpoints
-      .filter((endpoint) => endpoint.task === "llm/v1/chat")
+      .filter((endpoint) => classify.endpointCapabilities(endpoint).chat)
       .map((endpoint) => ({
         slug: endpoint.name,
         display_name: endpoint.displayName ?? endpoint.name,
@@ -213,6 +226,10 @@ async function handleProxy(
   // Address the endpoint by URL; rewrite the body's `model` to the real id so
   // pay-per-token endpoints that echo it still see a valid value.
   body.model = resolved.modelId;
+  // This route forwards the client's body as-is, so anything Databricks refuses
+  // to parse fails the turn. Drop the known offenders rather than relaying a
+  // 400 the client can do nothing about.
+  const dropped = openaiChat.stripUnsupportedChatFields(body, extraDropFields());
 
   const wantsStream = body.stream === true;
   const headers = await backend.authHeaders();
@@ -224,6 +241,7 @@ async function handleProxy(
     resolved: resolved.modelId,
     matched: resolved.matched,
     stream: wantsStream,
+    ...(dropped.length > 0 ? { dropped } : {}),
   });
 
   const upstream = await fetch(backend.invocationsUrl(resolved.modelId), {

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

package/src/responses.ts

@@ -1,391 +0,0 @@
-/**
- * OpenAI Responses API <-> Chat Completions translation.
- *
- * The Codex CLI speaks only the Responses API (`POST /v1/responses`), but
- * Databricks serving endpoints speak only Chat Completions (`messages`) at
- * their `invocations` URL. This module bridges the two:
- *
- *   - {@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 chatStreamToResponsesSse} lifts a streaming chat completion (an
- *     OpenAI SSE `chat.completion.chunk` stream) into the Responses SSE event
- *     stream Codex consumes (`response.created`, `response.output_text.delta`,
- *     function-call argument deltas, `response.completed`).
- *
- * Only the surface Codex actually exercises is translated; unknown fields are
- * ignored rather than rejected, so a newer client degrades instead of breaking.
- *
- * @module
- */
-
-/** A minimal chat message as Databricks Model Serving expects it. */
-interface ChatMessage {
-  role: string;
-  content?: string | null;
-  tool_calls?: ChatToolCall[];
-  tool_call_id?: string;
-  name?: string;
-}
-
-interface ChatToolCall {
-  id: string;
-  type: "function";
-  function: { name: string; arguments: string };
-}
-
-/** Extract plain text from a Responses `content` value (string or typed parts). */
-function contentToText(content: unknown): string {
-  if (typeof content === "string") return content;
-  if (!Array.isArray(content)) return "";
-  const parts: string[] = [];
-  for (const part of content) {
-    if (part && typeof part === "object") {
-      const p = part as Record<string, unknown>;
-      // input_text / output_text / text all carry their text on `.text`.
-      if (typeof p.text === "string") parts.push(p.text);
-    }
-  }
-  return parts.join("");
-}
-
-/**
- * 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 : contentToText(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: contentToText(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, …}}`). Codex also
-  // sends 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;
-      if (body.parallel_tool_calls !== undefined) {
-        chat.parallel_tool_calls = body.parallel_tool_calls;
-      }
-    }
-  }
-
-  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`;
-}
-
-/**
- * Translate an upstream chat-completions SSE stream into the Responses SSE
- * event stream Codex 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)
- *
- * `feed(chunk)` returns the SSE bytes to forward for that upstream chunk;
- * `finish()` returns the closing `response.completed` event. The generator is
- * intentionally tolerant: malformed/keepalive lines yield nothing.
- */
-export function createResponsesStreamTranslator(model: string, responseId: string) {
-  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 };
-}
-