@bitkyc08/opencodex 2.55.0 → 2.57.0

package/src/adapters/openai-chat/tool-call-validation.ts

@@ -0,0 +1,200 @@
+import { debugProviderDiagnostic } from "../../lib/debug";
+import { isDebugEnabled } from "../../lib/debug-settings";
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+type InvalidToolCallReason =
+  | "tool_calls_not_array"
+  | "tool_call_not_object"
+  | "tool_call_id_invalid"
+  | "tool_call_function_not_object"
+  | "tool_call_function_name_invalid"
+  | "tool_call_function_name_blank"
+  | "tool_call_function_arguments_invalid";
+
+export type InvalidToolCallDiagnostic = {
+  reason: InvalidToolCallReason;
+  callIndex?: number;
+  valueType: string;
+};
+
+type InvalidFieldShape =
+  | {
+      kind: "object";
+      knownKeys: string[];
+      knownFieldTypes: Record<string, string>;
+      hasUnknownKeys: boolean;
+    }
+  | {
+      kind: "array";
+      length: number;
+    };
+
+const SAFE_TOOL_CALL_SHAPE_KEYS = [
+  "name",
+  "type",
+  "value",
+  "function",
+  "arguments",
+  "id",
+  "index",
+] as const;
+const SAFE_TOOL_CALL_SHAPE_KEY_SET = new Set<string>(SAFE_TOOL_CALL_SHAPE_KEYS);
+
+function structuralValueType(value: unknown): string {
+  return value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+}
+
+function invalidToolCallField(rawToolCalls: unknown, diagnostic: InvalidToolCallDiagnostic): unknown {
+  if (diagnostic.reason === "tool_calls_not_array") return rawToolCalls;
+  if (!Array.isArray(rawToolCalls) || diagnostic.callIndex === undefined) return undefined;
+
+  const rawToolCall = rawToolCalls[diagnostic.callIndex];
+  if (diagnostic.reason === "tool_call_not_object") return rawToolCall;
+  if (!isRecord(rawToolCall)) return undefined;
+  if (diagnostic.reason === "tool_call_function_not_object") return rawToolCall.function;
+
+  const rawFunction = rawToolCall.function;
+  switch (diagnostic.reason) {
+    case "tool_call_id_invalid":
+      return rawToolCall.id;
+    case "tool_call_function_name_invalid":
+      return isRecord(rawFunction) ? rawFunction.name : undefined;
+    case "tool_call_function_arguments_invalid":
+      return isRecord(rawFunction) ? rawFunction.arguments : undefined;
+    default:
+      return undefined;
+  }
+}
+
+function fingerprintInvalidField(value: unknown): InvalidFieldShape | undefined {
+  if (Array.isArray(value)) return { kind: "array", length: value.length };
+  if (!isRecord(value)) return undefined;
+
+  const knownKeys: string[] = [];
+  const knownFieldTypes: Record<string, string> = {};
+  for (const key of SAFE_TOOL_CALL_SHAPE_KEYS) {
+    if (!Object.hasOwn(value, key)) continue;
+    knownKeys.push(key);
+    knownFieldTypes[key] = structuralValueType(value[key]);
+  }
+
+  let hasUnknownKeys = false;
+  for (const key of Object.keys(value)) {
+    if (!SAFE_TOOL_CALL_SHAPE_KEY_SET.has(key)) {
+      hasUnknownKeys = true;
+      break;
+    }
+  }
+  return { kind: "object", knownKeys, knownFieldTypes, hasUnknownKeys };
+}
+
+/**
+ * Streamed string fields are absent when null or undefined (#1731): OpenAI-compatible
+ * streamers repeat already-sent `id`/`name`/`arguments` as null on continuation deltas.
+ * The accumulator and this diagnostic share this predicate so they cannot disagree about
+ * which delta was the invalid one.
+ */
+export function isInvalidStreamStringField(value: unknown): boolean {
+  return value != null && typeof value !== "string";
+}
+
+/**
+ * Explain only the rejected wire shape, never its values. This diagnostic exists so provider
+ * compatibility can be tightened from evidence without retaining tool arguments or credentials.
+ */
+export function diagnoseInvalidToolCalls(
+  rawToolCalls: unknown,
+  mode: "stream" | "response",
+): InvalidToolCallDiagnostic | undefined {
+  if (!Array.isArray(rawToolCalls)) {
+    return { reason: "tool_calls_not_array", valueType: rawToolCalls === null ? "null" : typeof rawToolCalls };
+  }
+  for (let callIndex = 0; callIndex < rawToolCalls.length; callIndex++) {
+    const rawToolCall = rawToolCalls[callIndex];
+    if (!isRecord(rawToolCall)) {
+      return {
+        reason: "tool_call_not_object",
+        callIndex,
+        valueType: rawToolCall === null ? "null" : Array.isArray(rawToolCall) ? "array" : typeof rawToolCall,
+      };
+    }
+    if (mode === "stream") {
+      // The streamed path validates the pieces it is about to store (#1531): a present
+      // `function` must be a record, and a present `name`/`arguments`/`id` must be a string.
+      // Blank names are caught later at flush, not here, so they are not diagnosed on this
+      // branch. Describe exactly that boundary rather than tightening compatibility in a
+      // diagnostic change.
+      // #1731: "present" means the same thing here as in the accumulator — null and undefined
+      // are both absent, because some OpenAI-compatible streamers repeat already-sent fields
+      // as null on continuation deltas. A separate predicate here would diagnose accepted
+      // padding as the failure and point compatibility work at the wrong delta.
+      const streamFunction = (rawToolCall as { function?: unknown }).function;
+      if (streamFunction !== undefined && streamFunction !== null) {
+        if (!isRecord(streamFunction)) {
+          return {
+            reason: "tool_call_function_not_object",
+            callIndex,
+            valueType: Array.isArray(streamFunction) ? "array" : typeof streamFunction,
+          };
+        }
+        if (isInvalidStreamStringField(streamFunction.name)) {
+          return { reason: "tool_call_function_name_invalid", callIndex, valueType: typeof streamFunction.name };
+        }
+        if (isInvalidStreamStringField(streamFunction.arguments)) {
+          return { reason: "tool_call_function_arguments_invalid", callIndex, valueType: typeof streamFunction.arguments };
+        }
+      }
+      if (isInvalidStreamStringField(rawToolCall.id)) {
+        return { reason: "tool_call_id_invalid", callIndex, valueType: typeof rawToolCall.id };
+      }
+      continue;
+    }
+    // Precedence must mirror the buffered validator below, or a payload with more than one
+    // problem is reported under the wrong reason and sends compatibility work after the wrong
+    // shape. That validator checks the `function` container first (`!isRecord(rawToolCall) ||
+    // !isRecord(rawToolCall.function)`), then id/name/arguments types together, and only then
+    // the blank name.
+    if (!isRecord(rawToolCall.function)) {
+      return {
+        reason: "tool_call_function_not_object",
+        callIndex,
+        valueType: rawToolCall.function === null ? "null" : Array.isArray(rawToolCall.function) ? "array" : typeof rawToolCall.function,
+      };
+    }
+    if (typeof rawToolCall.id !== "string") {
+      return { reason: "tool_call_id_invalid", callIndex, valueType: typeof rawToolCall.id };
+    }
+    if (typeof rawToolCall.function.name !== "string") {
+      return { reason: "tool_call_function_name_invalid", callIndex, valueType: typeof rawToolCall.function.name };
+    }
+    if (typeof rawToolCall.function.arguments !== "string") {
+      return { reason: "tool_call_function_arguments_invalid", callIndex, valueType: typeof rawToolCall.function.arguments };
+    }
+    // Last, matching the validator: #1531 also rejects a blank or whitespace-only name here,
+    // because such a call cannot select a dispatch target. Reporting it as `name_invalid`
+    // would claim a type problem for a correctly-typed value, so it gets its own code.
+    if (rawToolCall.function.name.trim().length === 0) {
+      return { reason: "tool_call_function_name_blank", callIndex, valueType: "string" };
+    }
+  }
+  return undefined;
+}
+
+export function logInvalidToolCalls(
+  mode: "stream" | "response",
+  rawToolCalls: unknown,
+  diagnosticOverride?: InvalidToolCallDiagnostic,
+): void {
+  if (!isDebugEnabled()) return;
+  const diagnostic = diagnosticOverride ?? diagnoseInvalidToolCalls(rawToolCalls, mode);
+  if (!diagnostic) return;
+  const fieldShape = fingerprintInvalidField(invalidToolCallField(rawToolCalls, diagnostic));
+  debugProviderDiagnostic("openai-chat", "invalid-tool-calls", {
+    mode,
+    ...diagnostic,
+    ...(fieldShape ? { fieldShape } : {}),
+  });
+}

