@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
183 lines (171 loc) • 8.16 kB
text/typescript
/**
* Codex App visualization references for models that cannot see private-use characters.
*
* The bundled Visualize skill teaches the model to answer with
*
* \uE200visualize\uE202{"path":"/abs/chart.html"}\uE201
*
* and the Codex App renders that span as an inline visualization. Some providers drop Basic
* Multilingual Plane private-use characters before the model sees them (every Claude route checked
* on 2026-09-27, direct and through Cursor), so the model reads and writes a bare
* `visualize{"path":...}` that the app shows verbatim.
*
* The app does not need the private-use form. Its own renderer rewrites each span into the plain
* directive `::codex-inline-vis{path="/abs/chart.html"}` before parsing, and it renders that
* directive when it appears directly. Rewriting the span the same way in model-visible text gives
* every model an ASCII instruction it can read and repeat.
*
* The rules mirror the app (26.924.22138, `f2` in app-shared) with two deliberate differences: code
* blocks are rewritten too, because the skill's example sits in a fenced block, and the skill's
* `<absolute-path>/<title>.html` placeholder is accepted so the model still sees the template.
* Matching follows the app's regex `/\uE200visualize\uE202([^\uE201]+)\uE201/g` exactly, scanned in
* linear time. Anything the app would keep as-is is kept as-is here.
*
* Only the parsed context is rewritten. The raw request body, which native passthrough serializes
* and which is stored for `previous_response_id` replay, is never touched.
*/
import { posix } from "node:path";
import type { OcxContentPart, OcxContext, OcxMessage, OcxTextContent } from "../types";
const START = "\uE200";
const END = "\uE201";
const PREFIX = `${START}visualize\uE202`;
const INLINE_DIRECTIVE = "codex-inline-vis";
const LIVE_DIRECTIVE = "codex-live-vis";
/** The placeholder path in the Visualize skill's own template. */
const TEMPLATE_PATH = "<absolute-path>/<title>.html";
const HTML_BASENAME = /^[a-z0-9]+(?:-[a-z0-9]+)*\.html$/;
const PARENT_SEGMENT = /(?:^|[\\/])\.\.(?:[\\/]|$)/;
const UNSAFE_ATTRIBUTE = /["\n\r]/;
/** The app's absolute-path test: POSIX (not `//`), drive letter, UNC with either slash. */
function isAbsoluteAppPath(path: string): boolean {
return (path.startsWith("/") && !path.startsWith("//"))
|| /^[A-Za-z]:[\\/]/.test(path)
|| /^\\\\[^\\]+\\[^\\]+/.test(path)
|| /^\/\/[^/]+\/[^/]+/.test(path);
}
interface VisualizationReference {
path: string | null;
title?: string;
type?: "inline" | "live";
mode?: "wide";
}
/** The app's payload schema: `path` is required but nullable; the rest are optional and typed. */
function parseReference(value: unknown): VisualizationReference | undefined {
if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
const record = value as Record<string, unknown>;
if (!("path" in record) || (record.path !== null && typeof record.path !== "string")) return undefined;
if (record.title !== undefined && typeof record.title !== "string") return undefined;
if (record.type !== undefined && record.type !== "inline" && record.type !== "live") return undefined;
if (record.mode !== undefined && record.mode !== "wide") return undefined;
if (record.wide !== undefined && typeof record.wide !== "boolean") return undefined;
return {
path: record.path as string | null,
...(record.title !== undefined ? { title: record.title as string } : {}),
...(record.type !== undefined ? { type: record.type as "inline" | "live" } : {}),
...(record.mode !== undefined ? { mode: "wide" as const } : {}),
};
}
/** The ASCII directive for one span payload, or undefined when the app would keep the span. */
function toAsciiDirective(payload: string): string | undefined {
const isJson = payload.startsWith("{");
let raw: unknown = { path: payload };
if (isJson) {
try {
raw = JSON.parse(payload);
} catch {
return undefined;
}
}
const reference = parseReference(raw);
if (!reference) return undefined;
const live = reference.type === "live";
const { path } = reference;
if (path === null) return live ? `::${LIVE_DIRECTIVE}{}` : undefined;
const template = isJson && path === TEMPLATE_PATH;
if (!template) {
const basename = posix.basename(path.replaceAll("\\", "/"));
if (PARENT_SEGMENT.test(path) || UNSAFE_ATTRIBUTE.test(path) || !HTML_BASENAME.test(basename)) return undefined;
if (!isAbsoluteAppPath(path) && (isJson || path !== basename)) return undefined;
}
const attribute = template || isAbsoluteAppPath(path) ? "path" : "file";
const title = reference.title !== undefined && !UNSAFE_ATTRIBUTE.test(reference.title)
? ` title="${reference.title}"`
: "";
const mode = !live && reference.mode === "wide" ? ` mode="wide"` : "";
return `::${live ? LIVE_DIRECTIVE : INLINE_DIRECTIVE}{${attribute}="${path}"${title}${mode}}`;
}
/**
* Rewrite every visualization span in `text` to the app's ASCII directive.
*
* Returns the same string when nothing changes. The scan finds the same matches as the app's regex:
* a prefix, one or more characters that are not END, then END. When no END follows a prefix, no
* later prefix can match either, so the scan stops instead of rescanning the tail for every prefix.
*/
export function normalizeVisualizationText(text: string): string {
let prefixAt = text.indexOf(PREFIX);
if (prefixAt === -1) return text;
let out = "";
let copiedTo = 0;
while (prefixAt !== -1) {
const payloadStart = prefixAt + PREFIX.length;
const endAt = text.indexOf(END, payloadStart);
if (endAt === -1) break;
if (endAt === payloadStart) {
// Empty payload: the regex moves on one character and tries again.
prefixAt = text.indexOf(PREFIX, prefixAt + 1);
continue;
}
const directive = toAsciiDirective(text.slice(payloadStart, endAt));
if (directive !== undefined) {
out += text.slice(copiedTo, prefixAt) + directive;
copiedTo = endAt + 1;
}
prefixAt = text.indexOf(PREFIX, endAt + 1);
}
return copiedTo === 0 ? text : out + text.slice(copiedTo);
}
function normalizeParts<P extends { type: string }>(parts: P[]): P[] {
let changed = false;
const next = parts.map((part) => {
if (part.type !== "text") return part;
const text = (part as unknown as OcxTextContent).text;
if (typeof text !== "string") return part;
const normalized = normalizeVisualizationText(text);
if (normalized === text) return part;
changed = true;
return { ...part, text: normalized };
});
return changed ? next : parts;
}
function normalizeContent<P extends { type: string }>(content: string | P[]): string | P[] {
return typeof content === "string" ? normalizeVisualizationText(content) : normalizeParts(content);
}
function normalizeMessage(message: OcxMessage): OcxMessage {
if (message.role === "assistant") {
const content = normalizeParts(message.content);
return content === message.content ? message : { ...message, content };
}
const content = normalizeContent<OcxContentPart>(message.content);
return content === message.content ? message : { ...message, content } as OcxMessage;
}
/**
* Rewrite visualization spans in the conversation text a routed model reads: the system prompt,
* string message content, and text parts of every role. Other fields, including images, tool calls,
* reasoning parts, and tool definitions, are returned by reference. The context itself is returned
* unchanged when no text changed.
*/
export function normalizeVisualizationContext(context: OcxContext): OcxContext {
let changed = false;
const systemPrompt = context.systemPrompt?.map((text) => {
const normalized = normalizeVisualizationText(text);
if (normalized !== text) changed = true;
return normalized;
});
const messages = context.messages.map((message) => {
const normalized = normalizeMessage(message);
if (normalized !== message) changed = true;
return normalized;
});
if (!changed) return context;
return { ...context, ...(systemPrompt ? { systemPrompt } : {}), messages };
}