@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
179 lines (168 loc) • 6.46 kB
text/typescript
// Shared client export contracts.
import type { OcxConfig } from "../../types";
import type { ConfigFormat } from "../../integrations/serialize";
/**
* 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;
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[];
/**
* Declared default effort. Carried so every client export reads one deduped, visibility-
* filtered ladder per model. The opencode serializer deliberately does NOT turn it into a
* model-level setting — see {@link opencodeEffortVariants} for why.
*/
defaultReasoningEffort?: string;
}
/**
* 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;
/** 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;
inputModalities?: string[];
/** Optional effort ladder exported only to clients that support it. */
reasoningEfforts?: string[];
defaultReasoningEffort?: string;
}
export interface ExportContext {
/** `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;
}
export type ExportClientId =
| "opencode"
| "pi"
| "omp"
| "hermes"
| "openclaw"
| "kimi"
| "gajae"
| "dsh"
| "mcode"
| "zcode"
| "prime"
| "aside"
| "raycast"
| "omo"
| "cline"
| "kilo"
| "droid";
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;
/**
* 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>;
}