@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
238 lines (216 loc) • 8.63 kB
text/typescript
export const REMOTE_WORKSPACE_TOOL_NAMESPACE = "ocx_remote_workspace" as const;
export const REMOTE_WORKSPACE_MAX_TOOL_RESULT_BYTES = 256 * 1024;
export const REMOTE_WORKSPACE_CAPABILITIES = [
"workspace.read",
"workspace.write",
"workspace.exec",
] as const;
export type RemoteWorkspaceCapability = typeof REMOTE_WORKSPACE_CAPABILITIES[number];
export type RemoteWorkspaceToolName =
| "list_directory"
| "read_file"
| "write_file"
| "exec";
export interface RemoteWorkspaceDynamicToolFunction {
type: "function";
name: RemoteWorkspaceToolName;
description: string;
inputSchema: Record<string, unknown>;
}
export interface RemoteWorkspaceDynamicToolNamespace {
type: "namespace";
name: typeof REMOTE_WORKSPACE_TOOL_NAMESPACE;
description: string;
tools: RemoteWorkspaceDynamicToolFunction[];
}
export interface RemoteWorkspaceToolCallParams {
threadId: string;
turnId: string;
callId: string;
namespace: typeof REMOTE_WORKSPACE_TOOL_NAMESPACE;
tool: RemoteWorkspaceToolName;
arguments: unknown;
}
export type RemoteWorkspaceToolResult =
| { ok: true; value?: unknown; error?: never }
| { ok: false; error: string; value?: never };
const RELATIVE_PATH = {
type: "string",
minLength: 1,
maxLength: 4096,
description: "Path relative to the workspace root. Absolute paths and parent traversal are rejected.",
} as const;
export const REMOTE_WORKSPACE_DYNAMIC_TOOLS: readonly [RemoteWorkspaceDynamicToolNamespace] = [{
type: "namespace",
name: REMOTE_WORKSPACE_TOOL_NAMESPACE,
description: "Operate only on the selected remote OpenCodex executor workspace.",
tools: [
{
type: "function",
name: "list_directory",
description: "List one directory inside the selected remote workspace.",
inputSchema: {
type: "object",
properties: { path: { ...RELATIVE_PATH, default: "." } },
additionalProperties: false,
},
},
{
type: "function",
name: "read_file",
description: "Read a bounded UTF-8 regular file from the selected remote workspace.",
inputSchema: {
type: "object",
properties: {
path: RELATIVE_PATH,
maxBytes: { type: "integer", minimum: 1, maximum: REMOTE_WORKSPACE_MAX_TOOL_RESULT_BYTES },
},
required: ["path"],
additionalProperties: false,
},
},
{
type: "function",
name: "write_file",
description: "Atomically replace a bounded UTF-8 file in the selected remote workspace.",
inputSchema: {
type: "object",
properties: {
path: RELATIVE_PATH,
content: { type: "string", maxLength: REMOTE_WORKSPACE_MAX_TOOL_RESULT_BYTES },
expectedSha256: {
type: ["string", "null"],
pattern: "^[0-9a-f]{64}$",
description: "Expected current file hash, or null when the file must not already exist.",
},
},
required: ["path", "content", "expectedSha256"],
additionalProperties: false,
},
},
{
type: "function",
name: "exec",
description: "Execute an argv vector in a directory inside the selected remote workspace.",
inputSchema: {
type: "object",
properties: {
command: {
type: "array",
minItems: 1,
maxItems: 64,
items: { type: "string", minLength: 1, maxLength: 4096 },
},
cwd: { ...RELATIVE_PATH, default: "." },
timeoutMs: { type: "integer", minimum: 1, maximum: 60_000 },
},
required: ["command"],
additionalProperties: false,
},
},
],
}];
const TOOL_CAPABILITY: Readonly<Record<RemoteWorkspaceToolName, RemoteWorkspaceCapability>> = {
list_directory: "workspace.read",
read_file: "workspace.read",
write_file: "workspace.write",
exec: "workspace.exec",
};
export function parseRemoteWorkspaceCapabilities(
value: unknown,
fallback: readonly RemoteWorkspaceCapability[] = ["workspace.read", "workspace.write"],
): RemoteWorkspaceCapability[] {
if (value === undefined) return [...fallback];
if (!Array.isArray(value) || value.length < 1 || value.length > REMOTE_WORKSPACE_CAPABILITIES.length) {
throw new Error("invalid remote workspace capabilities");
}
const result = new Set<RemoteWorkspaceCapability>();
for (const capability of value) {
if (!isRemoteWorkspaceCapability(capability)) {
throw new Error("invalid remote workspace capability");
}
result.add(capability);
}
if (!result.has("workspace.read")) {
throw new Error("remote workspace executors must support workspace.read");
}
return REMOTE_WORKSPACE_CAPABILITIES.filter(capability => result.has(capability));
}
export function remoteWorkspaceToolsForCapabilities(
capabilities: readonly RemoteWorkspaceCapability[],
): RemoteWorkspaceToolName[] {
const allowed = new Set(parseRemoteWorkspaceCapabilities(capabilities));
return REMOTE_WORKSPACE_DYNAMIC_TOOLS[0].tools
.filter(tool => allowed.has(TOOL_CAPABILITY[tool.name]))
.map(tool => tool.name);
}
export function remoteWorkspaceDynamicToolsForCapabilities(
capabilities: readonly RemoteWorkspaceCapability[],
): readonly [RemoteWorkspaceDynamicToolNamespace] {
const names = new Set(remoteWorkspaceToolsForCapabilities(capabilities));
return [{
...REMOTE_WORKSPACE_DYNAMIC_TOOLS[0],
tools: REMOTE_WORKSPACE_DYNAMIC_TOOLS[0].tools.filter(tool => names.has(tool.name)),
}];
}
export function remoteWorkspaceCapabilityForTool(tool: RemoteWorkspaceToolName): RemoteWorkspaceCapability {
return TOOL_CAPABILITY[tool];
}
const TOOL_NAMES: ReadonlySet<string> = new Set(
REMOTE_WORKSPACE_DYNAMIC_TOOLS[0].tools.map(tool => tool.name),
);
export function isRemoteWorkspaceCapability(value: unknown): value is RemoteWorkspaceCapability {
return value === "workspace.read" || value === "workspace.write" || value === "workspace.exec";
}
export function isRemoteWorkspaceToolName(value: unknown): value is RemoteWorkspaceToolName {
return typeof value === "string" && TOOL_NAMES.has(value);
}
function boundedIdentifier(value: unknown): value is string {
return typeof value === "string" && value.length >= 1 && value.length <= 256 && !/[\x00-\x1f\x7f]/.test(value);
}
export function parseRemoteWorkspaceToolCall(value: unknown): RemoteWorkspaceToolCallParams {
if (!value || typeof value !== "object" || Array.isArray(value)) {
throw new Error("invalid remote workspace tool call");
}
const raw = value as Record<string, unknown>;
if (
!boundedIdentifier(raw.threadId)
|| !boundedIdentifier(raw.turnId)
|| !boundedIdentifier(raw.callId)
|| raw.namespace !== REMOTE_WORKSPACE_TOOL_NAMESPACE
|| !isRemoteWorkspaceToolName(raw.tool)
) throw new Error("invalid remote workspace tool call identity");
return {
threadId: raw.threadId,
turnId: raw.turnId,
callId: raw.callId,
namespace: REMOTE_WORKSPACE_TOOL_NAMESPACE,
tool: raw.tool,
arguments: raw.arguments,
};
}
export function remoteWorkspaceDeveloperInstructions(
deviceName: string,
tools: readonly RemoteWorkspaceToolName[] = REMOTE_WORKSPACE_DYNAMIC_TOOLS[0].tools.map(tool => tool.name),
): string {
const safeName = deviceName.replace(/[\x00-\x1f\x7f]/g, " ").slice(0, 120) || "remote executor";
const allowed = tools.map(tool => `${REMOTE_WORKSPACE_TOOL_NAMESPACE}.${tool}`).join(", ");
return [
`This thread operates on the OpenCodex remote executor named ${JSON.stringify(safeName)}.`,
`Its available remote tools are: ${allowed}. Use no other tool for filesystem or command work.`,
"The coordinator filesystem is an empty isolation boundary and is not the user's workspace.",
"Never use local shell, local file, or local patch tools for this thread.",
"If a remote tool is unavailable, stop and report that the executor is offline; never fall back locally.",
].join(" ");
}
export function remoteWorkspaceCodexDeveloperInstructions(
deviceName: string,
tools: readonly RemoteWorkspaceToolName[] = REMOTE_WORKSPACE_DYNAMIC_TOOLS[0].tools.map(tool => tool.name),
): string {
const nestedTools = tools.map(tool => `tools.mcp__${REMOTE_WORKSPACE_TOOL_NAMESPACE}__${tool}`).join(", ");
return [
remoteWorkspaceDeveloperInstructions(deviceName, tools),
`Current Codex versions expose MCP through the functions.exec code-mode tool. Inside it, call only: ${nestedTools}.`,
"Do not call exec_command, apply_patch, view_image, browser, apps, plugins, or any other nested helper on the Hub.",
].join(" ");
}