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

package/dist/assets/codex-home/AGENTS.md

@@ -0,0 +1,50 @@
+## Merge Request and Pull Request Workflow
+
+- When code changes are complete, commit the changes, push a `feat/*` or `fix/*` branch, and create the corresponding merge request or pull request by default.
+- After creating a merge request or pull request, include the created MR/PR link in the response.
+- For GitLab merge request titles and descriptions, use the user's original language.
+- For GitHub pull request titles and descriptions, always use English.
+
+## Response Style
+
+- Reply in the same language the user used in their message. If the user writes in Chinese, answer in Chinese; if in English, answer in English.
+- When referencing workspace files or directories in a response, you may use Markdown links whose targets are absolute paths. The Matrix client opens these links in the current room workspace.
+
+## Hosting Tools
+
+- Repositories hosted on `git.easyops.local` are internal GitLab projects. Use `glab` for merge requests and other GitLab operations.
+- Repositories hosted on `github.com` are GitHub projects. Use `gh` for pull requests and other GitHub operations.
+- When creating or updating merge requests or pull requests with multiline Markdown bodies, do not pass the body directly inside a shell double-quoted argument. Markdown backticks and `$...` can be interpreted by the shell and corrupt the description. Write the body to a temporary file with a single-quoted heredoc first. For `gh`, pass the file with `--body-file <file>`. For the currently installed `glab`, which does not support `--description-file`, pass the file contents through a variable or command substitution, for example `body=$(cat "$file"); glab mr create --description "$body"`; command substitution output is not re-parsed for Markdown backticks. When a temporary file is used for a merge request or pull request description, delete it after the create or update operation completes successfully.
+
+## Git Conventions
+
+- Use English Conventional Commits for commit messages.
+- When making a git commit for a Matrix chat request, set the commit author to the last user who asked for the commit-triggering work. If there is no known mapping from that Matrix user ID to a git author name and email, ask the user for the author identity before committing.
+- Unless the user explicitly asks for it, do not proactively run code formatting; commit hooks handle formatting automatically. If related files are formatted after a commit, that is expected behavior.
+
+### Matrix Git Authors
+
+By default, map git author from the Matrix user localpart, and always use `@easyops.cn` as the email domain suffix.
+
+Example: `@tom:m.elevo.vip` -> `tom <tom@easyops.cn>`.
+
+## Task Management
+
+- Managed task operations require explicit task-management capabilities from the agent runtime.
+- Unless the user explicitly requests another tracking method, use managed task tools by default to track and manage problems and requirements.
+- Prefer existing task records over assumptions before updating or continuing a managed task.
+- Do not invent missing requirements, plans, decisions, or completion status. Ask the user when task intent or state is ambiguous.
+- When creating or updating managed tasks, write the task title and task documents in the user's original language.
+- When the user asks an Agent assistant to plan or implement a managed task, set that task's `assignee` to the Agent assistant itself.
+- When starting execution for a managed task, update the task's `workdir` to the workspace directory where the implementation is being performed.
+- When continuing a managed task that already has `workdir`, work in that directory by default.
+- Keep task titles concise; put detailed requirements, plans, notes, and results in task documents when the runtime supports them.
+
+Supported task statuses:
+
+- `backlog`
+- `planned`
+- `in_progress`
+- `completed`
+
+Only mark a task as `completed` after the related merge request or pull request has been merged. Completing code changes and opening an MR/PR is not enough to mark the task as completed.

package/dist/codex.d.ts

