UNPKG

@bitkyc08/opencodex

Version:

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

203 lines (181 loc) • 9.97 kB
/** * Agent Client Protocol (v1) framing for the official Antigravity CLI (`agy acp`). * * `agy acp` speaks newline-delimited JSON-RPC 2.0 on stdin/stdout. One ACP session answers one * turn: initialize -> session/new -> session/set_config_option (model, then thought level) -> * session/prompt, with session/update notifications streaming in between. This module is pure: it * never spawns a process, never touches the network and never sees a credential (the CLI owns its * own sign-in), so the framing and the terminal table are testable against captured lines. * * Framing descends from the retired Devin CLI ACP module (f97612c956^:src/adapters/devin-cli/acp.ts) * with three deliberate departures: frames are dispatched by shape rather than by numeric id (both * directions may reuse an id), stop reasons map through a complete terminal table instead of passing * through, and nothing child-authored ever reaches an error message. */ import type { AdapterEvent, OcxParsedRequest, OcxToolCall, OcxUsage } from "../../types"; /** Hard ceiling on a single buffered stdout line. */ export const MAX_ACP_LINE_BYTES = 8 * 1024 * 1024; /** Hard ceiling on total stdout bytes consumed for one turn. */ export const MAX_ACP_TOTAL_BYTES = 64 * 1024 * 1024; /** Ceiling on the flattened conversation handed to one ACP prompt. */ export const MAX_ACP_PROMPT_CHARS = 200_000; /** ACP v1 "Authentication required". */ export const ACP_AUTH_REQUIRED = -32000; /** JSON-RPC "Method not found". */ export const ACP_METHOD_NOT_FOUND = -32601; export type JsonRpcId = number | string; type Frame = Record<string, unknown>; export function initializeFrame(id: JsonRpcId, clientVersion: string): Frame { // No client capabilities: the CLI must not delegate file system or terminal work to this proxy. return { jsonrpc: "2.0", id, method: "initialize", params: { protocolVersion: 1, clientCapabilities: {}, clientInfo: { name: "opencodex", version: clientVersion } }, }; } export function sessionNewFrame(id: JsonRpcId, cwd: string, systemPrompt?: string): Frame { const params: Frame = { cwd, mcpServers: [] }; if (systemPrompt) params.systemPrompt = { mode: "append", content: [{ type: "text", text: systemPrompt }] }; return { jsonrpc: "2.0", id, method: "session/new", params }; } export function setConfigOptionFrame(id: JsonRpcId, sessionId: string, configId: string, value: string): Frame { return { jsonrpc: "2.0", id, method: "session/set_config_option", params: { sessionId, configId, value } }; } export function sessionPromptFrame(id: JsonRpcId, sessionId: string, text: string): Frame { return { jsonrpc: "2.0", id, method: "session/prompt", params: { sessionId, prompt: [{ type: "text", text }] } }; } export function sessionCancelFrame(sessionId: string): Frame { return { jsonrpc: "2.0", method: "session/cancel", params: { sessionId } }; } /** * The only answer to session/request_permission: cancelled. A headless proxy turn has nobody to * approve a tool, and the CLI's own permission engine (request-review) is the boundary this provider * relies on, so every ask is refused. No option is ever selected, allow-shaped or otherwise. */ export function permissionCancelledFrame(id: JsonRpcId): Frame { return { jsonrpc: "2.0", id, result: { outcome: { outcome: "cancelled" } } }; } /** Fixed answer to any other agent-to-client request (fs/*, terminal/*, ...): never executed here. */ export function methodNotFoundFrame(id: JsonRpcId): Frame { return { jsonrpc: "2.0", id, error: { code: ACP_METHOD_NOT_FOUND, message: "Method not found" } }; } export type ClassifiedFrame = | { kind: "request"; id: JsonRpcId; method: string; params: unknown } | { kind: "notification"; method: string; params: unknown } | { kind: "response"; id: JsonRpcId; result?: unknown; error?: { code?: unknown } } | { kind: "invalid" }; const isId = (value: unknown): value is JsonRpcId => (typeof value === "number" && Number.isSafeInteger(value)) || (typeof value === "string" && value.length > 0 && value.length <= 128); /** Classify by JSON-RPC shape: a method with an id is a request, without one a notification. */ export function classifyFrame(frame: unknown): ClassifiedFrame { if (!frame || typeof frame !== "object" || Array.isArray(frame)) return { kind: "invalid" }; const f = frame as Frame; if (typeof f.method === "string") { if (f.id === undefined) return { kind: "notification", method: f.method, params: f.params }; return isId(f.id) ? { kind: "request", id: f.id, method: f.method, params: f.params } : { kind: "invalid" }; } if (isId(f.id) && ("result" in f || "error" in f)) { const error = f.error && typeof f.error === "object" ? f.error as { code?: unknown } : undefined; return { kind: "response", id: f.id, ...(error ? { error } : { result: f.result }) }; } return { kind: "invalid" }; } /** Fence a block label so a message body cannot forge one. */ function fence(label: string, body: string): string { return `[${label}]\n${body.replace(/^\[(System|User|Assistant|Tool)\]/gm, " $&")}`; } /** The system text of a parsed request, or "" when there is none. */ export function acpSystemText(parsed: OcxParsedRequest): string { return parsed.context.systemPrompt?.filter(line => line.trim().length > 0).join("\n") ?? ""; } /** * Flatten the conversation into the single text block one ACP prompt carries. ACP has no * multi-message history on session/prompt. System text is included only when the CLI did not * advertise `sessionCapabilities.systemPrompt` (then it travels on session/new instead, never both). */ export function buildAcpPrompt(parsed: OcxParsedRequest, includeSystem: boolean): string { const blocks: string[] = []; const system = includeSystem ? acpSystemText(parsed) : ""; if (system) blocks.push(fence("System", system)); for (const message of parsed.context.messages) { if (message.role === "toolResult") { const body = typeof message.content === "string" ? message.content : JSON.stringify(message.content ?? ""); blocks.push(fence("Tool", `[result id=${message.toolCallId}]\n${body}`)); continue; } const parts = typeof message.content === "string" ? [] : message.content; let text = typeof message.content === "string" ? message.content : parts.map(p => (p.type === "text" ? p.text : "")).filter(Boolean).join("\n"); if (message.role === "assistant" && Array.isArray(parts)) { const calls = parts .filter((p): p is OcxToolCall => p.type === "toolCall") .map(c => `[call ${c.name} id=${c.id}]\n${JSON.stringify(c.arguments ?? {})}`) .join("\n\n"); if (calls) text = text ? `${text}\n\n${calls}` : calls; } if (!text.trim()) continue; const label = message.role === "assistant" ? "Assistant" : message.role === "developer" ? "System" : "User"; blocks.push(fence(label, text)); } if (blocks.length === 0) return "(empty)"; const joined = blocks.join("\n\n"); // Keep the newest turns when trimming: the tail is what the agent is answering. return joined.length > MAX_ACP_PROMPT_CHARS ? `[truncated]\n${joined.slice(joined.length - MAX_ACP_PROMPT_CHARS)}` : joined; } function chunkText(content: unknown): string { if (typeof content === "string") return content; if (content && typeof content === "object") { const text = (content as { text?: unknown }).text; if (typeof text === "string") return text; } return ""; } /** * Translate one session/update (other than config_option_update, which the driver owns) into * adapter events. The CLI's own tool calls are not client tools: the agent runs them inside its * session under its own permission engine, so they become heartbeats (proof of life) and never * tool_call_start, which would ask Codex to run something the agent already decided. */ export function acpUpdateToEvents(update: Record<string, unknown>): AdapterEvent[] { const kind = update.sessionUpdate; if (kind === "agent_message_chunk") { const text = chunkText(update.content); return text ? [{ type: "text_delta", text }] : []; } if (kind === "agent_thought_chunk") { const text = chunkText(update.content); return text ? [{ type: "thinking_delta", thinking: text }] : []; } if (typeof kind === "string") return [{ type: "heartbeat" }]; return []; } export function mapAcpUsage(raw: unknown): OcxUsage | undefined { if (!raw || typeof raw !== "object") return undefined; const u = raw as Record<string, unknown>; const input = typeof u.inputTokens === "number" && u.inputTokens >= 0 ? u.inputTokens : 0; const output = typeof u.outputTokens === "number" && u.outputTokens >= 0 ? u.outputTokens : 0; if (input === 0 && output === 0) return undefined; return { inputTokens: input, outputTokens: output }; } export type AcpFailureCode = | "agy_acp_turn_limit" | "agy_acp_cancelled" | "agy_acp_protocol" | "agy_login_required" | "agy_acp_model_unproven" | "agy_acp_model_switched" | "agy_acp_unsupported_selection" | "agy_acp_unavailable"; export type AcpTerminal = | { kind: "done"; stopReason?: "max_tokens" } | { kind: "refusal" } | { kind: "aborted" } | { kind: "error"; code: AcpFailureCode }; /** * Only end_turn and max_tokens complete an answer. A refusal ends the turn without retry. * A turn limit, an unrequested cancellation and anything unrecognised are errors. */ export function acpTerminal(stopReason: unknown, callerAborted: boolean): AcpTerminal { switch (stopReason) { case "end_turn": return { kind: "done" }; case "max_tokens": return { kind: "done", stopReason: "max_tokens" }; case "refusal": return { kind: "refusal" }; case "max_turn_requests": return { kind: "error", code: "agy_acp_turn_limit" }; case "cancelled": return callerAborted ? { kind: "aborted" } : { kind: "error", code: "agy_acp_cancelled" }; default: return { kind: "error", code: "agy_acp_protocol" }; } }