@abitat_reece/host-daemon 0.1.9 → 0.1.11

package/dist/local-control/codex-bridge.js

@@ -1,8 +1,10 @@
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
-import { basename, normalize } from "node:path";
+import { readFile, stat } from "node:fs/promises";
+import { basename, extname, isAbsolute, join, normalize } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import WebSocket from "ws";
+import { attachmentDiagnostics, errorDiagnostics, logDiagnostics, promptDiagnostics } from "./diagnostics-log.js";
 const CODEX_PROJECT_PREFIX = "codex_project_";
 const CODEX_THREAD_PREFIX = "codex_thread_";
 const DEFAULT_SERVER_URL = "ws://127.0.0.1:47777";
@@ -10,7 +12,10 @@ const DEFAULT_CODEX_BINARY = "/Applications/Codex.app/Contents/Resources/codex";
 const REQUEST_TIMEOUT_MS = 30_000;
 const START_TIMEOUT_MS = 15_000;
 const TURN_KEEPALIVE_TIMEOUT_MS = 30 * 60_000;
+const QUEUED_TURN_POLL_INTERVAL_MS = 250;
+const THREAD_LIST_CACHE_TTL_MS = 2_500;
 const MAX_CODEX_MESSAGE_CONTENT_LENGTH = 12_000;
