@bitkyc08/opencodex 2.65.0-preview.20260925 → 2.66.0-preview.20260925

package/src/protocols/features.ts

@@ -0,0 +1,295 @@
+/**
+ * Request features whose survival depends on the protocol path, and the declared
+ * disposition of each feature across every cross-wire hop.
+ *
+ * LEAF MODULE (see `contract.ts`). Dispositions reuse the compatibility-manifest vocabulary
+ * (`passthrough | translated | degraded | unsupported`). A hop into `other` has no entry on
+ * purpose: nothing is claimed about adapters outside the three public protocols, and an absent
+ * entry is how "unknown" is spelled here — never as a fifth disposition.
+ *
+ * These are declared claims about the current code, pinned by fixtures; they are not Lab
+ * evidence and they never imply VERIFIED.
+ */
+import type { CompatibilityDisposition } from "../compatibility/manifest";
+import { protocolNodes, type Fidelity, type Protocol, type ProtocolHop, type UpstreamWire } from "./contract";
+
+export type FeatureDisposition = CompatibilityDisposition;
+
+export const PROTOCOL_FEATURES = [
+  "request.tools",
+  "request.hosted_tools",
+  "request.images",
+  "request.documents",
+  "request.multiple_choices",
+  "request.logprobs",
+  "request.logit_bias",
+  "request.seed",
+  "request.audio",
+  "request.prediction",
+  "request.response_format",
+  "request.reasoning",
+  "request.thinking_budget",
+  "request.top_k",
+  "request.cache_control",
+  "request.previous_response_id",
+  "request.store",
+  "request.background",
+  "request.compaction",
+] as const;
+export type ProtocolFeature = (typeof PROTOCOL_FEATURES)[number];
+
+const FEATURE_SET = new Set<string>(PROTOCOL_FEATURES);
+export function isProtocolFeature(value: unknown): value is ProtocolFeature {
+  return typeof value === "string" && FEATURE_SET.has(value);
+}
+
+/** Which public protocols can express each feature at all. */
+export const FEATURE_SOURCES: Readonly<Record<ProtocolFeature, readonly Protocol[]>> = {
+  "request.tools": ["responses", "chat", "messages"],
+  "request.hosted_tools": ["responses"],
+  "request.images": ["responses", "chat", "messages"],
+  "request.documents": ["responses", "chat", "messages"],
+  "request.multiple_choices": ["chat"],
+  "request.logprobs": ["responses", "chat"],
+  "request.logit_bias": ["chat"],
+  "request.seed": ["chat"],
+  "request.audio": ["chat"],
+  "request.prediction": ["chat"],
+  "request.response_format": ["responses", "chat"],
+  "request.reasoning": ["responses", "chat", "messages"],
+  "request.thinking_budget": ["messages"],
+  "request.top_k": ["messages"],
+  "request.cache_control": ["messages"],
+  "request.previous_response_id": ["responses"],
+  "request.store": ["responses"],
+  "request.background": ["responses"],
+  "request.compaction": ["responses"],
+};
+
+type WireHop = `${Protocol}>${Protocol}`;
+const T: FeatureDisposition = "translated";
+const D: FeatureDisposition = "degraded";
+const U: FeatureDisposition = "unsupported";
+
+/**
+ * Cross-wire hop dispositions. Same-wire hops are `passthrough` by definition and never listed.
+ * Evidence for each current-code claim lives in `devlog/_plan/260924_protocol_first_class/010_contract_and_baseline.md`.
+ */
+export const FEATURE_HOP_DISPOSITIONS: Readonly<Record<ProtocolFeature, Readonly<Partial<Record<WireHop, FeatureDisposition>>>>> = {
+  "request.tools": {
+    "chat>responses": T, "responses>chat": T, "messages>responses": T,
+    "responses>messages": T, "chat>messages": T, "messages>chat": T,
+  },
+  "request.hosted_tools": { "responses>chat": D, "responses>messages": D },
+  "request.images": {
+    "chat>responses": T, "responses>chat": T, "messages>responses": T,
+    "responses>messages": T, "chat>messages": T, "messages>chat": T,
+  },
+  "request.documents": {
+    "chat>responses": D, "responses>chat": D, "messages>responses": T,
+    "responses>messages": T, "chat>messages": D, "messages>chat": D,
+  },
+  "request.multiple_choices": { "chat>responses": U, "chat>messages": U },
+  "request.logprobs": { "chat>responses": U, "chat>messages": U, "responses>chat": U, "responses>messages": U },
+  "request.logit_bias": { "chat>responses": U, "chat>messages": U },
+  "request.seed": { "chat>responses": U, "chat>messages": U },
+  "request.audio": { "chat>responses": U, "chat>messages": U },
+  "request.prediction": { "chat>responses": U, "chat>messages": U },
+  "request.response_format": { "chat>responses": T, "responses>chat": T, "chat>messages": T, "responses>messages": T },
+  "request.reasoning": {
+    "chat>responses": T, "responses>chat": T, "messages>responses": D,
+    "responses>messages": T, "chat>messages": T, "messages>chat": D,
+  },
+  "request.thinking_budget": { "messages>responses": D, "messages>chat": D },
+  "request.top_k": { "messages>responses": U, "messages>chat": U },
+  "request.cache_control": { "messages>responses": D, "messages>chat": D },
+  "request.previous_response_id": { "responses>chat": T, "responses>messages": T },
+  "request.store": { "responses>chat": D, "responses>messages": D },
+  "request.background": { "responses>chat": U, "responses>messages": U },
+  "request.compaction": { "responses>chat": T, "responses>messages": T },
+};
+
+const RANK: Readonly<Record<FeatureDisposition, number>> = {
+  passthrough: 0,
+  translated: 1,
+  degraded: 2,
+  unsupported: 3,
+};
+
+/**
+ * Disposition of one feature over one hop between wire nodes. `undefined` means unknown:
+ * either end is `other`, or the pair is not declared.
+ */
+export function featureHopDisposition(
+  feature: ProtocolFeature,
+  from: UpstreamWire,
+  to: UpstreamWire,
+): FeatureDisposition | undefined {
+  if (from === "other" || to === "other") return undefined;
+  if (from === to) return "passthrough";
+  return FEATURE_HOP_DISPOSITIONS[feature][`${from}>${to}`];
+}
+
+export interface FeatureEffect {
+  feature: ProtocolFeature;
+  disposition: FeatureDisposition;
+}
+
+export interface PathFeatureEffects {
+  effects: FeatureEffect[];
+  /** Present features with no declared disposition on some hop. */
+  unknown: ProtocolFeature[];
+  fidelity: Fidelity;
+}
+
+/**
+ * The worst disposition each present feature meets along a request path. A feature the
+ * inbound protocol cannot express is ignored rather than reported.
+ */
+export function featureEffectsForPath(
+  inbound: Protocol,
+  path: readonly ProtocolHop[],
+  present: Iterable<ProtocolFeature>,
+): PathFeatureEffects {
+  const nodes = protocolNodes(path);
+  const effects: FeatureEffect[] = [];
+  const unknown: ProtocolFeature[] = [];
+  const seen = new Set<ProtocolFeature>();
+  for (const feature of present) {
+    if (seen.has(feature) || !FEATURE_SOURCES[feature].includes(inbound)) continue;
+    seen.add(feature);
+    let worst: FeatureDisposition = "passthrough";
+    let unknownHop = false;
+    for (let i = 1; i < nodes.length; i++) {
+      const hop = featureHopDisposition(feature, nodes[i - 1]!, nodes[i]!);
+      if (hop === undefined) unknownHop = true;
+      else if (RANK[hop] > RANK[worst]) worst = hop;
+    }
+    // A loss already declared on a known hop is reported even when a later hop is unknown:
+    // an unknown adapter cannot restore what an earlier hop dropped.
+    if (unknownHop && RANK[worst] < RANK.degraded) unknown.push(feature);
+    else effects.push({ feature, disposition: worst });
+  }
+  effects.sort((a, b) => PROTOCOL_FEATURES.indexOf(a.feature) - PROTOCOL_FEATURES.indexOf(b.feature));
+  unknown.sort((a, b) => PROTOCOL_FEATURES.indexOf(a) - PROTOCOL_FEATURES.indexOf(b));
+  const degraded = effects.some(effect => RANK[effect.disposition] >= RANK.degraded);
+  return {
+    effects,
+    unknown,
+    fidelity: degraded ? "degraded" : unknown.length > 0 ? "unknown" : "preserved",
+  };
+}
+
+/** Features that would be refused under `reject-unrepresentable`. */
+export function unrepresentableFeatures(effects: readonly FeatureEffect[]): ProtocolFeature[] {
+  return effects.filter(effect => effect.disposition === "unsupported").map(effect => effect.feature);
+}
+
+type Rec = Record<string, unknown>;
+function isRec(value: unknown): value is Rec {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function nonEmptyArray(value: unknown): value is unknown[] {
+  return Array.isArray(value) && value.length > 0;
+}
+
+const HOSTED_TOOL_TYPES = new Set([
+  "web_search", "web_search_preview", "image_generation", "file_search",
+  "code_interpreter", "computer_use_preview", "mcp", "local_shell",
+]);
+
+function hasPartType(messages: unknown, types: ReadonlySet<string>): boolean {
+  if (!Array.isArray(messages)) return false;
+  for (const message of messages) {
+    if (!isRec(message) || !Array.isArray(message.content)) continue;
+    for (const part of message.content) {
+      if (isRec(part) && typeof part.type === "string" && types.has(part.type)) return true;
+      if (isRec(part) && Array.isArray(part.content) && hasPartType([part], types)) return true;
+    }
+  }
+  return false;
+}
+
+const CHAT_IMAGE_PARTS = new Set(["image_url", "input_image", "image"]);
+const CHAT_FILE_PARTS = new Set(["file", "input_file"]);
+const MESSAGES_IMAGE_PARTS = new Set(["image"]);
+const MESSAGES_DOCUMENT_PARTS = new Set(["document"]);
+const RESPONSES_IMAGE_PARTS = new Set(["input_image"]);
+const RESPONSES_FILE_PARTS = new Set(["input_file"]);
+
+function hasCacheControl(value: unknown, depth = 0): boolean {
+  if (depth > 4) return false;
+  if (Array.isArray(value)) return value.some(item => hasCacheControl(item, depth + 1));
+  if (!isRec(value)) return false;
+  if (value.cache_control !== undefined) return true;
+  return hasCacheControl(value.content, depth + 1);
+}
+
+/**
+ * Features present in a Chat Completions body. Reads only structure; never retains content.
+ * Bounded: nested content is inspected two levels deep at most.
+ */
+export function featuresFromChatBody(body: unknown): Set<ProtocolFeature> {
+  const out = new Set<ProtocolFeature>();
+  if (!isRec(body)) return out;
+  if (nonEmptyArray(body.tools) || nonEmptyArray(body.functions)) out.add("request.tools");
+  if (hasPartType(body.messages, CHAT_IMAGE_PARTS)) out.add("request.images");
+  if (hasPartType(body.messages, CHAT_FILE_PARTS)) out.add("request.documents");
+  if (typeof body.n === "number" && body.n > 1) out.add("request.multiple_choices");
+  if (body.logprobs === true || typeof body.top_logprobs === "number") out.add("request.logprobs");
+  if (isRec(body.logit_bias) && Object.keys(body.logit_bias).length > 0) out.add("request.logit_bias");
+  if (typeof body.seed === "number") out.add("request.seed");
+  if (body.audio !== undefined || (Array.isArray(body.modalities) && body.modalities.includes("audio"))) out.add("request.audio");
+  if (body.prediction !== undefined) out.add("request.prediction");
+  if (isRec(body.response_format) && body.response_format.type !== "text") out.add("request.response_format");
+  if (typeof body.reasoning_effort === "string" || isRec(body.reasoning)) out.add("request.reasoning");
+  return out;
+}
+
+/** Features present in an Anthropic Messages body. */
+export function featuresFromMessagesBody(body: unknown): Set<ProtocolFeature> {
+  const out = new Set<ProtocolFeature>();
+  if (!isRec(body)) return out;
+  if (nonEmptyArray(body.tools)) out.add("request.tools");
+  if (hasPartType(body.messages, MESSAGES_IMAGE_PARTS)) out.add("request.images");
+  if (hasPartType(body.messages, MESSAGES_DOCUMENT_PARTS)) out.add("request.documents");
+  if (isRec(body.thinking) || isRec(body.output_config)) out.add("request.reasoning");
+  if (isRec(body.thinking) && typeof body.thinking.budget_tokens === "number") out.add("request.thinking_budget");
+  if (typeof body.top_k === "number") out.add("request.top_k");
+  if (hasCacheControl(body.system) || hasCacheControl(body.messages) || hasCacheControl(body.tools)) {
+    out.add("request.cache_control");
+  }
+  return out;
+}
+
+/** Features present in a Responses body. */
+export function featuresFromResponsesBody(body: unknown): Set<ProtocolFeature> {
+  const out = new Set<ProtocolFeature>();
+  if (!isRec(body)) return out;
+  if (Array.isArray(body.tools)) {
+    for (const tool of body.tools) {
+      if (!isRec(tool) || typeof tool.type !== "string") continue;
+      if (HOSTED_TOOL_TYPES.has(tool.type)) out.add("request.hosted_tools");
+      else out.add("request.tools");
+    }
+  }
+  if (hasPartType(body.input, RESPONSES_IMAGE_PARTS)) out.add("request.images");
+  if (hasPartType(body.input, RESPONSES_FILE_PARTS)) out.add("request.documents");
+  if (typeof body.top_logprobs === "number"
+    || (Array.isArray(body.include) && body.include.includes("message.output_text.logprobs"))) {
+    out.add("request.logprobs");
+  }
+  if (isRec(body.text) && isRec(body.text.format) && body.text.format.type !== "text") out.add("request.response_format");
+  if (isRec(body.reasoning)) out.add("request.reasoning");
+  if (typeof body.previous_response_id === "string" && body.previous_response_id.length > 0) out.add("request.previous_response_id");
+  if (body.store === true) out.add("request.store");
+  if (body.background === true) out.add("request.background");
+  if (body.compaction_trigger !== undefined) out.add("request.compaction");
+  return out;
+}
+
+export function featuresFromBody(protocol: Protocol, body: unknown): Set<ProtocolFeature> {
+  if (protocol === "chat") return featuresFromChatBody(body);
+  if (protocol === "messages") return featuresFromMessagesBody(body);
+  return featuresFromResponsesBody(body);
+}

package/src/protocols/guard.ts

@@ -0,0 +1,33 @@
+/**
+ * Refuse a request whose features its path cannot carry (PF-06).
+ *
+ * LEAF MODULE (see `contract.ts`). The caller supplies the request path it computed for the
+ * settled route (`path.ts`); this module only judges it. Only a declared `unsupported`
+ * disposition refuses. A hop into `other` has no declared disposition and so never refuses by
+ * itself, but a loss declared on an earlier known hop still does: an unknown adapter cannot
+ * restore what the internal Responses body already dropped.
+ */
+import type { Protocol, ProtocolHop, ProtocolReasonCode } from "./contract";
+import { featureEffectsForPath, unrepresentableFeatures, type ProtocolFeature } from "./features";
+
+export type RepresentableVerdict =
+  | { ok: true }
+  | { ok: false; features: ProtocolFeature[]; reasonCodes: ProtocolReasonCode[] };
+
+export function checkRepresentable(input: {
+  inbound: Protocol;
+  requestPath: readonly ProtocolHop[];
+  features: Iterable<ProtocolFeature>;
+  /** `UnrepresentablePolicy` from `settings.ts`, spelled out so this module stays a leaf. */
+  policy: "legacy" | "reject";
+}): RepresentableVerdict {
+  if (input.policy !== "reject") return { ok: true };
+  const { effects } = featureEffectsForPath(input.inbound, input.requestPath, input.features);
+  const features = unrepresentableFeatures(effects);
+  return features.length === 0 ? { ok: true } : { ok: false, features, reasonCodes: ["feature-unrepresentable"] };
+}
+
+/** Client-facing refusal text. Names feature keys only, never request content. */
+export function unrepresentableMessage(features: readonly ProtocolFeature[]): string {
+  return `The selected route cannot carry these request features: ${features.join(", ")}`;
+}

package/src/protocols/opaque-state.ts

@@ -0,0 +1,132 @@
+/**
+ * Opaque reasoning state and credential domains for native Messages sends (PF-10).
+ *
+ * A thinking block's `signature` and a `redacted_thinking` block's `data` are opaque to this
+ * proxy: they were minted by some Anthropic deployment for some credential, and only that side
+ * can verify or decrypt them. The native Messages lane therefore forwards them only to Anthropic
+ * itself (`api.anthropic.com` over HTTPS). For any other destination they are removed from the
+ * body that is sent — the signature field is dropped and the thinking text kept, a
+ * `redacted_thinking` block is dropped whole — and the caller's source body is left untouched,
+ * so the next build for the next destination starts from the full state again.
+ *
+ * A credential domain is the pair a destination is trusted as: the provider's base host and the
+ * class of credential it is reached with. Two sends share a domain only when both match; a key
+ * rotation within one provider keeps it, a move to another host or another credential class does
+ * not. Every build decides from its own domain, never from an earlier build's output.
+ *
+ * LEAF MODULE: type-only imports, no side effects, never logs or returns what it removed.
+ */
+import type { AnthropicProviderClass } from "../adapters/anthropic/beta-allowlist";
+import type { OcxProviderConfig } from "../types";
+
+type Rec = Record<string, unknown>;
+function isRec(value: unknown): value is Rec {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Anthropic's own API host. Nothing else is first-party, including look-alike subdomains. */
+export const FIRST_PARTY_ANTHROPIC_HOST = "api.anthropic.com";
+
+export type CredentialAuthClass = "key" | "oauth" | "forward" | "local" | "unknown";
+
+export interface CredentialDomain {
+  /** Lower-cased `host` (with a non-default port) of the provider's base URL. */
+  readonly host: string;
+  readonly authClass: CredentialAuthClass;
+  /** HTTPS to `api.anthropic.com` on the default port, with no userinfo. */
+  readonly firstPartyAnthropic: boolean;
+}
+
+function authClassOf(authMode: OcxProviderConfig["authMode"]): CredentialAuthClass {
+  switch (authMode) {
+    case undefined:
+    case "key":
+      return "key";
+    case "oauth":
+    case "forward":
+    case "local":
+      return authMode;
+    default:
+      return "unknown";
+  }
+}
+
+/** The credential domain a provider is reached in, or `undefined` for a malformed base URL. */
+export function credentialDomainFor(
+  provider: Pick<OcxProviderConfig, "baseUrl" | "authMode">,
+): CredentialDomain | undefined {
+  let url: URL;
+  try {
+    url = new URL(provider.baseUrl);
+  } catch {
+    return undefined;
+  }
+  const firstPartyAnthropic = url.protocol === "https:"
+    && url.hostname.toLowerCase() === FIRST_PARTY_ANTHROPIC_HOST
+    && url.port === ""
+    && url.username === ""
+    && url.password === "";
+  return { host: url.host.toLowerCase(), authClass: authClassOf(provider.authMode), firstPartyAnthropic };
+}
+
+/** Whether two sends share one credential domain. An unknown domain shares none. */
+export function sameCredentialDomain(a: CredentialDomain | undefined, b: CredentialDomain | undefined): boolean {
+  return a !== undefined && b !== undefined && a.host === b.host && a.authClass === b.authClass;
+}
+
+/** The beta-allowlist class of a provider: first-party only for Anthropic's own API. */
+export function anthropicProviderClass(provider: Pick<OcxProviderConfig, "baseUrl" | "authMode">): AnthropicProviderClass {
+  return credentialDomainFor(provider)?.firstPartyAnthropic ? "first-party" : "compatible";
+}
+
+function isOpaqueBlock(block: unknown): boolean {
+  if (!isRec(block)) return false;
+  if (block.type === "redacted_thinking") return true;
+  return block.type === "thinking" && Object.hasOwn(block, "signature");
+}
+
+/** Whether a Messages body carries any thinking signature or `redacted_thinking` block. */
+export function messagesBodyHasOpaqueState(body: Readonly<Rec>): boolean {
+  if (!Array.isArray(body.messages)) return false;
+  for (const message of body.messages) {
+    if (isRec(message) && Array.isArray(message.content) && message.content.some(isOpaqueBlock)) return true;
+  }
+  return false;
+}
+
+export interface OpaqueStateResult {
+  /** The body to send. The input itself when nothing had to change. */
+  body: Rec;
+  /** Whether opaque state was removed for this destination. */
+  stripped: boolean;
+}
+
+/**
+ * The body a destination may receive. First-party Anthropic keeps every signature and redacted
+ * block; any other or unknown destination gets a copy without them. Copy-on-write: only the
+ * messages that change are copied, and the input is never mutated. A message left with no
+ * content is dropped rather than sent empty.
+ */
+export function opaqueStateForDestination(body: Rec, domain: CredentialDomain | undefined): OpaqueStateResult {
+  if (domain?.firstPartyAnthropic || !messagesBodyHasOpaqueState(body)) return { body, stripped: false };
+  const messages: unknown[] = [];
+  for (const message of body.messages as unknown[]) {
+    if (!isRec(message) || !Array.isArray(message.content) || !message.content.some(isOpaqueBlock)) {
+      messages.push(message);
+      continue;
+    }
+    const content: unknown[] = [];
+    for (const block of message.content) {
+      if (!isOpaqueBlock(block)) {
+        content.push(block);
+        continue;
+      }
+      const opaque = block as Rec;
+      if (opaque.type === "redacted_thinking") continue;
+      const { signature: _signature, ...visible } = opaque;
+      content.push(visible);
+    }
+    if (content.length > 0) messages.push({ ...message, content });
+  }
+  return { body: { ...body, messages }, stripped: true };
+}

package/src/protocols/path.ts

@@ -0,0 +1,39 @@
+/**
+ * The request path a settled route takes, derived from the lane the ingress chose and the
+ * upstream wire of the final adapter. The observed trace (PF-02) and the planner (PF-03) both
+ * call this, so a preview and the log of the same request can never disagree on the rule.
+ *
+ * LEAF MODULE (see `contract.ts`).
+ */
+import { deliveryModeForPath, type DeliveryMode, type Protocol, type ProtocolHop, type UpstreamWire } from "./contract";
+
+/**
+ * `native`: the ingress sent its own wire to a same-wire upstream.
+ * `bridge`: the ingress projected the request into the Responses pipeline.
+ */
+export type ProtocolLane = "native" | "bridge";
+
+export function requestPathForLane(inbound: Protocol, lane: ProtocolLane, upstream: UpstreamWire): ProtocolHop[] {
+  if (inbound === "responses") {
+    return upstream === "responses" ? ["responses", "responses"] : ["responses", "ir", upstream];
+  }
+  if (lane === "native") return [inbound, inbound];
+  if (upstream === "responses") return [inbound, "responses"];
+  return [inbound, "responses-internal", "ir", upstream];
+}
+
+/** Upstream first, client last; the internal Responses hop is not replayed on the way back. */
+export function responsePathForLane(inbound: Protocol, lane: ProtocolLane, upstream: UpstreamWire): ProtocolHop[] {
+  if (inbound === "responses") return upstream === "responses" ? ["responses", "responses"] : [upstream, "ir", "responses"];
+  if (lane === "native") return [inbound, inbound];
+  if (upstream === "responses") return ["responses", inbound];
+  return [upstream, "ir", "responses-internal", inbound];
+}
+
+export function deliveryModeForLane(
+  inbound: Protocol,
+  lane: ProtocolLane,
+  upstream: UpstreamWire,
+): Exclude<DeliveryMode, "blocked"> {
+  return deliveryModeForPath(requestPathForLane(inbound, lane, upstream));
+}