@@ -0,0 +1,63 @@
+import type { AppServerEvent, SandboxMode, ThreadItem, ToolRequestUserInputResponse, TurnStartParams, Usage } from "./app-server-protocol.js";
+type SessionResult = {
+    thread: CodexThread;
+    sessionId: string | undefined;
+    isNewSession: boolean;
+};
+export type StreamedTurn = {
+    turnId: string;
+    events: AsyncIterable<AppServerEvent>;
+};
+type TurnRunOptions = {
+    signal?: AbortSignal;
+    collaborationMode?: TurnStartParams["collaborationMode"];
+};
+export declare class WorkdirNotFoundError extends Error {
+    path: string;
+    constructor(path: string);
+}
+export declare class CodexThread {
+    id: string;
+    private model;
+    private workingDirectory;
+    constructor(id: string, model: string, workingDirectory: string);
+    run(prompt: string, options?: TurnRunOptions): Promise<{
+        items: ThreadItem[];
+        finalResponse?: string;
+        usage?: Usage | null;
+    }>;
+    runStreamed(_prompt: string, options?: TurnRunOptions): Promise<StreamedTurn>;
+    steerStreamed(prompt: string, expectedTurnId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<StreamedTurn>;
+    continueWithUserInput(itemId: string, response: ToolRequestUserInputResponse, options?: {
+        signal?: AbortSignal;
+        sourceTurnId?: string;
+    }): Promise<StreamedTurn>;
+    submitPendingUserInput(itemId: string, response: ToolRequestUserInputResponse): Promise<string | undefined>;
+    interrupt(turnId: string): Promise<void>;
+    interruptPendingUserInput(turnId: string, itemId: string): Promise<void>;
+    private interruptStaleTurn;
+    private turnStartParams;
+    private eventsForTurn;
+}
+declare class SessionManager {
+    private sessions;
+    constructor();
+    getOrCreate(sessionId: string | undefined, botName: string | undefined | null, requestedWorkdir: string | undefined | null, requestedWorkspaceId: string | undefined | null, model: string, sandboxMode: SandboxMode, llmProxyBinding?: string): Promise<SessionResult>;
+    fork(source: {
+        threadId: string;
+        turnId: string;
+    }, botName: string | undefined | null, requestedWorkdir: string | undefined | null, requestedWorkspaceId: string | undefined | null, model: string, sandboxMode: SandboxMode, llmProxyBinding?: string): Promise<SessionResult>;
+    persist(sessionId: string, botName: string | undefined | null, workdir: string | undefined | null, workspaceId?: string | null, llmProxyBinding?: string): void;
+    bindingFor(sessionId: string | undefined): string | undefined;
+    workdirFor(sessionId: string | undefined): string | undefined;
+    hasSession(sessionId: string | undefined): boolean;
+    private resolveWorkdir;
+    private threadStartParams;
+    private threadResumeParams;
+    private threadForkParams;
+    private codexConfig;
+}
+export declare const sessionManager: SessionManager;
+export {};

package/dist/codex.js

@@ -0,0 +1,461 @@
+import { mkdirSync, existsSync } from "node:fs";
+import { appServerClient } from "./app-server-client.js";
+import { dynamicToolSpecs } from "./dynamic-tools.js";
+import { loadAllSessions, persistSession } from "./db.js";
+import { appConfig } from "./config.js";
+import { logger } from "@messenger-agent/shared/logger";
+import { resolveAgentWorkdir } from "@messenger-agent/shared/agent-workspaces";
+import { codexPlatformInstructions } from "./platform-instructions.js";
+export class WorkdirNotFoundError extends Error {
+    path;
+    constructor(path) {
+        super(`Workdir not found: ${path}`);
+        this.path = path;
+    }
+}
+export class CodexThread {
+    id;
+    model;
+    workingDirectory;
+    constructor(id, model, workingDirectory) {
+        this.id = id;
+        this.model = model;
+        this.workingDirectory = workingDirectory;
+    }
+    async run(prompt, options) {
+        const streamed = await this.runStreamed(prompt, options);
+        const items = new Map();
+        const completedItems = new Set();
+        let usage = null;
+        for await (const event of streamed.events) {
+            if (event.type === "item.started") {
+                if (!completedItems.has(event.item.id)) {
+                    items.set(event.item.id, event.item);
+                }
+            }
+            else if (event.type === "item.completed") {
+                completedItems.add(event.item.id);
+                items.set(event.item.id, event.item);
+            }
+            else if (event.type === "thread.tokenUsage.updated") {
+                usage = event.usage;
+            }
+            else if (event.type === "turn.failed") {
+                throw new Error(event.error.message);
+            }
+        }
+        const itemList = Array.from(items.values());
+        const finalResponse = itemList
+            .filter((item) => item.type === "agentMessage")
+            .map((item) => item.text)
+            .join("\n");
+        return { items: itemList, finalResponse: finalResponse || undefined, usage };
+    }
+    async runStreamed(_prompt, options) {
+        const response = await appServerClient.request("turn/start", this.turnStartParams(_prompt, options));
+        const turnId = response.turn.id;
+        return { turnId, events: this.eventsForTurn(turnId, response.turn, options?.signal) };
+    }
+    async steerStreamed(prompt, expectedTurnId, options) {
+        const params = {
+            threadId: this.id,
+            input: [{ type: "text", text: prompt }],
+            expectedTurnId,
+        };
+        const response = await appServerClient.request("turn/steer", params);
+        return {
+            turnId: response.turnId,
+            events: this.eventsForTurn(response.turnId, undefined, options?.signal, undefined, true),
+        };
+    }
+    async continueWithUserInput(itemId, response, options) {
+        const turnId = appServerClient.pendingUserInputTurnId(this.id, itemId);
+        if (!turnId) {
+            await this.interruptStaleTurn(options?.sourceTurnId);
+            return this.runStreamed(userInputResponsePrompt(itemId, response), options);
+        }
+        return {
+            turnId,
+            events: this.eventsForTurn(turnId, undefined, options?.signal, async () => {
+                const accepted = await appServerClient.respondToUserInput(this.id, itemId, response);
+                if (!accepted) {
+                    throw new Error(`No pending user input request found for item: ${itemId}`);
+                }
+            }),
+        };
+    }
+    async submitPendingUserInput(itemId, response) {
+        const turnId = appServerClient.pendingUserInputTurnId(this.id, itemId);
+        if (!turnId)
+            return undefined;
+        const accepted = await appServerClient.respondToUserInput(this.id, itemId, response);
+        if (!accepted)
+            return undefined;
+        return turnId;
+    }
+    async interrupt(turnId) {
+        await appServerClient.request("turn/interrupt", { threadId: this.id, turnId });
+    }
+    async interruptPendingUserInput(turnId, itemId) {
+        await this.interrupt(turnId);
+        appServerClient.discardPendingUserInput(this.id, itemId);
+    }
+    async interruptStaleTurn(turnId) {
+        if (!turnId)
+            return;
+        const response = await appServerClient.request("thread/read", {
+            threadId: this.id,
+            includeTurns: true,
+        });
+        const turn = response.thread.turns?.find((candidate) => candidate.id === turnId);
+        if (turn?.status === "inProgress") {
+            await this.interrupt(turnId);
+        }
+    }
+    turnStartParams(prompt, options) {
+        return {
+            threadId: this.id,
+            input: [{ type: "text", text: prompt, text_elements: [] }],
+            cwd: this.workingDirectory,
+            approvalPolicy: "never",
+            model: this.model,
+            ...(options?.collaborationMode ? { collaborationMode: options.collaborationMode } : null),
+        };
+    }
+    async *eventsForTurn(turnId, initialTurn, signal, beforeWait, emitStarted = false) {
+        const queue = [
+            ...(initialTurn || emitStarted
+                ? [
+                    { type: "thread.started", thread_id: this.id },
+                    { type: "turn.started", turn_id: turnId },
+                ]
+                : []),
+            ...(initialTurn ? eventsFromInitialTurn(initialTurn) : []),
+        ];
+        let done = initialTurn?.status === "completed" || initialTurn?.status === "failed" || initialTurn?.status === "interrupted";
+        let failure;
+        let stopped = false;
+        let wake = () => { };
+        const onNotification = ({ method, params }) => {
+            if (stopped)
+                return;
+            const event = notificationToEvent(method, params, this.id, turnId);
+            if (!event)
+                return;
+            queue.push(event);
+            if (event.type === "turn.completed" || event.type === "turn.failed") {
+                done = true;
+            }
+            wake();
+        };
+        const onExit = (err) => {
+            failure = err;
+            done = true;
+            wake();
+        };
+        const onAbort = () => {
+            stopped = true;
+            queue.length = 0;
+            done = true;
+            wake();
+        };
+        appServerClient.on("notification", onNotification);
+        appServerClient.on("exit", onExit);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        if (signal?.aborted)
+            onAbort();
+        try {
+            await beforeWait?.();
+            while (!done || queue.length > 0) {
+                while (queue.length > 0) {
+                    yield queue.shift();
+                }
+                if (done)
+                    break;
+                await new Promise((resolve) => {
+                    const timer = setTimeout(() => {
+                        wake = () => { };
+                        resolve();
+                    }, 50);
+                    wake = () => {
+                        clearTimeout(timer);
+                        wake = () => { };
+                        resolve();
+                    };
+                });
+            }
+            if (failure) {
+                yield { type: "error", message: failure.message };
+            }
+        }
+        finally {
+            appServerClient.off("notification", onNotification);
+            appServerClient.off("exit", onExit);
+            signal?.removeEventListener("abort", onAbort);
+        }
+    }
+}
+function userInputResponsePrompt(itemId, response) {
+    return [
+        `The user answered a previous request_user_input prompt (${itemId}), but the original pending tool request is no longer active.`,
+        "Continue the task using this answer:",
+        JSON.stringify(response, null, 2),
+    ].join("\n");
+}
+class SessionManager {
+    sessions = new Map();
+    constructor() {
+        for (const row of loadAllSessions()) {
+            this.sessions.set(row.sessionId, {
+                workdir: row.workdir,
+                botName: row.botName ?? "main",
+                llmProxyBinding: row.llmProxyBinding,
+            });
+        }
+        logger.info(`SessionManager: loaded ${this.sessions.size} persisted sessions`);
+    }
+    async getOrCreate(sessionId, botName, requestedWorkdir, requestedWorkspaceId, model, sandboxMode, llmProxyBinding) {
+        const targetWorkdir = this.resolveWorkdir(requestedWorkdir, requestedWorkspaceId);
+        if (sessionId) {
+            const stored = this.sessions.get(sessionId);
+            if (stored && stored.workdir === targetWorkdir) {
+                const effectiveLlmProxyBinding = stored.llmProxyBinding ?? llmProxyBinding;
+                const response = await appServerClient.request("thread/resume", this.threadResumeParams(sessionId, model, targetWorkdir, sandboxMode, effectiveLlmProxyBinding));
+                if (!stored.llmProxyBinding && effectiveLlmProxyBinding) {
+                    const updated = { ...stored, llmProxyBinding: effectiveLlmProxyBinding };
+                    this.sessions.set(sessionId, updated);
+                    persistSession({
+                        sessionId,
+                        botName: updated.botName,
+                        workdir: updated.workdir,
+                        createdAt: Date.now(),
+                        llmProxyBinding: effectiveLlmProxyBinding,
+                    });
+                }
+                return { thread: new CodexThread(response.thread.id, model, targetWorkdir), sessionId, isNewSession: false };
+            }
+        }
+        if (requestedWorkdir && !existsSync(targetWorkdir)) {
+            throw new WorkdirNotFoundError(targetWorkdir);
+        }
+        mkdirSync(targetWorkdir, { recursive: true });
+        const response = await appServerClient.request("thread/start", this.threadStartParams(model, targetWorkdir, sandboxMode, llmProxyBinding));
+        return {
+            thread: new CodexThread(response.thread.id, model, targetWorkdir),
+            sessionId: undefined,
+            isNewSession: true,
+        };
+    }
+    async fork(source, botName, requestedWorkdir, requestedWorkspaceId, model, sandboxMode, llmProxyBinding) {
+        const targetWorkdir = this.resolveWorkdir(requestedWorkdir, requestedWorkspaceId);
+        if (requestedWorkdir && !existsSync(targetWorkdir)) {
+            throw new WorkdirNotFoundError(targetWorkdir);
+        }
+        mkdirSync(targetWorkdir, { recursive: true });
+        const forkResponse = await appServerClient.request("thread/fork", this.threadForkParams(source.threadId, source.turnId, model, targetWorkdir, sandboxMode, llmProxyBinding));
+        const threadId = forkResponse.thread.id;
+        this.persist(threadId, botName, requestedWorkdir, requestedWorkspaceId, llmProxyBinding);
+        return {
+            thread: new CodexThread(threadId, model, targetWorkdir),
+            sessionId: threadId,
+            isNewSession: false,
+        };
+    }
+    persist(sessionId, botName, workdir, workspaceId, llmProxyBinding) {
+        const resolvedBotName = botName ?? "main";
+        const resolvedWorkdir = this.resolveWorkdir(workdir, workspaceId);
+        this.sessions.set(sessionId, { botName: resolvedBotName, workdir: resolvedWorkdir, llmProxyBinding });
+        persistSession({
+            sessionId,
+            botName: resolvedBotName,
+            workdir: resolvedWorkdir,
+            createdAt: Date.now(),
+            llmProxyBinding,
+        });
+    }
+    bindingFor(sessionId) {
+        return sessionId ? this.sessions.get(sessionId)?.llmProxyBinding : undefined;
+    }
+    workdirFor(sessionId) {
+        return sessionId ? this.sessions.get(sessionId)?.workdir : undefined;
+    }
+    hasSession(sessionId) {
+        return !!sessionId && this.sessions.has(sessionId);
+    }
+    resolveWorkdir(subpath, workspaceId) {
+        return resolveAgentWorkdir(appConfig, workspaceId, subpath);
+    }
+    threadStartParams(model, cwd, sandbox, llmProxyBinding) {
+        return {
+            model,
+            modelProvider: appConfig.codex.baseUrl ? "custom" : null,
+            cwd,
+            approvalPolicy: "never",
+            sandbox,
+            config: this.codexConfig(llmProxyBinding),
+            developerInstructions: codexPlatformInstructions,
+            dynamicTools: dynamicToolSpecs(),
+            experimentalRawEvents: false,
+            persistExtendedHistory: false,
+        };
+    }
+    threadResumeParams(threadId, model, cwd, sandbox, llmProxyBinding) {
+        return {
+            threadId,
+            model,
+            modelProvider: appConfig.codex.baseUrl ? "custom" : null,
+            cwd,
+            approvalPolicy: "never",
+            sandbox,
+            config: this.codexConfig(llmProxyBinding),
+            developerInstructions: codexPlatformInstructions,
+            excludeTurns: true,
+            persistExtendedHistory: false,
+        };
+    }
+    threadForkParams(threadId, lastTurnId, model, cwd, sandbox, llmProxyBinding) {
+        return {
+            threadId,
+            lastTurnId,
+            model,
+            modelProvider: appConfig.codex.baseUrl ? "custom" : null,
+            cwd,
+            approvalPolicy: "never",
+            sandbox,
+            config: this.codexConfig(llmProxyBinding),
+            developerInstructions: codexPlatformInstructions,
+            ephemeral: false,
+            excludeTurns: true,
+        };
+    }
+    codexConfig(llmProxyBinding) {
+        return {
+            approval_policy: "never",
+            ...(appConfig.codex.baseUrl
+                ? {
+                    model_provider: "custom",
+                    model_reasoning_effort: "medium",
+                    disable_response_storage: true,
+                    model_providers: {
+                        custom: {
+                            name: "custom",
+                            base_url: appConfig.codex.baseUrl,
+                            wire_api: "responses",
+                            ...(appConfig.codex.apiKey ? { env_key: "OPENAI_API_KEY" } : null),
+                            ...(llmProxyBinding ? { http_headers: { "X-Elevo-LLM-Binding": llmProxyBinding } } : null),
+                        },
+                    },
+                    "features.default_mode_request_user_input": true,
+                }
+                : null),
+        };
+    }
+}
+if (appConfig.codex.apiKey && !process.env.OPENAI_API_KEY) {
+    process.env.OPENAI_API_KEY = appConfig.codex.apiKey;
+}
+function eventsFromInitialTurn(turn) {
+    const events = [];
+    for (const item of turn.items ?? []) {
+        events.push({ type: "item.completed", item });
+    }
+    if (turn.status === "completed") {
+        events.push({ type: "turn.completed" });
+    }
+    else if (turn.status === "failed") {
+        events.push({ type: "turn.failed", error: { message: turn.error?.message ?? "Codex turn failed" } });
+    }
+    return events;
+}
+function notificationToEvent(method, params, expectedThreadId, expectedTurnId) {
+    const record = params;
+    if (!record)
+        return undefined;
+    const threadId = record.threadId;
+    const turnId = record.turnId;
+    if (typeof threadId === "string" && threadId !== expectedThreadId)
+        return undefined;
+    if (typeof turnId === "string" && turnId !== expectedTurnId)
+        return undefined;
+    if (method === "item/started" && isThreadItem(record.item)) {
+        return { type: "item.started", item: record.item };
+    }
+    if (method === "item/completed" && isThreadItem(record.item)) {
+        return { type: "item.completed", item: record.item };
+    }
+    if (method === "item/agentMessage/delta") {
+        return deltaEvent(record, "agentMessage");
+    }
+    if (method === "item/reasoning/summaryTextDelta" || method === "item/reasoning/textDelta") {
+        return deltaEvent(record, "reasoning");
+    }
+    if (method === "item/plan/delta") {
+        return deltaEvent(record, "plan");
+    }
+    if (method === "item/tool/requestUserInput") {
+        return { type: "item.tool.requestUserInput", params: record };
+    }
+    if (method === "turn/diff/updated" && typeof record.diff === "string") {
+        return { type: "turn.diff.updated", diff: record.diff };
+    }
+    if (method === "thread/tokenUsage/updated") {
+        return { type: "thread.tokenUsage.updated", usage: usageFromTokenUsageUpdate(record) };
+    }
+    if (method === "turn/completed") {
+        const turn = record.turn;
+        if (turn?.status === "failed") {
+            return { type: "turn.failed", error: { message: turn.error?.message ?? "Codex turn failed" } };
+        }
+        return { type: "turn.completed" };
+    }
+    if (method === "error") {
+        console.error("Received error notification from app-server:", record);
+        return { type: "error", message: errorMessageFromRecord(record) };
+    }
+    return undefined;
+}
+function errorMessageFromRecord(record) {
+    const nestedError = record.error;
+    const message = nestedError && typeof nestedError === "object" && "message" in nestedError
+        ? nestedError.message
+        : undefined;
+    const details = record.additionalDetails;
+    const messageText = typeof message === "string" && message.trim() ? message : "Codex app-server error";
+    if (typeof details === "string" && details.trim()) {
+        return `${messageText}: ${details}`;
+    }
+    return messageText;
+}
+function deltaEvent(record, itemType) {
+    if (typeof record.itemId !== "string" || typeof record.delta !== "string")
+        return undefined;
+    return { type: "item.delta", item_id: record.itemId, item_type: itemType, delta: record.delta };
+}
+function usageFromTokenUsageUpdate(record) {
+    const tokenUsage = record.tokenUsage;
+    if (!tokenUsage || typeof tokenUsage !== "object")
+        return null;
+    const usage = tokenUsage;
+    const total = usage.total;
+    const last = usage.last;
+    if (!total || typeof total !== "object" || !last || typeof last !== "object")
+        return null;
+    const breakdown = (value) => {
+        const fields = value;
+        return {
+            input_tokens: typeof fields.inputTokens === "number" ? fields.inputTokens : undefined,
+            output_tokens: typeof fields.outputTokens === "number" ? fields.outputTokens : undefined,
+            total_tokens: typeof fields.totalTokens === "number" ? fields.totalTokens : undefined,
+        };
+    };
+    const modelContextWindow = usage.modelContextWindow;
+    return {
+        total: breakdown(total),
+        last: breakdown(last),
+        model_context_window: typeof modelContextWindow === "number" ? modelContextWindow : undefined,
+    };
+}
+function isThreadItem(item) {
+    return Boolean(item && typeof item === "object" && "type" in item && "id" in item);
+}
+export const sessionManager = new SessionManager();

package/dist/config.d.ts

@@ -0,0 +1,32 @@
+import { type AgentAuthConfig, type AgentWorkspacesConfig, type GitInitConfig } from "@messenger-agent/shared/agent-config";
+import { type LogLevel } from "@messenger-agent/shared/logger";
+export type AppConfig = {
+    configPath: string;
+    logLevel: LogLevel;
+    logFile?: string;
+    port: number;
+    fileUploads: {
+        tempDir: string;
+    };
+    dataDir: string;
+    sessionsDbPath: string;
+    codex: {
+        apiKey?: string;
+        baseUrl?: string;
+    };
+    openai: {
+        apiKey?: string;
+        baseUrl?: string;
+        imageModel: string;
+    };
+    tunnel: {
+        enabled: boolean;
+        serverUrl?: string;
+        tunnelId?: string;
+        token?: string;
+        reconnectInitialMs: number;
+        reconnectMaxMs: number;
+        heartbeatIntervalMs: number;
+    };
+} & GitInitConfig & AgentAuthConfig & AgentWorkspacesConfig;
+export declare const appConfig: AppConfig;