+const HIDDEN_CODEX_ITEM_TYPES = new Set(["reasoning"]);
 const PHONE_FULL_ACCESS_TURN_OPTIONS = {
     approvalPolicy: "never",
     sandboxPolicy: { type: "dangerFullAccess" }
@@ -27,14 +32,38 @@ export class LocalCodexConversationBusyError extends Error {
 }
 export function createLocalCodexBridge(options = {}) {
     const client = createCodexAppClient(options);
+    const diagnostics = options.diagnostics;
     const workspaceId = options.workspaceId ?? "local";
     const userId = options.userId ?? "local";
+    const queuedTurnsByThread = new Map();
+    const queueDrainTimers = new Map();
+    const threadListCache = new Map();
+    const messageHistoryCache = new Map();
     async function listAllThreads(params = {}) {
-        const stateThreads = await listAllThreadsOnce({ ...params, useStateDbOnly: true });
-        if (stateThreads.length > 0 || params.useStateDbOnly !== undefined) {
-            return stateThreads;
+        const cacheKey = threadListCacheKey(params);
+        const cached = threadListCache.get(cacheKey);
+        const now = Date.now();
+        if (cached && cached.expiresAt > now) {
+            return cached.promise;
+        }
+        const promise = loadAllThreads(params).catch((error) => {
+            threadListCache.delete(cacheKey);
+            throw error;
+        });
+        threadListCache.set(cacheKey, {
+            expiresAt: now + THREAD_LIST_CACHE_TTL_MS,
+            promise
+        });
+        return promise;
+    }
+    async function loadAllThreads(params = {}) {
+        if (params.useStateDbOnly !== undefined) {
+            return listAllThreadsOnce(params);
         }
-        return listAllThreadsOnce({ ...params, useStateDbOnly: false });
+        const stateThreads = await listAllThreadsOnce({ ...params, useStateDbOnly: true });
+        const liveThreads = await listAllThreadsOnce({ ...params, useStateDbOnly: false }).catch(() => []);
+        const loadedThreads = await listLoadedThreads(params).catch(() => []);
+        return mergeCodexThreadLists(stateThreads, liveThreads, loadedThreads);
     }
     async function listAllThreadsOnce(params) {
         const threads = [];
@@ -46,12 +75,21 @@ export function createLocalCodexBridge(options = {}) {
         } while (cursor);
         return threads;
     }
+    async function listLoadedThreads(params) {
+        const loadedThreadIds = await client.listLoadedThreads();
+        const threads = await Promise.all(loadedThreadIds.map(async (threadId) => {
+            const thread = await client.readThread(threadId, false).catch(() => null);
+            return thread ? { ...thread, abitatLoadedFromAppServer: true } : null;
+        }));
+        return threads.filter((thread) => Boolean(thread && !thread.ephemeral && thread.cwd && threadMatchesListParams(thread, params)));
+    }
     async function resolveProjectCwd(projectId) {
-        const project = (await listProjects()).find((candidate) => candidate.id === projectId);
-        if (!project) {
-            throw Object.assign(new Error("Codex project not found"), { statusCode: 404 });
+        for (const thread of await listAllThreads()) {
+            if (externalCodexProjectId(thread.cwd) === projectId) {
+                return thread.cwd;
+            }
         }
-        return project.hostLocalPath;
+        throw Object.assign(new Error("Codex project not found"), { statusCode: 404 });
     }
     async function listProjects() {
         const grouped = new Map();
@@ -78,61 +116,231 @@ export function createLocalCodexBridge(options = {}) {
             workspaceId
         }));
     }
+    function enqueueTurn(threadId, input, options = { front: false }) {
+        invalidateMessageHistoryCache(threadId);
+        const existing = queuedTurnsByThread.get(threadId) ?? [];
+        const next = options.front ? [input, ...existing] : [...existing, input];
+        queuedTurnsByThread.set(threadId, next);
+        scheduleQueueDrain(threadId);
+    }
+    function deleteQueuedTurn(threadId, clientMessageId) {
+        const existing = queuedTurnsByThread.get(threadId);
+        if (!existing?.length) {
+            return false;
+        }
+        const next = existing.filter((turn) => turn.clientMessageId !== clientMessageId);
+        if (next.length === existing.length) {
+            return false;
+        }
+        invalidateMessageHistoryCache(threadId);
+        if (next.length > 0) {
+            queuedTurnsByThread.set(threadId, next);
+        }
+        else {
+            queuedTurnsByThread.delete(threadId);
+            const timer = queueDrainTimers.get(threadId);
+            if (timer) {
+                clearTimeout(timer);
+                queueDrainTimers.delete(threadId);
+            }
+        }
+        return true;
+    }
+    function updateQueuedTurn(threadId, clientMessageId, prompt) {
+        const existing = queuedTurnsByThread.get(threadId);
+        if (!existing?.length) {
+            return false;
+        }
+        const index = existing.findIndex((turn) => turn.clientMessageId === clientMessageId);
+        if (index < 0) {
+            return false;
+        }
+        invalidateMessageHistoryCache(threadId);
+        queuedTurnsByThread.set(threadId, existing.map((turn, turnIndex) => (turnIndex === index ? { ...turn, prompt } : turn)));
+        return true;
+    }
+    function invalidateMessageHistoryCache(threadId) {
+        messageHistoryCache.delete(threadId);
+    }
+    function scheduleQueueDrain(threadId, delayMs = QUEUED_TURN_POLL_INTERVAL_MS) {
+        if (queueDrainTimers.has(threadId)) {
+            return;
+        }
+        const timer = setTimeout(() => {
+            queueDrainTimers.delete(threadId);
+            void drainQueuedTurns(threadId);
+        }, delayMs);
+        timer.unref?.();
+        queueDrainTimers.set(threadId, timer);
+    }
+    async function drainQueuedTurns(threadId) {
+        const queue = queuedTurnsByThread.get(threadId);
+        if (!queue?.length) {
+            queuedTurnsByThread.delete(threadId);
+            return;
+        }
+        let thread;
+        try {
+            thread = await client.readThread(threadId, true);
+        }
+        catch {
+            scheduleQueueDrain(threadId);
+            return;
+        }
+        if (isCodexThreadBusy(thread)) {
+            scheduleQueueDrain(threadId);
+            return;
+        }
+        const nextInput = queue.shift();
+        if (!nextInput) {
+            queuedTurnsByThread.delete(threadId);
+            return;
+        }
+        if (queue.length === 0) {
+            queuedTurnsByThread.delete(threadId);
+        }
+        await startConversationTurn(threadId, thread, nextInput);
+        if ((queuedTurnsByThread.get(threadId)?.length ?? 0) > 0) {
+            scheduleQueueDrain(threadId);
+        }
+    }
+    async function startConversationTurn(threadId, thread, input) {
+        invalidateMessageHistoryCache(threadId);
+        let activeThread = thread;
+        if (threadStatusType(activeThread.status) !== "active") {
+            activeThread = (await client.resumeThread({ excludeTurns: false, threadId })).thread;
+        }
+        await client.startTurn(threadId, userInput(input.prompt, input.attachments), {
+            ...PHONE_FULL_ACCESS_TURN_OPTIONS,
+            cwd: activeThread.cwd,
+            ...turnModelSettings(input.modelSettings)
+        });
+    }
     return {
         async bootstrap() {
             try {
                 await client.listThreads({ limit: 1, useStateDbOnly: true });
+                logDiagnostics(diagnostics, "info", "codex.app_server.bootstrap", {
+                    available: true
+                });
                 return { available: true };
             }
             catch (error) {
+                logDiagnostics(diagnostics, "error", "codex.app_server.bootstrap_failure", {
+                    available: false,
+                    error: errorDiagnostics(error)
+                });
                 return { available: false, error: errorMessage(error) };
             }
         },
         async continueConversation(conversationId, input) {
             const threadId = toCodexThreadId(conversationId);
-            let thread = await client.readThread(threadId, true);
+            const thread = await client.readThread(threadId, true);
+            const delivery = input.delivery ?? "queue";
             if (isCodexThreadBusy(thread)) {
-                throw new LocalCodexConversationBusyError();
+                if (delivery === "steer") {
+                    const activeTurn = latestActiveTurn(thread);
+                    if (!activeTurn) {
+                        throw Object.assign(new Error("No active Codex turn is available to steer"), {
+                            statusCode: 409
+                        });
+                    }
+                    invalidateMessageHistoryCache(threadId);
+                    await client.steerTurn(threadId, userInput(input.prompt, input.attachments), activeTurn.id);
+                    if (input.clientMessageId) {
+                        deleteQueuedTurn(threadId, input.clientMessageId);
+                    }
+                    return {
+                        conversationId: externalCodexConversationId(threadId),
+                        status: "running"
+                    };
+                }
+                enqueueTurn(threadId, input);
+                return {
+                    conversationId: externalCodexConversationId(threadId),
+                    status: "queued"
+                };
             }
-            if (threadStatusType(thread.status) !== "active") {
-                thread = (await client.resumeThread({ excludeTurns: false, threadId })).thread;
+            if ((queuedTurnsByThread.get(threadId)?.length ?? 0) > 0) {
+                enqueueTurn(threadId, input, { front: delivery === "steer" });
+                return {
+                    conversationId: externalCodexConversationId(threadId),
+                    status: "queued"
+                };
             }
-            await client.startTurn(threadId, userInput(input.prompt, input.attachments), {
-                ...PHONE_FULL_ACCESS_TURN_OPTIONS,
-                cwd: thread.cwd,
-                ...turnModelSettings(input.modelSettings)
-            });
+            await startConversationTurn(threadId, thread, input);
             return {
                 conversationId: externalCodexConversationId(threadId),
                 status: "running"
             };
         },
+        async deleteQueuedTurn(conversationId, input) {
+            const threadId = toCodexThreadId(conversationId);
+            const removed = deleteQueuedTurn(threadId, input.clientMessageId);
+            return {
+                conversationId: externalCodexConversationId(threadId),
+                removed,
+                status: (queuedTurnsByThread.get(threadId)?.length ?? 0) > 0 ? "queued" : "running"
+            };
+        },
+        async updateQueuedTurn(conversationId, input) {
+            const threadId = toCodexThreadId(conversationId);
+            const updated = updateQueuedTurn(threadId, input.clientMessageId, input.prompt);
+            return {
+                conversationId: externalCodexConversationId(threadId),
+                status: (queuedTurnsByThread.get(threadId)?.length ?? 0) > 0 ? "queued" : "running",
+                updated
+            };
+        },
         async listCompletionStates() {
-            const threads = await readThreadsWithTurns(await listAllThreads());
-            return threads
-                .sort((left, right) => right.updatedAt - left.updatedAt)
-                .map((thread) => codexThreadToCompletionState(thread, workspaceId));
+            const threads = await readThreadsWithTurns(await loadAllThreads());
+            const states = threads.map((thread) => codexThreadToCompletionState(thread, workspaceId));
+            logDiagnostics(diagnostics, "info", "completion.states.result", {
+                activeCount: states.filter((state) => isActiveMobileConversationStatus(state.status))
+                    .length,
+                stateCount: states.length
+            });
+            return states.sort((left, right) => Date.parse(right.updatedAt) - Date.parse(left.updatedAt));
         },
         async listMessages(conversationId, messageOptions = {}) {
             const threadId = toCodexThreadId(conversationId);
-            const messages = flattenThreadMessages(await client.readThread(threadId, true), externalCodexConversationId(threadId));
-            const filtered = messageOptions.includeRuntime
-                ? messages
-                : messages.filter((message) => message.role !== "runtime");
-            if (typeof messageOptions.afterSequence !== "number") {
-                return filtered;
+            const messages = await readCachedThreadMessages(threadId, {
+                afterSequence: messageOptions.afterSequence,
+                forceRefresh: messageOptions.forceRefresh === true
+            });
+            const returned = filterThreadMessages(messages, messageOptions);
+            logDiagnostics(diagnostics, "info", "messages.list.bridge_result", {
+                ...messageCounts(messages),
+                afterSequence: messageOptions.afterSequence,
+                conversationId: externalCodexConversationId(threadId),
+                forceRefresh: messageOptions.forceRefresh === true,
+                includeRuntime: messageOptions.includeRuntime === true,
+                returned: returned.length,
+                total: messages.length
+            });
+            return returned;
+        },
+        async listGeneratedFiles(conversationId) {
+            return generatedFilesForThread(await client.readThread(toCodexThreadId(conversationId), true));
+        },
+        async downloadGeneratedFile(conversationId, fileId) {
+            const files = await generatedFilesForThread(await client.readThread(toCodexThreadId(conversationId), true));
+            const file = files.find((candidate) => candidate.id === fileId);
+            if (!file) {
+                throw Object.assign(new Error("Generated file not found"), { statusCode: 404 });
             }
-            const maxSequence = filtered.reduce((max, message) => Math.max(max, message.sequence), 0);
-            return messageOptions.afterSequence > maxSequence
-                ? filtered
-                : filtered.filter((message) => message.sequence > messageOptions.afterSequence);
+            const data = await readFile(file.path);
+            return {
+                ...file,
+                dataBase64: data.toString("base64")
+            };
         },
         listModelOptions() {
             return client.listModels();
         },
         async listProjectConversations(projectId) {
             const cwd = await resolveProjectCwd(projectId);
-            const threads = await readThreadsWithTurns(await listAllThreads({ cwd }));
+            const threads = await hydrateConversationStatusThreads(await listAllThreads({ cwd }));
             return threads
                 .filter((thread) => externalCodexProjectId(thread.cwd) === projectId)
                 .sort((left, right) => right.updatedAt - left.updatedAt)
@@ -146,6 +354,7 @@ export function createLocalCodexBridge(options = {}) {
                 experimentalRawEvents: false,
                 persistExtendedHistory: true
             });
+            invalidateMessageHistoryCache(thread.id);
             await client.startTurn(thread.id, userInput(input.prompt, input.attachments), {
                 ...PHONE_FULL_ACCESS_TURN_OPTIONS,
                 cwd,
@@ -158,12 +367,52 @@ export function createLocalCodexBridge(options = {}) {
         }
     };
     async function readThreadsWithTurns(threads) {
-        return Promise.all(threads.map((thread) => client.readThread(thread.id, true).catch(() => thread)));
+        return Promise.all(threads.map(async (thread) => {
+            const readThread = await client.readThread(thread.id, true).catch(() => thread);
+            return mergeCodexThreadSnapshots(readThread, thread);
+        }));
+    }
+    async function hydrateConversationStatusThreads(threads) {
+        return Promise.all(threads.map(async (thread) => {
+            if (!needsConversationStatusHydration(thread)) {
+                return thread;
+            }
+            const readThread = await client.readThread(thread.id, true).catch(() => thread);
+            return mergeCodexThreadSnapshots(readThread, thread);
+        }));
+    }
+    async function readCachedThreadMessages(threadId, options) {
+        const cached = messageHistoryCache.get(threadId);
+        if (!options.forceRefresh && typeof options.afterSequence === "number" && cached) {
+            const summary = await client.readThread(threadId, false).catch(() => null);
+            if (summary && canUseCachedMessageHistory(cached, summary)) {
+                return cached.messages;
+            }
+        }
+        const thread = await client.readThread(threadId, true);
+        const messages = flattenThreadMessages(thread, externalCodexConversationId(threadId), diagnostics);
+        if (isCodexThreadMessageHistoryStable(thread)) {
+            messageHistoryCache.set(threadId, {
+                messages,
+                statusType: threadStatusType(thread.status),
+                updatedAt: safeSeconds(thread.updatedAt, thread.createdAt)
+            });
+        }
+        else {
+            invalidateMessageHistoryCache(threadId);
+        }
+        return messages;
+    }
+    function canUseCachedMessageHistory(cached, summary) {
+        return (!isCodexThreadBusy(summary) &&
+            cached.statusType === threadStatusType(summary.status) &&
+            cached.updatedAt === safeSeconds(summary.updatedAt, summary.createdAt));
     }
 }
 function createCodexAppClient(options) {
     const serverUrl = options.serverUrl ?? process.env.CODEX_APP_SERVER_URL ?? DEFAULT_SERVER_URL;
     const codexBinaryPath = options.codexBinaryPath ?? process.env.CODEX_APP_BINARY ?? DEFAULT_CODEX_BINARY;
+    const diagnostics = options.diagnostics;
     return {
         listModels: async () => {
             const models = [];
@@ -173,33 +422,66 @@ function createCodexAppClient(options) {
                     cursor,
                     includeHidden: false,
                     limit: 200
-                });
+                }, diagnostics);
                 models.push(...response.data.flatMap(normalizeCodexModel));
                 cursor = response.nextCursor;
             } while (cursor);
             return models;
         },
+        async listLoadedThreads() {
+            const threadIds = [];
+            let cursor = null;
+            do {
+                const response = await callCodexApp(serverUrl, codexBinaryPath, "thread/loaded/list", {
+                    cursor,
+                    limit: 200
+                }, diagnostics);
+                threadIds.push(...response.data);
+                cursor = response.nextCursor;
+            } while (cursor);
+            return threadIds;
+        },
         listThreads: (params = {}) => callCodexApp(serverUrl, codexBinaryPath, "thread/list", {
             archived: false,
             limit: 200,
             sortDirection: "desc",
             useStateDbOnly: true,
             ...params
-        }),
+        }, diagnostics),
         async readThread(threadId, includeTurns = true) {
-            const response = await callCodexApp(serverUrl, codexBinaryPath, "thread/read", { includeTurns, threadId });
-            return response.thread;
+            logDiagnostics(diagnostics, "info", "codex.thread_read.call", {
+                includeTurns,
+                threadId
+            });
+            try {
+                const response = await callCodexApp(serverUrl, codexBinaryPath, "thread/read", { includeTurns, threadId }, diagnostics);
+                logDiagnostics(diagnostics, "info", "codex.thread_read.result", {
+                    includeTurns,
+                    threadId,
+                    turnCount: response.thread.turns.length
+                });
+                return response.thread;
+            }
+            catch (error) {
+                logDiagnostics(diagnostics, "error", "codex.thread_read.failure", {
+                    error: errorDiagnostics(error),
+                    includeTurns,
+                    threadId
+                });
+                throw error;
+            }
         },
-        resumeThread: (params) => callCodexApp(serverUrl, codexBinaryPath, "thread/resume", params),
+        resumeThread: (params) => callCodexApp(serverUrl, codexBinaryPath, "thread/resume", params, diagnostics),
         startThread: (params) => callCodexApp(serverUrl, codexBinaryPath, "thread/start", {
             experimentalRawEvents: false,
             persistExtendedHistory: true,
             ...params
-        }),
-        startTurn: (threadId, input, turnOptions) => startTurnWithKeepAlive(serverUrl, codexBinaryPath, threadId, input, turnOptions)
+        }, diagnostics),
+        startTurn: (threadId, input, turnOptions) => startTurnWithKeepAlive(serverUrl, codexBinaryPath, threadId, input, turnOptions, diagnostics),
+        steerTurn: (threadId, input, expectedTurnId) => steerTurnWithKeepAlive(serverUrl, codexBinaryPath, threadId, input, expectedTurnId, diagnostics)
     };
 }
