@bitkyc08/opencodex 2.84.0 → 2.87.0

package/src/server/messages-antigravity-direct.ts

@@ -0,0 +1,195 @@
+/**
+ * The Antigravity direct lane for the Messages ingress (`protocols.rollout.antigravityDirect`).
+ *
+ * The Messages ingress translates before it routes: the route is decided on the translated body's
+ * resolved model. So the lane is planned ahead of translation on the settings-only body
+ * (`anthropicSettingsTranslation`), whose model is that same resolved model, against a preview of
+ * the route; the conversation is decoded straight into the IR only when that preview is an
+ * eligible Antigravity route. The ingress then routes the settings-only body as usual and keeps
+ * the lane only if the settled route is still the one the plan was made for; otherwise it builds
+ * the full bridge translation, as it would have without the switch.
+ *
+ * Refusals stay the bridge's by construction: a settings error, or an undecodable proxy envelope
+ * (which the bridge retries through the native projection), returns no plan and the ingress takes
+ * its ordinary translation path, which answers exactly as before. Any other decode error is one
+ * the translator's walk raises with the same message at the same point
+ * (`tests/responses/protocol-messages-ir-parity.test.ts`).
+ */
+import { anthropicSettingsTranslation, AnthropicRequestError, type ClaudeCacheKeySource } from "../claude/inbound";
+import { messagesToResponsesTranslation } from "../protocols/codecs/messages";
+import {
+  MALFORMED_REASONING_SIGNATURE,
+  messagesConversationToIr,
+  messagesRouteEvidence,
+  withDirectMessagesConversation,
+  type MessagesIrConversation,
+} from "../protocols/codecs/messages-ir";
+import { resolveProtocolSettings } from "../protocols/settings";
+import type { TranslatorBudget, TranslatorBufferKind } from "../lib/translator-budget";
+import type { PolicyRequestEvidence } from "../routing/evaluator";
+import { previewRouteModel, type RouteResult } from "../router";
+import type { OcxClaudeCodeConfig, OcxConfig } from "../types";
+import { antigravityMessagesDeclineReason, type AntigravityDirectDeclineReason } from "./antigravity-direct-eligibility";
+import { cacheDiagnosticsObserving } from "./request-log";
+import type { DirectRequestOption } from "./responses/core-options";
+
+type Rec = Record<string, unknown>;
+
+export interface MessagesDirectPlan {
+  /** The concrete route the plan was made for. */
+  providerName: string;
+  modelId: string;
+  /** The settings-only Responses body the core receives, and its prompt-cache key provenance. */
+  settingsBody: Rec;
+  cacheKeySource: ClaudeCacheKeySource;
+  conversation: MessagesIrConversation;
+  /** What the core would have read from the bridge body for policy routing. */
+  evidence: PolicyRequestEvidence;
+  /**
+   * Release the retained charges the plan's decode made. The ingress calls it when it abandons
+   * the plan for the full translation, which charges the same reasoning copies again.
+   */
+  releaseDecodeCharges(): void;
+}
+
+/**
+ * The request budget, with the retained charges made through it recorded so a decode the ingress
+ * abandons can hand them back. Without that, the bridge translation that follows would be held to
+ * a budget already spent on a copy nobody keeps, and could answer 413 where the bridge alone fits.
+ */
+function recordingBudget(budget: TranslatorBudget): { budget: TranslatorBudget; release(): void } {
+  const charged = new Map<TranslatorBufferKind, number>();
+  const recording: TranslatorBudget = {
+    openCall: id => budget.openCall(id),
+    closeCall: id => budget.closeCall(id),
+    reserveTransient: (bytes, scope) => budget.reserveTransient(bytes, scope),
+    chargeRetained: (delta, scope) => {
+      budget.chargeRetained(delta, scope);
+      charged.set(scope.kind, (charged.get(scope.kind) ?? 0) + delta);
+    },
+    releaseRetained: (bytes, scope) => {
+      budget.releaseRetained(bytes, scope);
+      charged.set(scope.kind, (charged.get(scope.kind) ?? 0) - bytes);
+    },
+    observeAcceptedRequestCopy: bytes => budget.observeAcceptedRequestCopy(bytes),
+    observeExternallyCapped: (kind, bytes) => budget.observeExternallyCapped(kind, bytes),
+    snapshot: () => budget.snapshot(),
+    dispose: () => budget.dispose(),
+  };
+  return {
+    budget: recording,
+    release: () => {
+      for (const [kind, bytes] of charged) if (bytes > 0) budget.releaseRetained(bytes, { kind });
+      charged.clear();
+    },
+  };
+}
+
+/**
+ * Plan the direct lane for a Messages body, or return `undefined` to translate as before. Throws
+ * only what the translator's conversation walk throws for the same body.
+ */
+export function planMessagesAntigravityDirect(
+  body: unknown,
+  cc: OcxClaudeCodeConfig | undefined,
+  config: OcxConfig,
+  budget: TranslatorBudget,
+): MessagesDirectPlan | undefined {
+  if (!resolveProtocolSettings(config).rollout.antigravityDirect) return undefined;
+  if (!body || typeof body !== "object" || Array.isArray(body)) return undefined;
+  let settings: ReturnType<typeof anthropicSettingsTranslation>;
+  let route: RouteResult;
+  try {
+    settings = anthropicSettingsTranslation(body, cc);
+    route = previewRouteModel(config, settings.body.model as string);
+  } catch {
+    return undefined;
+  }
+  const model = settings.body.model as string;
+  if (!messagesDirectRouteHolds(route, body as Rec, model, config)) return undefined;
+  const recorded = recordingBudget(budget);
+  let conversation: MessagesIrConversation;
+  try {
+    conversation = messagesConversationToIr(body, cc, recorded.budget, model);
+  } catch (err) {
+    if (err instanceof AnthropicRequestError && err.message === MALFORMED_REASONING_SIGNATURE) {
+      // The bridge retries this body through the native projection; give it the whole budget.
+      recorded.release();
+      return undefined;
+    }
+    throw err;
+  }
+  return {
+    providerName: route.providerName,
+    modelId: route.modelId,
+    settingsBody: settings.body,
+    cacheKeySource: settings.cacheKeySource,
+    conversation,
+    evidence: messagesRouteEvidence(body),
+    releaseDecodeCharges: recorded.release,
+  };
+}
+
+/** Whether a route may carry this body on the direct lane, judged as the ingress judges it. */
+export function messagesDirectRouteHolds(
+  route: Pick<RouteResult, "providerName" | "modelId" | "provider" | "combo" | "routeKind">,
+  body: Rec,
+  model: string,
+  config: OcxConfig,
+): boolean {
+  return antigravityMessagesDeclineReason(route, body, model, config, { cacheDiagnostics: cacheDiagnosticsObserving() }) === undefined;
+}
+
+/** Whether the route the ingress settled is still the one `plan` was made for, and still eligible. */
+export function messagesDirectPlanHolds(plan: MessagesDirectPlan, route: RouteResult, body: Rec, config: OcxConfig): boolean {
+  return route.providerName === plan.providerName && route.modelId === plan.modelId
+    && messagesDirectRouteHolds(route, body, plan.settingsBody.model as string, config);
+}
+
+/**
+ * The lane's decline for a bridged request's trace, when it says something about this route: with
+ * the switch off or a non-Antigravity target the path already explains the bridge.
+ */
+export function messagesDirectTraceDecline(
+  route: RouteResult,
+  body: unknown,
+  model: string,
+  config: OcxConfig,
+): AntigravityDirectDeclineReason | undefined {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return undefined;
+  const reason = antigravityMessagesDeclineReason(route, body as Rec, model, config, { cacheDiagnostics: cacheDiagnosticsObserving() });
+  return reason === "rollout-disabled" || reason === "not-migrated" ? undefined : reason;
+}
+
+/**
+ * The core option for a planned request. The bridge conversation is translated at most once, and
+ * only if the core asks for it (a reroute, or an ambiguous-reset judgment).
+ */
+export function messagesDirectRequestOption(
+  plan: MessagesDirectPlan,
+  body: unknown,
+  cc: OcxClaudeCodeConfig | undefined,
+  budget: TranslatorBudget,
+): DirectRequestOption {
+  let bridge: Rec | undefined;
+  return {
+    protocol: "messages",
+    providerName: plan.providerName,
+    modelId: plan.modelId,
+    evidence: plan.evidence,
+    decode: base => withDirectMessagesConversation(
+      base,
+      plan.conversation,
+      modelId => messagesConversationToIr(body, cc, budget, modelId),
+    ),
+    bridgeConversation: () => {
+      bridge ??= messagesToResponsesTranslation(body, cc, budget).body;
+      return {
+        input: bridge.input,
+        ...(bridge.instructions !== undefined ? { instructions: bridge.instructions } : {}),
+        ...(bridge.tools !== undefined ? { tools: bridge.tools } : {}),
+      };
+    },
+  };
+}
+

