@nordbyte/nordrelay 0.2.1 → 0.3.1

package/dist/relay-runtime.js

@@ -0,0 +1,908 @@
+import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { createArtifactZipBundle, getArtifactTurnReport, ensureOutDir, listRecentArtifactReports, removeArtifactTurn, totalArtifactSize, } from "./artifacts.js";
+import { buildFileInstructions, outboxPath, stageFile, } from "./attachments.js";
+import { CODEX_AGENT_CAPABILITIES, CODEX_REASONING_EFFORTS, PI_THINKING_LEVELS, agentLabel, agentReasoningLabel, } from "./agent.js";
+import { enabledAgents } from "./agent-factory.js";
+import { checkAuthStatus } from "./codex-auth.js";
+import { getThreadRolloutSnapshot, } from "./codex-state.js";
+import { friendlyErrorText } from "./error-messages.js";
+import { getConnectorHealth, getVersionChecks, readFormattedLogTail, spawnConnectorRestart } from "./operations.js";
+import { PromptStore, toPromptEnvelope } from "./prompt-store.js";
+import { renderSessionInfoPlain } from "./session-format.js";
+import { SessionRegistry } from "./session-registry.js";
+import { transcribeAudio } from "./voice.js";
+import { WebActivityStore, WebChatStore, } from "./web-state.js";
+import { evaluateWorkspacePolicy, filterAllowedWorkspaces } from "./workspace-policy.js";
+const WEB_CONTEXT_KEY = "web:dashboard";
+const MAX_WEB_SESSION_PAGE_SIZE = 50;
+const MAX_CHAT_HISTORY = 250;
+const MAX_TEXT_PREVIEW_BYTES = 256 * 1024;
+export class RelayRuntime {
+    config;
+    registry;
+    promptStore;
+    chatStore;
+    activityStore;
+    subscribers = new Set();
+    externalMonitor;
+    draining = false;
+    currentTurnId = null;
+    accumulatedText = "";
+    currentTurnStartedAt = 0;
+    externalMirror = null;
+    constructor(config) {
+        this.config = config;
+        this.registry = new SessionRegistry(config, {
+            fileName: "web-contexts.json",
+            sqliteKey: "web-contexts",
+        });
+        this.promptStore = new PromptStore(config.workspace, config.stateBackend);
+        this.chatStore = new WebChatStore(config.workspace, config.stateBackend, MAX_CHAT_HISTORY);
+        this.activityStore = new WebActivityStore(config.workspace, config.stateBackend, config.auditMaxEvents);
+        if (config.codexExternalBusyCheckMs > 0) {
+            this.externalMonitor = setInterval(() => {
+                void this.monitorExternalActivity().catch((error) => this.broadcastStatus(friendlyErrorText(error), "error"));
+            }, config.codexExternalBusyCheckMs);
+            this.externalMonitor.unref?.();
+        }
+    }
+    subscribe(callback) {
+        this.subscribers.add(callback);
+        void this.snapshot().then((data) => callback({ type: "snapshot", data })).catch(() => { });
+        void this.chatHistory().then((messages) => callback({ type: "chat_history", messages })).catch(() => { });
+        callback({ type: "activity_update", events: this.activity({ limit: 50 }) });
+        return () => this.subscribers.delete(callback);
+    }
+    async snapshot() {
+        const session = await this.getSession(true);
+        const info = this.publicInfo(session);
+        return {
+            session: info,
+            sessionText: renderSessionInfoPlain(info),
+            queue: this.queue(),
+            queuePaused: this.queuePaused(),
+            processing: session.isProcessing(),
+            enabledAgents: enabledAgents(this.config),
+            workspaces: filterAllowedWorkspaces(session.listWorkspaces(), this.config),
+        };
+    }
+    async status() {
+        return {
+            health: await getConnectorHealth(),
+            versionChecks: await getVersionChecks({ piCliPath: this.config.piCliPath }),
+            snapshot: await this.snapshot(),
+        };
+    }
+    async diagnostics() {
+        return {
+            health: await getConnectorHealth(),
+            versionChecks: await getVersionChecks({ piCliPath: this.config.piCliPath }),
+            snapshot: await this.snapshot(),
+            runtime: {
+                stateBackend: this.config.stateBackend,
+                sourceWorkspace: this.config.workspace,
+                queuePaused: this.promptStore.isPaused(WEB_CONTEXT_KEY),
+                externalMirror: this.externalMirror ? { ...this.externalMirror } : null,
+            },
+        };
+    }
+    async controlOptions() {
+        const session = await this.getSession(true);
+        const info = this.publicInfo(session);
+        const capabilities = info.capabilities ?? CODEX_AGENT_CAPABILITIES;
+        return {
+            models: capabilities.modelSelection ? session.listModels() : [],
+            reasoningLabel: agentReasoningLabel(info.agentId),
+            reasoningOptions: info.agentId === "pi" ? PI_THINKING_LEVELS : CODEX_REASONING_EFFORTS,
+            launchProfiles: capabilities.launchProfiles
+                ? this.config.launchProfiles.map((profile) => ({
+                    id: profile.id,
+                    label: profile.label,
+                    behavior: `${profile.sandboxMode} / ${profile.approvalPolicy}`,
+                    unsafe: profile.unsafe,
+                }))
+                : [],
+            workspaces: filterAllowedWorkspaces(session.listWorkspaces(), this.config),
+            capabilities,
+        };
+    }
+    async chatHistory(limit = 200) {
+        const session = await this.getSession(true);
+        return this.chatStore.list(this.publicInfo(session).threadId, limit);
+    }
+    async clearChatHistory() {
+        const session = await this.getSession(true);
+        const removed = this.chatStore.clear(this.publicInfo(session).threadId);
+        const messages = await this.chatHistory();
+        this.broadcast({ type: "chat_history", messages });
+        return { removed, messages };
+    }
+    activity(options = {}) {
+        return this.activityStore.list(options);
+    }
+    async listSessions(limit = 80, query = "") {
+        return this.filteredSessions(await this.getSession(true), query, Math.max(1, limit * 3)).slice(0, limit);
+    }
+    async listSessionsPage(page = 1, pageSize = MAX_WEB_SESSION_PAGE_SIZE, query = "") {
+        const session = await this.getSession(true);
+        const effectivePage = Math.max(1, Math.floor(page));
+        const effectivePageSize = Math.min(MAX_WEB_SESSION_PAGE_SIZE, Math.max(1, Math.floor(pageSize)));
+        const offset = (effectivePage - 1) * effectivePageSize;
+        const requested = Math.min(5_000, Math.max(100, (offset + effectivePageSize + 1) * 3));
+        const records = this.filteredSessions(session, query, requested);
+        return {
+            sessions: records.slice(offset, offset + effectivePageSize),
+            pagination: {
+                page: effectivePage,
+                pageSize: effectivePageSize,
+                hasPrevious: effectivePage > 1,
+                hasNext: records.length > offset + effectivePageSize,
+            },
+        };
+    }
+    filteredSessions(session, query, limit) {
+        const normalized = query.trim().toLowerCase();
+        return session.listAllSessions(limit)
+            .filter((record) => evaluateWorkspacePolicy(record.cwd, this.config).allowed)
+            .filter((record) => {
+            if (!normalized) {
+                return true;
+            }
+            return [
+                record.id,
+                record.title,
+                record.cwd,
+                record.model,
+                record.reasoningEffort,
+                record.firstUserMessage,
+            ].some((value) => value?.toLowerCase().includes(normalized));
+        });
+    }
+    async listModels() {
+        return (await this.getSession(true)).listModels();
+    }
+    async setAgent(agentId) {
+        if (!enabledAgents(this.config).includes(agentId)) {
+            throw new Error(`Agent is not enabled: ${agentId}`);
+        }
+        const session = await this.registry.switchAgent(WEB_CONTEXT_KEY, agentId);
+        this.updateSession(session);
+        return this.publicInfo(session);
+    }
+    async newSession(options = {}) {
+        const session = options.agentId ? await this.registry.switchAgent(WEB_CONTEXT_KEY, options.agentId) : await this.getSession(true);
+        this.ensureIdle(session);
+        if (options.reasoningEffort) {
+            const reasoningOptions = session.getInfo().agentId === "pi" ? PI_THINKING_LEVELS : CODEX_REASONING_EFFORTS;
+            if (!reasoningOptions.includes(options.reasoningEffort)) {
+                throw new Error(`Invalid ${agentReasoningLabel(session.getInfo().agentId)} value: ${options.reasoningEffort}`);
+            }
+            session.setReasoningEffort(options.reasoningEffort);
+        }
+        if (options.launchProfileId && (session.getInfo().capabilities ?? CODEX_AGENT_CAPABILITIES).launchProfiles) {
+            session.setLaunchProfile(options.launchProfileId);
+        }
+        if (typeof options.fastMode === "boolean" && (session.getInfo().capabilities ?? CODEX_AGENT_CAPABILITIES).fastMode) {
+            session.setFastMode(options.fastMode);
+        }
+        const info = await session.newThread(options.workspace, options.model);
+        this.updateSession(session);
+        this.appendActivity({
+            source: "web",
+            status: "info",
+            type: "session_new",
+            threadId: info.threadId,
+            workspace: info.workspace,
+            agentId: info.agentId,
+            detail: "New dashboard session created.",
+        });
+        return this.publicInfo(session);
+    }
+    async switchSession(threadId) {
+        const session = await this.getSession(true);
+        this.ensureIdle(session);
+        const info = await session.switchSession(threadId);
+        this.updateSession(session);
+        this.broadcast({ type: "chat_history", messages: await this.chatHistory() });
+        this.appendActivity({
+            source: "web",
+            status: "info",
+            type: "session_switch",
+            threadId: info.threadId,
+            workspace: info.workspace,
+            agentId: info.agentId,
+            detail: "Dashboard switched session.",
+        });
+        return this.publicInfo(session);
+    }
+    async attachSession(threadId) {
+        return this.switchSession(threadId);
+    }
+    async setModel(model) {
+        const session = await this.getSession(true);
+        this.ensureIdle(session);
+        await session.setModelForCurrentSession(model);
+        this.updateSession(session);
+        return this.publicInfo(session);
+    }
+    async setReasoningEffort(effort) {
+        const session = await this.getSession(true);
+        this.ensureIdle(session);
+        const options = session.getInfo().agentId === "pi" ? PI_THINKING_LEVELS : CODEX_REASONING_EFFORTS;
+        if (!options.includes(effort)) {
+            throw new Error(`Invalid ${agentReasoningLabel(session.getInfo().agentId)} value: ${effort}`);
+        }
+        await session.setReasoningEffortForCurrentSession(effort);
+        this.updateSession(session);
+        return this.publicInfo(session);
+    }
+    async setFastMode(enabled) {
+        const session = await this.getSession(true);
+        this.ensureIdle(session);
+        if (!(session.getInfo().capabilities ?? CODEX_AGENT_CAPABILITIES).fastMode) {
+            throw new Error(`Fast mode is not supported for ${agentLabel(session.getInfo().agentId)}.`);
+        }
+        session.setFastMode(enabled);
+        this.updateSession(session);
+        return this.publicInfo(session);
+    }
+    async setLaunchProfile(profileId) {
+        const session = await this.getSession(true);
+        this.ensureIdle(session);
+        session.setLaunchProfile(profileId);
+        this.updateSession(session);
+        return this.publicInfo(session);
+    }
+    async handback() {
+        const session = await this.getSession(true);
+        this.ensureIdle(session);
+        const result = session.handback();
+        this.updateSession(session);
+        return result;
+    }
+    async abort() {
+        const session = await this.getSession(true);
+        await session.abort();
+        this.broadcast({ type: "status", level: "warn", message: "Current operation aborted.", at: new Date().toISOString() });
+    }
+    async sendPrompt(text) {
+        const trimmed = text.trim();
+        if (!trimmed) {
+            throw new Error("Prompt is empty.");
+        }
+        return this.sendEnvelope(toPromptEnvelope(trimmed));
+    }
+    async sendUploadPrompt(options) {
+        const text = options.text?.trim() ?? "";
+        const files = options.files.filter((file) => file.data.byteLength > 0);
+        if (!text && files.length === 0) {
+            throw new Error("Prompt is empty.");
+        }
+        const session = await this.getSession(false);
+        const workspace = session.getInfo().workspace;
+        const turnId = randomUUID().slice(0, 12);
+        const outDir = outboxPath(workspace, turnId);
+        await ensureOutDir(outDir);
+        const stagedFiles = [];
+        const imagePaths = [];
+        const transcriptParts = [];
+        for (const [index, file] of files.entries()) {
+            const mimeType = normalizeMimeType(file.mimeType, file.name);
+            const staged = await stageFile(file.data, file.name || `upload-${index + 1}`, mimeType, {
+                workspace,
+                turnId,
+                maxFileSize: this.config.maxFileSize,
+            });
+            stagedFiles.push(staged);
+            if (mimeType.startsWith("image/")) {
+                imagePaths.push(staged.localPath);
+            }
+            if (mimeType.startsWith("audio/")) {
+                const result = await transcribeAudio(staged.localPath, {
+                    preferredBackend: this.config.voicePreferredBackend === "auto"
+                        ? undefined
+                        : this.config.voicePreferredBackend,
+                    language: this.config.voiceDefaultLanguage,
+                });
+                const transcript = result.text.trim();
+                if (transcript) {
+                    transcriptParts.push(`Audio transcript (${staged.safeName}, via ${result.backend}):\n${transcript}`);
+                }
+            }
+        }
+        const audioOnly = stagedFiles.length > 0 && stagedFiles.every((file) => file.mimeType.startsWith("audio/"));
+        if (this.config.voiceTranscribeOnly && audioOnly && !text) {
+            return {
+                queued: false,
+                transcript: transcriptParts.join("\n\n"),
+                transcribeOnly: true,
+                files: uploadFileDtos(stagedFiles),
+            };
+        }
+        const promptInput = {};
+        const textParts = [text, ...transcriptParts].filter(Boolean);
+        if (textParts.length > 0) {
+            promptInput.text = textParts.join("\n\n");
+        }
+        if (imagePaths.length > 0) {
+            promptInput.imagePaths = imagePaths;
+        }
+        if (stagedFiles.length > 0) {
+            promptInput.stagedFileInstructions = buildFileInstructions(stagedFiles, outDir);
+        }
+        const result = await this.sendEnvelope(toPromptEnvelope(promptInput, outDir));
+        return {
+            ...result,
+            transcript: transcriptParts.join("\n\n") || undefined,
+            files: uploadFileDtos(stagedFiles),
+        };
+    }
+    async sendEnvelope(envelope) {
+        const session = await this.getSession(false);
+        if (session.isProcessing()) {
+            const queued = this.promptStore.enqueue(WEB_CONTEXT_KEY, envelope);
+            const info = this.publicInfo(session);
+            this.appendActivity({
+                source: "web",
+                status: "queued",
+                type: "prompt_queued",
+                threadId: info.threadId,
+                workspace: info.workspace,
+                agentId: info.agentId,
+                prompt: envelope.description,
+                detail: `Queued at position ${this.promptStore.list(WEB_CONTEXT_KEY).length}.`,
+            });
+            this.broadcastQueue();
+            return { queued: true, queueId: queued.id };
+        }
+        void this.runPrompt(session, envelope).catch((error) => {
+            this.broadcast({ type: "turn_error", id: this.currentTurnId ?? "turn", error: friendlyErrorText(error), at: new Date().toISOString() });
+        });
+        return { queued: false };
+    }
+    queue() {
+        return this.promptStore.list(WEB_CONTEXT_KEY).map(queueItemDto);
+    }
+    queuePaused() {
+        return this.promptStore.isPaused(WEB_CONTEXT_KEY);
+    }
+    queueAction(action, id) {
+        if (action === "pause")
+            this.promptStore.pause(WEB_CONTEXT_KEY);
+        if (action === "resume")
+            this.promptStore.resume(WEB_CONTEXT_KEY);
+        if (action === "clear")
+            this.promptStore.clear(WEB_CONTEXT_KEY);
+        if (id && action === "cancel")
+            this.promptStore.remove(WEB_CONTEXT_KEY, id);
+        if (id && action === "top")
+            this.promptStore.moveToTop(WEB_CONTEXT_KEY, id);
+        if (id && action === "up")
+            this.promptStore.moveUp(WEB_CONTEXT_KEY, id);
+        if (id && action === "down")
+            this.promptStore.moveDown(WEB_CONTEXT_KEY, id);
+        if (id && action === "run") {
+            const item = this.promptStore.remove(WEB_CONTEXT_KEY, id);
+            if (item)
+                this.promptStore.enqueueFront(WEB_CONTEXT_KEY, item);
+            void this.drainQueue().catch((error) => this.broadcastStatus(friendlyErrorText(error), "error"));
+        }
+        this.appendActivity({
+            source: "web",
+            status: "info",
+            type: "queue_updated",
+            threadId: null,
+            workspace: this.config.workspace,
+            detail: id ? `${action}: ${id}` : action,
+        });
+        this.broadcastQueue();
+        return this.queue();
+    }
+    async artifacts() {
+        const session = await this.getSession(true);
+        return (await listRecentArtifactReports(session.getInfo().workspace, 20, this.config.maxFileSize)).map(artifactDto);
+    }
+    async artifact(turnId) {
+        const session = await this.getSession(true);
+        return getArtifactTurnReport(session.getInfo().workspace, turnId, this.config.maxFileSize);
+    }
+    async deleteArtifact(turnId) {
+        const session = await this.getSession(true);
+        return removeArtifactTurn(session.getInfo().workspace, turnId);
+    }
+    async createArtifactZip(turnId) {
+        const report = await this.artifact(turnId);
+        if (!report) {
+            return null;
+        }
+        const bundle = await createArtifactZipBundle(report.artifacts, report.outDir, {
+            maxFileSize: this.config.maxFileSize,
+            bundleName: `nordrelay-artifacts-${turnId}.zip`,
+        });
+        return bundle ? { path: bundle.localPath, name: bundle.name } : null;
+    }
+    async artifactPreview(turnId, relativePath) {
+        const report = await this.artifact(turnId);
+        const artifact = report?.artifacts.find((candidate) => candidate.relativePath.split(path.sep).join("/") === relativePath);
+        if (!artifact) {
+            return null;
+        }
+        const extension = path.extname(artifact.name).toLowerCase();
+        if ([".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg"].includes(extension)) {
+            return {
+                kind: "image",
+                name: artifact.name,
+                sizeBytes: artifact.sizeBytes,
+            };
+        }
+        if (!isPreviewableTextFile(extension, artifact.sizeBytes)) {
+            return {
+                kind: "unsupported",
+                name: artifact.name,
+                sizeBytes: artifact.sizeBytes,
+                detail: artifact.sizeBytes > MAX_TEXT_PREVIEW_BYTES ? "File is too large for inline preview." : "File type is not previewable.",
+            };
+        }
+        const buffer = await readFile(artifact.localPath);
+        const truncated = buffer.byteLength > MAX_TEXT_PREVIEW_BYTES;
+        return {
+            kind: "text",
+            name: artifact.name,
+            sizeBytes: artifact.sizeBytes,
+            truncated,
+            text: buffer.subarray(0, MAX_TEXT_PREVIEW_BYTES).toString("utf8"),
+        };
+    }
+    async logs(target = "connector", lines = 100) {
+        if (target === "update") {
+            const { getUpdateLogPath } = await import("./operations.js");
+            return readFormattedLogTail(lines, getUpdateLogPath());
+        }
+        return readFormattedLogTail(lines);
+    }
+    restartConnector() {
+        spawnConnectorRestart();
+        this.broadcastStatus("Restart requested. The dashboard may disconnect briefly.", "warn");
+        this.appendActivity({
+            source: "web",
+            status: "info",
+            type: "restart_requested",
+            threadId: null,
+            workspace: this.config.workspace,
+            detail: "Dashboard requested a connector restart.",
+        });
+        return { ok: true, message: "Restart requested." };
+    }
+    dispose() {
+        if (this.externalMonitor) {
+            clearInterval(this.externalMonitor);
+        }
+        this.registry.disposeAll();
+        this.subscribers.clear();
+    }
+    async monitorExternalActivity() {
+        const session = await this.getSession(true);
+        const info = this.publicInfo(session);
+        if (!info.capabilities.externalActivity || info.agentId !== "codex" || !info.threadId || session.isProcessing()) {
+            return;
+        }
+        const snapshot = getThreadRolloutSnapshot(info.threadId, {
+            afterLine: this.externalMirror?.threadId === info.threadId ? this.externalMirror.lastLine : Number.MAX_SAFE_INTEGER,
+            staleAfterMs: this.config.codexExternalBusyStaleMs,
+        }) ?? getThreadRolloutSnapshot(info.threadId, {
+            staleAfterMs: this.config.codexExternalBusyStaleMs,
+            maxEvents: 0,
+        });
+        if (!snapshot) {
+            return;
+        }
+        if (!this.externalMirror || this.externalMirror.threadId !== snapshot.threadId || this.externalMirror.rolloutPath !== snapshot.rolloutPath) {
+            this.externalMirror = {
+                threadId: snapshot.threadId,
+                rolloutPath: snapshot.rolloutPath,
+                lastLine: snapshot.lineCount,
+                turnId: snapshot.activity.turnId,
+                startedAt: snapshot.activity.startedAt?.toISOString() ?? null,
+            };
+            if (snapshot.activity.active) {
+                this.startExternalTurn(snapshot);
+            }
+            return;
+        }
+        const mirror = this.externalMirror;
+        if (snapshot.activity.active) {
+            if (mirror.turnId !== snapshot.activity.turnId) {
+                mirror.turnId = snapshot.activity.turnId;
+                mirror.startedAt = snapshot.activity.startedAt?.toISOString() ?? null;
+                mirror.latestAgentLine = undefined;
+                this.startExternalTurn(snapshot);
+            }
+            this.broadcastExternalEvents(snapshot, snapshot.events.filter((event) => event.lineNumber > mirror.lastLine));
+            mirror.lastLine = Math.max(mirror.lastLine, snapshot.lineCount);
+            mirror.latestStatus = externalStatusLine(snapshot, this.queue().length);
+            this.broadcastStatus(mirror.latestStatus, "info");
+            return;
+        }
+        const terminalEvent = [...snapshot.events].reverse().find((event) => event.kind === "task" && event.status && event.status !== "started");
+        if (terminalEvent && terminalEvent.lineNumber > mirror.lastLine) {
+            const finalAgent = snapshot.events.filter((event) => event.kind === "agent" && event.text).at(-1);
+            const finalText = finalAgent?.text ?? snapshot.latestAgentMessage;
+            const finalLine = finalAgent?.lineNumber ?? snapshot.lineCount;
+            if (finalText && finalLine !== mirror.latestAgentLine) {
+                this.chatStore.append({
+                    threadId: snapshot.threadId,
+                    role: "agent",
+                    text: finalText,
+                    source: "cli",
+                    turnId: terminalEvent.turnId ?? undefined,
+                });
+                this.broadcast({ type: "text_delta", id: terminalEvent.turnId ?? "cli", delta: finalText });
+                mirror.latestAgentLine = finalLine;
+            }
+            const externalStartedAt = mirror.startedAt ? new Date(mirror.startedAt) : snapshot.activity.startedAt;
+            this.broadcast({
+                type: "turn_complete",
+                id: terminalEvent.turnId ?? "cli",
+                at: terminalEvent.timestamp?.toISOString() ?? new Date().toISOString(),
+            });
+            this.appendActivity({
+                source: "cli",
+                status: terminalEvent.status === "aborted" ? "aborted" : terminalEvent.status === "failed" ? "failed" : "completed",
+                type: "cli_turn_finished",
+                threadId: snapshot.threadId,
+                workspace: info.workspace,
+                agentId: info.agentId,
+                prompt: snapshot.latestUserMessage ?? undefined,
+                detail: `Codex CLI task ${terminalEvent.status ?? "finished"}.`,
+                durationMs: durationFromDates(externalStartedAt, terminalEvent.timestamp),
+            });
+            this.broadcastStatus(`Codex CLI task ${terminalEvent.status ?? "finished"}.`, terminalEvent.status === "failed" ? "error" : terminalEvent.status === "aborted" ? "warn" : "info");
+            this.broadcast({ type: "chat_history", messages: await this.chatHistory() });
+        }
+        mirror.lastLine = Math.max(mirror.lastLine, snapshot.lineCount);
+    }
+    startExternalTurn(snapshot) {
+        const prompt = snapshot.latestUserMessage ?? "Codex CLI task";
+        this.chatStore.append({
+            threadId: snapshot.threadId,
+            role: "user",
+            text: prompt,
+            source: "cli",
+            turnId: snapshot.activity.turnId ?? undefined,
+            timestamp: snapshot.activity.startedAt?.toISOString(),
+        });
+        this.broadcast({
+            type: "turn_start",
+            id: snapshot.activity.turnId ?? "cli",
+            prompt,
+            at: snapshot.activity.startedAt?.toISOString() ?? new Date().toISOString(),
+            source: "cli",
+        });
+        this.appendActivity({
+            source: "cli",
+            status: "running",
+            type: "cli_turn_started",
+            threadId: snapshot.threadId,
+            prompt,
+            detail: `Rollout: ${snapshot.rolloutPath}`,
+        });
+    }
+    broadcastExternalEvents(snapshot, events) {
+        for (const event of events) {
+            if (event.kind === "tool" && event.status === "started") {
+                this.broadcast({
+                    type: "tool_start",
+                    id: snapshot.activity.turnId ?? "cli",
+                    toolCallId: `cli-${event.lineNumber}`,
+                    toolName: event.toolName ?? "tool",
+                });
+                this.appendActivity({
+                    source: "cli",
+                    status: "running",
+                    type: "cli_tool_started",
+                    threadId: snapshot.threadId,
+                    detail: event.toolName ?? "tool",
+                });
+            }
+            if (event.kind === "tool" && event.status === "finished") {
+                this.broadcast({
+                    type: "tool_end",
+                    id: snapshot.activity.turnId ?? "cli",
+                    toolCallId: `cli-${event.lineNumber}`,
+                    isError: false,
+                });
+            }
+        }
+    }
+    async getSession(deferThreadStart) {
+        return this.registry.getOrCreate(WEB_CONTEXT_KEY, { deferThreadStart });
+    }
+    async ensureActiveThread(session) {
+        if (!session.hasActiveThread()) {
+            await session.newThread();
+            this.updateSession(session);
+        }
+    }
+    ensureIdle(session) {
+        if (session.isProcessing()) {
+            throw new Error("The active session is still processing a turn.");
+        }
+    }
+    async runPrompt(session, envelope) {
+        await this.ensureActiveThread(session);
+        const info = session.getInfo();
+        if ((info.capabilities ?? CODEX_AGENT_CAPABILITIES).auth) {
+            const auth = await checkAuthStatus(this.config.codexApiKey);
+            if (!auth.authenticated) {
+                throw new Error(`Codex is not authenticated: ${auth.detail}`);
+            }
+        }
+        const workspacePolicy = evaluateWorkspacePolicy(session.getInfo().workspace, this.config);
+        if (!workspacePolicy.allowed) {
+            throw new Error(workspacePolicy.warning ?? "Current workspace is blocked by policy.");
+        }
+        const turnId = randomUUID().slice(0, 12);
+        this.currentTurnId = turnId;
+        this.currentTurnStartedAt = Date.now();
+        this.accumulatedText = "";
+        this.promptStore.setLastPrompt(WEB_CONTEXT_KEY, envelope);
+        const startedAt = new Date().toISOString();
+        this.chatStore.append({
+            threadId: info.threadId ?? "pending",
+            role: "user",
+            text: envelope.description,
+            source: "web",
+            turnId,
+            timestamp: startedAt,
+        });
+        this.appendActivity({
+            source: "web",
+            status: "running",
+            type: "prompt_started",
+            threadId: info.threadId,
+            workspace: info.workspace,
+            agentId: info.agentId,
+            prompt: envelope.description,
+        });
+        this.broadcast({ type: "turn_start", id: turnId, prompt: envelope.description, at: startedAt, source: "web" });
+        const callbacks = {
+            onTextDelta: (delta) => {
+                this.accumulatedText += delta;
+                this.broadcast({ type: "text_delta", id: turnId, delta });
+            },
+            onToolStart: (toolName, toolCallId) => this.broadcast({ type: "tool_start", id: turnId, toolCallId, toolName }),
+            onToolUpdate: (toolCallId, partialResult) => this.broadcast({ type: "tool_update", id: turnId, toolCallId, partialResult }),
+            onToolEnd: (toolCallId, isError) => this.broadcast({ type: "tool_end", id: turnId, toolCallId, isError }),
+            onTodoUpdate: (items) => this.broadcast({ type: "todo_update", id: turnId, items }),
+            onTurnComplete: () => { },
+            onAgentEnd: () => this.broadcast({ type: "turn_complete", id: turnId, at: new Date().toISOString() }),
+        };
+        try {
+            await session.prompt(envelope.input, callbacks);
+            this.updateSession(session);
+            if (this.accumulatedText.trim()) {
+                this.chatStore.append({
+                    threadId: info.threadId ?? "pending",
+                    role: "agent",
+                    text: this.accumulatedText,
+                    source: "web",
+                    turnId,
+                });
+            }
+            this.appendActivity({
+                source: "web",
+                status: "completed",
+                type: "prompt_completed",
+                threadId: info.threadId,
+                workspace: info.workspace,
+                agentId: info.agentId,
+                prompt: envelope.description,
+                durationMs: Date.now() - this.currentTurnStartedAt,
+            });
+            this.broadcast({ type: "turn_complete", id: turnId, at: new Date().toISOString() });
+            this.broadcast({ type: "chat_history", messages: await this.chatHistory() });
+        }
+        catch (error) {
+            const errorText = friendlyErrorText(error);
+            this.chatStore.append({
+                threadId: info.threadId ?? "pending",
+                role: "system",
+                text: `Error: ${errorText}`,
+                source: "web",
+                turnId,
+            });
+            this.appendActivity({
+                source: "web",
+                status: "failed",
+                type: "prompt_failed",
+                threadId: info.threadId,
+                workspace: info.workspace,
+                agentId: info.agentId,
+                prompt: envelope.description,
+                detail: errorText,
+                durationMs: Date.now() - this.currentTurnStartedAt,
+            });
+            this.broadcast({ type: "turn_error", id: turnId, error: errorText, at: new Date().toISOString() });
+            this.broadcast({ type: "chat_history", messages: await this.chatHistory() });
+            throw error;
+        }
+        finally {
+            this.currentTurnId = null;
+            await this.drainQueue();
+        }
+    }
+    async drainQueue() {
+        if (this.draining || this.promptStore.isPaused(WEB_CONTEXT_KEY)) {
+            return;
+        }
+        this.draining = true;
+        try {
+            const session = await this.getSession(false);
+            while (!session.isProcessing()) {
+                const next = this.promptStore.dequeue(WEB_CONTEXT_KEY);
+                this.broadcastQueue();
+                if (!next) {
+                    return;
+                }
+                await this.runPrompt(session, next);
+            }
+        }
+        finally {
+            this.draining = false;
+        }
+    }
+    updateSession(session) {
+        this.registry.updateMetadata(WEB_CONTEXT_KEY, session);
+        this.broadcast({ type: "session_update", session: this.publicInfo(session) });
+    }
+    appendActivity(input) {
+        const event = this.activityStore.append(input);
+        this.broadcast({ type: "activity_update", events: this.activity({ limit: 50 }) });
+        return event;
+    }
+    broadcastQueue() {
+        this.broadcast({ type: "queue_update", queue: this.queue(), paused: this.queuePaused() });
+    }
+    broadcastStatus(message, level = "info") {
+        this.broadcast({ type: "status", message, level, at: new Date().toISOString() });
+    }
+    broadcast(event) {
+        for (const subscriber of this.subscribers) {
+            try {
+                subscriber(event);
+            }
+            catch {
+                this.subscribers.delete(subscriber);
+            }
+        }
+    }
+    publicInfo(session) {
+        const info = session.getInfo();
+        const agentId = info.agentId ?? "codex";
+        return {
+            ...info,
+            agentId,
+            agentLabel: info.agentLabel ?? agentLabel(agentId),
+            capabilities: info.capabilities ?? CODEX_AGENT_CAPABILITIES,
+        };
+    }
+}
+function queueItemDto(item) {
+    return {
+        id: item.id,
+        description: item.description,
+        createdAt: new Date(item.createdAt).toISOString(),
+        attempts: item.attempts ?? 0,
+        notBefore: item.notBefore ? new Date(item.notBefore).toISOString() : undefined,
+        lastError: item.lastError,
+    };
+}
+function artifactDto(report) {
+    return {
+        turnId: report.turnId,
+        updatedAt: report.updatedAt.toISOString(),
+        source: report.source,
+        fileCount: report.artifacts.length,
+        totalSizeBytes: totalArtifactSize(report.artifacts),
+        skippedCount: report.skippedCount,
+        omittedCount: report.omittedCount,
+        artifacts: report.artifacts.map((artifact) => ({
+            name: artifact.name,
+            relativePath: artifact.relativePath.split(path.sep).join("/"),
+            sizeBytes: artifact.sizeBytes,
+        })),
+    };
+}
+function externalStatusLine(snapshot, queueLength) {
+    const elapsed = snapshot.activity.startedAt
+        ? formatDuration((Date.now() - snapshot.activity.startedAt.getTime()) / 1000)
+        : "-";
+    const tool = snapshot.latestToolName ?? "-";
+    return `Codex CLI running · ${elapsed} · tool ${tool} · ${queueLength} queued`;
+}
+function durationFromDates(start, end) {
+    if (!start || !end) {
+        return undefined;
+    }
+    return Math.max(0, end.getTime() - start.getTime());
+}
+function formatDuration(seconds) {
+    if (!Number.isFinite(seconds) || seconds < 0) {
+        return "-";
+    }
+    if (seconds < 60) {
+        return `${Math.round(seconds)}s`;
+    }
+    const minutes = Math.floor(seconds / 60);
+    const remainder = Math.round(seconds % 60);
+    return `${minutes}m ${remainder}s`;
+}
+function normalizeMimeType(value, name) {
+    const configured = value?.trim();
+    if (configured) {
+        return configured;
+    }
+    const extension = path.extname(name).toLowerCase();
+    if ([".jpg", ".jpeg"].includes(extension))
+        return "image/jpeg";
+    if (extension === ".png")
+        return "image/png";
+    if (extension === ".gif")
+        return "image/gif";
+    if (extension === ".webp")
+        return "image/webp";
+    if (extension === ".mp3")
+        return "audio/mpeg";
+    if (extension === ".wav")
+        return "audio/wav";
+    if (extension === ".ogg" || extension === ".oga")
+        return "audio/ogg";
+    if (extension === ".m4a")
+        return "audio/mp4";
+    if (extension === ".webm")
+        return "audio/webm";
+    return "application/octet-stream";
+}
+function uploadFileDtos(files) {
+    return files.map((file) => ({
+        name: file.safeName,
+        mimeType: file.mimeType,
+        sizeBytes: file.sizeBytes,
+    }));
+}
+function isPreviewableTextFile(extension, sizeBytes) {
+    if (sizeBytes > MAX_TEXT_PREVIEW_BYTES * 4) {
+        return false;
+    }
+    return [
+        "",
+        ".c",
+        ".conf",
+        ".cpp",
+        ".css",
+        ".csv",
+        ".env",
+        ".go",
+        ".html",
+        ".java",
+        ".js",
+        ".json",
+        ".jsx",
+        ".log",
+        ".md",
+        ".py",
+        ".rb",
+        ".rs",
+        ".sh",
+        ".sql",
+        ".toml",
+        ".ts",
+        ".tsx",
+        ".txt",
+        ".xml",
+        ".yaml",
+        ".yml",
+    ].includes(extension);
+}