@messenger-agent/codex-agent 0.24.0-alpha.2

package/dist/app-server-client.d.ts

@@ -0,0 +1,32 @@
+import { EventEmitter } from "node:events";
+import { handleDynamicToolCall } from "./dynamic-tools.js";
+import type { ToolRequestUserInputResponse } from "./app-server-protocol.js";
+type DynamicToolHandler = typeof handleDynamicToolCall;
+export declare function findCodexPath(): string;
+export declare class AppServerClient extends EventEmitter {
+    private toolHandler;
+    private child;
+    private nextId;
+    private pending;
+    private pendingUserInputRequests;
+    private notifiedUserInputRequests;
+    private answeredUserInputRequests;
+    private started;
+    private buffer;
+    constructor(toolHandler?: DynamicToolHandler);
+    request<T = unknown>(method: string, params: unknown): Promise<T>;
+    private writeRequest;
+    notify(method: string, params: unknown): Promise<void>;
+    respondToUserInput(threadId: string, itemId: string, response: ToolRequestUserInputResponse): Promise<boolean>;
+    pendingUserInputTurnId(threadId: string, itemId: string): string | undefined;
+    discardPendingUserInput(threadId: string, itemId: string): void;
+    private ensureStarted;
+    private start;
+    private handleStdout;
+    private handleMessage;
+    private handleServerRequest;
+    private handleExit;
+    private handleProcessError;
+}
+export declare const appServerClient: AppServerClient;
+export {};

package/dist/app-server-client.js

