@meistrari/agent-core 0.0.0 → 0.1.0

package/src/agents/codex/codex-json-rpc-client.ts

@@ -0,0 +1,326 @@
+import type { ChildProcessWithoutNullStreams } from 'node:child_process'
+import type {
+    ClientNotificationMethod,
+    ClientNotificationParamsByMethod,
+    ClientRequestMethod,
+    ClientRequestParamsByMethod,
+    ClientRequestResponsesByMethod,
+    ServerNotificationMethod,
+    ServerNotificationParamsByMethod,
+    ServerRequestMethod,
+    ServerRequestParamsByMethod,
+} from './codex-protocol'
+import { spawn } from 'node:child_process'
+import { createInterface } from 'node:readline'
+import { CodexJsonRpcResponseError, CodexJsonRpcTransportClosedError } from './codex.errors'
+
+type JsonRpcId = string | number | null
+
+export type CodexServerNotification = {
+    [Method in ServerNotificationMethod]: {
+        id?: undefined
+        method: Method
+        params: ServerNotificationParamsByMethod[Method]
+    }
+}[ServerNotificationMethod]
+
+export type CodexServerRequest = {
+    [Method in ServerRequestMethod]: {
+        id: JsonRpcId
+        method: Method
+        params: ServerRequestParamsByMethod[Method]
+    }
+}[ServerRequestMethod]
+
+interface CodexClientResponse {
+    id: JsonRpcId
+    method?: undefined
+    params?: undefined
+    result?: unknown
+    error?: unknown
+}
+
+export type CodexJsonRpcMessage = CodexServerNotification | CodexServerRequest | CodexClientResponse
+
+export function isCodexServerRequest(message: CodexJsonRpcMessage): message is CodexServerRequest {
+    return message.method !== undefined && message.id !== undefined
+}
+
+export function isCodexServerNotification(message: CodexJsonRpcMessage): message is CodexServerNotification {
+    return message.method !== undefined && message.id === undefined
+}
+
+const PROCESS_SHUTDOWN_GRACE_MS = 5_000
+
+export { CodexJsonRpcResponseError } from './codex.errors'
+
+export class CodexJsonRpcClient {
+    readonly child: ChildProcessWithoutNullStreams
+    private nextId = 0
+    private stopped = false
+    private readonly closed: Promise<void>
+    private readonly pending = new Map<string, {
+        method: ClientRequestMethod
+        resolve: (value: unknown) => void
+        reject: (error: Error) => void
+    }>()
+
+    constructor(
+        executable: string,
+        options: {
+            cwd: string
+            environment?: Record<string, string | undefined>
+            onMessage: (message: CodexJsonRpcMessage) => void
+            onInvalidLine: (line: string, error: unknown) => void
+            onStderr: (line: string) => void
+        },
+    ) {
+        this.child = spawn(executable, ['app-server', '--listen', 'stdio://'], {
+            cwd: options.cwd,
+            env: options.environment,
+            stdio: 'pipe',
+        })
+        this.closed = new Promise(resolve => this.child.once('close', () => resolve()))
+
+        this.child.on('error', (error) => {
+            // The process never started, so no buffered request reached a live Codex: before_write.
+            // The client is also terminal — later requests must reject immediately, never hang.
+            this.stopped = true
+            for (const [, waiter] of this.pending) {
+                waiter.reject(new CodexJsonRpcTransportClosedError({
+                    method: waiter.method,
+                    writeState: 'before_write',
+                    message: `Codex app-server process failed to start (${executable}).`,
+                    cause: error,
+                }))
+            }
+            this.pending.clear()
+        })
+
+        this.child.on('close', (code, signal) => {
+            this.stopped = true
+            if (this.pending.size === 0)
+                return
+            // The request was written to a live process that died before responding: the input may
+            // already have been consumed, so non-delivery cannot be proven (possible_write).
+            for (const [, waiter] of this.pending) {
+                waiter.reject(new CodexJsonRpcTransportClosedError({
+                    method: waiter.method,
+                    writeState: 'possible_write',
+                    message: `Codex app-server closed before responding (exit ${code ?? 'null'}, signal ${signal ?? 'null'}).`,
+                }))
+            }
+            this.pending.clear()
+        })
+
+        // stdin can error independently of process exit (e.g. EPIPE when the child closed its
+        // read end); unhandled it would crash the host process, and any written request is
+        // unprovable: possible_write.
+        this.child.stdin.on('error', (error) => {
+            this.stopped = true
+            for (const [, waiter] of this.pending) {
+                waiter.reject(new CodexJsonRpcTransportClosedError({
+                    method: waiter.method,
+                    writeState: 'possible_write',
+                    message: 'Codex app-server stdin failed.',
+                    cause: error,
+                }))
+            }
+            this.pending.clear()
+        })
+
+        readLines(this.child.stdout, (line) => {
+            if (this.stopped)
+                return
+            try {
+                const parsed = JSON.parse(line) as CodexJsonRpcMessage
+                this.handleMessage(parsed, options.onMessage)
+            }
+            catch (error) {
+                if (!this.stopped)
+                    options.onInvalidLine(line, error)
+            }
+        })
+        readLines(this.child.stderr, (line) => {
+            if (!this.stopped)
+                options.onStderr(line)
+        })
+    }
+
+    async request<M extends ClientRequestMethod>(
+        method: M,
+        params: ClientRequestParamsByMethod[M],
+    ): Promise<ClientRequestResponsesByMethod[M]> {
+        if (this.stopped)
+            throw closedClientError(method, 'before_write')
+
+        const id = this.nextId
+        this.nextId += 1
+
+        return await new Promise<ClientRequestResponsesByMethod[M]>((resolve, reject) => {
+            // Register the waiter before the write: a close/error racing the write must find and
+            // reject it instead of leaving the request hanging forever.
+            this.pending.set(String(id), {
+                method,
+                resolve: value => resolve(value as ClientRequestResponsesByMethod[M]),
+                reject,
+            })
+            const settleWriteFailure = (cause: unknown) => {
+                const waiter = this.pending.get(String(id))
+                if (!waiter)
+                    return
+                this.pending.delete(String(id))
+                // A failed write attempt cannot prove zero bytes reached the process: possible_write.
+                waiter.reject(new CodexJsonRpcTransportClosedError({
+                    method,
+                    writeState: 'possible_write',
+                    message: 'Codex app-server stdin write failed.',
+                    cause,
+                }))
+            }
+            try {
+                this.child.stdin.write(`${JSON.stringify({ id, method, params })}\n`, (error: Error | null | undefined) => {
+                    if (error)
+                        settleWriteFailure(error)
+                })
+            }
+            catch (error) {
+                settleWriteFailure(error)
+            }
+        })
+    }
+
+    notify<M extends ClientNotificationMethod>(method: M, params: ClientNotificationParamsByMethod[M]): void {
+        if (this.stopped)
+            return
+        this.write(params === undefined ? { method } : { method, params })
+    }
+
+    respond(id: JsonRpcId, result: unknown): void {
+        if (this.stopped)
+            return
+        this.write({ id, result })
+    }
+
+    respondError(id: JsonRpcId, error: { code: number, message: string }): void {
+        if (this.stopped)
+            return
+        this.write({ id, error })
+    }
+
+    async respondErrorAndFlush(id: JsonRpcId, error: { code: number, message: string }): Promise<void> {
+        if (this.stopped)
+            return
+        await this.writeAndFlush({ id, error })
+    }
+
+    async closeInputAndStop(): Promise<void> {
+        if (this.stopped) {
+            await this.closed
+            return
+        }
+        this.stopped = true
+        for (const waiter of this.pending.values()) {
+            waiter.reject(closedClientError(waiter.method, 'possible_write'))
+        }
+        this.pending.clear()
+        await endWritable(this.child.stdin)
+        if (await waitForClosed(this.closed, PROCESS_SHUTDOWN_GRACE_MS))
+            return
+        await terminateChild(this.child, this.closed)
+    }
+
+    async stop(): Promise<void> {
+        await this.closeInputAndStop()
+    }
+
+    private write(message: object): void {
+        if (this.stopped)
+            return
+        this.child.stdin.write(`${JSON.stringify(message)}\n`)
+    }
+
+    private async writeAndFlush(message: object): Promise<void> {
+        if (this.stopped)
+            return
+        await new Promise<void>((resolve, reject) => {
+            this.child.stdin.write(`${JSON.stringify(message)}\n`, (error: Error | null | undefined) => {
+                if (error)
+                    reject(error)
+                else
+                    resolve()
+            })
+        })
+    }
+
+    private handleMessage(message: CodexJsonRpcMessage, onMessage: (message: CodexJsonRpcMessage) => void): void {
+        if (message.id !== undefined && !message.method && ('result' in message || 'error' in message)) {
+            const waiter = this.pending.get(String(message.id))
+            if (!waiter)
+                return
+            this.pending.delete(String(message.id))
+            if ('error' in message) {
+                waiter.reject(new CodexJsonRpcResponseError({ method: waiter.method, responseError: message.error }))
+                return
+            }
+            waiter.resolve(message.result)
+            return
+        }
+
+        onMessage(message)
+    }
+}
+
+async function endWritable(stream: NodeJS.WritableStream): Promise<void> {
+    await new Promise<void>(resolve => stream.end(resolve))
+}
+
+async function terminateChild(child: ChildProcessWithoutNullStreams, closed: Promise<void>): Promise<void> {
+    if (child.exitCode !== null || child.signalCode !== null) {
+        await closed
+        return
+    }
+
+    child.kill('SIGINT')
+    if (await waitForClosed(closed, PROCESS_SHUTDOWN_GRACE_MS))
+        return
+
+    if (child.exitCode === null && child.signalCode === null)
+        child.kill('SIGTERM')
+    if (await waitForClosed(closed, PROCESS_SHUTDOWN_GRACE_MS))
+        return
+
+    if (child.exitCode === null && child.signalCode === null)
+        child.kill('SIGKILL')
+    await closed
+}
+
+async function waitForClosed(closed: Promise<void>, timeoutMs: number): Promise<boolean> {
+    return await new Promise<boolean>((resolve) => {
+        const timer = setTimeout(() => resolve(false), timeoutMs)
+        timer.unref?.()
+        void closed.then(
+            () => {
+                clearTimeout(timer)
+                resolve(true)
+            },
+            () => {
+                clearTimeout(timer)
+                resolve(false)
+            },
+        )
+    })
+}
+
+function closedClientError(method: ClientRequestMethod, writeState: 'before_write' | 'possible_write'): CodexJsonRpcTransportClosedError {
+    return new CodexJsonRpcTransportClosedError({ method, writeState, message: 'Codex app-server client is closed.' })
+}
+
+function readLines(stream: NodeJS.ReadableStream, onLine: (line: string) => void): void {
+    const rl = createInterface({ input: stream })
+    rl.on('line', (line) => {
+        const trimmed = line.trim()
+        if (trimmed)
+            onLine(trimmed)
+    })
+}

