@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
294 lines (278 loc) • 12.7 kB
text/typescript
// Shared client export contracts.
import type { ExportClientId } from "../client-ids";
export type { ExportClientId } from "../client-ids";
import { canonicalizeReasoningEfforts } from "../../reasoning-effort";
import type { OcxConfig } from "../../types";
import type { ConfigFormat } from "../../integrations/serialize";
import type { ExportModelNames } from "./model-names";
export const DROID_DEFAULT_EFFORT_HEADER = "x-opencodex-droid-default-effort";
/**
* One entry opencodex owns inside a client's config: the JSON path to it and
* the value we put there.
*
* A path list rather than a single provider key because ownership is not
* always one entry — Kimi owns its provider block AND one model entry per
* model, and a writer that only knew about the provider would strand the rest
* (devlog 260802 006 §2).
*/
export interface ManagedFragment {
path: readonly string[];
value: unknown;
}
/** Everything opencodex contributes to one client's config, as one unit. */
export interface ManagedContribution {
clientId: ExportClientId;
fragments: readonly ManagedFragment[];
}
export type BuildContribution = (ctx: ExportContext) => ManagedContribution;
export interface OpencodeLaunchEnv {
[key: string]: string | undefined;
}
/** Visible catalog entry keyed by the proxy's canonical namespaced selector. */
export interface OpencodeCatalogModel {
namespaced: string;
/** Hub-resolved Fast availability. Missing metadata means unavailable. */
fastRowAvailable?: boolean;
native?: boolean;
provider?: string;
id?: string;
contextWindow?: number;
maxTokens?: number;
/**
* Authoritative input ceiling, distinct from `contextWindow` (GPT-5.6 advertises 922k
* usable input under a 1.05M window). Carried from the catalog row so a client that has a
* separate input limit never treats the whole window as prompt budget.
*/
maxInputTokens?: number;
displayName?: string;
/**
* Declared input modalities, carried verbatim from `/api/models`. Serialized as opencode's
* per-model `attachment` + `modalities`, because opencode gates attachments CLIENT-side:
* without them every `opencodex` model is text-only in its picker and an image never
* reaches the proxy or the vision sidecar (#4286).
*/
inputModalities?: readonly string[];
/** Declared effort ladder. Exported as opencode model variants where the client reads them. */
reasoningEfforts?: readonly string[];
supportsThinkingToggle?: boolean;
supportsReasoningEffort?: boolean;
defaultThinkingEnabled?: boolean;
/**
* Declared default effort. Carried so every client export reads one deduped, visibility-
* filtered ladder per model. Client serializers map it into their own model defaults
* and allow the selected variant to override it.
*/
defaultReasoningEffort?: string;
supportsTools?: boolean;
supportsReasoning?: boolean;
supportsReasoningSummaries?: boolean;
}
/**
* One proxy-routed model destined for a client config. Deliberately narrower than
* `CatalogModel` so a serializer cannot reach for a field that does not survive the
* `/api/models` boundary.
*/
export interface ExportModel {
/** Canonical proxy selector: `provider/id`, or bare slug for native. */
namespaced: string;
/** Provider-qualified alias proven equivalent by the shared management row loader. */
aliasNamespaced?: string;
/** Raw nested upstream selector the serving proxy proved equivalent (#8172); Pi only. */
nestedNamespaced?: string;
/** Hub-resolved Fast availability; exporters never infer it from local config. */
fastRowAvailable?: boolean;
provider: string;
id: string;
/** Native OpenAI entry. Read by the shared label rule. */
native?: boolean;
displayName?: string;
contextWindow?: number;
maxTokens?: number;
/** Authoritative input ceiling; optional and never guessed from the context window. */
maxInputTokens?: number;
inputModalities?: string[];
/** Optional effort ladder exported only to clients that support it. */
reasoningEfforts?: string[];
supportsThinkingToggle?: boolean;
supportsReasoningEffort?: boolean;
defaultThinkingEnabled?: boolean;
defaultReasoningEffort?: string;
supportsTools?: boolean;
supportsReasoning?: boolean;
supportsReasoningSummaries?: boolean;
}
/**
* Effective, override-applied export metadata for one model row: what a client export should
* serialize, as distinct from the raw editor representation `/api/models` also carries.
*
* Custom rows are the reason this exists. Their row fields are the operator's stored
* OVERRIDES (an absent field means "not overridden", an empty ladder means "no rungs"), so a
* serializer reading only them drops every capability the model inherits from the provider,
* the registry, or the gathered catalog. The management row list resolves that projection
* from the same canonical sources routed rows use and attaches it additively — the raw
* override fields stay exactly what the editor wrote.
*/
export interface EffectiveModelExportMetadata {
contextWindow?: number;
/** Input ceiling; distinct from `contextWindow`, carried only when a source asserts one. */
maxInputTokens?: number;
/** Output ceiling (a catalog row's `maxOutputTokens`). */
maxTokens?: number;
inputModalities?: string[];
/** Effective ladder; `[]` is an explicit "no rungs" declaration and survives as `[]`. */
reasoningEfforts?: string[];
supportsThinkingToggle?: boolean;
supportsReasoningEffort?: boolean;
defaultThinkingEnabled?: boolean;
/**
* A default some canonical source declared — never one synthesized from the ladder's
* preference order, and only when it is a member of the effective ladder. An empty
* ladder suppresses it entirely: there is no rung to default to.
*/
defaultReasoningEffort?: string;
supportsTools?: boolean;
supportsReasoning?: boolean;
supportsReasoningSummaries?: boolean;
}
/**
* Canonical explicit capabilities and positive evidence for otherwise unknown booleans.
* No independent provider fact tables or name-based inference.
*/
export interface ExportCapabilityEvidence {
native?: boolean;
supportsReasoning?: boolean;
supportsThinkingToggle?: boolean;
supportsReasoningEffort?: boolean;
reasoningEfforts?: readonly string[];
supportsReasoningSummaries?: boolean;
/** Normalized upstream capability names a catalog row carried (e.g. `"tools"`). */
capabilities?: readonly string[];
/** Provider-level parallel tool call opt-in for this model. */
parallelToolCalls?: boolean;
}
/**
* Tool support a canonical source positively asserts, or undefined when nothing is known.
*
* Mirrors the routing reader (`src/routing/capability.ts`): a catalog row without `"tools"`
* is UNKNOWN, never a negative — the row may simply not enumerate capabilities. `native`
* rows and the parallel-call opt-in are positive evidence on their own.
*/
export function knownToolsSupport(evidence: ExportCapabilityEvidence): boolean | undefined {
if (evidence.native === true) return true;
if (evidence.capabilities?.includes("tools") === true) return true;
if (evidence.parallelToolCalls === true) return true;
return undefined;
}
/**
* Explicit reasoning support, or positive canonical evidence when no boolean is declared.
*
* Never `false` from a missing or empty effort ladder: an empty ladder says "no ADJUSTABLE
* effort", which is not the claim "cannot reason" — a model can reason at a fixed depth with
* no rung to select. Known evidence is a positive reasoning rung (the catalog's own statement
* that the model accepts reasoning parameters) or delivered reasoning summaries. `none` is
* the off sentinel, not a rung: a ladder of only `none` offers an off variant and asserts
* nothing about whether the model reasons, so it is not positive evidence on its own.
*/
export function knownReasoningSupport(evidence: ExportCapabilityEvidence): boolean | undefined {
if (typeof evidence.supportsReasoning === "boolean") return evidence.supportsReasoning;
if (evidence.supportsThinkingToggle === true || evidence.supportsReasoningEffort === true) return true;
if (evidence.supportsReasoningSummaries === true) return true;
if (evidence.supportsReasoningEffort !== false && evidence.reasoningEfforts !== undefined
&& canonicalizeReasoningEfforts(evidence.reasoningEfforts).some(effort => effort !== "none")) {
return true;
}
return undefined;
}
export interface ExportContext {
modelNames?: ExportModelNames;
/** `http://host:port/v1` — the OpenAI-compatible surface the client dials. */
baseUrl: string;
models: readonly ExportModel[];
/**
* Live proxy config. Only the OpenCode path reads it: a non-loopback bind moves
* admission from `apiKey` to the `x-opencodex-api-key` header.
*/
config?: OcxConfig;
droidReasoningDefaults?: DroidReasoningDefaults;
/**
* The parsed target document, when the caller has one in hand.
*
* A client whose reader picks between two roots needs the bytes on disk to
* choose: Command Code resolves `document.provider ?? document.providers`, so
* writing the singular root into a document that already carries the plural one
* leaves the user's providers unreadable rather than merging with them. Absent
* for `ocx export`, which has no target file — the builder then writes its
* default root, exactly as before.
*/
document?: unknown;
}
/** Namespaced model selector to one of that model's declared reasoning efforts. */
export type DroidReasoningDefaults = Record<string, string>;
export interface ExportClientSpec {
id: ExportClientId;
/** Download filename; matches the destination file's own name (003 §5). */
filename: string;
/** Canonical destination for humans. Never written to. */
destination: (env: NodeJS.ProcessEnv) => string;
/** Env var the config references; the value is never serialized. */
apiKeyEnv: string;
/** Shell line the user runs before launching the client. */
exportHint: string;
build: (ctx: ExportContext) => unknown;
/**
* Text format of the client's config file. `filename` already carries the
* extension; this drives serialization and the download media type so no
* consumer has to infer either from the name.
*/
format: ConfigFormat;
/**
* Count models in THIS client's document shape. Required so a new client
* cannot be added without teaching the summarizer about it — the old
* "anything that is not OpenCode must be Pi" branch was a latent bug.
*/
summarize: (document: unknown) => { modelCount: number; modelsWithoutLimits: number };
/**
* The fragments opencodex owns inside this client's config. Only the builder
* knows where a client keeps our entries, so ownership paths originate here
* rather than being re-derived by the writer.
*/
buildContribution: BuildContribution;
/**
* True when the generated integration deliberately supports loopback only.
*
* `/v1/chat/completions` rejects bearer credentials and requires the
* dedicated `x-opencodex-api-key` header (AUTH_MATRIX in
* src/server/auth-cors.ts). If this exporter cannot safely emit that header,
* it refuses a remote bind rather than generating a config that 401s. Same
* reasoning as the Grok managed block's non-loopback refusal.
*/
loopbackOnly: boolean;
/** Refuse apply/refresh without blocking status, disable or Undo. Pure and value-free. */
validateApply?: (ctx: ExportContext) => string | null;
/**
* True when the destination file may carry comments and trailing commas
* even though `format` is "json" and serialization stays pretty JSON.
*
* Parse tolerates them by canonicalizing the text before the rewrite-safety
* scan (Kilo's kilo.jsonc). A spec flag rather than a client-name branch:
* the next OpenCode-family client opts in here instead of growing another
* `clientId ===` check at every parse site.
*/
jsonc?: boolean;
}
export interface PiModelEntry {
id: string;
name: string;
input: string[];
contextWindow?: number;
maxTokens?: number;
/** Advertised when the catalog row carries a non-empty effort ladder. */
reasoning?: true;
/**
* Constrains pi's own level scale (minimal..max) to the declared ladder: members map to
* themselves, everything else is hidden (`null`). Without it pi would offer levels the
* ladder does not contain — harmless for provider-config ladders (the proxy clamps those
* at the wire) but a real 400 risk for custom-row ladders, which are advertisement-only.
*/
thinkingLevelMap?: Record<string, string | null>;
}