@@ -0,0 +1,316 @@
+import { spawn } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { statSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { handleDynamicToolCall, inheritManagedTaskToolContextFromNotification } from "./dynamic-tools.js";
+import { logger } from "@messenger-agent/shared/logger";
+const CODEX_NPM_NAME = "@openai/codex";
+const PLATFORM_PACKAGE_BY_TARGET = {
+    "x86_64-unknown-linux-musl": "@openai/codex-linux-x64",
+    "aarch64-unknown-linux-musl": "@openai/codex-linux-arm64",
+    "x86_64-apple-darwin": "@openai/codex-darwin-x64",
+    "aarch64-apple-darwin": "@openai/codex-darwin-arm64",
+    "x86_64-pc-windows-msvc": "@openai/codex-win32-x64",
+    "aarch64-pc-windows-msvc": "@openai/codex-win32-arm64",
+};
+const moduleRequire = createRequire(import.meta.url);
+export function findCodexPath() {
+    const { platform, arch } = process;
+    let targetTriple = null;
+    switch (platform) {
+        case "linux":
+        case "android":
+            if (arch === "x64")
+                targetTriple = "x86_64-unknown-linux-musl";
+            if (arch === "arm64")
+                targetTriple = "aarch64-unknown-linux-musl";
+            break;
+        case "darwin":
+            if (arch === "x64")
+                targetTriple = "x86_64-apple-darwin";
+            if (arch === "arm64")
+                targetTriple = "aarch64-apple-darwin";
+            break;
+        case "win32":
+            if (arch === "x64")
+                targetTriple = "x86_64-pc-windows-msvc";
+            if (arch === "arm64")
+                targetTriple = "aarch64-pc-windows-msvc";
+            break;
+        default:
+            break;
+    }
+    if (!targetTriple) {
+        throw new Error(`Unsupported platform: ${platform} (${arch})`);
+    }
+    const platformPackage = PLATFORM_PACKAGE_BY_TARGET[targetTriple];
+    if (!platformPackage) {
+        throw new Error(`Unsupported target triple: ${targetTriple}`);
+    }
+    let vendorRoot;
+    try {
+        const codexPackageJsonPath = moduleRequire.resolve(`${CODEX_NPM_NAME}/package.json`);
+        const codexRequire = createRequire(codexPackageJsonPath);
+        const platformPackageJsonPath = codexRequire.resolve(`${platformPackage}/package.json`);
+        vendorRoot = path.join(path.dirname(platformPackageJsonPath), "vendor");
+    }
+    catch {
+        throw new Error(`Unable to locate Codex CLI binaries. Ensure ${CODEX_NPM_NAME} is installed with optional dependencies.`);
+    }
+    const codexBinaryName = process.platform === "win32" ? "codex.exe" : "codex";
+    const nativePackage = resolveNativePackage(vendorRoot, targetTriple, codexBinaryName);
+    if (!nativePackage) {
+        throw new Error(`Unable to locate Codex CLI binaries for ${targetTriple}. Ensure ${CODEX_NPM_NAME} is installed with optional dependencies.`);
+    }
+    return nativePackage.executablePath;
+}
+function resolveNativePackage(vendorRoot, targetTriple, codexBinaryName) {
+    const packageRoot = path.join(vendorRoot, targetTriple);
+    const packageBinaryPath = path.join(packageRoot, "bin", codexBinaryName);
+    if (isFile(packageBinaryPath) && isFile(path.join(packageRoot, "codex-package.json"))) {
+        return {
+            executablePath: packageBinaryPath,
+            pathDirs: existingDirs(path.join(packageRoot, "codex-path")),
+        };
+    }
+    const legacyBinaryPath = path.join(packageRoot, "codex", codexBinaryName);
+    if (isFile(legacyBinaryPath)) {
+        return {
+            executablePath: legacyBinaryPath,
+            pathDirs: existingDirs(path.join(packageRoot, "path")),
+        };
+    }
+    return null;
+}
+function existingDirs(...dirs) {
+    return dirs.filter(isDirectory);
+}
+function isFile(filePath) {
+    try {
+        return statSync(filePath).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function isDirectory(filePath) {
+    try {
+        return statSync(filePath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function parseCommand(command) {
+    const trimmed = command.trim();
+    if (!trimmed)
+        return { command: "codex", args: ["app-server", "--listen", "stdio://"] };
+    const parts = trimmed.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? [];
+    const [cmd, ...args] = parts.map((part) => {
+        if ((part.startsWith('"') && part.endsWith('"')) || (part.startsWith("'") && part.endsWith("'"))) {
+            return part.slice(1, -1);
+        }
+        return part;
+    });
+    return { command: cmd ?? "codex", args };
+}
+export class AppServerClient extends EventEmitter {
+    toolHandler;
+    child;
+    nextId = 1;
+    pending = new Map();
+    pendingUserInputRequests = new Map();
+    notifiedUserInputRequests = new Set();
+    answeredUserInputRequests = new Set();
+    started;
+    buffer = "";
+    constructor(toolHandler = handleDynamicToolCall) {
+        super();
+        this.toolHandler = toolHandler;
+    }
+    async request(method, params) {
+        await this.ensureStarted();
+        return this.writeRequest(method, params);
+    }
+    async writeRequest(method, params) {
+        if (!this.child)
+            throw new Error("Codex app-server is not running");
+        const id = this.nextId++;
+        const payload = JSON.stringify({ jsonrpc: "2.0", id, method, params });
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve: (value) => resolve(value), reject });
+            this.child?.stdin.write(`${payload}\n`, (err) => {
+                if (err) {
+                    this.pending.delete(id);
+                    reject(err);
+                }
+            });
+        });
+    }
+    async notify(method, params) {
+        await this.ensureStarted();
+        if (!this.child)
+            throw new Error("Codex app-server is not running");
+        this.child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`);
+    }
+    async respondToUserInput(threadId, itemId, response) {
+        await this.ensureStarted();
+        if (!this.child)
+            throw new Error("Codex app-server is not running");
+        const key = userInputRequestKey(threadId, itemId);
+        if (this.answeredUserInputRequests.has(key)) {
+            throw new Error(`User input request already answered for item: ${itemId}`);
+        }
+        const pending = this.pendingUserInputRequests.get(key);
+        if (!pending)
+            return false;
+        this.pendingUserInputRequests.delete(key);
+        this.answeredUserInputRequests.add(key);
+        this.child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id: pending.requestId, result: response })}\n`);
+        return true;
+    }
+    pendingUserInputTurnId(threadId, itemId) {
+        return this.pendingUserInputRequests.get(userInputRequestKey(threadId, itemId))?.turnId;
+    }
+    discardPendingUserInput(threadId, itemId) {
+        const key = userInputRequestKey(threadId, itemId);
+        this.pendingUserInputRequests.delete(key);
+        this.notifiedUserInputRequests.delete(key);
+        this.answeredUserInputRequests.delete(key);
+    }
+    async ensureStarted() {
+        if (!this.started) {
+            this.started = this.start();
+        }
+        return this.started;
+    }
+    async start() {
+        const configured = process.env.CODEX_APP_SERVER_COMMAND;
+        const { command, args } = configured
+            ? parseCommand(configured)
+            : { command: findCodexPath(), args: ["app-server", "--listen", "stdio://"] };
+        const env = { ...process.env };
+        this.child = spawn(command, args, { env, stdio: ["pipe", "pipe", "pipe"] });
+        this.child.stdout.setEncoding("utf-8");
+        this.child.stderr.setEncoding("utf-8");
+        this.child.stdout.on("data", (chunk) => this.handleStdout(chunk));
+        this.child.stderr.on("data", (chunk) => logger.debug(`codex app-server stderr: ${chunk.trimEnd()}`));
+        this.child.on("exit", (code, signal) => this.handleExit(code, signal));
+        this.child.on("error", (err) => this.handleProcessError(err));
+        await this.writeRequest("initialize", {
+            clientInfo: { name: "codex-agent", title: "codex-agent", version: "0.1.0" },
+            capabilities: { experimentalApi: true, requestAttestation: false },
+        });
+    }
+    handleStdout(chunk) {
+        this.buffer += chunk;
+        while (true) {
+            const newline = this.buffer.indexOf("\n");
+            if (newline === -1)
+                break;
+            const line = this.buffer.slice(0, newline).trim();
+            this.buffer = this.buffer.slice(newline + 1);
+            if (!line)
+                continue;
+            try {
+                this.handleMessage(JSON.parse(line));
+            }
+            catch (err) {
+                logger.error("Failed to parse codex app-server JSON-RPC message:", err);
+            }
+        }
+    }
+    handleMessage(message) {
+        if (!message.method ||
+            !(message.method.endsWith("/delta") ||
+                message.method.endsWith("/outputDelta") ||
+                message.method === "turn/diff/updated")) {
+            logger.debug(`Received message:`, message);
+        }
+        if (message.id !== undefined && message.method) {
+            this.handleServerRequest(message).catch((err) => logger.error("Failed to handle app-server request:", err));
+            return;
+        }
+        if (message.id !== undefined) {
+            const pending = this.pending.get(message.id);
+            if (!pending)
+                return;
+            this.pending.delete(message.id);
+            if (message.error) {
+                pending.reject(new Error(message.error.message ?? `Codex app-server request failed: ${message.error.code}`));
+            }
+            else {
+                pending.resolve(message.result);
+            }
+            return;
+        }
+        if (message.method) {
+            inheritManagedTaskToolContextFromNotification(message.method, message.params);
+            this.emit("notification", { method: message.method, params: message.params });
+        }
+    }
+    async handleServerRequest(message) {
+        if (!this.child || message.id === undefined || !message.method)
+            return;
+        try {
+            if (message.method === "item/tool/call") {
+                const result = await this.toolHandler(message.params);
+                this.child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id: message.id, result })}\n`);
+                return;
+            }
+            if (message.method === "item/tool/requestUserInput") {
+                const requestParams = message.params;
+                const requestKey = userInputRequestKey(requestParams.threadId, requestParams.itemId);
+                this.pendingUserInputRequests.set(requestKey, {
+                    threadId: requestParams.threadId,
+                    turnId: requestParams.turnId,
+                    itemId: requestParams.itemId,
+                    requestId: message.id,
+                });
+                if (this.notifiedUserInputRequests.has(requestKey))
+                    return;
+                this.notifiedUserInputRequests.add(requestKey);
+                this.emit("notification", { method: message.method, params: requestParams });
+                return;
+            }
+            this.child.stdin.write(`${JSON.stringify({
+                jsonrpc: "2.0",
+                id: message.id,
+                error: { code: -32601, message: `Unsupported server request: ${message.method}` },
+            })}\n`);
+        }
+        catch (err) {
+            const messageText = err instanceof Error ? err.message : String(err);
+            this.child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id: message.id, error: { code: -32000, message: messageText } })}\n`);
+        }
+    }
+    handleExit(code, signal) {
+        const err = new Error(`Codex app-server exited${signal ? ` with signal ${signal}` : ` with code ${code}`}`);
+        for (const pending of this.pending.values()) {
+            pending.reject(err);
+        }
+        this.pending.clear();
+        this.pendingUserInputRequests.clear();
+        this.notifiedUserInputRequests.clear();
+        this.answeredUserInputRequests.clear();
+        this.child = undefined;
+        this.started = undefined;
+        this.emit("exit", err);
+    }
+    handleProcessError(err) {
+        for (const pending of this.pending.values()) {
+            pending.reject(err);
+        }
+        this.pending.clear();
+        this.pendingUserInputRequests.clear();
+        this.notifiedUserInputRequests.clear();
+        this.answeredUserInputRequests.clear();
+        this.emit("exit", err);
+    }
+}
+function userInputRequestKey(threadId, itemId) {
+    return `${threadId}:${itemId}`;
+}
+export const appServerClient = new AppServerClient();
+appServerClient.setMaxListeners(20);