package/src/adapters/openai-chat/tool-name-registry.ts

@@ -0,0 +1,166 @@
+import { createHash } from "node:crypto";
+import { namespacedToolName, type OcxParsedRequest, type OcxTool } from "../../types";
+import { frameAgentRouterMessages } from "../agentrouter";
+
+const MAX_CHAT_TOOL_NAME_LENGTH = 64;
+const ALIAS_HINT_CHARS = 16;
+const RESERVED_ALIAS_PATTERN = /^ocx_[a-zA-Z0-9_-]{16}_[a-zA-Z0-9_-]{43}$/;
+type ToolIdentity = Readonly<Pick<OcxTool, "namespace" | "name">>;
+
+export interface OpenAIChatToolNameRegistry {
+  alias(tool: ToolIdentity): string;
+  aliasWireName(wireName: string): string;
+  restore(wireName: string): string;
+}
+
+interface OpenAIChatToolNameScope {
+  messages(parsed: OcxParsedRequest, baseUrl: string, messages: readonly unknown[]): unknown;
+  registry(): OpenAIChatToolNameRegistry;
+  restore(wireName: string): string;
+}
+
+function identityKey(tool: ToolIdentity): string {
+  return JSON.stringify([tool.namespace ?? null, tool.name]);
+}
+
+function boundedAlias(tool: ToolIdentity, wireName: string): string {
+  const hint = wireName
+    .replace(/[^a-zA-Z0-9_-]/g, "_")
+    .slice(-ALIAS_HINT_CHARS)
+    .padStart(ALIAS_HINT_CHARS, "_");
+  const key = identityKey(tool);
+  const digest = createHash("sha256")
+    .update(key)
+    .digest("base64url");
+  return `ocx_${hint}_${digest}`;
+}
+
+/** Catalog declarations plus structured calls retained in replay history. */
+export function openAIChatToolNameIdentities(parsed: OcxParsedRequest): ToolIdentity[] {
+  const identities: ToolIdentity[] = [...(parsed.context.tools ?? [])];
+  for (const message of parsed.context.messages) {
+    if (message.role !== "assistant" || !Array.isArray(message.content)) continue;
+    for (const part of message.content) {
+      if (part.type !== "toolCall") continue;
+      identities.push({
+        name: part.name,
+        ...(part.namespace === undefined ? {} : { namespace: part.namespace }),
+      });
+    }
+  }
+  return identities;
+}
+
+/**
+ * One collision domain for a translated Chat Completions request.
+ *
+ * Namespaced names whose flattened spelling exceeds Chat Completions' 64-character function-name
+ * bound are rewritten. Ordinary names and bare names pass through byte-for-byte unless they occupy
+ * the reserved alias spelling; those are re-aliased so no declaration can shadow another identity's
+ * deterministic alias. Distinct identities sharing one flattened spelling each keep an identity
+ * alias, while replay rewriting leaves that ambiguous spelling untouched. Echoed aliases restore to
+ * the original flattened name consumed by the Responses bridge's existing namespace map.
+ */
+export function createOpenAIChatToolNameRegistry(
+  tools: readonly ToolIdentity[] | undefined,
+): OpenAIChatToolNameRegistry {
+  const identities = new Map<string, ToolIdentity>();
+  for (const tool of tools ?? []) identities.set(identityKey(tool), tool);
+  const sortedIdentities = [...identities.entries()]
+    .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
+
+  const aliasesByIdentity = new Map<string, string>();
+  const aliasesByWireName = new Map<string, string>();
+  const originalsByAlias = new Map<string, string>();
+  const wireOwners = new Map<string, string | null>();
+  for (const [key, tool] of sortedIdentities) {
+    const wireName = namespacedToolName(tool.namespace, tool.name);
+    const owner = wireOwners.get(wireName);
+    if (owner === undefined) wireOwners.set(wireName, key);
+    else if (owner !== key) wireOwners.set(wireName, null);
+  }
+
+  const aliasOwners = new Map<string, string>();
+  const wireClaims = new Map<string, { key: string; alias: string } | null>();
+  for (const [key, tool] of sortedIdentities) {
+    const wireName = namespacedToolName(tool.namespace, tool.name);
+    const candidate = (tool.namespace !== undefined && wireName.length > MAX_CHAT_TOOL_NAME_LENGTH)
+      || RESERVED_ALIAS_PATTERN.test(wireName)
+      || wireOwners.get(wireName) === null
+      ? boundedAlias(tool, wireName)
+      : wireName;
+    // A full SHA-256 collision is not safely attributable. Keep the later identity's native
+    // spelling instead of failing the request or stealing the first identity's restore entry.
+    const alias = aliasOwners.has(candidate) ? wireName : candidate;
+    aliasesByIdentity.set(key, alias);
+    if (!aliasOwners.has(alias)) aliasOwners.set(alias, key);
+    if (alias !== wireName) originalsByAlias.set(alias, wireName);
+
+    const claim = wireClaims.get(wireName);
+    if (claim === undefined) wireClaims.set(wireName, { key, alias });
+    else if (claim !== null && claim.key !== key) wireClaims.set(wireName, null);
+  }
+  for (const [wireName, claim] of wireClaims) {
+    if (claim !== null) aliasesByWireName.set(wireName, claim.alias);
+  }
+
+  return {
+    alias(tool: ToolIdentity): string {
+      const key = identityKey(tool);
+      const known = aliasesByIdentity.get(key);
+      if (known !== undefined) return known;
+      return namespacedToolName(tool.namespace, tool.name);
+    },
+    aliasWireName(wireName: string): string {
+      return aliasesByWireName.get(wireName) ?? wireName;
+    },
+    restore(wireName: string): string {
+      return originalsByAlias.get(wireName) ?? wireName;
+    },
+  };
+}
+
+export function restoreOpenAIChatToolName(
+  registry: OpenAIChatToolNameRegistry,
+  wireName: string,
+): string {
+  return registry.restore(wireName);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Rewrite replayed assistant tool calls after the ordinary message converter has flattened them. */
+export function aliasOpenAIChatMessageToolNames(
+  messages: readonly unknown[],
+  registry: OpenAIChatToolNameRegistry,
+): unknown[] {
+  return messages.map(message => {
+    if (!isRecord(message) || !Array.isArray(message.tool_calls)) return message;
+    let changed = false;
+    const toolCalls = message.tool_calls.map(toolCall => {
+      if (!isRecord(toolCall) || !isRecord(toolCall.function)
+          || typeof toolCall.function.name !== "string") return toolCall;
+      const name = registry.aliasWireName(toolCall.function.name);
+      if (name === toolCall.function.name) return toolCall;
+      changed = true;
+      return { ...toolCall, function: { ...toolCall.function, name } };
+    });
+    return changed ? { ...message, tool_calls: toolCalls } : message;
+  });
+}
+
+export function withOpenAIChatToolNames<T>(
+  build: (scope: OpenAIChatToolNameScope) => T,
+): T {
+  let registry = createOpenAIChatToolNameRegistry(undefined);
+  return build({
+    messages(parsed, baseUrl, messages): unknown {
+      registry = createOpenAIChatToolNameRegistry(openAIChatToolNameIdentities(parsed));
+      return frameAgentRouterMessages(baseUrl, aliasOpenAIChatMessageToolNames(messages, registry));
+    },
+    registry: () => registry,
+    restore: wireName => restoreOpenAIChatToolName(registry, wireName),
+  });
+}