@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
201 lines (187 loc) • 8.06 kB
text/typescript
/**
* The protocol planner: given a snapshot of what the router settled, predict the path each
* candidate would take, what it does to the request's features, and whether it would be
* refused under the unrepresentable policy.
*
* LEAF MODULE (see `contract.ts`) and PURE. The planner never selects a provider and never
* reads config; `plan-snapshot.ts` builds its input on the server. Paths come from
* `path.ts`, the same rule the observed trace uses, so a preview and the log of the same
* request cannot disagree about how a lane maps to hops. Settings and surfaces are taken
* structurally rather than imported from `settings.ts`, which reads config types and is
* therefore not a leaf.
*/
import { PROTOCOL_CONTRACT_VERSION, upstreamWireForAdapter, type Protocol, type ProtocolReasonCode } from "./contract";
import {
PROTOCOL_DTO_LIMITS,
PROTOCOL_PLAN_SCHEMA_VERSION,
type ProtocolPlanCandidateV1,
type ProtocolPlanV1,
} from "./dto";
import { featureEffectsForPath, PROTOCOL_FEATURES, unrepresentableFeatures, type ProtocolFeature } from "./features";
import { deliveryModeForLane, requestPathForLane, responsePathForLane, type ProtocolLane } from "./path";
/** One settled route target, as the server resolved it. */
export interface ProtocolPlanCandidateInput {
provider: string;
model: string;
/** Final adapter id after the wire override for this inbound. */
adapter: string;
/** True when the ingress would send its own wire to this candidate. */
nativeEligible: boolean;
/**
* True when the ingress would decode its own wire straight into the IR for this candidate (the
* Antigravity direct lane). Only meaningful toward an `other` upstream; `path.ts` ignores it
* anywhere else.
*/
directEligible?: boolean;
/** Why the ingress declined its native lane, when it did. */
declineReasons: readonly ProtocolReasonCode[];
}
export interface ProtocolPlanInput {
inbound: Protocol;
requestedModel: string;
routeKind: ProtocolPlanV1["routeKind"];
candidates: readonly ProtocolPlanCandidateInput[];
features: readonly ProtocolFeature[];
surfaces: Readonly<Record<Protocol, { readonly enabled: boolean }>>;
settings: { readonly unrepresentable: "legacy" | "reject" };
policyRevision: string;
basis: ProtocolPlanV1["basis"];
/** Plan-level reasons the snapshot observed, such as `caller-credential-required`. */
reasonCodes?: readonly ProtocolReasonCode[];
}
function bounded(codes: Iterable<ProtocolReasonCode>): ProtocolReasonCode[] {
return [...new Set(codes)].slice(0, PROTOCOL_DTO_LIMITS.reasonCodes);
}
function orderedFeatures(features: Iterable<ProtocolFeature>): ProtocolFeature[] {
const present = new Set(features);
return PROTOCOL_FEATURES.filter(feature => present.has(feature));
}
function blockedCandidate(candidate: ProtocolPlanCandidateInput, reason: ProtocolReasonCode): ProtocolPlanCandidateV1 {
return {
provider: candidate.provider,
model: candidate.model,
adapter: candidate.adapter,
upstream: upstreamWireForAdapter(candidate.adapter),
mode: "blocked",
requestPath: [],
responsePath: [],
fidelity: "unknown",
reasonCodes: [reason],
featureEffects: [],
unknownFeatures: [],
eligible: false,
};
}
function planCandidate(
input: ProtocolPlanInput,
candidate: ProtocolPlanCandidateInput,
features: readonly ProtocolFeature[],
): ProtocolPlanCandidateV1 {
const upstream = upstreamWireForAdapter(candidate.adapter);
// A native lane only exists toward the ingress's own wire; an inconsistent snapshot must
// not produce a path that claims the source body reached a different wire untouched.
const lane: ProtocolLane = candidate.nativeEligible && upstream === input.inbound
? "native"
: candidate.directEligible === true ? "direct" : "bridge";
const requestPath = requestPathForLane(input.inbound, lane, upstream);
const responsePath = responsePathForLane(input.inbound, lane, upstream);
const mode = deliveryModeForLane(input.inbound, lane, upstream);
const effects = featureEffectsForPath(input.inbound, requestPath, features);
const eligible = input.settings.unrepresentable !== "reject" || unrepresentableFeatures(effects.effects).length === 0;
const reasons: ProtocolReasonCode[] = [];
if (mode === "native") reasons.push("same-wire-native");
else if (mode === "translated") reasons.push(requestPath.length === 2 ? "cross-wire-codec" : "cross-wire-ir");
else reasons.push("not-migrated");
if (upstream === "other") reasons.push("upstream-other");
// Why the native lane was declined matters only where a native lane could exist: toward a
// different wire the path reason above already says it.
if (lane === "bridge" && input.inbound !== "responses" && upstream === input.inbound) {
reasons.push(...candidate.declineReasons);
}
if (!eligible) reasons.push("feature-unrepresentable");
return {
provider: candidate.provider,
model: candidate.model,
adapter: candidate.adapter,
upstream,
mode,
requestPath,
responsePath,
fidelity: effects.fidelity,
reasonCodes: bounded(reasons),
featureEffects: effects.effects.map(effect => ({ feature: effect.feature, disposition: effect.disposition })),
unknownFeatures: effects.unknown,
eligible,
};
}
/** Features preserved (passthrough or translated) by every / by only some eligible candidates. */
function featureSplit(
eligible: readonly ProtocolPlanCandidateV1[],
features: readonly ProtocolFeature[],
): { guaranteed: ProtocolFeature[]; partial: ProtocolFeature[] } {
const guaranteed: ProtocolFeature[] = [];
const partial: ProtocolFeature[] = [];
if (eligible.length === 0) return { guaranteed, partial };
for (const feature of features) {
let preserved = 0;
for (const candidate of eligible) {
const effect = candidate.featureEffects.find(entry => entry.feature === feature);
if (effect && (effect.disposition === "passthrough" || effect.disposition === "translated")) preserved++;
}
if (preserved === eligible.length) guaranteed.push(feature);
else if (preserved > 0) partial.push(feature);
}
return { guaranteed, partial };
}
export function planProtocol(input: ProtocolPlanInput): ProtocolPlanV1 {
const features = orderedFeatures(input.features);
const snapshotCandidates = input.candidates.slice(0, PROTOCOL_DTO_LIMITS.candidates);
const base = {
schemaVersion: PROTOCOL_PLAN_SCHEMA_VERSION,
basis: input.basis,
contractVersion: PROTOCOL_CONTRACT_VERSION,
policyRevision: input.policyRevision,
inbound: input.inbound,
requestedModel: input.requestedModel,
routeKind: input.routeKind,
} as const;
if (!input.surfaces[input.inbound].enabled) {
return {
...base,
mode: "blocked",
reasonCodes: ["surface-disabled"],
candidates: snapshotCandidates.map(candidate => blockedCandidate(candidate, "surface-disabled")),
guaranteedFeatures: [],
partialFeatures: [],
};
}
if (input.routeKind === "unknown" || snapshotCandidates.length === 0) {
return {
...base,
mode: "blocked",
reasonCodes: bounded([...(input.reasonCodes ?? []), "unknown-model"]),
candidates: [],
guaranteedFeatures: [],
partialFeatures: [],
};
}
const candidates = snapshotCandidates.map(candidate => planCandidate(input, candidate, features));
const eligible = candidates.filter(candidate => candidate.eligible);
const first = eligible[0];
const { guaranteed, partial } = featureSplit(eligible, features);
const routeReasons: ProtocolReasonCode[] = input.routeKind === "combo" || input.routeKind === "policy"
? ["combo-or-policy-route"]
: [];
return {
...base,
mode: first ? first.mode : "blocked",
reasonCodes: bounded([
...(input.reasonCodes ?? []),
...routeReasons,
...(first ? first.reasonCodes : ["feature-unrepresentable" as const]),
]),
candidates,
guaranteedFeatures: guaranteed,
partialFeatures: partial,
};
}