-async function callCodexApp(serverUrl, codexBinaryPath, method, params) {
+async function callCodexApp(serverUrl, codexBinaryPath, method, params, diagnostics) {
     try {
         return await callCodexAppOnce(serverUrl, method, params);
     }
@@ -207,7 +489,12 @@ async function callCodexApp(serverUrl, codexBinaryPath, method, params) {
         if (!isConnectionFailure(error) || !canStartLocalServer(serverUrl)) {
             throw error;
         }
-        await ensureLocalAppServer(serverUrl, codexBinaryPath);
+        logDiagnostics(diagnostics, "warn", "codex.app_server.connect_failure", {
+            error: errorDiagnostics(error),
+            method,
+            serverUrl
+        });
+        await ensureLocalAppServer(serverUrl, codexBinaryPath, diagnostics);
         return callCodexAppOnce(serverUrl, method, params);
     }
 }
@@ -221,16 +508,53 @@ async function callCodexAppOnce(serverUrl, method, params) {
         connection.close();
     }
 }
-async function startTurnWithKeepAlive(serverUrl, codexBinaryPath, threadId, input, options) {
+async function startTurnWithKeepAlive(serverUrl, codexBinaryPath, threadId, input, options, diagnostics) {
+    logDiagnostics(diagnostics, "info", "codex.turn_start.call", {
+        ...turnInputDiagnostics(input),
+        cwd: options.cwd,
+        effort: options.effort,
+        model: options.model,
+        threadId
+    });
     try {
-        return await startTurnWithKeepAliveOnce(serverUrl, threadId, input, options);
+        const response = await startTurnWithKeepAliveOnce(serverUrl, threadId, input, options);
+        logDiagnostics(diagnostics, "info", "codex.turn_start.result", {
+            status: turnStatusType(response.turn),
+            threadId,
+            turnId: response.turn.id
+        });
+        return response;
     }
     catch (error) {
         if (!isConnectionFailure(error) || !canStartLocalServer(serverUrl)) {
+            logDiagnostics(diagnostics, "error", "codex.turn_start.failure", {
+                error: errorDiagnostics(error),
+                threadId
+            });
             throw error;
         }
-        await ensureLocalAppServer(serverUrl, codexBinaryPath);
-        return startTurnWithKeepAliveOnce(serverUrl, threadId, input, options);
+        logDiagnostics(diagnostics, "warn", "codex.app_server.connect_failure", {
+            error: errorDiagnostics(error),
+            method: "turn/start",
+            serverUrl
+        });
+        await ensureLocalAppServer(serverUrl, codexBinaryPath, diagnostics);
+        try {
+            const response = await startTurnWithKeepAliveOnce(serverUrl, threadId, input, options);
+            logDiagnostics(diagnostics, "info", "codex.turn_start.result", {
+                status: turnStatusType(response.turn),
+                threadId,
+                turnId: response.turn.id
+            });
+            return response;
+        }
+        catch (retryError) {
+            logDiagnostics(diagnostics, "error", "codex.turn_start.failure", {
+                error: errorDiagnostics(retryError),
+                threadId
+            });
+            throw retryError;
+        }
     }
 }
 async function startTurnWithKeepAliveOnce(serverUrl, threadId, input, options) {
@@ -259,6 +583,75 @@ async function startTurnWithKeepAliveOnce(serverUrl, threadId, input, options) {
         }
     }
 }