package/dist/app-server-protocol.d.ts

@@ -0,0 +1,325 @@
+export type SandboxMode = "read-only" | "workspace-write" | "danger-full-access";
+export type UsageBreakdown = {
+    input_tokens?: number;
+    output_tokens?: number;
+    total_tokens?: number;
+};
+export type Usage = {
+    total?: UsageBreakdown;
+    last?: UsageBreakdown;
+    model_context_window?: number;
+};
+export type UserInput = {
+    type: "text";
+    text: string;
+    text_elements?: [];
+};
+export type DynamicToolSpec = {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+    namespace?: string;
+    deferLoading?: boolean;
+};
+export type ThreadStartParams = {
+    model?: string | null;
+    modelProvider?: string | null;
+    cwd?: string | null;
+    approvalPolicy?: "never" | "on-request" | "on-failure" | "untrusted" | null;
+    sandbox?: SandboxMode | null;
+    config?: Record<string, unknown> | null;
+    baseInstructions?: string | null;
+    developerInstructions?: string | null;
+    dynamicTools?: DynamicToolSpec[] | null;
+    experimentalRawEvents: boolean;
+    persistExtendedHistory: boolean;
+};
+export type ThreadResumeParams = {
+    threadId: string;
+    model?: string | null;
+    modelProvider?: string | null;
+    cwd?: string | null;
+    approvalPolicy?: "never" | "on-request" | "on-failure" | "untrusted" | null;
+    sandbox?: SandboxMode | null;
+    config?: Record<string, unknown> | null;
+    baseInstructions?: string | null;
+    developerInstructions?: string | null;
+    excludeTurns?: boolean;
+    persistExtendedHistory: boolean;
+};
+export type ThreadForkParams = {
+    threadId: string;
+    lastTurnId?: string | null;
+    model?: string | null;
+    modelProvider?: string | null;
+    cwd?: string | null;
+    approvalPolicy?: "never" | "on-request" | "on-failure" | "untrusted" | null;
+    sandbox?: SandboxMode | null;
+    config?: Record<string, unknown> | null;
+    baseInstructions?: string | null;
+    developerInstructions?: string | null;
+    ephemeral?: boolean;
+    excludeTurns?: boolean;
+};
+export type ThreadReadParams = {
+    threadId: string;
+    includeTurns?: boolean;
+};
+export type ThreadRollbackParams = {
+    threadId: string;
+    numTurns: number;
+};
+export type TurnStartParams = {
+    threadId: string;
+    input: UserInput[];
+    cwd?: string | null;
+    approvalPolicy?: "never" | "on-request" | "on-failure" | "untrusted" | null;
+    model?: string | null;
+    collaborationMode?: {
+        mode: "plan" | "default";
+        settings: {
+            model?: string | null;
+            reasoning_effort?: string | null;
+            developer_instructions: null;
+        };
+    } | null;
+};
+export type TurnInterruptParams = {
+    threadId: string;
+    turnId: string;
+};
+export type TurnSteerParams = {
+    threadId: string;
+    input: UserInput[];
+    expectedTurnId: string;
+};
+export type Thread = {
+    id: string;
+    turns?: Turn[];
+};
+export type Turn = {
+    id: string;
+    items: ThreadItem[];
+    status: "completed" | "interrupted" | "failed" | "inProgress";
+    error: {
+        message: string;
+    } | null;
+};
+export type CommandExecutionItem = {
+    type: "commandExecution";
+    id: string;
+    command: string;
+    status: "inProgress" | "completed" | "failed" | "declined";
+    aggregatedOutput: string | null;
+};
+export type FileChangeItem = {
+    type: "fileChange";
+    id: string;
+    changes: Array<{
+        path: string;
+        kind: {
+            type: "add" | "update" | "delete";
+            move_path: string | null;
+        };
+        diff?: string;
+    }>;
+    status: "inProgress" | "completed" | "failed" | "declined";
+};
+export type PlanItem = {
+    type: "plan";
+    id: string;
+    text: string;
+};
+export type McpToolCallItem = {
+    type: "mcpToolCall";
+    id: string;
+    server: string;
+    tool: string;
+    arguments: unknown;
+    status: "inProgress" | "completed" | "failed";
+    result: {
+        content?: unknown[];
+        structuredContent?: unknown;
+    } | null;
+    error: {
+        message: string;
+    } | null;
+};
+export type DynamicToolCallItem = {
+    type: "dynamicToolCall";
+    id: string;
+    namespace: string | null;
+    tool: string;
+    arguments: unknown;
+    status: "inProgress" | "completed" | "failed";
+    contentItems: Array<{
+        type: "inputText";
+        text: string;
+    } | {
+        type: "inputImage";
+        imageUrl: string;
+    }> | null;
+    success: boolean | null;
+};
+export type WebSearchAction = {
+    type: "search";
+    query?: string;
+    queries?: string[];
+} | {
+    type: "openPage";
+    url?: string;
+} | {
+    type: "findInPage";
+    url?: string;
+    pattern?: string;
+} | {
+    type: "other";
+};
+export type WebSearchItem = {
+    type: "webSearch";
+    id: string;
+    query: string;
+    action?: WebSearchAction;
+};
+export type ContextCompactionItem = {
+    type: "contextCompaction";
+    id: string;
+};
+export type SubAgentActivityItem = {
+    type: "subAgentActivity";
+    id: string;
+    kind: "started" | "interacted" | "interrupted";
+    agentThreadId: string;
+    agentPath: string;
+};
+export type CollabAgentStatus = "pendingInit" | "running" | "interrupted" | "completed" | "errored" | "shutdown" | "notFound";
+export type CollabAgentToolCallItem = {
+    type: "collabAgentToolCall";
+    id: string;
+    tool: string;
+    status: "inProgress" | "completed" | "failed";
+    senderThreadId: string;
+    receiverThreadIds: string[];
+    prompt: string | null;
+    model: string | null;
+    reasoningEffort: string | null;
+    agentsStates: Record<string, {
+        status: CollabAgentStatus;
+        message: string | null;
+    } | undefined>;
+};
+export type ThreadItem = {
+    type: "agentMessage";
+    id: string;
+    text: string;
+} | {
+    type: "reasoning";
+    id: string;
+    summary: string[];
+    content: string[];
+} | CommandExecutionItem | FileChangeItem | PlanItem | McpToolCallItem | DynamicToolCallItem | WebSearchItem | ContextCompactionItem | SubAgentActivityItem | CollabAgentToolCallItem;
+export type ItemDeltaEvent = {
+    type: "item.delta";
+    item_id: string;
+    item_type: "agentMessage" | "reasoning" | "plan";
+    delta: string;
+};
+export type AppServerEvent = {
+    type: "thread.started";
+    thread_id: string;
+} | {
+    type: "turn.started";
+    turn_id: string;
+} | {
+    type: "turn.diff.updated";
+    diff: string;
+} | {
+    type: "thread.tokenUsage.updated";
+    usage: Usage | null;
+} | {
+    type: "item.started";
+    item: ThreadItem;
+} | {
+    type: "item.updated";
+    item: ThreadItem;
+} | {
+    type: "item.delta";
+    item_id: string;
+    item_type: "agentMessage" | "reasoning" | "plan";
+    delta: string;
+} | {
+    type: "item.completed";
+    item: ThreadItem;
+} | {
+    type: "item.tool.requestUserInput";
+    params: ToolRequestUserInputParams;
+} | {
+    type: "turn.completed";
+} | {
+    type: "turn.failed";
+    error: {
+        message: string;
+    };
+} | {
+    type: "error";
+    message: string;
+};
+export type DynamicToolCallParams = {
+    threadId: string;
+    turnId: string;
+    callId: string;
+    namespace: string | null;
+    tool: string;
+    arguments: unknown;
+};
+export type DynamicToolCallResponse = {
+    contentItems: Array<{
+        type: "inputText";
+        text: string;
+    } | {
+        type: "inputImage";
+        imageUrl: string;
+    }>;
+    success: boolean;
+};
+/**
+ * EXPERIMENTAL. Params sent with a request_user_input event.
+ */
+export type ToolRequestUserInputParams = {
+    threadId: string;
+    turnId: string;
+    itemId: string;
+    questions: Array<ToolRequestUserInputQuestion>;
+};
+/**
+ * EXPERIMENTAL. Params sent with a request_user_input event.
+ */
+export type ToolRequestUserInputQuestion = {
+    id: string;
+    header: string;
+    question: string;
+    isOther: boolean;
+    isSecret: boolean;
+    options: Array<ToolRequestUserInputOption> | null;
+};
+/**
+ * EXPERIMENTAL. Defines a single selectable option for request_user_input.
+ */
+export type ToolRequestUserInputOption = {
+    label: string;
+    description: string;
+};
+/**
+ * EXPERIMENTAL. Response payload mapping question ids to answers.
+ */
+export type ToolRequestUserInputResponse = {
+    answers: {
+        [key in string]?: ToolRequestUserInputAnswer;
+    };
+};
+/**
+ * EXPERIMENTAL. Captures a user's answer to a request_user_input question.
+ */
+export type ToolRequestUserInputAnswer = {
+    answers: Array<string>;
+};

package/dist/app-server-protocol.js

@@ -0,0 +1 @@
+export {};

package/dist/app.d.ts

@@ -0,0 +1,3 @@
+import { Hono } from "hono";
+declare const app: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+export default app;

package/dist/app.js

@@ -0,0 +1,15 @@
+import { Hono } from "hono";
+import { logger as honoLogger } from "hono/logger";
+import chat from "./routes/chat.js";
+import { logger } from "@messenger-agent/shared/logger";
+import { agentAuthMiddleware } from "@messenger-agent/shared/agent-auth";
+import { appConfig } from "./config.js";
+import { installAgentActivityResponder } from "@messenger-agent/shared/agent-activity";
+import { codexActivitySnapshot } from "./routes/chat.js";
+const app = new Hono();
+installAgentActivityResponder("codex", codexActivitySnapshot);
+app.use(honoLogger((str, ...rest) => logger.info(str, ...rest)));
+app.get("/health", (c) => c.json({ status: "ok" }));
+app.use("/*", agentAuthMiddleware(appConfig.authTokens));
+app.route("/", chat);
+export default app;