UNPKG

@bitkyc08/opencodex

Version:

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

253 lines (237 loc) • 14.5 kB
import { isAbsolute } from "node:path"; import { realpathSync, statSync } from "node:fs"; import { MessageBudget } from "./budget"; import { isResumeProfile, verifyResumeProfile } from "./resume-permissions"; import { localSocket, type LocalSocket } from "./socket"; import { isRecord, isThreadId, LocalMessagingError, type LocalMetadataClient, type LocalThread } from "./types"; type Method = "initialize" | "thread/loaded/list" | "thread/read" | "thread/queue/add" | "configRequirements/read" | "permissionProfile/list"; interface QueueResult { status: "not_sent" | "queued" | "unknown"; error?: { code: string; message: string }; } /** Only a validated server rejection can establish non-submission after a write. */ class QueueRejection extends LocalMessagingError {} interface Pending { resolve(value: unknown): void; reject(error: Error): void; timer: ReturnType<typeof setTimeout>; method: Method; } /** Default metadata/queue connection; lifecycle access requires a separate explicit factory. */ export class LocalMessageRpc implements LocalMetadataClient { private nextId = 0; private allowResume = false; private serverHome: unknown; private readonly pending = new Map<number, Pending>(); private closed = false; private readonly abort: () => void; /** Bind connection failure and operation cancellation to all pending requests. */ private constructor(private readonly socket: LocalSocket, private readonly budget: MessageBudget, private readonly rpcTimeoutMs: number) { this.abort = () => this.close(budget.signal.reason); socket.onmessage = event => this.receive(event.data); socket.onerror = socket.onclose = () => this.close(); budget.signal.addEventListener("abort", this.abort, { once: true }); if (budget.signal.aborted) this.abort(); } /** Connect and initialize an existing local daemon within budget; never start or repair one. */ static async connect(url: string, budget: MessageBudget, rpcTimeoutMs = 10_000): Promise<LocalMessageRpc> { budget.throwIfEnded(); if (!Number.isInteger(rpcTimeoutMs) || rpcTimeoutMs <= 0 || rpcTimeoutMs > 10_000) { throw new LocalMessagingError("invalid_budget", "RPC timeout must be between 1 and 10000 milliseconds."); } const socket = localSocket(url); try { await new Promise<void>((resolve, reject) => { const cleanup = () => { clearTimeout(timer); budget.signal.removeEventListener("abort", abort); socket.onopen = socket.onerror = socket.onclose = null; }; const abort = () => { cleanup(); reject(budget.signal.reason); }; const timer = budget.stageTimer(rpcTimeoutMs, () => { cleanup(); reject(new LocalMessagingError("daemon_unavailable", "Local Codex connection timed out; no daemon was started.")); }); budget.signal.addEventListener("abort", abort, { once: true }); socket.onopen = () => { cleanup(); resolve(); }; socket.onerror = socket.onclose = () => { cleanup(); reject(new LocalMessagingError("daemon_unavailable", "Cannot connect to the existing local Codex daemon.")); }; if (budget.signal.aborted) abort(); }); } catch (error) { socket.terminate(); throw error; } return LocalMessageRpc.attach(socket, budget, rpcTimeoutMs); } /** Initialize an already authenticated transport; local connect still accepts Unix sockets only. */ static async attach(socket: LocalSocket, budget: MessageBudget, rpcTimeoutMs = 10_000): Promise<LocalMessageRpc> { try { budget.throwIfEnded(); } catch (error) { socket.terminate(); throw error; } if (socket.readyState !== 1 || !Number.isInteger(rpcTimeoutMs) || rpcTimeoutMs <= 0 || rpcTimeoutMs > 10_000) { socket.terminate(); throw new LocalMessagingError("invalid_transport", "Messaging transport must be connected with a bounded RPC deadline."); } const rpc = new LocalMessageRpc(socket, budget, rpcTimeoutMs); try { const result = await rpc.request("initialize", { clientInfo: { name: "opencodex_message", version: "1.0.0" }, capabilities: { experimentalApi: true }, }); if (!isRecord(result)) throw rpc.invalidMetadata(); rpc.serverHome = result.codexHome; budget.throwIfEnded(); socket.send(JSON.stringify({ method: "initialized", params: {} })); return rpc; } catch (error) { rpc.close(); throw error; } } /** Grant only resume preflight on an explicitly selected trusted local server. */ static async connectForResume(url: string, budget: MessageBudget, codexHome: string): Promise<LocalMessageRpc> { const rpc = await LocalMessageRpc.connect(url, budget); try { if (typeof rpc.serverHome !== "string" || !isAbsolute(rpc.serverHome) || !statSync(codexHome).isDirectory() || realpathSync(rpc.serverHome) !== realpathSync(codexHome)) { throw new LocalMessagingError("resume_home_mismatch", "The selected server must report the configured Codex home."); } rpc.allowResume = true; return rpc; } catch (error) { rpc.close(); throw error instanceof LocalMessagingError ? error : new LocalMessagingError("resume_home_unverified", "The selected server home could not be verified."); } } /** Inspect the target but refuse execution until native conditional resume is available. */ async resumeThread(threadId: string, permissionProfile: string) { try { if (!this.allowResume || !isThreadId(threadId) || !isResumeProfile(permissionProfile)) throw new LocalMessagingError("resume_disabled", "An explicit resume grant, thread UUID and permission profile are required."); const state = await this.request("thread/read", { threadId, includeTurns: false }); const target = this.projectThread(state, threadId); if (target.status === "systemError") throw new LocalMessagingError("resume_target_unhealthy", "The target is unhealthy."); if (target.status !== "notLoaded") return { status: "already_loaded" as const, observedStatus: target.status }; await verifyResumeProfile((method, params) => this.request(method, params), permissionProfile, (state as {thread: Record<string, unknown>}).thread.cwd); // Codex 0.166.0 can replace an unsubscribed idle thread loaded after preflight. // No atomic not-loaded condition exists in its resume API; never send an unconditional resume. throw new LocalMessagingError("resume_atomicity_unsupported", "The server cannot enforce an unloaded-only resume; no resume was submitted."); } catch (error) { return { status: "not_resumed" as const, error: error instanceof LocalMessagingError ? { code: error.code } : { code: "resume_unavailable" } }; } } /** Read up to 50 loaded UUIDs, rejecting malformed IDs and unbounded pagination cursors. */ async loadedPage(cursor?: string): Promise<{ data: string[]; nextCursor: string | null }> { const raw = await this.request("thread/loaded/list", { limit: 50, ...(cursor ? { cursor } : {}) }); if (!isRecord(raw) || !Array.isArray(raw.data) || raw.data.length > 50 || !raw.data.every(isThreadId) || (raw.nextCursor !== undefined && raw.nextCursor !== null && (typeof raw.nextCursor !== "string" || !raw.nextCursor || raw.nextCursor.length > 4096))) { throw this.invalidMetadata(); } return { data: raw.data, nextCursor: typeof raw.nextCursor === "string" ? raw.nextCursor : null }; } /** Validate one exact thread and project ID/name/status only, without requesting turns. */ async readThread(id: string): Promise<LocalThread> { if (!isThreadId(id)) throw new LocalMessagingError("invalid_selector", "A valid Codex thread ID is required."); const raw = await this.request("thread/read", { threadId: id, includeTurns: false }); return this.projectThread(raw, id); } /** Metadata projection shared by normal reads and the resume-only preflight. */ private projectThread(raw: unknown, id: string): LocalThread { const thread = isRecord(raw) ? raw.thread : null; if (!isRecord(thread) || thread.id !== id || (thread.name !== undefined && thread.name !== null && (typeof thread.name !== "string" || thread.name.length > 4096)) || !isRecord(thread.status) || !["idle", "active", "systemError", "notLoaded"].includes(String(thread.status.type))) { throw this.invalidMetadata(); } return { id, name: typeof thread.name === "string" ? thread.name : null, status: thread.status.type as LocalThread["status"] }; } /** Submit once on this connection; after an accepted write only a correlated reply is definitive. */ async queueMessage(threadId: string, text: string, messageId: string, acknowledge?: (submissionId: string) => void): Promise<QueueResult> { let written = false; try { if (!isThreadId(threadId) || !isThreadId(messageId) || !text || text.includes("\0") || Buffer.byteLength(text) > 32 * 1024) { throw new LocalMessagingError("invalid_message", "A bounded text message and UUID correlation are required."); } const raw = await this.request("thread/queue/add", { threadId, input: [{ type: "text", text }], clientUserMessageId: messageId, }, () => { written = true; }); const queued = isRecord(raw) ? raw.queuedSubmission : null; if (!isRecord(queued) || typeof queued.id !== "string" || !queued.id || queued.id.length > 4096 || queued.clientUserMessageId !== messageId || !Array.isArray(queued.input) || queued.input.length !== 1 || !isRecord(queued.input[0]) || queued.input[0].type !== "text" || queued.input[0].text !== text || (queued.input[0].text_elements !== undefined && (!Array.isArray(queued.input[0].text_elements) || queued.input[0].text_elements.length !== 0))) { throw this.invalidMetadata(); } acknowledge?.(queued.id); return { status: "queued" }; } catch (error) { if (error instanceof QueueRejection || !written) { return { status: "not_sent", error: error instanceof LocalMessagingError ? { code: error.code, message: error.message } : { code: "messaging_failed", message: "Local queue submission could not be started." } }; } return { status: "unknown", error: { code: "submission_unknown", message: "Local queue submission may have occurred. Do not replay; recipient processing is unknown." } }; } } /** Idempotently reject pending work, remove handlers and terminate only this connection. */ close(error: Error = new LocalMessagingError("daemon_unavailable", "Local Codex connection closed.")): void { if (this.closed) return; this.closed = true; this.budget.signal.removeEventListener("abort", this.abort); this.socket.onopen = this.socket.onmessage = this.socket.onerror = this.socket.onclose = null; for (const pending of this.pending.values()) { clearTimeout(pending.timer); pending.reject(error); } this.pending.clear(); this.socket.terminate(); } /** Fail closed on malformed metadata without including the daemon's response in the error. */ private invalidMetadata(): LocalMessagingError { const error = new LocalMessagingError("invalid_metadata", "Codex returned invalid local session metadata."); this.close(error); return error; } /** Issue one whitelisted RPC with bounded concurrency and timeout; record accepted writes. */ private request(method: Method, params: Record<string, unknown>, onWritten?: () => void): Promise<unknown> { this.budget.throwIfEnded(); if (this.closed || this.socket.readyState !== 1) throw new LocalMessagingError("daemon_unavailable", "Local Codex connection is closed."); if (this.pending.size >= 4) throw new LocalMessagingError("rpc_limit", "Local Codex metadata concurrency limit exceeded."); const id = ++this.nextId; return new Promise((resolve, reject) => { const timer = this.budget.stageTimer(this.rpcTimeoutMs, () => this.close(new LocalMessagingError("rpc_timeout", "Local Codex request timed out."))); this.pending.set(id, { resolve, reject, timer, method }); try { this.socket.send(JSON.stringify({ id, method, params })); onWritten?.(); } catch { this.close(); } }); } /** Settle matching bounded RPC frames; ignore notifications and sanitize remote errors. */ private receive(data: unknown): void { try { if (typeof data !== "string" || Buffer.byteLength(data) > 1024 * 1024) throw new Error(); const raw: unknown = JSON.parse(data); if (!isRecord(raw)) throw new Error(); if (typeof raw.method === "string" && raw.id === undefined) return; if (typeof raw.id !== "number" || !Number.isSafeInteger(raw.id) || Object.hasOwn(raw, "result") === Object.hasOwn(raw, "error")) throw new Error(); const pending = this.pending.get(raw.id); if (!pending) { // During a one-shot submission an uncorrelated response cannot acknowledge our write. if ([...this.pending.values()].some(request => request.method === "thread/queue/add")) throw new Error(); return; } let rejection: LocalMessagingError | undefined; if (Object.hasOwn(raw, "error")) { const error = raw.error; if (!isRecord(error) || !Number.isSafeInteger(error.code) || typeof error.message !== "string") throw new Error(); if (pending.method === "thread/queue/add") { const unsupported = error.code === -32601 || (error.code === -32600 && (error.message === "thread/queue/add requires experimentalApi capability" || error.message.startsWith("Invalid request: unknown variant `thread/queue/add`"))); rejection = unsupported ? new QueueRejection("unsupported_queue", "Your Codex daemon does not support local queueing (experimental thread/queue/add).") : new QueueRejection("queue_rejected", "Codex rejected the local queue submission."); } else rejection = new LocalMessagingError("rpc_rejected", "Codex rejected the local metadata request."); } this.pending.delete(raw.id); clearTimeout(pending.timer); if (rejection) pending.reject(rejection); else pending.resolve(raw.result); } catch { this.close(new LocalMessagingError("invalid_metadata", "Codex returned an invalid or oversized RPC frame.")); } } }