+async function steerTurnWithKeepAlive(serverUrl, codexBinaryPath, threadId, input, expectedTurnId, diagnostics) {
+    logDiagnostics(diagnostics, "info", "codex.turn_steer.call", {
+        ...turnInputDiagnostics(input),
+        expectedTurnId,
+        threadId
+    });
+    try {
+        const response = await steerTurnWithKeepAliveOnce(serverUrl, threadId, input, expectedTurnId);
+        logDiagnostics(diagnostics, "info", "codex.turn_steer.result", {
+            expectedTurnId,
+            threadId,
+            turnId: response.turnId
+        });
+        return response;
+    }
+    catch (error) {
+        if (!isConnectionFailure(error) || !canStartLocalServer(serverUrl)) {
+            logDiagnostics(diagnostics, "error", "codex.turn_steer.failure", {
+                error: errorDiagnostics(error),
+                expectedTurnId,
+                threadId
+            });
+            throw error;
+        }
+        logDiagnostics(diagnostics, "warn", "codex.app_server.connect_failure", {
+            error: errorDiagnostics(error),
+            method: "turn/steer",
+            serverUrl
+        });
+        await ensureLocalAppServer(serverUrl, codexBinaryPath, diagnostics);
+        try {
+            const response = await steerTurnWithKeepAliveOnce(serverUrl, threadId, input, expectedTurnId);
+            logDiagnostics(diagnostics, "info", "codex.turn_steer.result", {
+                expectedTurnId,
+                threadId,
+                turnId: response.turnId
+            });
+            return response;
+        }
+        catch (retryError) {
+            logDiagnostics(diagnostics, "error", "codex.turn_steer.failure", {
+                error: errorDiagnostics(retryError),
+                expectedTurnId,
+                threadId
+            });
+            throw retryError;
+        }
+    }
+}
+async function steerTurnWithKeepAliveOnce(serverUrl, threadId, input, expectedTurnId) {
+    const connection = await JsonRpcConnection.connect(serverUrl);
+    let keepAliveStarted = false;
+    try {
+        await initializeConnection(connection);
+        const response = await connection.call("turn/steer", {
+            expectedTurnId,
+            input,
+            threadId
+        });
+        keepAliveStarted = true;
+        keepTurnConnectionAlive(connection, threadId, response.turnId);
+        return response;
+    }
+    finally {
+        if (!keepAliveStarted) {
+            connection.close();
+        }
+    }
+}
 async function initializeConnection(connection) {
     await connection.call("initialize", {
         capabilities: {
@@ -410,8 +803,12 @@ function keepTurnConnectionAlive(connection, threadId, turnId) {
     activeTurnKeepAlives.add(keepAlive);
     void keepAlive;
 }
-async function ensureLocalAppServer(serverUrl, codexBinaryPath) {
+async function ensureLocalAppServer(serverUrl, codexBinaryPath, diagnostics) {
     if (!spawnedAppServer || spawnedAppServer.exitCode !== null || spawnedAppServer.killed) {
+        logDiagnostics(diagnostics, "info", "codex.app_server.bootstrap_start", {
+            codexBinaryPath,
+            serverUrl
+        });
         spawnedAppServer = spawn(codexBinaryPath, ["app-server", "--listen", serverUrl, "--analytics-default-enabled"], {
             detached: true,
             stdio: "ignore"
@@ -421,10 +818,18 @@ async function ensureLocalAppServer(serverUrl, codexBinaryPath) {
     const startedAt = Date.now();
     while (Date.now() - startedAt < START_TIMEOUT_MS) {
         if (await canOpenWebSocket(serverUrl)) {
+            logDiagnostics(diagnostics, "info", "codex.app_server.bootstrap_connected", {
+                elapsedMs: Date.now() - startedAt,
+                serverUrl
+            });
             return;
         }
         await delay(250);
     }
+    logDiagnostics(diagnostics, "error", "codex.app_server.bootstrap_failure", {
+        elapsedMs: Date.now() - startedAt,
+        serverUrl
+    });
     throw new Error("Unable to start Codex app-server. Open Codex.app or set CODEX_APP_SERVER_URL.");
 }
 function canOpenWebSocket(serverUrl) {
@@ -469,6 +874,123 @@ function toCodexThreadId(conversationId) {
         ? decodeURIComponent(conversationId.slice(CODEX_THREAD_PREFIX.length))
         : conversationId;
 }
+function threadListCacheKey(params) {
+    return JSON.stringify({
+        archived: params.archived ?? null,
+        cursor: params.cursor ?? null,
+        cwd: params.cwd ?? null,
+        limit: params.limit ?? null,
+        sortDirection: params.sortDirection ?? null,
+        useStateDbOnly: params.useStateDbOnly ?? null
+    });
+}
+function mergeCodexThreadLists(...threadLists) {
+    const byId = new Map();
+    for (const thread of threadLists.flat()) {
+        byId.set(thread.id, mergeCodexThreadSnapshots(byId.get(thread.id), thread));
+    }
+    return Array.from(byId.values()).sort((left, right) => safeSeconds(right.updatedAt, right.createdAt) - safeSeconds(left.updatedAt, left.createdAt));
+}
+function mergeCodexThreadSnapshots(baseThread, nextThread) {
+    if (!baseThread) {
+        return nextThread;
+    }
+    const abitatLoadedFromAppServer = baseThread.abitatLoadedFromAppServer || nextThread.abitatLoadedFromAppServer || undefined;
+    const abitatThreadListActivityAt = maxOptionalSeconds(threadListActivitySeconds(baseThread), threadListActivitySeconds(nextThread));
+    return {
+        ...baseThread,
+        ...nextThread,
+        abitatLoadedFromAppServer,
+        abitatThreadListActivityAt: abitatThreadListActivityAt ?? undefined,
+        createdAt: safeSeconds(baseThread.createdAt, nextThread.createdAt),
+        status: hasUnpersistedThreadListActivity(baseThread, nextThread, {
+            threadListActivityAt: abitatThreadListActivityAt
+        })
+            ? { activeFlags: [], type: "active" }
+            : preferredMergedThreadStatus(baseThread, nextThread),
+        turns: nextThread.turns.length > 0 ? nextThread.turns : baseThread.turns,
+        updatedAt: Math.max(safeSeconds(baseThread.updatedAt, baseThread.createdAt), safeSeconds(nextThread.updatedAt, nextThread.createdAt))
+    };
+}
+function preferredThreadStatus(baseStatus, nextStatus) {
+    if (threadStatusType(baseStatus) === "active" && threadStatusType(nextStatus) === "active") {
+        return { activeFlags: uniqueActiveFlags(baseStatus, nextStatus), type: "active" };
+    }
+    return threadStatusRank(nextStatus) > threadStatusRank(baseStatus) ? nextStatus : baseStatus;
+}
+function preferredMergedThreadStatus(baseThread, nextThread) {
+    const baseLatestTurn = baseThread.turns.at(-1) ?? null;
+    const nextIsActiveSummary = threadStatusType(nextThread.status) === "active" && nextThread.turns.length === 0;
+    if (nextIsActiveSummary && baseLatestTurn && isTurnTerminal(baseLatestTurn)) {
+        return baseThread.status;
+    }
+    return preferredThreadStatus(baseThread.status, nextThread.status);
+}
+function threadStatusRank(status) {
+    switch (threadStatusType(status)) {
+        case "active":
+            return 4;
+        case "systemError":
+            return 3;
+        case "idle":
+            return 2;
+        case "notLoaded":
+            return 0;
+        default:
+            return 1;
+    }
+}
+function threadMatchesListParams(thread, params) {
+    if (!params.cwd) {
+        return true;
+    }
+    const cwds = Array.isArray(params.cwd) ? params.cwd : [params.cwd];
+    return cwds.includes(thread.cwd);
+}
+function uniqueActiveFlags(...statuses) {
+    return [...new Set(statuses.flatMap((status) => activeFlags(status)))];
+}
+function activeFlags(status) {
+    return status && typeof status === "object" && Array.isArray(status.activeFlags)
+        ? status.activeFlags.filter((flag) => typeof flag === "string")
+        : [];
+}
+function hasUnpersistedThreadListActivity(persistedThread, listedThread, input) {
+    if (input.threadListActivityAt === null) {
+        return false;
+    }
+    const latestTurn = threadWithTurns(persistedThread, listedThread)?.turns.at(-1) ?? null;
+    if (!latestTurn) {
+        return false;
+    }
+    return (isTurnInterrupted(latestTurn) &&
+        latestTurn.completedAt === null &&
+        input.threadListActivityAt >= safeSeconds(latestTurn.startedAt));
+}
+function isThreadListActivitySummaryStatus(status) {
+    const statusType = threadStatusType(status);
+    return statusType === "idle" || statusType === "notLoaded";
+}
+function needsConversationStatusHydration(thread) {
+    return (thread.turns.length === 0 &&
+        (isThreadListActivitySummaryStatus(thread.status) ||
+            threadStatusType(thread.status) === "active"));
+}
+function threadListActivitySeconds(thread) {
+    const currentActivity = thread.turns.length === 0 &&
+        (isThreadListActivitySummaryStatus(thread.status) ||
+            threadStatusType(thread.status) === "active")
+        ? safeSeconds(thread.updatedAt, thread.createdAt)
+        : null;
+    return maxOptionalSeconds(thread.abitatThreadListActivityAt ?? null, currentActivity);
+}
+function threadWithTurns(...threads) {
+    return threads.find((thread) => thread.turns.length > 0) ?? null;
+}
+function maxOptionalSeconds(...values) {
+    const seconds = values.filter((value) => typeof value === "number" && Number.isFinite(value));
+    return seconds.length > 0 ? Math.max(...seconds) : null;
+}
 function codexThreadToConversation(thread, workspaceId, userId) {
     return {
         agentId: "codex_app",
@@ -491,15 +1013,15 @@ function codexThreadToConversation(thread, workspaceId, userId) {
 function codexThreadToCompletionState(thread, workspaceId) {
     const latestTurn = thread.turns.at(-1) ?? null;
     const status = codexThreadToConversationStatus(thread);
-    const failed = Boolean(latestTurn?.error) || Boolean(latestTurn && isTurnInterrupted(latestTurn));
+    const activelyWorking = isActiveMobileConversationStatus(status);
+    const failed = !activelyWorking &&
+        (Boolean(latestTurn?.error) || Boolean(latestTurn && isTurnInterrupted(latestTurn)));
     const latestTurnCompletedAt = latestTurnCompletedAtIso(thread, latestTurn);
     const latestTurnFinished = Boolean(latestTurn && isTurnTerminal(latestTurn));
     return {
         conversationId: externalCodexConversationId(thread.id),
         failed,
-        isComplete: Boolean(latestTurn?.id &&
-            (latestTurnCompletedAt || latestTurnFinished || failed) &&
-            status !== "running"),
+        isComplete: Boolean(latestTurn?.id && (latestTurnCompletedAt || latestTurnFinished || failed) && !activelyWorking),
         latestTurnCompletedAt,
         latestTurnId: latestTurn?.id ?? null,
         projectId: externalCodexProjectId(thread.cwd),
@@ -511,14 +1033,28 @@ function codexThreadToCompletionState(thread, workspaceId) {
         workspaceId
     };
 }
-function flattenThreadMessages(thread, conversationId = externalCodexConversationId(thread.id)) {
+export function flattenThreadMessages(thread, conversationId = externalCodexConversationId(thread.id), diagnostics) {
     const messages = [];
     const itemOccurrences = new Map();
+    const itemTypeCounts = new Map();
+    const unknownItemTypes = new Set();
+    const assistantMessagesByTurn = new Map();
     let sequence = 1;
     for (const turn of thread.turns) {
         for (const [itemIndex, item] of turn.items.entries()) {
+            itemTypeCounts.set(item.type, (itemTypeCounts.get(item.type) ?? 0) + 1);
             const flattened = threadItemToMessageContent(item);
             if (!flattened) {
+                if (!HIDDEN_CODEX_ITEM_TYPES.has(item.type) && !isKnownCodexItemType(item.type)) {
+                    unknownItemTypes.add(item.type);
+                    logDiagnostics(diagnostics, "warn", "codex.thread_item.unknown", {
+                        codexItemId: item.id,
+                        codexItemType: item.type,
+                        conversationId,
+                        threadId: thread.id,
+                        turnId: turn.id
+                    });
+                }
                 continue;
             }
             const codexItemId = item.id ?? `item_${itemIndex}`;
@@ -541,36 +1077,152 @@ function flattenThreadMessages(thread, conversationId = externalCodexConversatio
                 sequence,
                 sourceDeviceId: null
             });
+            if (flattened.role === "assistant") {
+                assistantMessagesByTurn.set(turn.id, (assistantMessagesByTurn.get(turn.id) ?? 0) + 1);
+            }
             sequence += 1;
         }
+        if (isTurnCompleted(turn) && (assistantMessagesByTurn.get(turn.id) ?? 0) === 0) {
+            logDiagnostics(diagnostics, "warn", "codex.turn.completed_without_visible_assistant", {
+                conversationId,
+                itemTypeCounts: Object.fromEntries(itemTypeCounts.entries()),
+                threadId: thread.id,
+                turnId: turn.id,
+                unknownItemTypes: [...unknownItemTypes]
+            });
+        }
     }
+    logDiagnostics(diagnostics, "info", "codex.thread.messages_flattened", {
+        ...messageCounts(messages),
+        conversationId,
+        itemTypeCounts: Object.fromEntries(itemTypeCounts.entries()),
+        threadId: thread.id,
+        total: messages.length,
+        unknownItemTypes: [...unknownItemTypes]
+    });
     return messages;
 }
-function codexThreadToConversationStatus(thread) {
-    const latestTurn = thread.turns.at(-1) ?? null;
-    if (latestTurn?.error) {
-        return "failed";
+async function generatedFilesForThread(thread) {
+    const paths = new Set();
+    for (const turn of thread.turns) {
+        for (const item of turn.items) {
+            if (item.type !== "fileChange") {
+                continue;
+            }
+            const fileChange = item;
+            for (const change of fileChange.changes ?? []) {
+                const path = generatedFilePath(thread.cwd, change);
+                if (path) {
+                    paths.add(path);
+                }
+            }
+        }
     }
-    if (latestTurn && isTurnInterrupted(latestTurn)) {
-        return "cancelled";
+    const files = await Promise.all(Array.from(paths)
+        .sort()
+        .map(async (path) => {
+        const stats = await stat(path).catch(() => null);
+        if (!stats?.isFile()) {
+            return null;
+        }
+        return {
+            id: generatedFileId(thread.id, path),
+            mimeType: mimeTypeForPath(path),
+            name: basename(path),
+            path,
+            size: stats.size
+        };
+    }));
+    return files.filter((file) => Boolean(file));
+}
+function generatedFilePath(cwd, change) {
+    if (!change || typeof change !== "object") {
+        return null;
     }
+    const candidate = change;
+    const value = stringField(candidate, "path") ??
+        stringField(candidate, "filePath") ??
+        stringField(candidate, "absolutePath") ??
+        stringField(candidate, "relativePath");
+    if (!value) {
+        return null;
+    }
+    return isAbsolute(value) ? normalize(value) : normalize(join(cwd, value));
+}
+function generatedFileId(threadId, path) {
+    return `file_${createHash("sha256")
+        .update(`${threadId}\0${normalize(path)}`)
+        .digest("hex")
+        .slice(0, 24)}`;
+}
+function stringField(value, key) {
+    const field = value[key];
+    return typeof field === "string" && field.trim() ? field.trim() : null;
+}
+function mimeTypeForPath(path) {
+    switch (extname(path).toLowerCase()) {
+        case ".html":
+            return "text/html";
+        case ".md":
+        case ".markdown":
+            return "text/markdown";
+        case ".mp4":
+            return "video/mp4";
+        case ".mov":
+            return "video/quicktime";
+        case ".png":
+            return "image/png";
+        case ".jpg":
+        case ".jpeg":
+            return "image/jpeg";
+        case ".gif":
+            return "image/gif";
+        case ".pdf":
+            return "application/pdf";
+        case ".json":
+            return "application/json";
+        case ".txt":
+            return "text/plain";
+        default:
+            return "application/octet-stream";
+    }
+}
+function codexThreadToConversationStatus(thread) {
+    const latestTurn = thread.turns.at(-1) ?? null;
     if (threadStatusType(thread.status) === "active") {
-        if (latestTurn && isTurnTerminal(latestTurn)) {
-            return "approved";
-        }
         if (hasActiveFlag(thread.status, "waitingOnApproval")) {
             return "awaiting_approval";
         }
         return "running";
     }
+    if (latestTurn && isTurnInProgress(latestTurn)) {
+        return "running";
+    }
+    if (latestTurn?.error) {
+        return "failed";
+    }
+    if (latestTurn && isTurnInterrupted(latestTurn)) {
+        return "cancelled";
+    }
     return "approved";
 }
 function isCodexThreadBusy(thread) {
-    if (threadStatusType(thread.status) !== "active") {
-        return false;
+    return threadStatusType(thread.status) === "active" || thread.turns.some(isTurnInProgress);
+}
+function isCodexThreadMessageHistoryStable(thread) {
+    return !isCodexThreadBusy(thread) && !thread.turns.some(isTurnInProgress);
+}
+function latestActiveTurn(thread) {
+    for (let index = thread.turns.length - 1; index >= 0; index -= 1) {
+        const turn = thread.turns[index];
+        if (turn && isTurnInProgress(turn)) {
+            return turn;
+        }
     }
-    const latestTurn = thread.turns.at(-1) ?? null;
-    return !(latestTurn && isTurnTerminal(latestTurn));
+    return null;
+}
+function isActiveMobileConversationStatus(status) {
+    return status === "running" || status === "awaiting_approval";
 }
 function latestTurnCompletedAtIso(thread, turn) {
     if (!turn) {
@@ -614,6 +1266,52 @@ function threadItemToMessageContent(item) {
     }
     return null;
 }
+function isKnownCodexItemType(type) {
+    return (type === "userMessage" ||
+        type === "agentMessage" ||
+        type === "plan" ||
+        type === "commandExecution" ||
+        type === "fileChange" ||
+        HIDDEN_CODEX_ITEM_TYPES.has(type));
+}
+function filterThreadMessages(messages, options) {
+    const filtered = options.includeRuntime
+        ? messages
+        : messages.filter((message) => message.role !== "runtime");
+    return typeof options.afterSequence === "number"
+        ? filtered.filter((message) => message.sequence > options.afterSequence)
+        : filtered;
+}
+function messageCounts(messages) {
+    const counts = {
+        assistant: 0,
+        runtime: 0,
+        user: 0,
+        visible: 0
+    };
+    for (const message of messages) {
+        if (message.role === "assistant") {
+            counts.assistant += 1;
+            counts.visible += 1;
+        }
+        else if (message.role === "user") {
+            counts.user += 1;
+            counts.visible += 1;
+        }
+        else if (message.role === "runtime") {
+            counts.runtime += 1;
+        }
+    }
+    return counts;
+}
+function turnInputDiagnostics(input) {
+    const text = input.flatMap((item) => (item.type === "text" ? [item.text] : [])).join("\n");
+    const attachments = input.filter((item) => item.type !== "text");
+    return {
+        ...promptDiagnostics(text),
+        ...attachmentDiagnostics(attachments)
+    };
+}
 function userInput(prompt, attachments = []) {
     return [
         { text: normalizedPrompt(prompt), text_elements: [], type: "text" },