package/src/server/messages-native-tool-guard.ts

@@ -0,0 +1,185 @@
+import { anthropicErrorBody } from "../claude/outbound";
+import { redactSecretString } from "../lib/redact";
+import { sseFieldValue } from "../lib/sse-decoder";
+import { TRANSLATOR_MAX_SSE_EVENT_BYTES, type TranslatorBudget } from "../lib/translator-budget";
+import { UNDECLARED_TOOL_CALL_ERROR_CODE, undeclaredToolCallMessage } from "./responses-undeclared-tool-guard";
+import { createSseBlockBuffer, sseDataPayload } from "./sse-payload-rewrite";
+
+type Rec = Record<string, unknown>;
+const isRec = (value: unknown): value is Rec => value !== null && typeof value === "object" && !Array.isArray(value);
+const NO_DECLARED_TOOLS: ReadonlySet<string> = new Set();
+
+/** Inline system-message definitions extend an otherwise empty native catalog. */
+export function nativeMessagesInlineToolNames(body: Rec): ReadonlySet<string> {
+  const definitions = new Set<string>();
+  const active = new Set<string>();
+  if (!Array.isArray(body.messages)) return active;
+  for (const message of body.messages) {
+    if (!isRec(message) || message.role !== "system" || !Array.isArray(message.content)) continue;
+    for (const block of message.content) {
+      if (!isRec(block) || !isRec(block.tool)) continue;
+      const tool = block.tool;
+      if (block.type === "tool_addition" && tool.type === "tool_definition" && isRec(tool.definition)
+        && typeof tool.definition.name === "string" && tool.definition.name.length > 0) {
+        definitions.add(tool.definition.name);
+        active.add(tool.definition.name);
+      } else if (tool.type === "tool_reference" && typeof tool.name === "string") {
+        if (block.type === "tool_addition" && definitions.has(tool.name)) active.add(tool.name);
+        // Like native admission, only a permanent removal withdraws a declaration.
+        if (block.type === "tool_removal" && (message.clear_at === undefined || message.clear_at === "never")) active.delete(tool.name);
+      }
+    }
+  }
+  return active;
+}
+
+/** Inspect only native message content; opaque extension fields do not carry client calls. */
+export function nativeMessagesClientToolName(value: unknown, declared: ReadonlySet<string> = NO_DECLARED_TOOLS): string | undefined {
+  if (!isRec(value)) return undefined;
+  const content = Array.isArray(value.content) ? value.content : [];
+  const block = content.find(item => isRec(item) && item.type === "tool_use"
+    && (typeof item.name !== "string" || !declared.has(item.name)));
+  if (isRec(block)) return typeof block.name === "string" ? block.name : "<unnamed>";
+  return undefined;
+}
+
+/** Used only when the current native request explicitly declares no client tools. */
+export function guardNativeMessagesEmptyToolCatalog(
+  source: ReadableStream<Uint8Array>,
+  budget: TranslatorBudget,
+  onRefusal: (message: string) => void,
+  declared: ReadonlySet<string> = NO_DECLARED_TOOLS,
+): ReadableStream<Uint8Array> {
+  const reader = source.getReader();
+  const decoder = new TextDecoder();
+  const encoder = new TextEncoder();
+  const scope = { kind: "live_transient" as const };
+  const buffer = createSseBlockBuffer(budget, bytes => {
+    if (bytes > TRANSLATOR_MAX_SSE_EVENT_BYTES) throw new Error("upstream SSE event exceeded the safe limit");
+  });
+  // Hosted tools share input_json_delta with client tools, but cannot grant client authority.
+  const permittedInputBlocks = new Set<number>();
+  let queuedBytes = 0;
+  let settled = false;
+  const releaseQueued = () => {
+    budget.releaseRetained(queuedBytes, scope);
+    queuedBytes = 0;
+  };
+  const clear = () => {
+    buffer.clear();
+    budget.releaseRetained(permittedInputBlocks.size * 32, scope);
+    permittedInputBlocks.clear();
+  };
+  const enqueue = (controller: ReadableStreamDefaultController<Uint8Array>, text: string) => {
+    const bytes = Buffer.byteLength(text);
+    const reservation = budget.reserveTransient(bytes, scope);
+    try {
+      controller.enqueue(encoder.encode(text));
+      reservation.commitRetained();
+      queuedBytes += bytes;
+    } catch (error) {
+      reservation.release();
+      throw error;
+    }
+  };
+  const cancelReader = (reason?: unknown) => {
+    void reader.cancel(reason).catch(() => {});
+  };
+  const process = (controller: ReadableStreamDefaultController<Uint8Array>, block: string, delimiter: string) => {
+    const payload = sseDataPayload(block);
+    let data: unknown;
+    let terminal = false;
+    try { data = payload === null ? undefined : JSON.parse(payload); } catch {
+      // The buffered Messages collector concatenates data lines without separators. Inspect
+      // that representation too, so an invalid SSE split cannot become a valid folded tool call.
+      try { data = payload === null ? undefined : JSON.parse(payload.replace(/\n/g, "")); } catch { /* preserve opaque frames */ }
+    }
+    if (isRec(data)) {
+      const eventName = block.split(/\r\n|\r|\n/).map(line => sseFieldValue(line, "event"))
+        .filter(value => value !== null).at(-1)?.trim();
+      // Stream clients use the payload type; the buffered collector uses the event field.
+      const isEvent = (type: string) => data.type === type || eventName === type;
+      terminal = isEvent("message_stop") || isEvent("error");
+      let name = isEvent("message_start") ? nativeMessagesClientToolName(data.message, declared) : undefined;
+      if (isEvent("content_block_start") && isRec(data.content_block) && data.content_block.type === "tool_use"
+        && (typeof data.content_block.name !== "string" || !declared.has(data.content_block.name))) {
+        name ??= typeof data.content_block.name === "string" ? data.content_block.name : "<unnamed>";
+      }
+      const index = typeof data.index === "number" && Number.isSafeInteger(data.index) ? data.index : undefined;
+      if (isEvent("content_block_delta") && isRec(data.delta) && data.delta.type === "input_json_delta"
+        && (index === undefined || !permittedInputBlocks.has(index))) name ??= "<unnamed>";
+      if (name !== undefined) {
+        clear();
+        const message = redactSecretString(undeclaredToolCallMessage(name));
+        onRefusal(message);
+        enqueue(controller, `event: error\ndata: ${JSON.stringify(anthropicErrorBody(502, message, "api_error", UNDECLARED_TOOL_CALL_ERROR_CODE))}\n\n`);
+        settled = true;
+        cancelReader(new Error(message));
+        controller.close();
+        return;
+      }
+      if (isEvent("content_block_start") && index !== undefined && isRec(data.content_block)) {
+        if (permittedInputBlocks.delete(index)) budget.releaseRetained(32, scope);
+        if (data.content_block.type === "server_tool_use" || data.content_block.type === "mcp_tool_use"
+          || data.content_block.type === "tool_use" && typeof data.content_block.name === "string" && declared.has(data.content_block.name)) {
+          budget.chargeRetained(32, scope);
+          permittedInputBlocks.add(index);
+        }
+      } else if (isEvent("content_block_stop") && index !== undefined && permittedInputBlocks.delete(index)) {
+        budget.releaseRetained(32, scope);
+      }
+    }
+    enqueue(controller, block + delimiter);
+    if (terminal) {
+      settled = true;
+      clear();
+      cancelReader();
+      controller.close();
+    }
+  };
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      releaseQueued();
+      if (settled) return;
+      try {
+        for (;;) {
+          const block = buffer.next();
+          if (block) {
+            buffer.compact();
+            process(controller, block.block, block.delimiter);
+            return;
+          }
+          const { done, value } = await reader.read();
+          if (settled) return;
+          if (!done) {
+            buffer.append(decoder.decode(value, { stream: true }));
+            continue;
+          }
+          buffer.append(decoder.decode());
+          const tail = buffer.tail();
+          if (tail) process(controller, tail, "");
+          if (!settled) {
+            settled = true;
+            clear();
+            controller.close();
+          }
+          return;
+        }
+      } catch (error) {
+        if (settled) return;
+        settled = true;
+        clear();
+        cancelReader(error);
+        controller.error(error);
+      } finally {
+        if (settled) releaseQueued();
+      }
+    },
+    cancel(reason) {
+      settled = true;
+      clear();
+      releaseQueued();
+      return reader.cancel(reason);
+    },
+  });
+}