@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
192 lines (174 loc) • 7.83 kB
text/typescript
/**
* Shared protocol vocabulary for the three public inference APIs.
*
* LEAF MODULE. The dashboard imports this file directly (`gui/src/*` reaches `src/` for pure
* contracts), so it must not import server, provider, router, or Lab code — not even as a type.
* Internal spellings that predate this vocabulary (`InboundWire` "anthropic", adapter ids, Lab
* protocol identities) are connected through the explicit mapping functions below rather than
* renamed in place; persisted rows and existing enums keep their spelling.
*/
/** Bumped when a reason code, hop, mode, or feature disposition changes meaning. */
export const PROTOCOL_CONTRACT_VERSION = "2026-09-25.2";
export const PROTOCOLS = ["responses", "chat", "messages"] as const;
/** A public inference API a client can speak to this proxy. */
export type Protocol = (typeof PROTOCOLS)[number];
export const UPSTREAM_WIRES = ["responses", "chat", "messages", "other"] as const;
/**
* The wire the final provider receives. `other` covers adapters whose upstream is none of
* the three public protocols (Gemini, Kiro, Cursor, ...); nothing is claimed about them here.
*/
export type UpstreamWire = (typeof UPSTREAM_WIRES)[number];
export const PROTOCOL_HOPS = ["responses", "chat", "messages", "other", "ir", "responses-internal"] as const;
/**
* One node of a request or response path.
*
* - a wire name: that wire's JSON/SSE is actually produced at this point;
* - `ir`: the adapter-neutral request (`OcxParsedRequest`) or event (`AdapterEvent`) form;
* - `responses-internal`: Responses JSON/SSE produced only as an internal bridge, never sent to
* the provider. Its presence is what makes a path `legacy-bridge`.
*/
export type ProtocolHop = (typeof PROTOCOL_HOPS)[number];
export const DELIVERY_MODES = ["native", "translated", "legacy-bridge", "blocked"] as const;
/**
* How one request (or one attempt) reached its upstream.
*
* - `native`: same wire end to end; the source body is the wire source. Model rewrites, auth
* injection and declared provider policy can still apply, so native is not byte-identical.
* - `translated`: cross-wire conversion whose only intermediate is the IR or the target wire.
* - `legacy-bridge`: the path contains `responses-internal`.
* - `blocked`: refused before any upstream send.
*/
export type DeliveryMode = (typeof DELIVERY_MODES)[number];
export const FIDELITIES = ["preserved", "degraded", "unknown"] as const;
export type Fidelity = (typeof FIDELITIES)[number];
/**
* Fixed reason codes. Never conversation-derived, never free text: plan and trace records carry
* only these, which is what keeps them safe to persist and to show on a remote dashboard.
*/
export const PROTOCOL_REASON_CODES = [
"same-wire-native",
"cross-wire-codec",
"cross-wire-ir",
"combo-or-policy-route",
"responses-only-feature",
"hosted-tool",
"vision-preprocessing",
"tool-result-image",
"auth-mode-not-native",
"effort-row",
"fast-row",
"caller-credential-required",
"not-migrated",
"surface-disabled",
"feature-unrepresentable",
"compatibility-reject",
"unknown-model",
"upstream-other",
"rollout-disabled",
/** Operator policy that only the bridge applies (pinned effort, skill elision, a sidecar). */
"bridge-only-policy",
/** A pooled Anthropic OAuth account set: the bridge owns rotation and affinity. */
"oauth-account-pool",
/** Caller `anthropic-beta` values outside the native lane's allowlist were not forwarded. */
"anthropic-beta-dropped",
/** Thinking signatures or `redacted_thinking` removed for a destination that cannot verify them. */
"opaque-state-stripped",
/** Claude Code's typed Advisor tool was not forwarded: the proxy Advisor's synthetic `advisor` owns the name this turn. */
"advisor-tool-shadowed-by-proxy-advisor",
/** A typed Advisor declaration named a model outside the caller's admission scope and was not forwarded. */
"advisor-tool-outside-model-scope",
/** The request enforces token spend ceilings, so the separately unaccounted hosted Advisor was withheld. */
"advisor-tool-withheld-by-spend-policy",
] as const;
export type ProtocolReasonCode = (typeof PROTOCOL_REASON_CODES)[number];
const PROTOCOL_SET = new Set<string>(PROTOCOLS);
const UPSTREAM_SET = new Set<string>(UPSTREAM_WIRES);
const HOP_SET = new Set<string>(PROTOCOL_HOPS);
const MODE_SET = new Set<string>(DELIVERY_MODES);
const FIDELITY_SET = new Set<string>(FIDELITIES);
const REASON_SET = new Set<string>(PROTOCOL_REASON_CODES);
export function isProtocol(value: unknown): value is Protocol {
return typeof value === "string" && PROTOCOL_SET.has(value);
}
export function isUpstreamWire(value: unknown): value is UpstreamWire {
return typeof value === "string" && UPSTREAM_SET.has(value);
}
export function isProtocolHop(value: unknown): value is ProtocolHop {
return typeof value === "string" && HOP_SET.has(value);
}
export function isDeliveryMode(value: unknown): value is DeliveryMode {
return typeof value === "string" && MODE_SET.has(value);
}
export function isFidelity(value: unknown): value is Fidelity {
return typeof value === "string" && FIDELITY_SET.has(value);
}
export function isProtocolReasonCode(value: unknown): value is ProtocolReasonCode {
return typeof value === "string" && REASON_SET.has(value);
}
/** The routing-layer spelling (`InboundWire` in `src/providers/registry/types.ts`). */
export type InboundWireSpelling = "responses" | "chat" | "anthropic";
export function protocolFromInboundWire(wire: InboundWireSpelling): Protocol {
return wire === "anthropic" ? "messages" : wire;
}
export function inboundWireForProtocol(protocol: Protocol): InboundWireSpelling {
return protocol === "messages" ? "anthropic" : protocol;
}
/** Lab protocol identities (`src/lab/conformance/fixtures/*`) to the public vocabulary. */
export function protocolFromLabProtocol(identity: string): Protocol | undefined {
switch (identity) {
case "openai-responses":
return "responses";
case "openai-chat":
return "chat";
case "anthropic-messages":
return "messages";
default:
return undefined;
}
}
export function labProtocolForProtocol(protocol: Protocol): string {
switch (protocol) {
case "responses":
return "openai-responses";
case "chat":
return "openai-chat";
case "messages":
return "anthropic-messages";
}
}
/**
* The upstream wire a provider adapter id speaks. Only the three adapters whose request body
* is one of the public protocols map to a protocol; every other adapter is `other`.
*/
export function upstreamWireForAdapter(adapter: string): UpstreamWire {
switch (adapter) {
case "openai-responses":
return "responses";
case "openai-chat":
return "chat";
case "anthropic":
return "messages";
default:
return "other";
}
}
/**
* The wire-producing nodes of a path: `ir` is dropped and `responses-internal` counts as
* Responses, because a feature lost in an internal Responses body is lost all the same.
*/
export function protocolNodes(path: readonly ProtocolHop[]): UpstreamWire[] {
const nodes: UpstreamWire[] = [];
for (const hop of path) {
if (hop === "ir") continue;
const node: UpstreamWire = hop === "responses-internal" ? "responses" : hop;
if (nodes[nodes.length - 1] !== node) nodes.push(node);
}
return nodes;
}
/** Mode implied by a request path. `blocked` is never implied; a refusal has no path. */
export function deliveryModeForPath(path: readonly ProtocolHop[]): Exclude<DeliveryMode, "blocked"> {
if (path.includes("responses-internal")) return "legacy-bridge";
const first = path[0];
const last = path[path.length - 1];
return path.length === 2 && first === last && first !== "other" ? "native" : "translated";
}