@ar-ai/brink-cli 0.0.0-stage → 1.0.4

package/support/messages-request.js

@@ -0,0 +1,442 @@
+"use strict";
+
+function invalid(message) {
+  throw Object.assign(new Error(message), {
+    status: 400,
+    code: "invalid_request_error",
+  });
+}
+
+function object(value, context) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    invalid(`${context} must be an object`);
+}
+
+function fields(value, allowed, context) {
+  object(value, context);
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key))
+      invalid(`${context}.${key} is not supported by the Messages-to-Responses bridge; remove it or use an Anthropic model`);
+  }
+}
+
+function text(value, context, nonempty = false) {
+  if (typeof value !== "string" || (nonempty && !value))
+    invalid(`${context} must be ${nonempty ? "a nonempty string" : "a string"}`);
+}
+
+function boolean(value, context) {
+  if (value != null && typeof value !== "boolean")
+    invalid(`${context} must be a boolean`);
+}
+
+function cacheControl(value, context) {
+  if (value == null) return;
+  fields(value, ["type", "ttl"], context);
+  if (value.type !== "ephemeral" ||
+      (value.ttl != null && !["5m", "1h"].includes(value.ttl)))
+    invalid(`${context} requires ephemeral caching with a 5m or 1h TTL`);
+  // Claude cache breakpoints/TTLs are provider billing hints, not Responses
+  // cache keys. Let the upstream manage caching rather than inventing a key.
+}
+
+function toolName(value, context) {
+  text(value, context, true);
+  if (!/^[a-zA-Z0-9_-]{1,64}$/.test(value))
+    invalid(`${context} must use 1-64 letters, digits, underscores or hyphens for Responses; rename the client tool`);
+}
+
+function json(value, context) {
+  try {
+    const result = JSON.stringify(value);
+    if (result !== undefined) return result;
+  } catch {}
+  invalid(`${context} must contain JSON-serializable data`);
+}
+
+function url(value, context) {
+  text(value, context, true);
+  try {
+    const parsed = new URL(value);
+    if (["https:", "http:"].includes(parsed.protocol)) return value;
+  } catch {}
+  invalid(`${context} must be an absolute HTTP or HTTPS URL`);
+}
+
+function citations(value, context, configuration = false) {
+  if (value == null) return;
+  if (configuration) {
+    fields(value, ["enabled"], context);
+    boolean(value.enabled, `${context}.enabled`);
+    if (value.enabled !== true) return;
+  } else if (Array.isArray(value) && !value.length) return;
+  invalid(`${context} cannot retain Anthropic citation indexes in Responses; disable citations or supply plain text without citation annotations`);
+}
+
+function directCaller(value, context) {
+  if (value == null) return;
+  fields(value, ["type"], context);
+  if (value.type !== "direct")
+    invalid(`${context} requires a direct client tool call; server-side code execution is not supported`);
+}
+
+function convertImage(block, context) {
+  fields(block, ["type", "source", "cache_control", "transformations"], context);
+  cacheControl(block.cache_control, `${context}.cache_control`);
+  if (block.transformations != null) {
+    fields(block.transformations, ["oversized_image"], `${context}.transformations`);
+    if (block.transformations.oversized_image != null &&
+        block.transformations.oversized_image !== "downsize")
+      invalid(`${context}.transformations cannot enforce Anthropic image-size limits; resize the image before sending it`);
+  }
+  const source = block.source;
+  object(source, `${context}.source`);
+  if (source.type === "base64") {
+    fields(source, ["type", "data", "media_type"], `${context}.source`);
+    if (!["image/jpeg", "image/png", "image/gif", "image/webp"].includes(source.media_type))
+      invalid(`${context}.source.media_type must be a supported image type`);
+    text(source.data, `${context}.source.data`, true);
+    return { type: "input_image", image_url: `data:${source.media_type};base64,${source.data}`, detail: "auto" };
+  }
+  if (source.type === "url") {
+    fields(source, ["type", "url"], `${context}.source`);
+    return { type: "input_image", image_url: url(source.url, `${context}.source.url`), detail: "auto" };
+  }
+  invalid(`${context}.source type is not supported; Anthropic file IDs cannot be resolved by Responses, so provide a base64 image or URL`);
+}
+
+function convertDocument(block, context) {
+  fields(block, ["type", "source", "cache_control", "citations", "title", "context"], context);
+  cacheControl(block.cache_control, `${context}.cache_control`);
+  citations(block.citations, `${context}.citations`, true);
+  const parts = [];
+  const metadata = {};
+  for (const key of ["title", "context"]) {
+    if (block[key] != null) {
+      text(block[key], `${context}.${key}`);
+      metadata[key] = block[key];
+    }
+  }
+  if (Object.keys(metadata).length)
+    parts.push({ type: "input_text", text: `Document metadata: ${JSON.stringify(metadata)}` });
+  const source = block.source;
+  object(source, `${context}.source`);
+  if (source.type === "base64") {
+    fields(source, ["type", "data", "media_type"], `${context}.source`);
+    if (source.media_type !== "application/pdf")
+      invalid(`${context}.source.media_type must be application/pdf for a base64 document`);
+    text(source.data, `${context}.source.data`, true);
+    parts.push({
+      type: "input_file",
+      filename: block.title && /\.pdf$/i.test(block.title) ? block.title : `${block.title || "document"}.pdf`,
+      file_data: `data:application/pdf;base64,${source.data}`,
+    });
+  } else if (source.type === "url") {
+    fields(source, ["type", "url"], `${context}.source`);
+    parts.push({ type: "input_file", file_url: url(source.url, `${context}.source.url`) });
+  } else if (source.type === "text") {
+    fields(source, ["type", "data", "media_type"], `${context}.source`);
+    if (source.media_type !== "text/plain")
+      invalid(`${context}.source.media_type must be text/plain for a text document`);
+    text(source.data, `${context}.source.data`);
+    parts.push({ type: "input_text", text: source.data });
+  } else if (source.type === "content") {
+    fields(source, ["type", "content"], `${context}.source`);
+    if (typeof source.content === "string")
+      parts.push({ type: "input_text", text: source.content });
+    else {
+      if (!Array.isArray(source.content))
+        invalid(`${context}.source.content must be text or an array of text/image blocks`);
+      for (const [index, part] of source.content.entries()) {
+        const location = `${context}.source.content[${index}]`;
+        object(part, location);
+        if (!["text", "image"].includes(part.type))
+          invalid(`${location} must be a text or image block`);
+        parts.push(...convertContent(part, location));
+      }
+    }
+  } else {
+    invalid(`${context}.source type is not supported; Anthropic file IDs cannot be resolved by Responses, so provide document data or a URL`);
+  }
+  return parts;
+}
+
+function convertContent(block, context, tools) {
+  // This helper converts user/system input and tool-result content. Assistant
+  // history is converted to output blocks when its message is flushed below.
+  object(block, context);
+  if (block.type === "text") {
+    fields(block, ["type", "text", "cache_control", "citations"], context);
+    text(block.text, `${context}.text`);
+    cacheControl(block.cache_control, `${context}.cache_control`);
+    citations(block.citations, `${context}.citations`);
+    return [{ type: "input_text", text: block.text }];
+  }
+  if (block.type === "image") return [convertImage(block, context)];
+  if (block.type === "document") return convertDocument(block, context);
+  if (block.type === "tool_reference" && tools) {
+    fields(block, ["type", "tool_name", "cache_control"], context);
+    cacheControl(block.cache_control, `${context}.cache_control`);
+    toolName(block.tool_name, `${context}.tool_name`);
+    if (!tools.has(block.tool_name))
+      invalid(`${context} references a tool without a supplied definition; include it in tools`);
+    // Deferred client tools are advertised eagerly, so this reference is an
+    // ordinary discovery result rather than an unsupported hosted search item.
+    return [{ type: "input_text", text: `Available client tool: ${block.tool_name}` }];
+  }
+  invalid(`${context} has unsupported content type ${block.type || "(missing)"}; supply text, images, documents or direct client tool results instead of server-tool content`);
+}
+
+function convertTools(definitions) {
+  if (definitions == null) return [];
+  if (!Array.isArray(definitions)) invalid("tools must be an array");
+  const names = new Set();
+  return definitions.map((tool, index) => {
+    const context = `tools[${index}]`;
+    fields(tool, ["type", "name", "description", "input_schema", "cache_control", "defer_loading", "allowed_callers", "input_examples", "strict", "eager_input_streaming"], context);
+    if (tool.type != null && tool.type !== "custom")
+      invalid(`${context} uses a server/built-in tool type; supply a client function with input_schema instead`);
+    toolName(tool.name, `${context}.name`);
+    if (names.has(tool.name)) invalid(`Duplicate tool definition: ${tool.name}`);
+    names.add(tool.name);
+    object(tool.input_schema, `${context}.input_schema`);
+    if (tool.input_schema.type !== "object")
+      invalid(`${context}.input_schema must describe an object`);
+    cacheControl(tool.cache_control, `${context}.cache_control`);
+    boolean(tool.defer_loading, `${context}.defer_loading`);
+    boolean(tool.eager_input_streaming, `${context}.eager_input_streaming`);
+    boolean(tool.strict, `${context}.strict`);
+    if (tool.strict === true)
+      invalid(`${context}.strict cannot guarantee Anthropic schema enforcement; remove strict or use an Anthropic model`);
+    if (tool.allowed_callers != null &&
+        (!Array.isArray(tool.allowed_callers) || !tool.allowed_callers.length ||
+         tool.allowed_callers.some((caller) => caller !== "direct")))
+      invalid(`${context}.allowed_callers must allow only direct client calls; server-side execution is not supported`);
+    const converted = { type: "function", name: tool.name, parameters: tool.input_schema, strict: false };
+    if (tool.description != null) {
+      text(tool.description, `${context}.description`);
+      converted.description = tool.description;
+    }
+    if (tool.input_examples != null) {
+      if (!Array.isArray(tool.input_examples)) invalid(`${context}.input_examples must be an array`);
+      for (const example of tool.input_examples) object(example, `${context}.input_examples entry`);
+      if (tool.input_examples.length)
+        converted.description = `${converted.description ? `${converted.description}\n\n` : ""}Example inputs:\n${json(tool.input_examples, `${context}.input_examples`)}`;
+    }
+    // Responses has no Claude deferral/cache/streaming hints. Advertise every
+    // definition eagerly; the Responses transport determines streaming cadence.
+    return converted;
+  });
+}
+
+function convertReasoning(payload, request) {
+  const config = payload.output_config;
+  if (config != null) fields(config, ["effort", "format"], "output_config");
+  let effort = config?.effort;
+  if (effort != null && !["low", "medium", "high", "xhigh", "max"].includes(effort))
+    invalid("output_config.effort must be low, medium, high, xhigh or max");
+  // Fixed compatibility policy: Claude's max effort maps to Responses xhigh.
+  // The caller logs this mapping without adding non-API fields to the request.
+  if (effort === "max") effort = "xhigh";
+  const thinking = payload.thinking;
+  if (thinking != null) {
+    fields(thinking, ["type", "budget_tokens", "display"], "thinking");
+    if (!["adaptive", "enabled", "disabled"].includes(thinking.type))
+      invalid("thinking.type must be adaptive, enabled or disabled");
+    if (thinking.display != null && !["summarized", "omitted"].includes(thinking.display))
+      invalid("thinking.display must be summarized or omitted");
+    if (thinking.type !== "enabled" && thinking.budget_tokens != null)
+      invalid("thinking.budget_tokens requires thinking.type enabled");
+    if (thinking.type === "disabled") {
+      if (effort != null) invalid("thinking disabled conflicts with output_config.effort; remove the effort or enable thinking");
+      if (thinking.display != null) invalid("thinking.display requires enabled or adaptive thinking");
+      request.reasoning = { effort: "none" };
+    } else {
+      if (thinking.type === "enabled" &&
+          (!Number.isSafeInteger(thinking.budget_tokens) || thinking.budget_tokens < 1024 ||
+           (payload.max_tokens != null && thinking.budget_tokens >= payload.max_tokens)))
+        invalid("thinking.budget_tokens must be an integer of at least 1024 and less than max_tokens");
+      // Responses has effort levels, not a separate thinking token cap. The
+      // total cap remains max_output_tokens; explicit effort always wins.
+      request.reasoning = {
+        effort: effort ?? (thinking.type === "enabled" && thinking.budget_tokens < 8192 ? "medium" : "high"),
+        summary: "auto",
+      };
+    }
+  } else if (effort != null) request.reasoning = { effort, summary: "auto" };
+  if (config?.format != null) {
+    fields(config.format, ["type", "schema"], "output_config.format");
+    if (config.format.type !== "json_schema")
+      invalid("output_config.format must use json_schema");
+    object(config.format.schema, "output_config.format.schema");
+    request.text = { format: { type: "json_schema", name: "response", schema: config.format.schema, strict: true } };
+  }
+}
+
+function contextManagement(value) {
+  if (value == null) return;
+  fields(value, ["edits"], "context_management");
+  if (!Array.isArray(value.edits)) invalid("context_management.edits must be an array");
+  for (const [index, edit] of value.edits.entries()) {
+    const context = `context_management.edits[${index}]`;
+    fields(edit, ["type", "keep"], context);
+    if (edit.type !== "clear_thinking_20251015")
+      invalid(`${context} cannot be applied by Responses; perform context edits in the client before sending the request`);
+    if (edit.keep != null && edit.keep !== "all")
+      invalid(`${context}.keep must be all; perform finite-turn thinking clearing in the client before sending the request`);
+    // All public prior thinking is retained below. Provider-specific opaque
+    // signatures are never replayable, so no Responses edit is necessary.
+  }
+}
+
+function buildMessagesRequest(payload) {
+  fields(payload, ["model", "messages", "system", "stream", "max_tokens", "tools", "tool_choice", "thinking", "output_config", "context_management", "metadata", "cache_control", "temperature", "top_p", "top_k", "stop_sequences", "service_tier"], "request");
+  text(payload.model, "model", true);
+  if (!Array.isArray(payload.messages) || !payload.messages.length)
+    invalid("messages must be a nonempty array");
+  boolean(payload.stream, "stream");
+  if (payload.max_tokens != null && (!Number.isSafeInteger(payload.max_tokens) || payload.max_tokens <= 0))
+    invalid("max_tokens must be a positive integer; Responses does not support cache-only max_tokens=0 requests");
+  for (const [key, defaults] of [["temperature", [1]], ["top_p", [1]], ["top_k", [0, -1]]]) {
+    if (payload[key] != null && !defaults.includes(payload[key]))
+      invalid(`${key} is not supported with GPT reasoning; omit it or use its default value instead of disabling reasoning`);
+  }
+  if (payload.stop_sequences != null &&
+      (!Array.isArray(payload.stop_sequences) || payload.stop_sequences.length))
+    invalid("stop_sequences is not supported by Responses; remove custom stop sequences");
+  if (payload.metadata != null) object(payload.metadata, "metadata");
+  // Client metadata is deliberately not forwarded as OpenAI user identity.
+  cacheControl(payload.cache_control, "cache_control");
+  contextManagement(payload.context_management);
+  const tools = convertTools(payload.tools);
+  const toolNames = new Set(tools.map((tool) => tool.name));
+  const request = { model: payload.model, input: [], stream: payload.stream === true, store: false };
+  if (payload.max_tokens != null) request.max_output_tokens = payload.max_tokens;
+  if (payload.tools != null) request.tools = tools;
+  convertReasoning(payload, request);
+  if (payload.service_tier != null) {
+    if (!["auto", "standard_only"].includes(payload.service_tier))
+      invalid("service_tier must be auto or standard_only");
+    request.service_tier = payload.service_tier === "standard_only" ? "default" : "auto";
+  }
+  if (payload.tool_choice != null) {
+    const choice = payload.tool_choice;
+    fields(choice, ["type", "name", "disable_parallel_tool_use"], "tool_choice");
+    if (!["auto", "any", "tool", "none"].includes(choice.type))
+      invalid("tool_choice.type must be auto, any, tool or none");
+    boolean(choice.disable_parallel_tool_use, "tool_choice.disable_parallel_tool_use");
+    if (choice.disable_parallel_tool_use != null)
+      request.parallel_tool_calls = !choice.disable_parallel_tool_use;
+    if (choice.type === "tool") {
+      toolName(choice.name, "tool_choice.name");
+      if (!toolNames.has(choice.name)) invalid("tool_choice.name must identify a supplied client tool");
+      request.tool_choice = { type: "function", name: choice.name };
+    } else {
+      if (choice.name != null) invalid("tool_choice.name requires tool_choice.type tool");
+      if (choice.type === "any" && !tools.length) invalid("tool_choice any requires at least one client tool");
+      request.tool_choice = choice.type === "any" ? "required" : choice.type;
+    }
+  }
+  if (payload.system != null) {
+    let content;
+    if (typeof payload.system === "string") content = payload.system;
+    else {
+      if (!Array.isArray(payload.system)) invalid("system must be text or an array of text blocks");
+      content = payload.system.flatMap((block, index) => {
+        if (!block || block.type !== "text") invalid(`system[${index}] must be a text block`);
+        return convertContent(block, `system[${index}]`);
+      });
+    }
+    if (content.length) request.input.push({ role: "system", content });
+  }
+  const calls = new Set();
+  const answered = new Set();
+  for (const [messageIndex, message] of payload.messages.entries()) {
+    const context = `messages[${messageIndex}]`;
+    fields(message, ["role", "content"], context);
+    // Claude Code gateway mode also emits environment messages with role system.
+    if (!["user", "assistant", "system"].includes(message.role)) invalid(`${context}.role must be user, assistant or system`);
+    if (typeof message.content === "string") {
+      request.input.push({ role: message.role, content: message.content });
+      continue;
+    }
+    if (!Array.isArray(message.content) || !message.content.length)
+      invalid(`${context}.content must be text or a nonempty content array`);
+    let content = [];
+    const flush = () => {
+      if (content.length) {
+        if (message.role === "assistant") {
+          for (const part of content) {
+            if (part.type !== "input_text")
+              invalid(`${context}: Responses assistant history supports text only; images and documents must be user content or tool results`);
+            part.type = "output_text";
+            part.annotations = [];
+          }
+        }
+        request.input.push({ role: message.role, content });
+        content = [];
+      }
+    };
+    for (const [blockIndex, block] of message.content.entries()) {
+      const location = `${context}.content[${blockIndex}]`;
+      object(block, location);
+      if (block.type === "tool_use") {
+        if (message.role !== "assistant") invalid(`${location}: tool_use requires the assistant role`);
+        fields(block, ["type", "id", "name", "input", "cache_control", "caller"], location);
+        text(block.id, `${location}.id`, true);
+        toolName(block.name, `${location}.name`);
+        object(block.input, `${location}.input`);
+        if (calls.has(block.id)) invalid(`${location}.id duplicates a preceding tool call`);
+        cacheControl(block.cache_control, `${location}.cache_control`);
+        directCaller(block.caller, `${location}.caller`);
+        calls.add(block.id);
+        flush();
+        request.input.push({ type: "function_call", call_id: block.id, name: block.name, arguments: json(block.input, `${location}.input`) });
+      } else if (block.type === "tool_result") {
+        if (message.role !== "user") invalid(`${location}: tool_result requires the user role`);
+        fields(block, ["type", "tool_use_id", "content", "is_error", "cache_control"], location);
+        text(block.tool_use_id, `${location}.tool_use_id`, true);
+        if (!calls.has(block.tool_use_id) || answered.has(block.tool_use_id))
+          invalid(`${location} requires its preceding, unanswered tool_use in messages`);
+        boolean(block.is_error, `${location}.is_error`);
+        cacheControl(block.cache_control, `${location}.cache_control`);
+        let output = block.content ?? "";
+        if (typeof output !== "string") {
+          if (!Array.isArray(output)) invalid(`${location}.content must be text or a content array`);
+          output = output.flatMap((part, index) => convertContent(part, `${location}.content[${index}]`, toolNames));
+        }
+        // Responses has no is_error bit; preserve the tool failure as visible
+        // output without losing any original text/image/file ordering.
+        if (block.is_error === true) {
+          const marker = "[Client tool execution failed]";
+          output = typeof output === "string" ? `${marker}\n${output}` : [{ type: "input_text", text: marker }, ...output];
+        }
+        answered.add(block.tool_use_id);
+        flush();
+        request.input.push({ type: "function_call_output", call_id: block.tool_use_id, output });
+      } else if (block.type === "thinking" || block.type === "redacted_thinking") {
+        if (message.role !== "assistant") invalid(`${location}: thinking requires the assistant role`);
+        if (block.type === "thinking") {
+          fields(block, ["type", "thinking", "signature"], location);
+          text(block.thinking, `${location}.thinking`);
+          if (block.signature != null) text(block.signature, `${location}.signature`);
+          // Native reasoning input requires a backend-issued ID. Do not invent
+          // rs IDs or encrypted state: retain only the supplied public summary
+          // as labelled assistant text, in its original position.
+          if (block.thinking)
+            content.push({ type: "input_text", text: `Prior public reasoning summary:\n${block.thinking}` });
+        } else {
+          fields(block, ["type", "data"], location);
+          text(block.data, `${location}.data`);
+          // Anthropic's opaque redacted state cannot be decrypted or replayed
+          // by OpenAI and contains no public content to preserve.
+        }
+      } else content.push(...convertContent(block, location));
+    }
+    flush();
+  }
+  if (!request.input.length) invalid("messages must contain public content or a client tool call");
+  return request;
+}
+
+module.exports = { buildMessagesRequest };