@sireai/optimus 0.1.1

package/dist/problem-solving-core/codex/codex-runner.js

@@ -0,0 +1,926 @@
+// CodexRunner is the execution bridge between Optimus task orchestration and the Codex SDK.
+// It prepares runtime-owned CODEX_HOME state, builds thread options and prompts, streams SDK events into task states, and validates structured results.
+// This module owns Codex execution behavior, but task claiming, harness selection, and persistence stay outside in orchestration/store layers.
+import { mkdir, writeFile, readFile, access } from "node:fs/promises";
+import { join, resolve, relative, sep, posix as posixPath } from "node:path";
+import { Codex } from "@openai/codex-sdk";
+import { buildExecutionContextPrompt, buildExecutionTaskPackage, getExecutionAdditionalDirectories } from "../../task-environment/execution-addresses.js";
+import { OptimusLogger } from "../../task-environment/observability/logger.js";
+import { CodexAuthResolver } from "./codex-auth-resolver.js";
+import { buildCodexConnectivityChecks } from "./codex-connectivity-checks.js";
+import { renderRuntimeCodexHomeConfig, resolveConfiguredCodexModelProvider, resolveEffectiveCodexModel } from "./codex-provider-profile.js";
+import { CodexPreflight } from "./codex-preflight.js";
+import { classifyCodexFailureCategory } from "./codex-failure-classifier.js";
+function normalizePromptValue(value) {
+    const trimmed = value?.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    return trimmed.replace(/\r\n/g, "\n");
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^$()|[\]{}]/g, "\\$&");
+}
+function resolveTaskResultPath(resultPath, artifactDir) {
+    if (resultPath.startsWith("/")) {
+        return resolve(resultPath);
+    }
+    return resolve(artifactDir, resultPath);
+}
+class CodexExecutionError extends Error {
+    failureCategory;
+    constructor(message, failureCategory) {
+        super(message);
+        this.name = "CodexExecutionError";
+        this.failureCategory = failureCategory;
+    }
+}
+export class CodexRunner {
+    config;
+    logger;
+    constructor(config) {
+        this.config = config;
+        this.logger = new OptimusLogger(config);
+    }
+    async runTask(request, context) {
+        await this.logger.info("optimus.runner.task_started", {
+            taskId: request.task.taskId,
+            taskType: request.task.taskType,
+            runId: request.task.activeRunId,
+            status: request.task.status,
+            stage: "runner_start",
+            sandboxMode: context.sandboxMode,
+            approvalPolicy: context.approvalPolicy
+        });
+        const preflight = await new CodexPreflight(this.config).run();
+        if (!preflight.ok) {
+            throw new CodexExecutionError(preflight.summary, preflight.failureCategory ?? "auth_missing");
+        }
+        const result = await this.runWithCodexSdk(request, context);
+        await this.logger.info("optimus.runner.task_finished", {
+            taskId: request.task.taskId,
+            taskType: request.task.taskType,
+            runId: request.task.activeRunId,
+            status: result.status,
+            stage: "runner_finish"
+        });
+        return result;
+    }
+    async runHealthCheck() {
+        const effectiveModel = resolveEffectiveCodexModel(this.config);
+        const effectiveProvider = resolveConfiguredCodexModelProvider(this.config);
+        const diagnosticsBase = {
+            codexHomeDir: this.config.codex.homeDir,
+            timeoutMs: this.config.runtime.startupTimeoutMs,
+            approvalPolicy: this.config.codex.approvalPolicy,
+            sandboxMode: this.config.codex.sandboxMode
+        };
+        if (effectiveModel) {
+            diagnosticsBase.model = effectiveModel;
+        }
+        if (effectiveProvider) {
+            diagnosticsBase.provider = effectiveProvider;
+        }
+        try {
+            const preflight = await new CodexPreflight(this.config).run();
+            if (!preflight.ok) {
+                return {
+                    ok: false,
+                    summary: preflight.summary,
+                    diagnostics: {
+                        ...diagnosticsBase,
+                        auth: preflight.auth,
+                        preflightChecks: preflight.checks,
+                        connectivityChecks: buildCodexConnectivityChecks({
+                            config: this.config,
+                            failureMessage: preflight.summary,
+                            failureCategory: preflight.failureCategory
+                        }),
+                        ...(preflight.failureCategory ? { failureCategory: preflight.failureCategory } : {})
+                    }
+                };
+            }
+            await this.ensureCodexHome();
+            const codex = this.createCodexClient();
+            const thread = codex.startThread(this.buildThreadOptions({
+                workingDirectory: process.cwd(),
+                sandboxMode: this.config.codex.sandboxMode,
+                approvalPolicy: this.config.codex.approvalPolicy
+            }));
+            const turn = await thread.run([{ type: "text", text: "hello" }], {
+                signal: this.createExecutionSignal(undefined, this.config.runtime.startupTimeoutMs)
+            });
+            const healthCheckOutput = this.parseHealthCheckResponse(turn.finalResponse);
+            const auth = new CodexAuthResolver(this.config).resolve();
+            return {
+                ok: true,
+                summary: "Codex SDK health-check passed.",
+                diagnostics: {
+                    ...diagnosticsBase,
+                    auth: auth.diagnostics,
+                    preflightChecks: preflight.checks,
+                    connectivityChecks: buildCodexConnectivityChecks({
+                        config: this.config,
+                        failureCategory: undefined
+                    })
+                },
+                rawOutput: healthCheckOutput
+            };
+        }
+        catch (error) {
+            const auth = new CodexAuthResolver(this.config).resolve();
+            const preflight = await new CodexPreflight(this.config).run();
+            const failureMessage = error instanceof Error ? error.message : "Unknown Codex SDK health-check failure";
+            const failureCategory = this.resolveFailureCategory(error) ?? "unknown";
+            return {
+                ok: false,
+                summary: failureMessage,
+                diagnostics: {
+                    ...diagnosticsBase,
+                    auth: auth.diagnostics,
+                    preflightChecks: preflight.checks,
+                    connectivityChecks: buildCodexConnectivityChecks({
+                        config: this.config,
+                        failureMessage,
+                        failureCategory
+                    }),
+                    failureCategory
+                }
+            };
+        }
+    }
+    async runWithCodexSdk(request, context) {
+        await this.ensureCodexHome();
+        const bundle = this.loadTaskHarnessDocumentSet(request);
+        const prompt = this.buildPrompt(request, bundle, context);
+        const promptText = prompt.map((item) => item.text).join("\n\n");
+        await this.logger.debug("optimus.runner.execution_prompt", {
+            taskId: request.task.taskId,
+            taskType: request.task.taskType,
+            runId: request.task.activeRunId,
+            stage: "execution_prompt",
+            prompt: promptText
+        });
+        const codex = this.createCodexClient();
+        const threadOptions = this.buildThreadOptions({
+            workingDirectory: context.addresses.workspaceDir,
+            sandboxMode: context.sandboxMode,
+            approvalPolicy: context.approvalPolicy
+        });
+        const additionalDirectories = getExecutionAdditionalDirectories(context.addresses);
+        if (additionalDirectories.length > 0) {
+            threadOptions.additionalDirectories = additionalDirectories;
+        }
+        const thread = codex.startThread(threadOptions);
+        await this.logger.debug("optimus.runner.prepared", {
+            taskId: request.task.taskId,
+            taskType: request.harness.taskType,
+            sourceEventId: request.task.sourceEventId,
+            runId: request.task.activeRunId,
+            workspaceDir: context.addresses.workspaceDir,
+            sandboxMode: context.sandboxMode,
+            approvalPolicy: context.approvalPolicy,
+            workspaceSkillMountDir: context.workspaceSkillMountDir ?? null,
+            mountedSkillCount: context.mountedSkills?.length ?? 0
+        });
+        const turnOptions = {
+            outputSchema: this.buildOutputSchema()
+        };
+        if (context.abortSignal) {
+            turnOptions.signal = context.abortSignal;
+        }
+        const { events } = await thread.runStreamed(prompt, turnOptions);
+        const heartbeatAt = () => new Date().toISOString();
+        const turnCollection = {
+            agentMessages: [],
+            sawTurnCompleted: false
+        };
+        for await (const event of events) {
+            await this.logger.debug("optimus.runner.stream_event", {
+                taskId: request.task.taskId,
+                taskType: request.task.taskType,
+                runId: request.task.activeRunId,
+                ...(thread.id ? { sdkThreadId: thread.id } : {}),
+                stage: "stream_event",
+                eventType: event.type,
+                ...(event.type.startsWith("item.") && "item" in event ? { itemType: event.item.type } : {}),
+                headline: this.describeStreamEvent(event),
+                detail: this.describeStreamEventDetail(event),
+                event
+            });
+            await context.onStatusUpdate?.({
+                status: "running",
+                detail: `Codex stream event received: ${event.type}.`,
+                runStatus: "sdk_streaming",
+                health: "healthy_running",
+                eventType: `stream.${event.type}`,
+                ...(thread.id ? { sdkThreadId: thread.id } : {}),
+                heartbeatAt: heartbeatAt()
+            });
+            if (event.type === "turn.started") {
+                await context.onStatusUpdate?.({
+                    status: "running",
+                    detail: "Codex turn started.",
+                    runStatus: "sdk_running",
+                    health: "healthy_running",
+                    eventType: event.type,
+                    ...(thread.id ? { sdkThreadId: thread.id } : {}),
+                    incrementProgressCounter: true,
+                    heartbeatAt: heartbeatAt()
+                });
+            }
+            if (event.type === "turn.completed") {
+                turnCollection.sawTurnCompleted = true;
+            }
+            if (event.type === "item.completed") {
+                const detail = this.describeCompletedItem(event.item);
+                if (detail) {
+                    await context.onStatusUpdate?.({
+                        ...detail,
+                        runStatus: event.item.type === "agent_message" ? "validating" : "sdk_streaming",
+                        health: "healthy_running",
+                        eventType: event.item.type,
+                        ...(thread.id ? { sdkThreadId: thread.id } : {}),
+                        incrementProgressCounter: true,
+                        incrementCommandCount: event.item.type === "command_execution",
+                        incrementFileChangeCount: event.item.type === "file_change",
+                        ...(event.item.type === "agent_message" ? { agentMessagePreview: event.item.text.slice(0, 160) } : {}),
+                        heartbeatAt: heartbeatAt()
+                    });
+                }
+                if (event.item.type === "agent_message") {
+                    turnCollection.agentMessages.push(event.item.text);
+                }
+            }
+            if (event.type === "turn.failed") {
+                await this.logger.error("optimus.runner.turn_failed", {
+                    taskId: request.task.taskId,
+                    taskType: request.task.taskType,
+                    runId: request.task.activeRunId,
+                    ...(thread.id ? { sdkThreadId: thread.id } : {}),
+                    stage: "turn_failed",
+                    reason: event.error.message
+                });
+                throw new CodexExecutionError(event.error.message, this.classifyFailureCategory(event.error.message));
+            }
+            if (event.type === "error") {
+                await this.logger.error("optimus.runner.turn_failed", {
+                    taskId: request.task.taskId,
+                    taskType: request.task.taskType,
+                    runId: request.task.activeRunId,
+                    ...(thread.id ? { sdkThreadId: thread.id } : {}),
+                    stage: "stream_error",
+                    reason: event.message
+                });
+                throw new CodexExecutionError(event.message, this.classifyFailureCategory(event.message));
+            }
+        }
+        const latestAgentMessage = turnCollection.agentMessages.at(-1) ?? "";
+        const rawResponsePath = await this.writeDebugResponseArtifact(context.addresses.artifactDir, request.task.activeRunId ?? request.task.taskId, "raw-response.json", latestAgentMessage);
+        const agentMessagesPath = await this.writeDebugResponseArtifact(context.addresses.artifactDir, request.task.activeRunId ?? request.task.taskId, "agent-messages.json", JSON.stringify(turnCollection.agentMessages, null, 2));
+        await this.logger.debug("optimus.runner.raw_response", {
+            taskId: request.task.taskId,
+            taskType: request.task.taskType,
+            runId: request.task.activeRunId,
+            ...(thread.id ? { sdkThreadId: thread.id } : {}),
+            stage: "raw_response",
+            sawTurnCompleted: turnCollection.sawTurnCompleted,
+            agentMessageCount: turnCollection.agentMessages.length,
+            responsePreview: this.previewResponse(latestAgentMessage, 4000),
+            response: latestAgentMessage,
+            responseArtifactPath: rawResponsePath,
+            agentMessagesArtifactPath: agentMessagesPath
+        });
+        const resolvedTurnResult = await this.resolveTurnResult(turnCollection, context, {
+            taskId: request.task.taskId,
+            taskType: request.task.taskType,
+            ...(request.task.activeRunId ? { runId: request.task.activeRunId } : {}),
+            ...(thread.id ? { sdkThreadId: thread.id } : {})
+        });
+        const parsed = resolvedTurnResult.response;
+        const normalizedResponseText = JSON.stringify(parsed, null, 2);
+        const parsedResponsePath = await this.writeDebugResponseArtifact(context.addresses.artifactDir, request.task.activeRunId ?? request.task.taskId, "parsed-response.json", normalizedResponseText);
+        await this.logger.debug("optimus.runner.parsed_response", {
+            taskId: request.task.taskId,
+            taskType: request.task.taskType,
+            runId: request.task.activeRunId,
+            ...(thread.id ? { sdkThreadId: thread.id } : {}),
+            stage: "parsed_response",
+            status: parsed.status,
+            ...(parsed.resultPath ? { resultPath: parsed.resultPath } : {}),
+            ...(parsed.error?.category ? { errorCategory: parsed.error.category } : {}),
+            parsedResponse: normalizedResponseText,
+            responseArtifactPath: parsedResponsePath,
+            usedFallback: resolvedTurnResult.diagnostics?.usedFallback ?? false,
+            ...(resolvedTurnResult.diagnostics?.fallbackReason ? { fallbackReason: resolvedTurnResult.diagnostics.fallbackReason } : {})
+        });
+        await this.logger.info("optimus.runner.result_parsed", {
+            taskId: request.task.taskId,
+            taskType: request.task.taskType,
+            runId: request.task.activeRunId,
+            ...(thread.id ? { sdkThreadId: thread.id } : {}),
+            stage: "result_parsed",
+            status: parsed.status,
+            artifactCount: parsed.resultPath ? 1 : 0,
+            ...(parsed.error?.category ? { failureCategory: parsed.error.category } : {}),
+            resultPath: parsed.resultPath
+        });
+        if (parsed.resultPath) {
+            const resolvedResultPath = resolveTaskResultPath(parsed.resultPath, context.addresses.artifactDir);
+            const resultDocument = await this.normalizeResultDocumentPaths(resolvedResultPath, context);
+            await this.logger.debug("optimus.runner.result_document", {
+                taskId: request.task.taskId,
+                taskType: request.task.taskType,
+                runId: request.task.activeRunId,
+                ...(thread.id ? { sdkThreadId: thread.id } : {}),
+                stage: "result_document",
+                resultPath: resolvedResultPath,
+                resultDocument
+            });
+        }
+        await this.logger.info("optimus.runner.turn_completed", {
+            taskId: request.task.taskId,
+            taskType: request.task.taskType,
+            runId: request.task.activeRunId,
+            ...(thread.id ? { sdkThreadId: thread.id } : {}),
+            stage: "turn_completed"
+        });
+        return {
+            status: parsed.status,
+            ...(parsed.error ? { error: parsed.error } : {}),
+            ...(parsed.resultPath ? { resultPath: parsed.resultPath } : {}),
+            diagnostics: this.createDiagnostics({
+                ...(thread.id ? { sdkThreadId: thread.id } : {}),
+                ...(resolvedTurnResult.diagnostics ?? {})
+            })
+        };
+    }
+    async resolveTurnResult(turnCollection, context, resolutionContext) {
+        if (!turnCollection.sawTurnCompleted) {
+            throw new CodexExecutionError("Codex stream ended without turn.completed.", "process_exit");
+        }
+        let lastContractError;
+        for (let index = turnCollection.agentMessages.length - 1; index >= 0; index -= 1) {
+            const candidate = turnCollection.agentMessages[index] ?? "";
+            if (!candidate.trim()) {
+                continue;
+            }
+            try {
+                const parsed = this.parseCodexResponse(candidate);
+                this.validateResultContract(parsed, context);
+                return {
+                    response: parsed,
+                    rawResponse: candidate
+                };
+            }
+            catch (error) {
+                if (error instanceof CodexExecutionError) {
+                    lastContractError = error;
+                    continue;
+                }
+                throw error;
+            }
+        }
+        const fallbackResult = await this.tryResolveResultDocumentFallback(context, resolutionContext, lastContractError);
+        if (fallbackResult) {
+            return fallbackResult;
+        }
+        if (lastContractError) {
+            throw lastContractError;
+        }
+        throw new CodexExecutionError("Codex turn completed without any agent_message result.", "schema_error");
+    }
+    async tryResolveResultDocumentFallback(context, resolutionContext, cause) {
+        const fallbackPath = join(context.addresses.artifactDir, "result.md");
+        try {
+            await access(fallbackPath);
+            const resultDocument = await readFile(fallbackPath, "utf8");
+            if (!resultDocument.trim()) {
+                return undefined;
+            }
+            const normalizedResultDocument = await this.normalizeResultDocumentPaths(fallbackPath, context);
+            await this.logger.warn("optimus.runner.result_fallback", {
+                taskId: resolutionContext.taskId,
+                taskType: resolutionContext.taskType,
+                runId: resolutionContext.runId,
+                stage: "result_fallback",
+                ...(resolutionContext.sdkThreadId ? { sdkThreadId: resolutionContext.sdkThreadId } : {}),
+                resultPath: fallbackPath,
+                reason: cause?.message ?? "structured_result_missing",
+                failureCategory: cause?.failureCategory ?? "schema_error",
+                resultDocument: normalizedResultDocument
+            });
+            return {
+                response: {
+                    status: "completed",
+                    resultPath: "result.md"
+                },
+                rawResponse: resultDocument,
+                diagnostics: {
+                    usedFallback: true,
+                    fallbackReason: "result_document_detected_after_invalid_structured_response",
+                    failureCategory: cause?.failureCategory ?? "schema_error",
+                    ...(resolutionContext.sdkThreadId ? { sdkThreadId: resolutionContext.sdkThreadId } : {})
+                }
+            };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    describeStreamEventDetail(event) {
+        if (!(event.type.startsWith("item.") && "item" in event && event.item)) {
+            return undefined;
+        }
+        const itemType = typeof event.item.type === "string" ? event.item.type : undefined;
+        if (!itemType) {
+            return undefined;
+        }
+        if (itemType === "command_execution") {
+            const command = this.extractCommandPreview(event.item);
+            return command ? `cmd: ${command}` : "command execution";
+        }
+        if (itemType === "reasoning") {
+            const text = this.extractTextPreview(event.item.text);
+            return text;
+        }
+        if (itemType === "agent_message") {
+            const text = this.extractTextPreview(event.item.text);
+            return text;
+        }
+        if (itemType === "mcp_tool_call") {
+            const server = typeof event.item.server === "string" ? event.item.server : undefined;
+            const tool = typeof event.item.tool === "string" ? event.item.tool : undefined;
+            return [server, tool].filter(Boolean).join("/") || undefined;
+        }
+        if (itemType === "web_search") {
+            const query = typeof event.item.query === "string" ? event.item.query : undefined;
+            return this.extractTextPreview(query);
+        }
+        if (itemType === "todo_list") {
+            const items = Array.isArray(event.item.items) ? (event.item.items ?? []) : [];
+            const pending = items.filter((item) => !item?.completed).map((item) => item?.text).filter((value) => typeof value === "string" && value.length > 0);
+            return this.extractTextPreview(pending.join("; "));
+        }
+        if (itemType === "file_change") {
+            const changes = Array.isArray(event.item.changes) ? (event.item.changes ?? []) : [];
+            const paths = changes.slice(0, 3).map((entry) => {
+                const filePath = entry["path"] ?? entry["file_path"] ?? entry["new_path"] ?? entry["old_path"];
+                return typeof filePath === "string" ? filePath : undefined;
+            }).filter((value) => typeof value === "string" && value.length > 0);
+            return paths.length > 0 ? this.extractTextPreview(paths.join(", ")) : "file changes";
+        }
+        return undefined;
+    }
+    extractCommandPreview(item) {
+        const command = item["command"] ?? item["cmd"] ?? item["shell_command"];
+        if (typeof command === "string") {
+            return this.extractTextPreview(command);
+        }
+        if (Array.isArray(command)) {
+            return this.extractTextPreview(command.filter((value) => typeof value === "string").join(" "));
+        }
+        return undefined;
+    }
+    extractTextPreview(value) {
+        if (typeof value !== "string") {
+            return undefined;
+        }
+        const collapsed = value.replace(/\s+/g, " ").trim();
+        if (!collapsed) {
+            return undefined;
+        }
+        return collapsed.length > 120 ? `${collapsed.slice(0, 117)}...` : collapsed;
+    }
+    describeStreamEvent(event) {
+        if (event.type === "thread.started") {
+            return "Execution workspace attached.";
+        }
+        if (event.type === "turn.started") {
+            return "Agent started working.";
+        }
+        if (event.type === "turn.completed") {
+            return "Agent finished this turn.";
+        }
+        if (event.type === "turn.failed") {
+            return "Agent turn failed.";
+        }
+        if (event.type === "error") {
+            return "Execution stream failed.";
+        }
+        if (event.type === "item.started") {
+            switch (event.item?.type) {
+                case "reasoning":
+                    return "Agent is planning.";
+                case "command_execution":
+                    return "Agent started a command.";
+                case "mcp_tool_call":
+                    return "Agent started a tool call.";
+                case "web_search":
+                    return "Agent started a search.";
+                case "file_change":
+                    return "Agent started editing files.";
+                case "agent_message":
+                    return "Agent is preparing the final answer.";
+                case "todo_list":
+                    return "Agent updated its plan.";
+                default:
+                    return `Agent started ${event.item?.type ?? "work"}.`;
+            }
+        }
+        if (event.type === "item.updated") {
+            switch (event.item?.type) {
+                case "reasoning":
+                    return "Agent is refining the plan.";
+                case "command_execution":
+                    return "Agent command is running.";
+                case "mcp_tool_call":
+                    return "Agent tool call is running.";
+                case "web_search":
+                    return "Agent search is running.";
+                case "file_change":
+                    return "Agent is updating files.";
+                case "todo_list":
+                    return "Agent adjusted the plan.";
+                default:
+                    return `Agent updated ${event.item?.type ?? "work"}.`;
+            }
+        }
+        if (event.type === "item.completed") {
+            switch (event.item?.type) {
+                case "reasoning":
+                    return "Planning step completed.";
+                case "command_execution":
+                    return "Command completed.";
+                case "mcp_tool_call":
+                    return "Tool call completed.";
+                case "web_search":
+                    return "Search completed.";
+                case "file_change":
+                    return "File changes prepared.";
+                case "agent_message":
+                    return "Final answer prepared.";
+                case "todo_list":
+                    return "Plan updated.";
+                default:
+                    return `${event.item?.type ?? "work"} completed.`;
+            }
+        }
+        return `Execution event: ${event.type}.`;
+    }
+    buildThreadOptions(input) {
+        const options = {
+            modelReasoningEffort: this.config.codex.reasoningEffort,
+            workingDirectory: input.workingDirectory,
+            skipGitRepoCheck: true,
+            sandboxMode: input.sandboxMode,
+            approvalPolicy: input.approvalPolicy,
+            networkAccessEnabled: this.config.runtime.networkAccessEnabled
+        };
+        const effectiveModel = resolveEffectiveCodexModel(this.config);
+        if (effectiveModel) {
+            options.model = effectiveModel;
+        }
+        if (input.additionalDirectories && input.additionalDirectories.length > 0) {
+            options.additionalDirectories = input.additionalDirectories;
+        }
+        return options;
+    }
+    describeCompletedItem(item) {
+        if (item.type === "command_execution") {
+            return { status: "running", detail: "Agent command execution completed." };
+        }
+        if (item.type === "file_change") {
+            return { status: "patch_generated", detail: "Agent generated file changes." };
+        }
+        if (item.type === "agent_message") {
+            return { status: "validating", detail: "Agent produced final response; validating output." };
+        }
+        return undefined;
+    }
+    // Harness documents stay ordered so the execution frame can deliver the task contract in the intended reading sequence.
+    loadTaskHarnessDocumentSet(request) {
+        return {
+            sections: [
+                {
+                    title: request.harness.roleDocument.title,
+                    content: request.harness.roleDocument.content
+                },
+                {
+                    title: request.harness.constraintsDocument.title,
+                    content: request.harness.constraintsDocument.content
+                },
+                {
+                    title: request.harness.contextDocument.title,
+                    content: request.harness.contextDocument.content
+                },
+                {
+                    title: request.harness.standardDocument.title,
+                    content: request.harness.standardDocument.content
+                },
+                {
+                    title: request.harness.evolutionDocument.title,
+                    content: request.harness.evolutionDocument.content
+                }
+            ]
+        };
+    }
+    // Prompt assembly applies a stable outer markdown hierarchy and normalizes harness-document headings to avoid flat top-level sections.
+    buildPrompt(request, bundle, context) {
+        const roleSection = this.renderExecutionFrameSection(bundle.sections[0], 2);
+        const constraintsSection = this.renderExecutionFrameSection(bundle.sections[1], 2);
+        const contextSection = this.renderExecutionFrameSection(bundle.sections[2], 2);
+        const standardSection = this.renderExecutionFrameSection(bundle.sections[3], 1);
+        const evolutionSection = this.renderExecutionFrameSection(bundle.sections[4], 1);
+        const promptTaskPackage = buildExecutionTaskPackage(request.taskPackage, context.addresses);
+        const executionContext = buildExecutionContextPrompt(context);
+        const repositoryMemorySection = context.repoMemory?.exists
+            ? [
+                "## REPOSITORY MEMORY\n\n",
+                this.demoteMarkdownHeadings((context.repoMemory.content ?? "").trim(), 2)
+            ].join("")
+            : [
+                "## REPOSITORY MEMORY STATUS\n\n",
+                `Repository memory is missing. Create or refresh it at ${context.repoMemory?.memoryFilePath ?? "<memory-path>"} before closing the task.`
+            ].join("");
+        const executionFrameCore = [
+            roleSection,
+            "\n\n",
+            constraintsSection,
+            "\n\n",
+            contextSection
+        ].join("");
+        const finalDeliveryRules = [
+            "## FINAL DELIVERY RULES\n\n",
+            "After writing `result.md` under `artifactDir`, return only the runtime JSON contract: `status`, optional `error`, and `resultPath`."
+        ].join("\n");
+        return [{
+                type: "text",
+                text: [
+                    "# EXECUTION FRAME\n\n",
+                    "Read and obey this frame before acting. Do not redo triage. Operate only as the execution agent for the accepted task.\n\n",
+                    executionFrameCore,
+                    "\n\n## COMPLETION STANDARD\n\n",
+                    standardSection,
+                    "\n\n## EVOLUTION\n\n",
+                    evolutionSection,
+                    "\n\n# TASK PACKAGE\n\n",
+                    "Treat this as the task payload. repo and branch are routing facts. input.metadata is open-ended and must be consumed generically.\n\n",
+                    "```json\n",
+                    JSON.stringify(promptTaskPackage, null, 2),
+                    "\n```\n\n",
+                    "# EXECUTION CONTEXT\n\n",
+                    "## RUNTIME\n\n",
+                    "Use this as runtime context, not as task policy.\n\n",
+                    "```json\n",
+                    JSON.stringify(executionContext, null, 2),
+                    "\n```\n\n",
+                    repositoryMemorySection,
+                    "\n\n",
+                    finalDeliveryRules
+                ].join("")
+            }];
+    }
+    renderExecutionFrameSection(section, headingLevels = 1) {
+        if (!section) {
+            return "";
+        }
+        return this.normalizeHarnessMarkdown(section.title, section.content, headingLevels);
+    }
+    normalizeHarnessMarkdown(sectionTitle, content, headingLevels = 1) {
+        const stripped = this.stripRedundantTopHeading(sectionTitle, content.trim());
+        return this.demoteMarkdownHeadings(stripped, headingLevels);
+    }
+    stripRedundantTopHeading(sectionTitle, content) {
+        const lines = content.split(/\r?\n/);
+        if (lines.length === 0) {
+            return content;
+        }
+        const firstLine = lines[0]?.trim() ?? "";
+        const headingMatch = firstLine.match(/^(#{1,6})\s+(.+)$/);
+        if (!headingMatch) {
+            return content;
+        }
+        const normalizedHeading = headingMatch[2]?.trim().toLowerCase();
+        const normalizedSectionTitle = sectionTitle.trim().toLowerCase();
+        if (normalizedHeading !== normalizedSectionTitle) {
+            return content;
+        }
+        let startIndex = 1;
+        while (startIndex < lines.length && lines[startIndex]?.trim() === "") {
+            startIndex += 1;
+        }
+        return lines.slice(startIndex).join("\n");
+    }
+    demoteMarkdownHeadings(content, levels) {
+        if (!content) {
+            return content;
+        }
+        return content.replace(/^(#{1,6})(\s+.*)$/gm, (_match, hashes, suffix) => {
+            const nextLevel = Math.min(6, hashes.length + levels);
+            return `${"#".repeat(nextLevel)}${suffix}`;
+        });
+    }
+    async normalizeResultDocumentPaths(resultPath, context) {
+        const original = await readFile(resultPath, "utf8");
+        const sanitized = this.sanitizeResultDocumentPaths(original, context);
+        if (sanitized !== original) {
+            await writeFile(resultPath, sanitized, "utf8");
+        }
+        return sanitized;
+    }
+    sanitizeResultDocumentPaths(document, context) {
+        const roots = Array.from(new Set([context.addresses.workspaceDir, context.addresses.sourceDir]
+            .map((value) => resolve(value))
+            .sort((left, right) => right.length - left.length)));
+        if (roots.length === 0) {
+            return document;
+        }
+        const toRepoRelative = (absolutePath, lineNumber) => {
+            const normalizedPath = resolve(absolutePath);
+            for (const root of roots) {
+                if (normalizedPath !== root && !normalizedPath.startsWith(`${root}${sep}`)) {
+                    continue;
+                }
+                const relativePath = relative(root, normalizedPath);
+                const displayPath = relativePath.length > 0 ? relativePath.split(sep).join(posixPath.sep) : ".";
+                return lineNumber ? `${displayPath}:L${lineNumber}` : displayPath;
+            }
+            return undefined;
+        };
+        let sanitized = document.replace(/\[([^\]]+)\]\((\/[^)\s#]+)(?:#L(\d+))?\)/g, (match, _label, absolutePath, lineNumber) => {
+            const repoRelative = toRepoRelative(absolutePath, lineNumber);
+            return repoRelative ? `\`${repoRelative}\`` : match;
+        });
+        for (const root of roots) {
+            const escapedRoot = escapeRegExp(root);
+            const pathPattern = new RegExp(`${escapedRoot}(?:\/[^\s)\]"']*)?(?:#L(\d+))?`, "g");
+            sanitized = sanitized.replace(pathPattern, (match, lineNumber) => {
+                const pathOnly = typeof lineNumber === "string" ? match.slice(0, match.length - (`#L${lineNumber}`).length) : match;
+                const repoRelative = toRepoRelative(pathOnly, lineNumber);
+                return repoRelative ?? match;
+            });
+        }
+        return sanitized;
+    }
+    buildOutputSchema() {
+        return {
+            type: "object",
+            additionalProperties: false,
+            // The provider currently enforces that root.required must cover every declared property
+            // when additionalProperties=false is used. Keep the transport schema strict-but-nullable,
+            // then let parseCodexResponse() apply the real status-dependent contract.
+            required: ["status", "error", "resultPath"],
+            properties: {
+                status: { type: "string", enum: ["completed", "failed"] },
+                error: {
+                    type: ["object", "null"],
+                    additionalProperties: false,
+                    required: ["category", "message"],
+                    properties: {
+                        category: { type: "string" },
+                        message: { type: "string" }
+                    }
+                },
+                resultPath: { type: ["string", "null"] }
+            }
+        };
+    }
+    parseCodexResponse(response) {
+        let parsed;
+        try {
+            parsed = JSON.parse(response);
+        }
+        catch (error) {
+            throw new CodexExecutionError(`Codex response was not valid JSON: ${error instanceof Error ? error.message : "unknown parse error"}`, "parse_error");
+        }
+        if (!parsed || typeof parsed !== "object") {
+            throw new CodexExecutionError("Codex response schema mismatch: root is not an object.", "schema_error");
+        }
+        const responseObject = parsed;
+        if (responseObject.status !== "completed" && responseObject.status !== "failed") {
+            throw new CodexExecutionError(`Codex response schema mismatch: missing status. Raw response preview: ${this.previewResponse(response)}`, "schema_error");
+        }
+        const resultPath = typeof responseObject.resultPath === "string" && responseObject.resultPath.trim().length > 0
+            ? responseObject.resultPath
+            : undefined;
+        if (responseObject.status === "failed") {
+            if (!responseObject.error || typeof responseObject.error !== "object") {
+                throw new CodexExecutionError("Codex response schema mismatch: failed result requires error.", "schema_error");
+            }
+            if (typeof responseObject.error.category !== "string" || typeof responseObject.error.message !== "string") {
+                throw new CodexExecutionError("Codex response schema mismatch: error.category/message missing.", "schema_error");
+            }
+            return {
+                status: "failed",
+                error: {
+                    category: responseObject.error.category,
+                    message: responseObject.error.message
+                },
+                ...(resultPath ? { resultPath } : {})
+            };
+        }
+        return {
+            status: "completed",
+            ...(resultPath ? { resultPath } : {})
+        };
+    }
+    validateResultContract(response, context) {
+        if (response.status === "failed") {
+            if (!response.error) {
+                throw new CodexExecutionError("Codex result contract mismatch: failed result is missing error.", "schema_error");
+            }
+            return;
+        }
+        if (!response.resultPath) {
+            throw new CodexExecutionError("Codex result contract mismatch: completed result must include resultPath.", "schema_error");
+        }
+        const resolvedArtifactDir = resolve(context.addresses.artifactDir);
+        const resolvedResultPath = resolveTaskResultPath(response.resultPath, context.addresses.artifactDir);
+        const relativeResultPath = relative(resolvedArtifactDir, resolvedResultPath);
+        const isWithinArtifactDir = relativeResultPath.length > 0 && !relativeResultPath.startsWith(`..${sep}`) && relativeResultPath !== "..";
+        if (!isWithinArtifactDir) {
+            throw new CodexExecutionError(`Codex result contract mismatch: resultPath ${response.resultPath} is outside artifactDir ${context.addresses.artifactDir}.`, "schema_error");
+        }
+    }
+    previewResponse(response, limit = 600) {
+        const normalized = response.replace(/\s+/g, " ").trim();
+        return normalized.length > limit ? `${normalized.slice(0, limit - 3)}...` : normalized;
+    }
+    // Debug response artifacts preserve the full Codex reply outside the rolling log preview, which is critical for schema troubleshooting.
+    async writeDebugResponseArtifact(artifactDir, runId, filename, content) {
+        const targetPath = join(artifactDir, `${runId}-${filename}`);
+        await writeFile(targetPath, content, "utf8");
+        return targetPath;
+    }
+    parseHealthCheckResponse(response) {
+        if (!response.trim()) {
+            throw new CodexExecutionError("Codex health-check returned an empty response.", "schema_error");
+        }
+        return response;
+    }
+    createExecutionSignal(externalSignal, timeoutMs) {
+        const timeoutSignal = AbortSignal.timeout(timeoutMs);
+        if (!externalSignal) {
+            return timeoutSignal;
+        }
+        if (typeof AbortSignal.any === "function") {
+            return AbortSignal.any([externalSignal, timeoutSignal]);
+        }
+        const controller = new AbortController();
+        const forwardAbort = (signal) => {
+            if (signal.aborted) {
+                controller.abort(signal.reason);
+                return;
+            }
+            signal.addEventListener("abort", () => controller.abort(signal.reason), { once: true });
+        };
+        forwardAbort(externalSignal);
+        forwardAbort(timeoutSignal);
+        return controller.signal;
+    }
+    // Runtime CODEX_HOME keeps provider routing isolated inside the Optimus workspace.
+    async ensureCodexHome() {
+        // Runtime always exports CODEX_HOME to Codex SDK, so the private home directory
+        // must exist before the first SDK call even if provider config rendering is deferred.
+        await mkdir(this.config.codex.homeDir, { recursive: true });
+        const configText = renderRuntimeCodexHomeConfig(this.config);
+        if (!configText) {
+            throw new CodexExecutionError("Unable to render runtime codex-home/config.toml. Check codex.provider and codex.model.", "config_error");
+        }
+        await writeFile(join(this.config.codex.homeDir, "config.toml"), configText, "utf8");
+    }
+    createCodexClient() {
+        const auth = new CodexAuthResolver(this.config).resolve();
+        const env = { ...auth.env };
+        // Keep the operator's HOME untouched and scope only Codex state to the private runtime home.
+        env.CODEX_HOME = this.config.codex.homeDir;
+        const options = { env };
+        if (auth.baseUrl) {
+            options.baseUrl = auth.baseUrl;
+        }
+        if (auth.apiKey) {
+            options.apiKey = auth.apiKey;
+        }
+        return new Codex(options);
+    }
+    resolveFailureCategory(error) {
+        if (typeof error === "object" && error && "failureCategory" in error) {
+            const category = error.failureCategory;
+            if (category) {
+                return category;
+            }
+        }
+        if (error instanceof Error) {
+            return classifyCodexFailureCategory(error.message);
+        }
+        return undefined;
+    }
+    classifyFailureCategory(message) {
+        return classifyCodexFailureCategory(message);
+    }
+    createDiagnostics(base) {
+        return base;
+    }
+}
+//# sourceMappingURL=codex-runner.js.map