UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

160 lines (144 loc) • 8.23 kB
/** * Protocol vocabulary and request-path preview for the dashboard. * * Loaded on demand from src/server/management-api.ts, like the other optional namespaces: * the planner reaches the router and the ingress eligibility rules, and a static import * would put them on every dashboard request. * * GET (optionally with `?provider=<name>`, src/protocols/provider-summary.ts) and the plan * preview are read-only. The preview is computed from config alone * (src/protocols/plan-snapshot.ts): it sends nothing upstream, advances no combo state, and * never logs its input. PATCH /api/protocols/settings is the one writer; it validates in * src/server/management/protocol-settings-patch.ts, persists through the locked * saveConfigPreservingClaudeCode, and answers with the fresh GET shape. Authentication is * inherited from the management chain. */ import { jsonResponse } from "../auth-cors"; import { isProtocol, PROTOCOL_CONTRACT_VERSION } from "../../protocols/contract"; import { isProtocolFeature, PROTOCOL_FEATURES, type ProtocolFeature } from "../../protocols/features"; import { previewProtocolPlan, type ProtocolPlanRequest } from "../../protocols/plan-snapshot"; import { buildProtocolProviderSummary } from "../../protocols/provider-summary"; import { protocolPolicyRevision, resolveApiSurfaceSettings, resolveProtocolSettings } from "../../protocols/settings"; import type { OcxConfig } from "../../types"; import type { ManagementContext } from "./context"; import { readManagementJsonBodyOr } from "./body"; import { applyProtocolSettingsPatch, parseProtocolSettingsPatch, restoreProtocolSettings, snapshotProtocolSettings, } from "./protocol-settings-patch"; export const PROTOCOL_PLAN_LIMITS = { modelLength: 200, features: 24 } as const; export const PROTOCOL_PROVIDER_QUERY_LIMIT = 200; const PLAN_BODY_KEYS = new Set(["model", "inbound", "features"]); const INVALID_BODY = Symbol("invalid-body"); type ParsedPlanBody = { ok: true; request: ProtocolPlanRequest } | { ok: false; code: string; message: string }; function invalid(code: string, message: string): ParsedPlanBody { return { ok: false, code, message }; } /** Validate a plan request body. Messages name the field, never echo its value. */ export function parseProtocolPlanBody(body: unknown): ParsedPlanBody { if (!body || typeof body !== "object" || Array.isArray(body)) return invalid("invalid_body", "body must be a JSON object"); const record = body as Record<string, unknown>; for (const key of Object.keys(record)) { if (!PLAN_BODY_KEYS.has(key)) return invalid("unknown_field", "body accepts only model, inbound and features"); } const model = typeof record.model === "string" ? record.model.trim() : ""; if (!model || model.length > PROTOCOL_PLAN_LIMITS.modelLength || /[\u0000-\u001f\u007f]/.test(model)) { return invalid("invalid_model", `model must be a non-empty string of at most ${PROTOCOL_PLAN_LIMITS.modelLength} characters`); } if (!isProtocol(record.inbound)) return invalid("invalid_inbound", "inbound must be responses, chat or messages"); let features: ProtocolFeature[] = []; if (record.features !== undefined) { if (!Array.isArray(record.features) || record.features.length > PROTOCOL_PLAN_LIMITS.features) { return invalid("invalid_features", `features must be an array of at most ${PROTOCOL_PLAN_LIMITS.features} entries`); } if (!record.features.every(isProtocolFeature)) return invalid("invalid_features", "features contains an unknown feature"); features = [...new Set(record.features)]; } return { ok: true, request: { model, inbound: record.inbound, features } }; } function protocolInfo(config: OcxConfig) { return { schemaVersion: 1, contractVersion: PROTOCOL_CONTRACT_VERSION, policyRevision: protocolPolicyRevision(config), surfaces: resolveApiSurfaceSettings(config), settings: resolveProtocolSettings(config), features: PROTOCOL_FEATURES, }; } /** * `GET /api/protocols?provider=<name>`: the usual body plus the provider's wire summary. The * name is bounded and must name a configured provider; neither error echoes it back. */ function protocolInfoForProvider(ctx: ManagementContext, values: string[]): Response { const { req, config } = ctx; const name = values.length === 1 ? values[0]!.trim() : ""; if (!name || name.length > PROTOCOL_PROVIDER_QUERY_LIMIT || /[\u0000-\u001f\u007f]/.test(name)) { const message = `provider must be one non-empty name of at most ${PROTOCOL_PROVIDER_QUERY_LIMIT} characters`; return jsonResponse({ error: { code: "invalid_provider", message } }, 400, req, config); } const provider = buildProtocolProviderSummary(config, name); if (!provider) return jsonResponse({ error: { code: "unknown_provider", message: "no provider with that name" } }, 404, req, config); return jsonResponse({ ...protocolInfo(config), provider }, 200, req, config); } /** Only SQLITE_BUSY is contention worth retrying; any other lock failure repeats forever. */ function isConfigLockContention(error: unknown): boolean { if (!error || typeof error !== "object") return false; if ((error as { code?: unknown }).code !== "CONFIG_MUTATION_LOCK_UNAVAILABLE") return false; return (error as { cause?: { code?: unknown } }).cause?.code === "SQLITE_BUSY"; } async function patchProtocolSettings(ctx: ManagementContext): Promise<Response> { const { req, config } = ctx; const body = await readManagementJsonBodyOr(req, INVALID_BODY); const parsed = body === INVALID_BODY ? { ok: false as const, code: "invalid_json", message: "body must be valid JSON" } : parseProtocolSettingsPatch(body); if (!parsed.ok) return jsonResponse({ error: { code: parsed.code, message: parsed.message } }, 400, req, config); const snapshot = snapshotProtocolSettings(config); const applied = applyProtocolSettingsPatch(config, parsed.patch); if (!applied.ok) { restoreProtocolSettings(config, snapshot); return jsonResponse({ error: { code: applied.code, message: applied.message } }, 400, req, config); } // `deps.` first: route tests with an in-memory fixture must never write the real config. const persist = ctx.deps.saveConfigPreservingClaudeCode ?? (await import("../../config")).saveConfigPreservingClaudeCode; try { persist(config); } catch (error) { // Undo in memory too: a live config that serves a state the file does not hold would // reopen (or keep closed) the surface only until the next restart. restoreProtocolSettings(config, snapshot); return isConfigLockContention(error) ? jsonResponse({ error: { code: "config_busy", message: "Another process is saving the configuration. Try again in a moment." } }, 409, req, config) : jsonResponse({ error: { code: "write_failed", message: "The configuration could not be saved." } }, 500, req, config); } // Closing Messages also turned the Claude integration off; prune its agent definitions the // way the Claude page toggle does. if (applied.claudeCodeChanged) await ctx.syncClaudeAgentDefsBestEffort?.(); return jsonResponse(protocolInfo(config), 200, req, config); } export async function handleProtocolRoutes(ctx: ManagementContext): Promise<Response | null> { const { url, req, config } = ctx; if (url.pathname === "/api/protocols") { if (req.method !== "GET") return null; if (!url.searchParams.has("provider")) return jsonResponse(protocolInfo(config), 200, req, config); return protocolInfoForProvider(ctx, url.searchParams.getAll("provider")); } if (url.pathname === "/api/protocols/settings") { if (req.method !== "PATCH") return null; return patchProtocolSettings(ctx); } if (url.pathname === "/api/protocols/plan") { if (req.method !== "POST") return null; const body = await readManagementJsonBodyOr(req, INVALID_BODY); const parsed = body === INVALID_BODY ? invalid("invalid_json", "body must be valid JSON") : parseProtocolPlanBody(body); if (!parsed.ok) { return jsonResponse({ error: { code: parsed.code, message: parsed.message } }, 400, req, config); } return jsonResponse(previewProtocolPlan(config, parsed.request), 200, req, config); } return null; }