package/src/agents/codex/codex-protocol.ts

@@ -0,0 +1,36 @@
+import type {
+    ClientRequestParamsByMethod,
+    ServerRequestParamsByMethod,
+    ServerRequestResponsesByMethod,
+} from './generated/meta.gen'
+import type { V2ThreadStartParams__DynamicToolSpec, V2TurnStartParams__UserInput } from './generated/schema.gen'
+
+export type {
+    ClientNotificationMethod,
+    ClientNotificationParamsByMethod,
+    ClientRequestMethod,
+    ClientRequestParamsByMethod,
+    ClientRequestResponsesByMethod,
+    ServerNotificationMethod,
+    ServerNotificationParamsByMethod,
+    ServerRequestMethod,
+    ServerRequestParamsByMethod,
+    ServerRequestResponsesByMethod,
+} from './generated/meta.gen'
+
+export type CodexUserInput = V2TurnStartParams__UserInput
+export type CodexDynamicToolSpec = V2ThreadStartParams__DynamicToolSpec
+export type CodexDynamicToolCallParams = ServerRequestParamsByMethod['item/tool/call']
+export type CodexDynamicToolCallResponse = ServerRequestResponsesByMethod['item/tool/call']
+export type CodexDynamicToolOutputContentItem = CodexDynamicToolCallResponse['contentItems'][number]
+export type CodexLoginStartParams = ClientRequestParamsByMethod['account/login/start']
+export type CodexChatGPTAuthTokensRefreshParams = ServerRequestParamsByMethod['account/chatgptAuthTokens/refresh']
+export type CodexChatGPTAuthTokensRefreshResponse = ServerRequestResponsesByMethod['account/chatgptAuthTokens/refresh']
+
+export type CodexThreadStartParams = ClientRequestParamsByMethod['thread/start'] & {
+    dynamicTools?: readonly CodexDynamicToolSpec[] | null
+}
+export type CodexThreadResumeParams = ClientRequestParamsByMethod['thread/resume']
+export type CodexTurnStartParams = ClientRequestParamsByMethod['turn/start']
+export type CodexTurnSteerParams = ClientRequestParamsByMethod['turn/steer']
+export type CodexTurnInterruptParams = ClientRequestParamsByMethod['turn/interrupt']