UNPKG

@bitkyc08/opencodex

Version:

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

598 lines (546 loc) • 23.3 kB
import { createHash } from "node:crypto"; import { namespacedToolName, toolChoiceToolPredicate, type OcxParsedRequest, type OcxTool, type OcxToolChoice, } from "../../types"; import { stripResponsesOnlyEncryptedMarker } from "../responses-tool-schema"; export const CODEBUDDY_MCP_SERVER_NAME = "opencodex"; export const CODEBUDDY_MCP_TOOL_PREFIX = `mcp__${CODEBUDDY_MCP_SERVER_NAME}__`; // These caps protect both the request path and the isolated MCP process. They sit // below the adapter's 4 MiB total prompt cap so a maximal tool catalog cannot // crowd the transcript and system prompt out of the request budget. export const CODEBUDDY_TOOL_LIMITS = Object.freeze({ maxTools: 128, // Captured tool_use blocks accepted in a single assistant turn. Kimi emits // parallel calls as sibling content blocks of one assistant message, all // streamed before message_stop; the capture-only MCP handler never returns, // so every block must be observed before the parent terminates the turn. // Each captured call is fully buffered under the per-call translator // budget, so this bound also caps per-turn capture memory. maxTurnToolCalls: 16, maxNameBytes: 512, maxDescriptionBytes: 64 * 1024, maxSchemaBytes: 224 * 1024, maxToolBytes: 256 * 1024, maxCatalogBytes: 2 * 1024 * 1024, maxSchemaDepth: 32, maxSchemaNodes: 4_096, maxPatternBytes: 8 * 1024, }); // CodeBuddy renders MCP tools as `mcp__<server>__<tool>`. Keep the complete // rendered name comfortably below the common 64-character function-name limit. const MAX_CODEBUDDY_TOOL_ALIAS_CHARS = 40; const CODEBUDDY_TOOL_ALIAS_HASH_CHARS = 16; const CODEBUDDY_TOOL_ALIAS_PATTERN = /^[A-Za-z0-9_-]+$/; const INVALID_TOOL_NAME_PATTERN = /[\s\u0000-\u001f\u007f]/u; const INVALID_DESCRIPTION_CONTROL_PATTERN = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/u; const JSON_SCHEMA_TYPES = new Set(["array", "boolean", "integer", "null", "number", "object", "string"]); const SCHEMA_MAP_KEYWORDS = [ "properties", "patternProperties", "$defs", "definitions", "dependentSchemas", ] as const; const SCHEMA_VALUE_KEYWORDS = [ "additionalItems", "additionalProperties", "contains", "contentSchema", "else", "if", "not", "propertyNames", "then", "unevaluatedItems", "unevaluatedProperties", ] as const; const SCHEMA_ARRAY_KEYWORDS = ["allOf", "anyOf", "oneOf", "prefixItems"] as const; const NON_NEGATIVE_INTEGER_KEYWORDS = [ "maxContains", "maxItems", "maxLength", "maxProperties", "minContains", "minItems", "minLength", "minProperties", ] as const; const FINITE_NUMBER_KEYWORDS = [ "exclusiveMaximum", "exclusiveMinimum", "maximum", "minimum", ] as const; const STRING_KEYWORDS = [ "$anchor", "$comment", "$id", "$schema", "$dynamicAnchor", "contentEncoding", "contentMediaType", "description", "format", "title", ] as const; const BOOLEAN_KEYWORDS = ["deprecated", "nullable", "readOnly", "uniqueItems", "writeOnly"] as const; const textEncoder = new TextEncoder(); export interface CodeBuddyMcpToolDefinition { name: string; description: string; inputSchema: Record<string, unknown>; } export interface CodeBuddyToolBridge { tools: CodeBuddyMcpToolDefinition[]; /** Exact nested-CLI-emitted MCP name -> Responses wire name. */ emittedNameMap: Map<string, string>; requireToolCall: boolean; } interface PreparedTool { source: OcxTool; wireName: string; description: string; inputSchema: Record<string, unknown>; } interface JsonCloneState { active: WeakSet<object>; nodes: number; } function utf8Bytes(value: string): number { return textEncoder.encode(value).byteLength; } function serializedBytes(value: unknown): number { return utf8Bytes(JSON.stringify(value)); } function hasUnpairedSurrogate(value: string): boolean { for (let index = 0; index < value.length; index++) { const unit = value.charCodeAt(index); if (unit >= 0xd800 && unit <= 0xdbff) { const next = value.charCodeAt(index + 1); if (next < 0xdc00 || next > 0xdfff) return true; index += 1; } else if (unit >= 0xdc00 && unit <= 0xdfff) { return true; } } return false; } function isRecord(value: unknown): value is Record<string, unknown> { return value !== null && typeof value === "object" && !Array.isArray(value); } function defineDataProperty(target: Record<string, unknown>, key: string, value: unknown): void { // `__proto__` is a valid JSON Schema property name. Defining it as data keeps // it from invoking Object.prototype's legacy setter while retaining a normal // object prototype for downstream SDKs. Object.defineProperty(target, key, { configurable: true, enumerable: true, value, writable: true, }); } function invalidJson(reason: string): never { throw new Error(`invalid JSON value (${reason})`); } /** * Clone one schema into inert JSON data. A bounded recursive walk is safe here: * the depth check happens before descent, and the resulting maximum call depth * is fixed rather than attacker-controlled. */ function cloneBoundedJson(value: unknown, depth: number, state: JsonCloneState): unknown { if (depth > CODEBUDDY_TOOL_LIMITS.maxSchemaDepth) invalidJson("nesting is too deep"); state.nodes += 1; if (state.nodes > CODEBUDDY_TOOL_LIMITS.maxSchemaNodes) invalidJson("node count is too large"); if (value === null || typeof value === "boolean" || typeof value === "string") { if (typeof value === "string" && hasUnpairedSurrogate(value)) invalidJson("text contains an unpaired surrogate"); return value; } if (typeof value === "number") { if (!Number.isFinite(value)) invalidJson("numbers must be finite"); return value; } if (typeof value !== "object") invalidJson(`unsupported ${typeof value}`); const object = value as object; if (state.active.has(object)) invalidJson("cycles are not allowed"); state.active.add(object); try { if (Array.isArray(value)) { if (Object.getPrototypeOf(value) !== Array.prototype) invalidJson("arrays must use the built-in prototype"); if (value.length > CODEBUDDY_TOOL_LIMITS.maxSchemaNodes) invalidJson("array length is too large"); const keys = Reflect.ownKeys(value); for (const key of keys) { if (key === "length") continue; if (typeof key !== "string" || !/^(?:0|[1-9][0-9]*)$/.test(key)) { invalidJson("arrays may not have custom properties"); } const index = Number(key); if (!Number.isSafeInteger(index) || index < 0 || index >= value.length) { invalidJson("array index is invalid"); } const descriptor = Object.getOwnPropertyDescriptor(value, key); if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) { invalidJson("array entries must be enumerable data properties"); } } if (keys.length - 1 !== value.length) invalidJson("sparse arrays are not allowed"); return value.map(entry => cloneBoundedJson(entry, depth + 1, state)); } const prototype = Object.getPrototypeOf(value); if (prototype !== Object.prototype && prototype !== null) invalidJson("objects must be plain records"); const out: Record<string, unknown> = {}; for (const key of Reflect.ownKeys(value)) { if (typeof key !== "string") invalidJson("symbol keys are not allowed"); if (hasUnpairedSurrogate(key)) invalidJson("property name contains an unpaired surrogate"); const descriptor = Object.getOwnPropertyDescriptor(value, key); if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) { invalidJson("object fields must be enumerable data properties"); } defineDataProperty(out, key, cloneBoundedJson(descriptor.value, depth + 1, state)); } return out; } finally { state.active.delete(object); } } function invalidSchema(reason: string): never { throw new Error(reason); } function assertStringArray(value: unknown, keyword: string, allowEmpty = true): string[] { if (!Array.isArray(value) || (!allowEmpty && value.length === 0)) { invalidSchema(`${keyword} must be ${allowEmpty ? "an" : "a non-empty"} array of unique strings`); } const seen = new Set<string>(); for (const item of value) { if (typeof item !== "string" || seen.has(item)) { invalidSchema(`${keyword} must be ${allowEmpty ? "an" : "a non-empty"} array of unique strings`); } seen.add(item); } return value as string[]; } function assertSchema(value: unknown, keyword: string): void { if (typeof value === "boolean") return; if (!isRecord(value)) invalidSchema(`${keyword} must contain a JSON Schema`); validateSchema(value); } function validateSchemaMap(value: unknown, keyword: string, validatePatterns = false): void { if (!isRecord(value)) invalidSchema(`${keyword} must be an object of JSON Schemas`); for (const [name, schema] of Object.entries(value)) { if (validatePatterns) validatePattern(name, `${keyword} key`); assertSchema(schema, `${keyword}.${name}`); } } function validatePattern(value: unknown, keyword = "pattern"): void { if (typeof value !== "string" || utf8Bytes(value) > CODEBUDDY_TOOL_LIMITS.maxPatternBytes) { invalidSchema(`${keyword} must be a bounded regular-expression string`); } try { new RegExp(value, "u"); } catch { invalidSchema(`${keyword} is not a valid regular expression`); } } function validateSchema(schema: Record<string, unknown>): void { if (Object.hasOwn(schema, "type")) { const type = schema.type; if (typeof type === "string") { if (!JSON_SCHEMA_TYPES.has(type)) invalidSchema("type contains an unknown JSON Schema type"); } else { const types = assertStringArray(type, "type", false); if (types.some(candidate => !JSON_SCHEMA_TYPES.has(candidate))) { invalidSchema("type contains an unknown JSON Schema type"); } } } for (const keyword of SCHEMA_MAP_KEYWORDS) { if (Object.hasOwn(schema, keyword)) { validateSchemaMap(schema[keyword], keyword, keyword === "patternProperties"); } } for (const keyword of SCHEMA_VALUE_KEYWORDS) { if (Object.hasOwn(schema, keyword)) assertSchema(schema[keyword], keyword); } for (const keyword of SCHEMA_ARRAY_KEYWORDS) { if (!Object.hasOwn(schema, keyword)) continue; const value = schema[keyword]; if (!Array.isArray(value) || (keyword !== "prefixItems" && value.length === 0)) { invalidSchema(`${keyword} must be an array of JSON Schemas${keyword === "prefixItems" ? "" : " with at least one entry"}`); } for (const entry of value) assertSchema(entry, keyword); } if (Object.hasOwn(schema, "items")) { const items = schema.items; if (Array.isArray(items)) { for (const entry of items) assertSchema(entry, "items"); } else { assertSchema(items, "items"); } } if (Object.hasOwn(schema, "required")) assertStringArray(schema.required, "required"); if (Object.hasOwn(schema, "enum")) { if (!Array.isArray(schema.enum) || schema.enum.length === 0) invalidSchema("enum must be a non-empty array"); } if (Object.hasOwn(schema, "examples") && !Array.isArray(schema.examples)) { invalidSchema("examples must be an array"); } for (const keyword of NON_NEGATIVE_INTEGER_KEYWORDS) { if (!Object.hasOwn(schema, keyword)) continue; const value = schema[keyword]; if (!Number.isSafeInteger(value) || (value as number) < 0) { invalidSchema(`${keyword} must be a non-negative safe integer`); } } for (const keyword of FINITE_NUMBER_KEYWORDS) { if (!Object.hasOwn(schema, keyword)) continue; if (typeof schema[keyword] !== "number" || !Number.isFinite(schema[keyword])) { invalidSchema(`${keyword} must be a finite number`); } } if (Object.hasOwn(schema, "multipleOf")) { if (typeof schema.multipleOf !== "number" || !Number.isFinite(schema.multipleOf) || schema.multipleOf <= 0) { invalidSchema("multipleOf must be a finite number greater than zero"); } } for (const keyword of STRING_KEYWORDS) { if (Object.hasOwn(schema, keyword) && typeof schema[keyword] !== "string") { invalidSchema(`${keyword} must be a string`); } } for (const keyword of BOOLEAN_KEYWORDS) { if (Object.hasOwn(schema, keyword) && typeof schema[keyword] !== "boolean") { invalidSchema(`${keyword} must be a boolean`); } } if (Object.hasOwn(schema, "pattern")) validatePattern(schema.pattern); for (const keyword of ["$ref", "$dynamicRef"] as const) { if (!Object.hasOwn(schema, keyword)) continue; const ref = schema[keyword]; // External references hand resolution authority to the nested runtime and // can turn a data-only catalog into network or filesystem access. Local // JSON Pointer/anchor references retain recursive and reusable schemas. if (typeof ref !== "string" || !ref.startsWith("#")) { invalidSchema(`${keyword} must be a local fragment reference`); } } if (Object.hasOwn(schema, "$vocabulary")) { if (!isRecord(schema.$vocabulary)) invalidSchema("$vocabulary must be an object"); for (const enabled of Object.values(schema.$vocabulary)) { if (typeof enabled !== "boolean") invalidSchema("$vocabulary values must be booleans"); } } if (Object.hasOwn(schema, "dependentRequired")) { if (!isRecord(schema.dependentRequired)) invalidSchema("dependentRequired must be an object"); for (const [name, required] of Object.entries(schema.dependentRequired)) { assertStringArray(required, `dependentRequired.${name}`); } } if (Object.hasOwn(schema, "dependencies")) { if (!isRecord(schema.dependencies)) invalidSchema("dependencies must be an object"); for (const [name, dependency] of Object.entries(schema.dependencies)) { if (Array.isArray(dependency)) assertStringArray(dependency, `dependencies.${name}`); else assertSchema(dependency, `dependencies.${name}`); } } for (const [minimum, maximum] of [ ["minContains", "maxContains"], ["minItems", "maxItems"], ["minLength", "maxLength"], ["minProperties", "maxProperties"], ] as const) { if ( typeof schema[minimum] === "number" && typeof schema[maximum] === "number" && schema[minimum] > schema[maximum] ) { invalidSchema(`${minimum} must not exceed ${maximum}`); } } if ( typeof schema.minimum === "number" && typeof schema.maximum === "number" && schema.minimum > schema.maximum ) { invalidSchema("minimum must not exceed maximum"); } } function normalizeInputSchema(parameters: unknown): Record<string, unknown> { if (!isRecord(parameters)) invalidSchema("the root must be an object schema"); const cloned = cloneBoundedJson(parameters, 0, { active: new WeakSet(), nodes: 0 }); if (!isRecord(cloned)) invalidSchema("the root must be an object schema"); if (serializedBytes(cloned) > CODEBUDDY_TOOL_LIMITS.maxSchemaBytes) { throw new Error(`schema exceeds ${CODEBUDDY_TOOL_LIMITS.maxSchemaBytes} bytes`); } validateSchema(cloned); if (Object.hasOwn(cloned, "type") && cloned.type !== "object") { invalidSchema('the root type must be "object"'); } const stripped = stripResponsesOnlyEncryptedMarker(cloned); if (!isRecord(stripped)) invalidSchema("the root must remain an object schema"); if (!Object.hasOwn(stripped, "type")) stripped.type = "object"; if (serializedBytes(stripped) > CODEBUDDY_TOOL_LIMITS.maxSchemaBytes) { throw new Error(`schema exceeds ${CODEBUDDY_TOOL_LIMITS.maxSchemaBytes} bytes`); } return stripped; } function shortHash(value: string, salt = 0): string { return createHash("sha256") .update(salt === 0 ? value : `${value}\0${salt}`) .digest("hex") .slice(0, CODEBUDDY_TOOL_ALIAS_HASH_CHARS); } function directCodeBuddyAlias(wireName: string): string | undefined { return CODEBUDDY_TOOL_ALIAS_PATTERN.test(wireName) && wireName.length <= MAX_CODEBUDDY_TOOL_ALIAS_CHARS ? wireName : undefined; } /** * Produce a deterministic MCP-safe alias while retaining a readable prefix. * `used` closes both normalization and truncated-hash collision domains. */ export function codeBuddyToolAlias(wireName: string, used = new Set<string>()): string { const direct = directCodeBuddyAlias(wireName); if (direct && !used.has(direct)) { used.add(direct); return direct; } const cleaned = wireName.replace(/[^A-Za-z0-9_-]/g, "_"); const maxBaseChars = MAX_CODEBUDDY_TOOL_ALIAS_CHARS - CODEBUDDY_TOOL_ALIAS_HASH_CHARS - 1; const base = (cleaned || "tool").slice(0, maxBaseChars); for (let salt = 0; salt <= CODEBUDDY_TOOL_LIMITS.maxTools; salt++) { const candidate = `${base}_${shortHash(wireName, salt)}`; if (!used.has(candidate)) { used.add(candidate); return candidate; } } throw new Error("CodeBuddy could not allocate a collision-free tool alias."); } /** Reserve direct names before hashing and sort the rest so request ordering cannot change aliases. */ function codeBuddyToolAliases(wireNames: readonly string[]): Map<string, string> { const aliases = new Map<string, string>(); const used = new Set<string>(); for (const wireName of wireNames) { const direct = directCodeBuddyAlias(wireName); if (direct) { aliases.set(wireName, direct); used.add(direct); } } const hashedNames = wireNames.filter(wireName => !aliases.has(wireName)).sort(); for (const wireName of hashedNames) aliases.set(wireName, codeBuddyToolAlias(wireName, used)); return aliases; } function requiresToolCall(choice: OcxToolChoice | undefined): boolean { return choice === "required" || (typeof choice === "object" && choice !== null && ( "name" in choice || ("mode" in choice && choice.mode === "required") )); } function validateToolNamePart(value: unknown): value is string { return typeof value === "string" && value.length > 0 && !hasUnpairedSurrogate(value) && !INVALID_TOOL_NAME_PATTERN.test(value); } function prepareTool(tool: OcxTool, index: number, seenWireNames: Set<string>): PreparedTool { if (!tool || typeof tool !== "object") throw new Error(`CodeBuddy tool ${index + 1} is not an object.`); if (!validateToolNamePart(tool.name) || ( tool.namespace !== undefined && !validateToolNamePart(tool.namespace) )) { throw new Error(`CodeBuddy tool ${index + 1} has an invalid name or namespace.`); } const wireName = namespacedToolName(tool.namespace, tool.name); if (utf8Bytes(wireName) > CODEBUDDY_TOOL_LIMITS.maxNameBytes) { throw new Error(`CodeBuddy tool ${index + 1} name exceeds ${CODEBUDDY_TOOL_LIMITS.maxNameBytes} bytes.`); } if (seenWireNames.has(wireName)) { throw new Error(`CodeBuddy tool catalog contains a duplicate wire name: ${wireName}.`); } seenWireNames.add(wireName); if (typeof tool.description !== "string" || hasUnpairedSurrogate(tool.description) || INVALID_DESCRIPTION_CONTROL_PATTERN.test(tool.description)) { throw new Error(`CodeBuddy tool ${index + 1} has an invalid description.`); } const description = tool.description || `Tool: ${wireName}`; if (utf8Bytes(description) > CODEBUDDY_TOOL_LIMITS.maxDescriptionBytes) { throw new Error(`CodeBuddy tool ${index + 1} description exceeds ${CODEBUDDY_TOOL_LIMITS.maxDescriptionBytes} bytes.`); } let inputSchema: Record<string, unknown>; try { inputSchema = normalizeInputSchema(tool.parameters ?? {}); } catch (error) { const detail = error instanceof Error ? error.message : "unknown schema error"; throw new Error(`CodeBuddy tool ${index + 1} has an invalid input schema: ${detail}.`); } return { source: tool, wireName, description, inputSchema }; } function buildToolBridge(parsed: OcxParsedRequest): CodeBuddyToolBridge { const allTools = parsed.context.tools ?? []; if (!Array.isArray(allTools)) throw new Error("CodeBuddy tool catalog must be an array."); const choice = parsed.options.toolChoice; const requireToolCall = requiresToolCall(choice); // `none` is an authorization decision, so do not traverse or validate a // catalog that the nested CLI must never see. Besides avoiding needless // work, this prevents an unselected malformed or oversized definition from // turning an explicitly tool-free request into a local adapter failure. if (choice === "none") { return { tools: [], emittedNameMap: new Map(), requireToolCall: false }; } // Named and allowed-tools choices still need the complete identity view to // reject ambiguous shorthand, but schema/description/size validation belongs // only to definitions that can actually be advertised. `auto`/`required` // select the whole catalog and therefore retain the original full boundary. // Non-object entries have no selectable identity. Ignore them for a selective // choice; if the choice names nothing else, the required-choice check below // still fails closed. Unfiltered modes retain them so prepareTool rejects the // malformed catalog as before. const identityCatalog = typeof choice === "object" && choice !== null ? allTools.filter(tool => tool !== null && typeof tool === "object") : allTools; const allows = toolChoiceToolPredicate(choice, identityCatalog); const selected = identityCatalog .map((tool, index) => ({ index, tool })) .filter(({ tool }) => allows(tool)); if (requireToolCall && selected.length === 0) { throw new Error("CodeBuddy tool_choice requires a tool, but no matching tool is available."); } if (selected.length > CODEBUDDY_TOOL_LIMITS.maxTools) { throw new Error(`CodeBuddy tool catalog exceeds the ${CODEBUDDY_TOOL_LIMITS.maxTools}-tool limit.`); } const seenWireNames = new Set<string>(); const prepared = selected.map(({ index, tool }) => prepareTool(tool, index, seenWireNames)); const aliases = codeBuddyToolAliases(prepared.map(tool => tool.wireName)); const definitions = prepared.map((tool, index): CodeBuddyMcpToolDefinition => { const definition = { name: aliases.get(tool.wireName)!, description: tool.description, inputSchema: tool.inputSchema, }; if (serializedBytes(definition) > CODEBUDDY_TOOL_LIMITS.maxToolBytes) { throw new Error(`CodeBuddy tool ${index + 1} definition exceeds ${CODEBUDDY_TOOL_LIMITS.maxToolBytes} bytes.`); } return definition; }); if (serializedBytes(definitions) > CODEBUDDY_TOOL_LIMITS.maxCatalogBytes) { throw new Error(`CodeBuddy tool catalog exceeds ${CODEBUDDY_TOOL_LIMITS.maxCatalogBytes} bytes.`); } const emittedNameMap = new Map<string, string>(); const tools = prepared.map((preparedTool, index) => { const definition = definitions[index]; const emittedName = `${CODEBUDDY_MCP_TOOL_PREFIX}${definition.name}`; if (emittedNameMap.has(emittedName)) { throw new Error("CodeBuddy tool catalog contains a colliding emitted alias."); } emittedNameMap.set(emittedName, preparedTool.wireName); return definition; }); return { tools, emittedNameMap, requireToolCall }; } export function buildCodeBuddyToolBridge(parsed: OcxParsedRequest): CodeBuddyToolBridge { return buildToolBridge(parsed); }