@meistrari/agent-core 0.2.0-experimental.0 → 0.2.0-experimental.2

package/scripts/generate-codex-protocol.ts

@@ -0,0 +1,711 @@
+#!/usr/bin/env bun
+import type { JSONSchema } from 'json-schema-to-typescript'
+import { spawnSync } from 'node:child_process'
+import {
+    existsSync,
+    mkdirSync,
+    mkdtempSync,
+    readdirSync,
+    readFileSync,
+    rmSync,
+    writeFileSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import { basename, dirname, join, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { compile } from 'json-schema-to-typescript'
+
+type JsonSchemaObject = JSONSchema & { [key: string]: unknown }
+interface SchemaMap { [key: string]: JSONSchema }
+
+interface JsonSchemaFile {
+    path: string
+    namespace: string | undefined
+    fileName: string
+    qualifiedName: string
+    exportName: string
+}
+
+interface MethodEntry {
+    method: string
+    paramsType: string | undefined
+}
+
+interface ResponseEntry {
+    method: string
+    responseType: string
+}
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const codexCliVersion = '0.156.1'
+const upstreamRef = '3d2ee51ca2d5db578f328aa75e20aa22c0197c9a'
+const upstreamSchemaRoot = generateCodexSchemas()
+const upstreamJsonDir = join(upstreamSchemaRoot, 'json')
+const upstreamTypescriptDir = join(upstreamSchemaRoot, 'typescript')
+const generatedDir = join(root, 'src', 'agents', 'codex', 'generated')
+
+const MANUAL_SCHEMAS = {
+    GetAuthStatusParams: {
+        type: 'object',
+        title: 'GetAuthStatusParams',
+        properties: {
+            includeToken: { anyOf: [{ type: 'boolean' }, { type: 'null' }] },
+            refreshToken: { anyOf: [{ type: 'boolean' }, { type: 'null' }] },
+        },
+    },
+    GetConversationSummaryParams: {
+        title: 'GetConversationSummaryParams',
+        oneOf: [
+            {
+                type: 'object',
+                properties: { rolloutPath: { type: 'string' } },
+                required: ['rolloutPath'],
+            },
+            {
+                type: 'object',
+                properties: { conversationId: { type: 'string' } },
+                required: ['conversationId'],
+            },
+        ],
+    },
+    GetConversationSummaryResponse: {
+        type: 'object',
+        title: 'GetConversationSummaryResponse',
+        properties: { summary: {} },
+        required: ['summary'],
+    },
+    GitDiffToRemoteParams: {
+        type: 'object',
+        title: 'GitDiffToRemoteParams',
+        properties: { cwd: { type: 'string' } },
+        required: ['cwd'],
+    },
+    GitDiffToRemoteResponse: {
+        type: 'object',
+        title: 'GitDiffToRemoteResponse',
+        properties: {
+            sha: { type: 'string' },
+            diff: { type: 'string' },
+        },
+        required: ['sha', 'diff'],
+    },
+    GetAuthStatusResponse: {
+        type: 'object',
+        title: 'GetAuthStatusResponse',
+        properties: {
+            authMethod: { anyOf: [{}, { type: 'null' }] },
+            authToken: { anyOf: [{ type: 'string' }, { type: 'null' }] },
+            requiresOpenaiAuth: { anyOf: [{ type: 'boolean' }, { type: 'null' }] },
+        },
+        required: ['authMethod', 'authToken', 'requiresOpenaiAuth'],
+    },
+} satisfies SchemaMap
+
+try {
+    await generateProtocolTypes()
+}
+finally {
+    rmSync(upstreamSchemaRoot, { recursive: true, force: true })
+}
+console.log(`Generated Codex ${codexCliVersion} experimental app-server protocol types at ${upstreamRef}`)
+
+async function generateProtocolTypes(): Promise<void> {
+    if (!existsSync(upstreamJsonDir))
+        throw new Error(`Codex JSON schema fixtures not found: ${upstreamJsonDir}`)
+    if (!existsSync(upstreamTypescriptDir))
+        throw new Error(`Codex TypeScript method fixtures not found: ${upstreamTypescriptDir}`)
+
+    rmSync(generatedDir, { recursive: true, force: true })
+    mkdirSync(generatedDir, { recursive: true })
+
+    const jsonSchemaFiles = listJsonSchemaFiles(upstreamJsonDir)
+    const exportNameByQualifiedName = new Map(
+        jsonSchemaFiles.map(file => [file.qualifiedName, file.exportName]),
+    )
+    const aggregateSchemas: SchemaMap = {}
+
+    for (const file of jsonSchemaFiles) {
+        const parsed = parseSchemaFile(file.path)
+        const localDefinitionNames = new Map(
+            Object.keys(parsed.definitions ?? {}).map(definitionName => [
+                definitionName,
+                `${file.exportName}__${definitionName.replace(/[^A-Z0-9]/gi, '')}`,
+            ]),
+        )
+
+        for (const [definitionName, definitionSchema] of Object.entries(parsed.definitions ?? {})) {
+            const exportName = localDefinitionNames.get(definitionName)
+            if (!exportName)
+                throw new Error(`Missing local definition export name for ${definitionName}`)
+            aggregateSchemas[exportName] = namedSchema(
+                exportName,
+                normalizeSchema(
+                    rewriteExternalRefs(
+                        definitionSchema,
+                        localDefinitionNames,
+                        file.namespace,
+                        exportNameByQualifiedName,
+                    ),
+                ),
+            )
+        }
+
+        const topLevelSchema = Object.fromEntries(
+            Object.entries(parsed).filter(([key]) => key !== 'definitions'),
+        )
+        aggregateSchemas[file.exportName] = namedSchema(
+            file.exportName,
+            normalizeSchema(
+                rewriteExternalRefs(
+                    topLevelSchema,
+                    localDefinitionNames,
+                    file.namespace,
+                    exportNameByQualifiedName,
+                ),
+            ),
+        )
+    }
+
+    for (const [name, schema] of Object.entries(MANUAL_SCHEMAS)) {
+        if (!(name in aggregateSchemas))
+            aggregateSchemas[name] = namedSchema(name, normalizeSchema(schema))
+    }
+
+    const generatedSchemaNames = new Set(Object.keys(aggregateSchemas))
+    const schemaSource = await compile(
+        {
+            title: 'CodexSchema',
+            type: 'object',
+            additionalProperties: true,
+            definitions: aggregateSchemas,
+        },
+        'CodexSchema',
+        {
+            bannerComment: '',
+            unreachableDefinitions: true,
+            style: {
+                bracketSpacing: true,
+                printWidth: 120,
+                semi: true,
+                singleQuote: false,
+                tabWidth: 2,
+                trailingComma: 'all',
+                useTabs: false,
+            },
+        },
+    )
+
+    writeFileSync(
+        join(generatedDir, 'schema.gen.ts'),
+        [
+            '/* eslint-disable style/indent, style/member-delimiter-style, style/quotes, style/semi, style/operator-linebreak, style/indent-binary-ops */',
+            '// This file is generated by scripts/generate-codex-protocol.ts. Do not edit manually.',
+            `// Upstream Codex protocol ref: ${upstreamRef}`,
+            '',
+            schemaSource.trim(),
+            '',
+        ].join('\n'),
+        'utf8',
+    )
+
+    const clientRequests = parseRequestEntries(readFileSync(join(upstreamTypescriptDir, 'ClientRequest.ts'), 'utf8'))
+    const clientNotifications = parseNotificationEntries(readFileSync(join(upstreamTypescriptDir, 'ClientNotification.ts'), 'utf8'))
+    const serverRequests = parseRequestEntries(readFileSync(join(upstreamTypescriptDir, 'ServerRequest.ts'), 'utf8'))
+    const serverNotifications = parseNotificationEntries(readFileSync(join(upstreamTypescriptDir, 'ServerNotification.ts'), 'utf8'))
+
+    writeFileSync(
+        join(generatedDir, 'meta.gen.ts'),
+        renderMeta({
+            upstreamRef,
+            generatedSchemaNames,
+            clientRequests,
+            clientNotifications,
+            serverRequests,
+            serverNotifications,
+        }),
+        'utf8',
+    )
+
+    writeFileSync(
+        join(generatedDir, 'namespaces.gen.ts'),
+        renderNamespaces(upstreamRef, jsonSchemaFiles),
+        'utf8',
+    )
+}
+
+function generateCodexSchemas(): string {
+    const dir = mkdtempSync(join(tmpdir(), 'codex-protocol-'))
+    try {
+        const jsonDir = join(dir, 'json')
+        const typescriptDir = join(dir, 'typescript')
+        mkdirSync(jsonDir, { recursive: true })
+        mkdirSync(typescriptDir, { recursive: true })
+
+        const executable = process.env.CODEX_EXECUTABLE
+        if (executable)
+            assertCodexVersion(executable)
+        const command = executable ?? 'bunx'
+        const prefix = executable ? [] : [`@openai/codex@${codexCliVersion}`]
+        run(command, [...prefix, 'app-server', 'generate-json-schema', '--out', jsonDir, '--experimental'])
+        run(command, [...prefix, 'app-server', 'generate-ts', '--out', typescriptDir, '--experimental'])
+        return dir
+    }
+    catch (error) {
+        rmSync(dir, { recursive: true, force: true })
+        throw error
+    }
+}
+
+function assertCodexVersion(executable: string): void {
+    const result = spawnSync(executable, ['--version'], { encoding: 'utf8' })
+    const expected = `codex-cli ${codexCliVersion}`
+    if (result.status !== 0 || result.stdout.trim() !== expected)
+        throw new Error(`CODEX_EXECUTABLE must report ${expected}.`)
+}
+
+function run(command: string, args: string[]): void {
+    const result = spawnSync(command, args, { encoding: 'utf8' })
+    if (result.status !== 0) {
+        process.stderr.write(result.stdout)
+        process.stderr.write(result.stderr)
+        throw new Error(`${command} ${args.join(' ')} failed`)
+    }
+}
+
+function parseSchemaFile(path: string): JsonSchemaObject {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'))
+    if (!isJsonObject(parsed))
+        throw new Error(`Codex schema fixture must be an object: ${path}`)
+    return parsed
+}
+
+function listJsonSchemaFiles(dir: string): JsonSchemaFile[] {
+    return walk(dir)
+        .filter(path => path.endsWith('.json') && !basename(path).startsWith('codex_app_server_protocol.'))
+        .map((path) => {
+            const qualifiedName = relative(dir, path).replace(/\\/g, '/').replace(/\.json$/, '')
+            const parts = qualifiedName.split('/')
+            const namespace = parts.length > 1 ? parts[0] : undefined
+            return {
+                path,
+                namespace,
+                fileName: basename(path),
+                qualifiedName,
+                exportName: exportNameForQualifiedName(qualifiedName),
+            }
+        })
+        .sort((left, right) => left.exportName.localeCompare(right.exportName))
+}
+
+function walk(dir: string): string[] {
+    const entries: string[] = []
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const path = join(dir, entry.name)
+        if (entry.isDirectory())
+            entries.push(...walk(path))
+        else entries.push(path)
+    }
+    return entries
+}
+
+function exportNameForQualifiedName(qualifiedName: string): string {
+    const parts = qualifiedName.split('/')
+    if (parts.length === 1)
+        return parts[0] ?? qualifiedName
+    const namespacePrefix = parts
+        .slice(0, -1)
+        .flatMap(part => part.split(/[^A-Z0-9]+/i))
+        .filter(segment => segment.length > 0)
+        .map(toPascalSegment)
+        .join('')
+    return `${namespacePrefix}${parts[parts.length - 1] ?? ''}`
+}
+
+function normalizeSchema(value: unknown): JSONSchema {
+    return stripNullDefaults(normalizeNullableTypes(value)) as JSONSchema
+}
+
+function namedSchema(name: string, schema: JSONSchema): JSONSchema {
+    if (!isJsonObject(schema))
+        return schema
+    return { ...schema, title: name }
+}
+
+function normalizeNullableTypes(value: unknown): unknown {
+    if (Array.isArray(value))
+        return value.map(normalizeNullableTypes)
+    if (!isJsonObject(value))
+        return value
+
+    const normalizedObject: JsonSchemaObject = Object.fromEntries(
+        Object.entries(value).map(([key, child]) => [key, normalizeNullableTypes(child)]),
+    )
+    const typeValue = normalizedObject.type
+    if (!Array.isArray(typeValue))
+        return normalizedObject
+
+    const normalizedTypes = typeValue.filter(entry => typeof entry === 'string')
+    if (normalizedTypes.length !== typeValue.length || !normalizedTypes.includes('null'))
+        return normalizedObject
+    const nonNullTypes = normalizedTypes.filter(entry => entry !== 'null')
+    if (nonNullTypes.length !== 1)
+        return normalizedObject
+
+    const withoutType = { ...normalizedObject }
+    delete withoutType.type
+    return {
+        anyOf: [
+            {
+                ...withoutType,
+                type: nonNullTypes[0],
+            },
+            { type: 'null' },
+        ],
+    }
+}
+
+function stripNullDefaults(value: unknown): unknown {
+    if (Array.isArray(value))
+        return value.map(stripNullDefaults)
+    if (!isJsonObject(value))
+        return value
+    return Object.fromEntries(
+        Object.entries(value)
+            .filter(([key, child]) => !(key === 'default' && child === null))
+            .map(([key, child]) => [key, stripNullDefaults(child)]),
+    )
+}
+
+function rewriteExternalRefs(
+    value: unknown,
+    localDefinitionNames: Map<string, string>,
+    currentNamespace: string | undefined,
+    exportNameByQualifiedName: Map<string, string>,
+): unknown {
+    if (Array.isArray(value)) {
+        return value.map(entry =>
+            rewriteExternalRefs(entry, localDefinitionNames, currentNamespace, exportNameByQualifiedName),
+        )
+    }
+    if (!isJsonObject(value))
+        return value
+
+    return Object.fromEntries(
+        Object.entries(value).map(([key, child]) => {
+            if (key === '$ref' && typeof child === 'string' && child.startsWith('#/definitions/')) {
+                const definitionName = child.slice('#/definitions/'.length)
+                const localRewrite = localDefinitionNames.get(definitionName)
+                if (localRewrite)
+                    return [key, `#/definitions/${localRewrite}`]
+
+                const candidates = [
+                    ...(currentNamespace ? [`${currentNamespace}/${definitionName}`] : []),
+                    definitionName,
+                    definitionName.replace(/^v[12]\//, ''),
+                    definitionName.replace(/^serde_json\//, ''),
+                    `v2/${definitionName}`,
+                    `v1/${definitionName}`,
+                    `serde_json/${definitionName}`,
+                ]
+                const rewritten = candidates
+                    .map(candidate => exportNameByQualifiedName.get(candidate))
+                    .find((candidate): candidate is string => candidate !== undefined)
+                if (!rewritten)
+                    throw new Error(`Missing rewritten definition for ref: ${child}`)
+                return [key, `#/definitions/${rewritten}`]
+            }
+
+            return [
+                key,
+                rewriteExternalRefs(child, localDefinitionNames, currentNamespace, exportNameByQualifiedName),
+            ]
+        }),
+    )
+}
+
+function parseRequestEntries(source: string): MethodEntry[] {
+    const declaration = extractRequestTypeDeclaration(source)
+    const nativeMethods = [...declaration.matchAll(/(?:["']method["']|\bmethod)\s*:\s*["']([^"']+)["']/g)]
+        .map(match => match[1])
+        .filter((method): method is string => method !== undefined)
+    assertUniqueMethods(nativeMethods, 'native request declaration')
+    if (nativeMethods.length === 0)
+        throw new Error('Codex request declaration contains no method entries')
+
+    const entryPattern = /\{\s*"method":\s*"([^"]+)",\s*id:\s*RequestId,\s*params(\?)?:([^,{}]+),\s*\}/g
+    const entries: MethodEntry[] = []
+    for (const match of declaration.matchAll(entryPattern)) {
+        const method = match[1]
+        const optionalParams = match[2] === '?'
+        const rawParamsType = match[3]?.trim()
+        if (!method || !rawParamsType)
+            throw new Error(`Unable to parse Codex request entry: ${match[0]}`)
+        const parsedParamsType = parseSupportedParamsType(rawParamsType)
+        const paramsType = optionalParams && !parsedParamsType.includesUndefined
+            ? `${rawParamsType} | undefined`
+            : rawParamsType
+        entries.push({ method, paramsType })
+    }
+
+    const parsedMethods = entries.map(entry => entry.method)
+    assertUniqueMethods(parsedMethods, 'parsed request entries')
+    const parsedMethodSet = new Set(parsedMethods)
+    const nativeMethodSet = new Set(nativeMethods)
+    const missingMethods = nativeMethods.filter(method => !parsedMethodSet.has(method))
+    const unexpectedMethods = parsedMethods.filter(method => !nativeMethodSet.has(method))
+    if (missingMethods.length > 0 || unexpectedMethods.length > 0) {
+        throw new Error([
+            'Codex request parsing did not cover the native method set.',
+            `Missing: ${missingMethods.join(', ') || 'none'}.`,
+            `Unexpected: ${unexpectedMethods.join(', ') || 'none'}.`,
+        ].join(' '))
+    }
+    return entries
+}
+
+function extractRequestTypeDeclaration(source: string): string {
+    const declarations = [...source.matchAll(/export type [A-Z]\w*Request\s*=\s*/g)]
+    if (declarations.length !== 1)
+        throw new Error(`Expected one Codex request type declaration, found ${declarations.length}`)
+    const declaration = declarations[0]
+    if (declaration?.index === undefined)
+        throw new Error('Unable to locate Codex request type declaration')
+    const body = source.slice(declaration.index + declaration[0].length).trim()
+    if (!body.endsWith(';'))
+        throw new Error('Codex request type declaration must end with a semicolon')
+    return body.slice(0, -1).trim()
+}
+
+function assertUniqueMethods(methods: string[], subject: string): void {
+    const seen = new Set<string>()
+    const duplicates = new Set<string>()
+    for (const method of methods) {
+        if (seen.has(method))
+            duplicates.add(method)
+        seen.add(method)
+    }
+    if (duplicates.size > 0)
+        throw new Error(`Duplicate methods in ${subject}: ${[...duplicates].join(', ')}`)
+}
+
+function parseNotificationEntries(source: string): MethodEntry[] {
+    const entryPattern = /"method": "([^"]+)"(?:, "params": (\w+(?: \| null)?))?/g
+    const entries: MethodEntry[] = []
+    for (const match of source.matchAll(entryPattern)) {
+        const method = match[1]
+        if (!method)
+            continue
+        entries.push({ method, paramsType: match[2]?.trim() })
+    }
+    return entries
+}
+
+function renderMeta({
+    upstreamRef,
+    generatedSchemaNames,
+    clientRequests,
+    clientNotifications,
+    serverRequests,
+    serverNotifications,
+}: {
+    upstreamRef: string
+    generatedSchemaNames: Set<string>
+    clientRequests: MethodEntry[]
+    clientNotifications: MethodEntry[]
+    serverRequests: MethodEntry[]
+    serverNotifications: MethodEntry[]
+}): string {
+    const clientResponses = responseEntries(clientRequests, generatedSchemaNames)
+    const serverResponses = responseEntries(serverRequests, generatedSchemaNames)
+    return [
+        '/* eslint-disable style/indent, style/member-delimiter-style, style/quotes, style/semi, style/quote-props */',
+        '// This file is generated by scripts/generate-codex-protocol.ts. Do not edit manually.',
+        `// Upstream Codex protocol ref: ${upstreamRef}`,
+        '',
+        'import type * as CodexSchema from "./schema.gen.js";',
+        '',
+        renderMethodConstants('CLIENT_REQUEST_METHODS', clientRequests),
+        renderMethodConstants('CLIENT_NOTIFICATION_METHODS', clientNotifications),
+        renderMethodConstants('SERVER_REQUEST_METHODS', serverRequests),
+        renderMethodConstants('SERVER_NOTIFICATION_METHODS', serverNotifications),
+        'export type ClientRequestMethod = keyof typeof CLIENT_REQUEST_METHODS;',
+        'export type ClientNotificationMethod = keyof typeof CLIENT_NOTIFICATION_METHODS;',
+        'export type ServerRequestMethod = keyof typeof SERVER_REQUEST_METHODS;',
+        'export type ServerNotificationMethod = keyof typeof SERVER_NOTIFICATION_METHODS;',
+        '',
+        renderTypeInterface('ClientRequestParamsByMethod', clientRequests, entry =>
+            resolveParamsTypeReference(entry.paramsType ?? 'undefined', generatedSchemaNames)),
+        renderTypeInterface('ClientRequestResponsesByMethod', clientResponses, entry =>
+            renderSchemaTypeReference(entry.responseType)),
+        renderTypeInterface('ClientNotificationParamsByMethod', clientNotifications, entry =>
+            resolveParamsTypeReference(entry.paramsType ?? 'undefined', generatedSchemaNames)),
+        renderTypeInterface('ServerRequestParamsByMethod', serverRequests, entry =>
+            resolveParamsTypeReference(entry.paramsType ?? 'undefined', generatedSchemaNames)),
+        renderTypeInterface('ServerRequestResponsesByMethod', serverResponses, entry =>
+            renderSchemaTypeReference(entry.responseType)),
+        renderTypeInterface('ServerNotificationParamsByMethod', serverNotifications, entry =>
+            resolveParamsTypeReference(entry.paramsType ?? 'undefined', generatedSchemaNames)),
+    ].join('\n')
+}
+
+function renderNamespaces(upstreamRef: string, jsonSchemaFiles: JsonSchemaFile[]): string {
+    const namespaceGroups = new Map<string, JsonSchemaFile[]>()
+    for (const file of jsonSchemaFiles) {
+        if (!file.namespace)
+            continue
+        const current = namespaceGroups.get(file.namespace) ?? []
+        current.push(file)
+        namespaceGroups.set(file.namespace, current)
+    }
+
+    return [
+        '/* eslint-disable style/indent, style/quotes, style/semi, style/quote-props */',
+        '// This file is generated by scripts/generate-codex-protocol.ts. Do not edit manually.',
+        `// Upstream Codex protocol ref: ${upstreamRef}`,
+        '',
+        ...[...namespaceGroups.entries()]
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([namespace, files]) => [
+                `export const ${namespace.replace(/[^A-Z0-9]/gi, '')} = {`,
+                ...files
+                    .sort((left, right) => left.fileName.localeCompare(right.fileName))
+                    .map(file => `  ${JSON.stringify(file.fileName.replace(/\.json$/, ''))}: ${JSON.stringify(file.exportName)},`),
+                '} as const;',
+                '',
+            ].join('\n')),
+    ].join('\n')
+}
+
+function responseEntries(requestEntries: MethodEntry[], generatedSchemaNames: Set<string>): ResponseEntry[] {
+    return requestEntries.map(entry => ({
+        method: entry.method,
+        responseType: resolveResponseTypeName(entry.method, entry.paramsType, generatedSchemaNames),
+    }))
+}
+
+function resolveSchemaTypeName(rawTypeName: string, generatedSchemaNames: Set<string>): string {
+    if (rawTypeName === 'undefined')
+        return 'undefined'
+    const resolved = schemaTypeCandidates(rawTypeName, false)
+        .find(candidate => generatedSchemaNames.has(candidate))
+    if (resolved)
+        return resolved
+    throw new Error(`Unable to resolve schema type name: ${rawTypeName}`)
+}
+
+function resolveParamsTypeReference(rawTypeName: string, generatedSchemaNames: Set<string>): string {
+    const parsed = parseSupportedParamsType(rawTypeName)
+    if (!parsed.typeName)
+        return 'undefined'
+
+    const candidates = parsed.includesNull
+        ? schemaTypeCandidates(parsed.typeName, true)
+        : [
+                ...schemaTypeCandidates(parsed.typeName, false),
+                ...(parsed.includesUndefined ? schemaTypeCandidates(parsed.typeName, true) : []),
+            ]
+    const schemaName = candidates.find(candidate => generatedSchemaNames.has(candidate))
+    if (!schemaName)
+        throw new Error(`Unable to resolve schema type name: ${rawTypeName}`)
+    const typeReference = renderSchemaTypeReference(schemaName)
+    return parsed.includesUndefined ? `${typeReference} | undefined` : typeReference
+}
+
+function schemaTypeCandidates(typeName: string, nullable: boolean): string[] {
+    return nullable
+        ? [`V2Nullable${typeName}`, `V1Nullable${typeName}`]
+        : [typeName, `V2${typeName}`, `V1${typeName}`, `SerdeJson${typeName}`]
+}
+
+function parseSupportedParamsType(rawTypeName: string): {
+    typeName: string | undefined
+    includesNull: boolean
+    includesUndefined: boolean
+} {
+    const parts = rawTypeName.split(/\s*\|\s*/)
+    if (parts.some(part => !/^[A-Z_$][\w$]*$/i.test(part)))
+        throw new Error(`Unsupported Codex params type syntax: ${rawTypeName}`)
+    if (new Set(parts).size !== parts.length)
+        throw new Error(`Duplicate Codex params type member: ${rawTypeName}`)
+
+    const typeNames = parts.filter(part => part !== 'null' && part !== 'undefined')
+    if (typeNames.length > 1)
+        throw new Error(`Unsupported Codex params type union: ${rawTypeName}`)
+    const includesNull = parts.includes('null')
+    const includesUndefined = parts.includes('undefined')
+    if (typeNames.length === 0 && (includesNull || !includesUndefined))
+        throw new Error(`Unsupported Codex params type union: ${rawTypeName}`)
+    return { typeName: typeNames[0], includesNull, includesUndefined }
+}
+
+function resolveResponseTypeName(method: string, paramsType: string | undefined, generatedSchemaNames: Set<string>): string {
+    const overrides: { [method: string]: string } = {
+        'account/logout': 'LogoutAccountResponse',
+        'account/rateLimits/read': 'GetAccountRateLimitsResponse',
+        'account/usage/read': 'GetAccountTokenUsageResponse',
+        'account/workspaceMessages/read': 'GetWorkspaceMessagesResponse',
+        'config/batchWrite': 'ConfigWriteResponse',
+        'config/mcpServer/reload': 'McpServerRefreshResponse',
+        'config/value/write': 'ConfigWriteResponse',
+        'configRequirements/read': 'ConfigRequirementsReadResponse',
+        'externalAgentConfig/import/readHistories': 'ExternalAgentConfigImportHistoriesReadResponse',
+        'windowsSandbox/readiness': 'WindowsSandboxReadinessResponse',
+    }
+
+    const override = overrides[method]
+    if (override)
+        return resolveSchemaTypeName(override, generatedSchemaNames)
+
+    if (paramsType && paramsType !== 'undefined') {
+        try {
+            const responseType = parseSupportedParamsType(paramsType).typeName?.replace(/Params$/, 'Response')
+            if (responseType)
+                return resolveSchemaTypeName(responseType, generatedSchemaNames)
+        }
+        catch {}
+    }
+    return resolveSchemaTypeName(`${toPascalCaseMethod(method)}Response`, generatedSchemaNames)
+}
+
+function toPascalCaseMethod(method: string): string {
+    return method
+        .split('/')
+        .flatMap(segment => segment.split(/(?=[A-Z])/))
+        .flatMap(segment => segment.split(/[-_]/))
+        .filter(segment => segment.length > 0)
+        .map(toPascalSegment)
+        .join('')
+}
+
+function toPascalSegment(segment: string): string {
+    const first = segment[0]
+    if (!first)
+        return ''
+    return `${first.toUpperCase()}${segment.slice(1)}`
+}
+
+function renderMethodConstants(name: string, entries: MethodEntry[]): string {
+    return [
+        `export const ${name} = {`,
+        ...entries.map(entry => `  ${JSON.stringify(entry.method)}: ${JSON.stringify(entry.method)},`),
+        '} as const;',
+        '',
+    ].join('\n')
+}
+
+function renderTypeInterface<TEntry extends { method: string }>(name: string, entries: TEntry[], typeName: (entry: TEntry) => string): string {
+    return [
+        `export interface ${name} {`,
+        ...entries.map(entry => `  readonly ${JSON.stringify(entry.method)}: ${typeName(entry)};`),
+        '}',
+        '',
+    ].join('\n')
+}
+
+function renderSchemaTypeReference(schemaName: string): string {
+    return schemaName === 'undefined' ? 'undefined' : `CodexSchema.${schemaName}`
+}
+
+function isJsonObject(value: unknown): value is { [key: string]: unknown } {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+}