@openclaw/codex 2026.6.1 → 2026.6.5-beta.1

package/dist/{run-attempt-DM53zFlW.js → run-attempt-B_6VkFQN.js}

@@ -1,16 +1,16 @@
-import { a as isCodexAppServerApprovalPolicyAllowedByRequirements, c as isCodexSandboxExecServerEnabled, d as resolveCodexAppServerRuntimeOptions, f as resolveCodexComputerUseConfig, g as withMcpElicitationsApprovalPolicy, h as shouldAutoApproveCodexAppServerApprovals, m as resolveOpenClawExecPolicyForCodexAppServer, p as resolveCodexPluginsPolicy, u as readCodexPluginConfig } from "./config-AlzuNKCY.js";
-import { a as readCodexDynamicToolCallParams, c as readCodexTurn, i as assertCodexTurnStartResponse } from "./protocol-validators-DIt7cXIp.js";
-import { a as isCodexAppServerConnectionClosedError, i as isCodexAppServerApprovalRequest, l as isJsonObject, r as compareCodexAppServerVersions, s as MIN_CODEX_SANDBOX_EXEC_SERVER_APP_SERVER_VERSION } from "./client-BnOmn0y-.js";
-import { A as projectContextEngineAssemblyForCodex, C as sanitizeCodexHistoryImagePayloads, D as normalizeCodexDynamicToolName$1, E as isForcedPrivateQaCodexRuntime, M as resolveCodexContextEngineProjectionReserveTokens, T as filterCodexDynamicTools, _ as shouldBuildCodexPluginThreadConfig, a as buildDeveloperInstructions, c as codexDynamicToolsFingerprint, f as startOrResumeThread, g as mergeCodexThreadConfigs, h as buildCodexPluginThreadConfigInputFingerprint, i as buildContextEngineBinding, j as resolveCodexContextEngineProjectionMaxChars, k as resolveCodexDynamicToolsLoadingForModel, l as isContextEngineBindingCompatible, m as buildCodexPluginThreadConfig, n as areCodexDynamicToolFingerprintsCompatible, o as buildTurnCollaborationMode, p as isCodexAppServerProfilerEnabled, s as buildTurnStartParams, x as defaultCodexAppInventoryCache } from "./thread-lifecycle-6nrEQZMV.js";
-import { a as readCodexAppServerBinding, n as clearCodexAppServerBindingForThread, s as writeCodexAppServerBinding, t as clearCodexAppServerBinding } from "./session-binding-DWiEGATW.js";
-import { n as buildCodexPluginAppCacheKey, r as CODEX_CONTROL_METHODS } from "./request-CPtFWp-f.js";
-import { _ as shouldRefreshCodexRateLimitsForUsageLimitMessage, g as resolveCodexUsageLimitResetAtMs, h as formatCodexUsageLimitErrorMessage, i as readCodexNotificationTurnId, n as isCodexNotificationForTurn, r as readCodexNotificationThreadId, s as formatCodexDisplayText, t as describeCodexNotificationCorrelation } from "./notification-correlation-BykOI_jh.js";
-import { a as releaseLeasedSharedCodexAppServerClient, d as resolveCodexAppServerAuthProfileId, f as resolveCodexAppServerAuthProfileIdForAgent, l as refreshCodexAppServerAuthTokens, m as resolveCodexAppServerHomeDir, o as retireSharedCodexAppServerClientIfCurrent, p as resolveCodexAppServerFallbackApiKeyCacheKey, t as clearSharedCodexAppServerClientIfCurrent, u as resolveCodexAppServerAuthAccountCacheKey } from "./shared-client-DUWLidr5.js";
-import { i as resolveCodexNativeExecutionPolicy } from "./sandbox-guard-DMCJlzmz.js";
-import { n as defaultLeasedCodexAppServerClientFactory } from "./client-factory-3ykiiX2z.js";
-import { S as withCodexStartupTimeout, _ as resolveCodexPostToolRawAssistantCompletionIdleTimeoutMs, a as createCodexNativeHookRelay, b as resolveCodexTurnCompletionIdleTimeoutMs, c as scheduleCodexNativeHookRelayUnregister, d as emitDynamicToolErrorDiagnostic, f as emitDynamicToolStartedDiagnostic, g as CODEX_POST_REASONING_REPLY_IDLE_TIMEOUT_MS, h as handleCodexAppServerApprovalRequest, i as buildCodexNativeHookRelayDisabledConfig, l as handleCodexAppServerElicitationRequest, m as filterToolsForVisionInputs, n as CODEX_NATIVE_HOOK_RELAY_TTL_GRACE_MS, o as resolveCodexNativeHookRelayEvents, p as emitDynamicToolTerminalDiagnostic, r as buildCodexNativeHookRelayConfig, s as resolveCodexNativeHookRelayTtlMs, u as createCodexDynamicToolBridge, v as resolveCodexStartupTimeoutMs, x as resolveCodexTurnTerminalIdleTimeoutMs, y as resolveCodexTurnAssistantCompletionIdleTimeoutMs } from "./native-hook-relay-CIJt8cLN.js";
-import { t as ensureCodexComputerUse } from "./computer-use-DYLSxIfq.js";
-import { n as rememberCodexRateLimits, t as readRecentCodexRateLimits } from "./rate-limit-cache-N66I-Rd7.js";
+import { c as readCodexPluginConfig, d as resolveCodexPluginsPolicy, f as resolveOpenClawExecPolicyForCodexAppServer, i as isCodexAppServerApprovalPolicyAllowedByRequirements, l as resolveCodexAppServerRuntimeOptions, m as withMcpElicitationsApprovalPolicy, o as isCodexSandboxExecServerEnabled, p as shouldAutoApproveCodexAppServerApprovals, u as resolveCodexComputerUseConfig } from "./config-BT6SLiE6.js";
+import { a as readCodexDynamicToolCallParams, c as readCodexTurn, i as assertCodexTurnStartResponse } from "./protocol-validators-CIpP8IJ2.js";
+import { a as isCodexAppServerConnectionClosedError, i as isCodexAppServerApprovalRequest, l as isJsonObject, r as compareCodexAppServerVersions, s as MIN_CODEX_SANDBOX_EXEC_SERVER_APP_SERVER_VERSION } from "./client-kMCtlApt.js";
+import { A as projectContextEngineAssemblyForCodex, C as sanitizeCodexHistoryImagePayloads, D as normalizeCodexDynamicToolName$1, E as isForcedPrivateQaCodexRuntime, M as resolveCodexContextEngineProjectionReserveTokens, T as filterCodexDynamicTools, _ as shouldBuildCodexPluginThreadConfig, a as buildDeveloperInstructions, c as codexDynamicToolsFingerprint, f as startOrResumeThread, g as mergeCodexThreadConfigs, h as buildCodexPluginThreadConfigInputFingerprint, i as buildContextEngineBinding, j as resolveCodexContextEngineProjectionMaxChars, k as resolveCodexDynamicToolsLoadingForModel, l as isContextEngineBindingCompatible, m as buildCodexPluginThreadConfig, n as areCodexDynamicToolFingerprintsCompatible, o as buildTurnCollaborationMode, p as isCodexAppServerProfilerEnabled, s as buildTurnStartParams, x as defaultCodexAppInventoryCache } from "./thread-lifecycle-BJsazZ8j.js";
+import { a as readCodexAppServerBinding, n as clearCodexAppServerBindingForThread, s as writeCodexAppServerBinding, t as clearCodexAppServerBinding } from "./session-binding-BgTv_YGm.js";
+import { n as buildCodexPluginAppCacheKey, r as CODEX_CONTROL_METHODS } from "./request-D64BfplD.js";
+import { _ as shouldRefreshCodexRateLimitsForUsageLimitMessage, g as resolveCodexUsageLimitResetAtMs, h as formatCodexUsageLimitErrorMessage, i as readCodexNotificationTurnId, n as isCodexNotificationForTurn, r as readCodexNotificationThreadId, s as formatCodexDisplayText, t as describeCodexNotificationCorrelation } from "./notification-correlation-o8quHmTK.js";
+import { d as resolveCodexAppServerAuthAccountCacheKey, f as resolveCodexAppServerAuthProfileId, h as resolveCodexAppServerHomeDir, m as resolveCodexAppServerFallbackApiKeyCacheKey, n as clearSharedCodexAppServerClientIfCurrentAndUnclaimed, o as releaseLeasedSharedCodexAppServerClient, p as resolveCodexAppServerAuthProfileIdForAgent, s as retireSharedCodexAppServerClientIfCurrent, t as clearSharedCodexAppServerClientIfCurrent, u as refreshCodexAppServerAuthTokens } from "./shared-client-xytpSKD0.js";
+import { i as resolveCodexNativeExecutionPolicy } from "./sandbox-guard-C-Yv9uwY.js";
+import { t as defaultLeasedCodexAppServerClientFactory } from "./client-factory-Bt49r45B.js";
+import { S as withCodexStartupTimeout, _ as resolveCodexPostToolRawAssistantCompletionIdleTimeoutMs, a as createCodexNativeHookRelay, b as resolveCodexTurnCompletionIdleTimeoutMs, c as scheduleCodexNativeHookRelayUnregister, d as emitDynamicToolErrorDiagnostic, f as emitDynamicToolStartedDiagnostic, g as CODEX_POST_REASONING_REPLY_IDLE_TIMEOUT_MS, h as handleCodexAppServerApprovalRequest, i as buildCodexNativeHookRelayDisabledConfig, l as handleCodexAppServerElicitationRequest, m as filterToolsForVisionInputs, n as CODEX_NATIVE_HOOK_RELAY_TTL_GRACE_MS, o as resolveCodexNativeHookRelayEvents, p as emitDynamicToolTerminalDiagnostic, r as buildCodexNativeHookRelayConfig, s as resolveCodexNativeHookRelayTtlMs, u as createCodexDynamicToolBridge, v as resolveCodexStartupTimeoutMs, x as resolveCodexTurnTerminalIdleTimeoutMs, y as resolveCodexTurnAssistantCompletionIdleTimeoutMs } from "./native-hook-relay-DZ3Oon0b.js";
+import { t as ensureCodexComputerUse } from "./computer-use-ClweWaMz.js";
+import { n as rememberCodexRateLimits, t as readRecentCodexRateLimits } from "./rate-limit-cache-C7qmZ0Jh.js";
 import { asDateTimestampMs, parseStrictNonNegativeInteger, resolveTimerTimeoutMs } from "openclaw/plugin-sdk/number-runtime";
 import { createHash, randomUUID } from "node:crypto";
 import fsSync from "node:fs";
@@ -33,6 +33,10 @@ import { generatedImageAssetFromBase64 } from "openclaw/plugin-sdk/image-generat
 import { saveMediaBuffer } from "openclaw/plugin-sdk/media-store";
 import { createAgentHarnessTaskRuntime, deliverAgentHarnessTaskCompletion, isDurableAgentHarnessCompletionDelivery } from "openclaw/plugin-sdk/agent-harness-task-runtime";
 //#region extensions/codex/src/app-server/app-server-policy.ts
+/**
+* Promotes implicit `never` approval policy to `untrusted` only when runtime
+* requirements allow OpenClaw to handle tool approvals.
+*/
 function resolveCodexAppServerForOpenClawToolPolicy(params) {
 	if (!params.shouldPromote || !params.canUseUntrustedApprovalPolicy || params.appServer.approvalPolicy !== "never") return params.appServer;
 	const explicitMode = params.execPolicy?.mode === "full" || params.pluginConfig.appServer?.mode !== void 0 || isCodexAppServerPolicyMode(params.env.OPENCLAW_CODEX_APP_SERVER_MODE);
@@ -51,8 +55,14 @@ function isCodexAppServerApprovalPolicy(value) {
 }
 //#endregion
 //#region extensions/codex/src/app-server/attempt-client-cleanup.ts
+/**
+* Best-effort cleanup helpers for timed-out or aborted Codex app-server turns.
+*/
+/** Timeout for best-effort app-server turn interruption during cleanup. */
 const CODEX_APP_SERVER_INTERRUPT_TIMEOUT_MS = 5e3;
+/** Timeout for best-effort thread unsubscribe during cleanup. */
 const CODEX_APP_SERVER_UNSUBSCRIBE_TIMEOUT_MS = 5e3;
+/** Sends a turn interrupt without blocking abort cleanup on app-server errors. */
 function interruptCodexTurnBestEffort(client, params) {
 	const requestOptions = params.timeoutMs && Number.isFinite(params.timeoutMs) && params.timeoutMs > 0 ? { timeoutMs: params.timeoutMs } : void 0;
 	const requestParams = {
@@ -68,6 +78,7 @@ function interruptCodexTurnBestEffort(client, params) {
 		embeddedAgentLog.debug("codex app-server turn interrupt failed during abort", { error });
 	}
 }
+/** Unsubscribes from a thread while swallowing cleanup-only failures. */
 async function unsubscribeCodexThreadBestEffort(client, params) {
 	try {
 		await client.request("thread/unsubscribe", { threadId: params.threadId }, { timeoutMs: params.timeoutMs });
@@ -78,6 +89,10 @@ async function unsubscribeCodexThreadBestEffort(client, params) {
 		});
 	}
 }
+/**
+* Retires the shared client after a timed-out turn so later runs do not reuse a
+* potentially wedged app-server connection.
+*/
 async function retireCodexAppServerClientAfterTimedOutTurn(client, params) {
 	const retiredSharedClient = retireSharedCodexAppServerClientIfCurrent(client);
 	const detachedSharedClient = Boolean(retiredSharedClient);
@@ -115,9 +130,14 @@ async function retireCodexAppServerClientAfterTimedOutTurn(client, params) {
 }
 //#endregion
 //#region extensions/codex/src/app-server/session-history.ts
+/**
+* Reads OpenClaw session history for Codex transcript mirroring and sanitizes
+* image payloads before replaying messages into the app-server projector.
+*/
 function isMissingFileError(error) {
 	return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
 }
+/** Returns sanitized session-context messages for a Codex mirrored session file. */
 async function readCodexMirroredSessionHistoryMessages(sessionFile) {
 	try {
 		const entries = parseSessionEntries(await fs.readFile(sessionFile, "utf-8"));
@@ -132,6 +152,10 @@ async function readCodexMirroredSessionHistoryMessages(sessionFile) {
 }
 //#endregion
 //#region extensions/codex/src/app-server/attempt-context.ts
+/**
+* Builds Codex app-server prompt context, workspace bootstrap injections,
+* system-prompt reports, and context-engine projection decisions.
+*/
 const CODEX_NATIVE_PROJECT_DOC_BASENAMES = new Set(["agents.md"]);
 const CODEX_INHERITED_WORKSPACE_DEVELOPER_CONTEXT_BASENAMES = new Set(["tools.md"]);
 const CODEX_TURN_SCOPED_WORKSPACE_DEVELOPER_CONTEXT_BASENAMES = new Set([
@@ -152,11 +176,13 @@ const CODEX_BOOTSTRAP_CONTEXT_ORDER = new Map([
 	["memory.md", 60],
 	["heartbeat.md", 70]
 ]);
+/** Reads mirrored Codex session history for harness hooks. */
 async function readMirroredSessionHistoryMessages(sessionFile) {
 	const messages = await readCodexMirroredSessionHistoryMessages(sessionFile);
 	if (!messages) embeddedAgentLog.warn("failed to read mirrored session history for codex harness hooks", { sessionFile });
 	return messages;
 }
+/** Reads a valid thread-bootstrap projection request from context-engine output. */
 function readContextEngineThreadBootstrapProjection(projection) {
 	if (projection?.mode !== "thread_bootstrap") return;
 	const epoch = projection.epoch?.trim();
@@ -171,6 +197,10 @@ function readContextEngineThreadBootstrapProjection(projection) {
 		...fingerprint ? { fingerprint } : {}
 	};
 }
+/**
+* Decides whether an existing Codex thread can reuse its context-engine
+* bootstrap projection or must be reprojected.
+*/
 function resolveContextEngineBootstrapProjectionDecision(params) {
 	const bindingProjection = params.startupBinding?.contextEngine?.projection;
 	if (!params.startupBinding?.threadId || !bindingProjection) return {
@@ -196,6 +226,10 @@ function resolveContextEngineBootstrapProjectionDecision(params) {
 		reason: "matching-thread-bootstrap-binding"
 	};
 }
+/**
+* Loads workspace bootstrap files and partitions them into Codex-native prompt,
+* developer-instruction, heartbeat, and memory-tool contexts.
+*/
 async function buildCodexWorkspaceBootstrapContext(params) {
 	try {
 		const memoryToolsAvailable = params.memoryToolNames.length > 0 && canRouteCodexWorkspaceMemoryThroughTools({
@@ -269,6 +303,10 @@ async function buildCodexWorkspaceBootstrapContext(params) {
 		};
 	}
 }
+/**
+* Builds the prompt-size, bootstrap-file, skill, and tool-schema accounting
+* report for a Codex run.
+*/
 function buildCodexSystemPromptReport(params) {
 	const toolEntries = params.tools.map(buildCodexToolReportEntry);
 	const schemaChars = toolEntries.reduce((sum, tool) => sum + tool.schemaChars, 0);
@@ -427,6 +465,9 @@ function readPositiveNumber(value) {
 function readNonEmptyString$1(value) {
 	return typeof value === "string" && value.trim().length > 0 ? value : void 0;
 }
+/**
+* Builds OpenClaw-provided workspace prompt context for the current Codex turn.
+*/
 function buildCodexOpenClawPromptContext(params) {
 	if (!shouldInjectCodexOpenClawPromptContext(params.params)) return;
 	const sections = [params.workspacePromptContext?.trim() ? [
@@ -445,6 +486,7 @@ function buildCodexOpenClawPromptContext(params) {
 function shouldInjectCodexOpenClawPromptContext(params) {
 	return !(params.bootstrapContextMode === "lightweight" && params.bootstrapContextRunKind === "cron");
 }
+/** Renders loaded OpenClaw skill prompts as Codex collaboration instructions. */
 function renderCodexSkillsCollaborationInstructions(params) {
 	if (!shouldInjectCodexOpenClawPromptContext(params.attempt)) return;
 	return params.skillsPrompt?.trim() ? [
@@ -453,6 +495,10 @@ function renderCodexSkillsCollaborationInstructions(params) {
 		params.skillsPrompt.trim()
 	].join("\n") : void 0;
 }
+/**
+* Prepends OpenClaw context while preserving leading delivery metadata as
+* routing guidance instead of user request text.
+*/
 function prependCodexOpenClawPromptContext(prompt, context, options = {}) {
 	const { deliveryHint, prompt: promptWithoutDeliveryHint } = splitLeadingCodexDeliveryHint(prompt);
 	if (!context?.trim() && (!deliveryHint || options.preservePromptWithoutContext)) return prompt;
@@ -567,6 +613,10 @@ function selectCodexWorkspaceMemoryReferenceFiles(params) {
 		}) && !file.missing && (file.content ?? "").trim().length > 0;
 	}).toSorted(compareCodexBootstrapFiles);
 }
+/**
+* Renders a memory-file reference that points Codex at memory tools instead of
+* embedding MEMORY.md contents.
+*/
 function renderCodexWorkspaceMemoryReference(params) {
 	if (params.files.length === 0) return;
 	const lines = [
@@ -578,6 +628,7 @@ function renderCodexWorkspaceMemoryReference(params) {
 	for (const file of params.files) lines.push(`- ${file.path}`);
 	return lines.join("\n").trim();
 }
+/** Lists available memory tool names understood by Codex workspace memory routing. */
 function getCodexWorkspaceMemoryToolNames(tools) {
 	const availableToolNames = new Set(tools.map((tool) => normalizeCodexDynamicToolName(tool.name)));
 	return Array.from(CODEX_MEMORY_TOOL_NAMES).filter((name) => availableToolNames.has(name));
@@ -616,6 +667,10 @@ function isCodexWorkspaceRootMemoryPath(params) {
 function isSameCodexWorkspacePath(left, right) {
 	return path.resolve(left) === path.resolve(right);
 }
+/**
+* Remaps bootstrap file paths from the resolved workspace to the effective Codex
+* workspace while preserving platform path separators.
+*/
 function remapCodexContextFilePath(params) {
 	const relativePath = path.relative(params.sourceWorkspaceDir, params.file.path);
 	if (!relativePath || relativePath === ".." || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath) || params.sourceWorkspaceDir === params.targetWorkspaceDir) return params.file;
@@ -657,9 +712,15 @@ function isNonEmptyString$2(value) {
 }
 //#endregion
 //#region extensions/codex/src/app-server/attempt-diagnostics.ts
+/**
+* Diagnostic helpers for Codex app-server model calls and plugin-thread config
+* eligibility.
+*/
+/** Reads a tool schema field in either app-server or OpenClaw naming. */
 function readCodexDiagnosticToolParameters(tool) {
 	return tool.inputSchema ?? tool.parameters;
 }
+/** Builds compact diagnostic tool definitions for trusted private telemetry. */
 function buildCodexDiagnosticToolDefinitions(tools) {
 	return tools.map((tool) => ({
 		name: tool.name,
@@ -667,6 +728,7 @@ function buildCodexDiagnosticToolDefinitions(tools) {
 		parameters: readCodexDiagnosticToolParameters(tool)
 	}));
 }
+/** Returns the serialized UTF-8 byte length for a JSON-compatible value. */
 function utf8JsonByteLength(value) {
 	try {
 		return Buffer.byteLength(JSON.stringify(value), "utf8");
@@ -674,6 +736,7 @@ function utf8JsonByteLength(value) {
 		return;
 	}
 }
+/** Builds a short namespaced fingerprint for sensitive log values. */
 function fingerprintCodexLogValue(namespace, value) {
 	const hash = createHash("sha256");
 	hash.update(namespace);
@@ -681,6 +744,10 @@ function fingerprintCodexLogValue(namespace, value) {
 	hash.update(value);
 	return `sha256:${hash.digest("hex").slice(0, 16)}`;
 }
+/**
+* Builds redacted diagnostics explaining whether plugin thread config was
+* eligible for a Codex app-server attempt.
+*/
 function buildCodexPluginThreadConfigEligibilityLogData(params) {
 	return {
 		sessionId: params.sessionId,
@@ -696,6 +763,10 @@ function buildCodexPluginThreadConfigEligibilityLogData(params) {
 		appServerCommandSource: params.appServer.start.commandSource
 	};
 }
+/**
+* Creates lifecycle emitters for trusted model-call diagnostics with optional
+* private payload capture.
+*/
 function createCodexModelCallDiagnosticEmitter(params) {
 	const now = params.now ?? (() => Date.now());
 	const toolDefinitions = params.capture.toolDefinitions ? buildCodexDiagnosticToolDefinitions(params.tools) : void 0;
@@ -756,6 +827,7 @@ function createCodexModelCallDiagnosticEmitter(params) {
 		}
 	};
 }
+/** Classifies model-call failures into timeout/abort buckets for diagnostics. */
 function classifyCodexModelCallFailureKind(params) {
 	if (params.timedOut || params.turnCompletionIdleTimedOut) return "timeout";
 	const errorMessage = params.error ? params.formatError(params.error).toLowerCase() : "";
@@ -765,10 +837,14 @@ function classifyCodexModelCallFailureKind(params) {
 }
 //#endregion
 //#region extensions/codex/src/app-server/attempt-notifications.ts
+/**
+* Predicates and readers for Codex app-server notification envelopes.
+*/
 const CODEX_TURN_ABORT_MARKER_START = "<turn_aborted>";
 const CODEX_TURN_ABORT_MARKER_END = "</turn_aborted>";
 const CODEX_INTERRUPTED_USER_GUIDANCE = "The user interrupted the previous turn on purpose. Any running unified exec processes may still be running in the background. If any tools/commands were aborted, they may have partially executed.";
 const CODEX_INTERRUPTED_DEVELOPER_GUIDANCE = "The previous turn was interrupted on purpose. Any running unified exec processes may still be running in the background. If any tools/commands were aborted, they may have partially executed.";
+/** Builds compact activity metadata for watchdog and diagnostic updates. */
 function describeNotificationActivity(notification) {
 	if (!isJsonObject(notification.params)) return { lastNotificationMethod: notification.method };
 	if (notification.method !== "rawResponseItem/completed") return { lastNotificationMethod: notification.method };
@@ -782,6 +858,7 @@ function describeNotificationActivity(notification) {
 		lastAssistantTextPreview: readRawAssistantTextPreview(item)
 	};
 }
+/** Tracks active app-server item ids from item start/completion notifications. */
 function updateActiveTurnItemIds(notification, activeItemIds) {
 	if (notification.method !== "item/started" && notification.method !== "item/completed") return;
 	const itemId = readNotificationItemId(notification);
@@ -798,36 +875,43 @@ function isCompletedAssistantNotification(notification) {
 	const item = isJsonObject(notification.params.item) ? notification.params.item : void 0;
 	return Boolean(item && readString$6(item, "type") === "agentMessage" && readString$6(item, "phase") !== "commentary");
 }
+/** Returns true for completed app-server reasoning items. */
 function isReasoningItemCompletionNotification(notification) {
 	if (!isJsonObject(notification.params) || notification.method !== "item/completed") return false;
 	const item = isJsonObject(notification.params.item) ? notification.params.item : void 0;
 	return item ? readString$6(item, "type") === "reasoning" : false;
 }
+/** Returns true for completed assistant commentary items. */
 function isAssistantCommentaryCompletionNotification(notification) {
 	if (!isJsonObject(notification.params) || notification.method !== "item/completed") return false;
 	const item = isJsonObject(notification.params.item) ? notification.params.item : void 0;
 	return Boolean(item && readString$6(item, "type") === "agentMessage" && readString$6(item, "phase") === "commentary");
 }
+/** Returns true for completed raw response reasoning items. */
 function isRawReasoningCompletionNotification(notification) {
 	if (!isJsonObject(notification.params) || notification.method !== "rawResponseItem/completed") return false;
 	const item = isJsonObject(notification.params.item) ? notification.params.item : void 0;
 	return item ? readString$6(item, "type") === "reasoning" : false;
 }
+/** Returns true when assistant completion can release the short idle watch. */
 function isAssistantCompletionReleaseNotification(notification, turnCrossedToolHandoff) {
 	if (isCompletedAssistantNotification(notification)) return true;
 	return !turnCrossedToolHandoff && isRawAssistantCompletionNotification(notification);
 }
+/** Returns true when a notification proves assistant output is still active. */
 function shouldDisarmAssistantCompletionIdleWatch(notification) {
 	if (!isJsonObject(notification.params)) return false;
 	if (notification.method === "item/started") return true;
 	if (notification.method === "item/agentMessage/delta") return true;
 	return false;
 }
+/** Reads an item id from supported notification envelope shapes. */
 function readNotificationItemId(notification) {
 	if (!isJsonObject(notification.params)) return;
 	const item = isJsonObject(notification.params.item) ? notification.params.item : void 0;
 	return (item ? readString$6(item, "id") : void 0) ?? readString$6(notification.params, "itemId") ?? readString$6(notification.params, "id");
 }
+/** Detects completion for an OpenClaw dynamic tool result still awaited by Codex. */
 function isPendingOpenClawDynamicToolCompletionNotification(notification, pendingOpenClawDynamicToolCompletionIds) {
 	if (notification.method !== "item/completed" || !isJsonObject(notification.params)) return false;
 	const itemId = readNotificationItemId(notification);
@@ -836,11 +920,13 @@ function isPendingOpenClawDynamicToolCompletionNotification(notification, pendin
 	const itemType = item ? readString$6(item, "type") : void 0;
 	return itemType === void 0 || itemType === "dynamicToolCall";
 }
+/** Returns true for raw response tool-output completion notifications. */
 function isRawToolOutputCompletionNotification(notification) {
 	if (notification.method !== "rawResponseItem/completed" || !isJsonObject(notification.params)) return false;
 	const item = isJsonObject(notification.params.item) ? notification.params.item : void 0;
 	return item ? readString$6(item, "type") === "custom_tool_call_output" : false;
 }
+/** Returns true for progress on Codex-native tool item types. */
 function isNativeToolProgressNotification(notification) {
 	if (notification.method !== "item/started" && notification.method !== "item/completed" && notification.method !== "item/updated") return false;
 	if (!isJsonObject(notification.params)) return false;
@@ -853,17 +939,21 @@ function isNativeToolProgressNotification(notification) {
 		default: return false;
 	}
 }
+/** Returns true for raw native response stream delta events. */
 function isNativeResponseStreamDeltaNotification(notification) {
 	return notification.method.startsWith("response.") && notification.method.endsWith(".delta");
 }
+/** Returns true for file-change patch update notifications. */
 function isFileChangePatchUpdatedNotification(notification) {
 	return notification.method === "item/fileChange/patchUpdated" && isJsonObject(notification.params);
 }
+/** Returns true for raw assistant message progress with readable text. */
 function isRawAssistantProgressNotification(notification) {
 	if (notification.method !== "rawResponseItem/completed" || !isJsonObject(notification.params)) return false;
 	const item = isJsonObject(notification.params.item) ? notification.params.item : void 0;
 	return Boolean(item && readString$6(item, "type") === "message" && readString$6(item, "role") === "assistant" && readRawAssistantTextPreview(item));
 }
+/** Returns true for raw assistant completion outside commentary phase. */
 function isRawAssistantCompletionNotification(notification) {
 	if (!isRawAssistantProgressNotification(notification) || !isJsonObject(notification.params)) return false;
 	const item = isJsonObject(notification.params.item) ? notification.params.item : void 0;
@@ -879,34 +969,45 @@ function readRawAssistantTextPreview(item) {
 	if (!text) return;
 	return text.length > 240 ? `${text.slice(0, 237)}...` : text;
 }
+/** Returns true when notification params correlate to a specific thread/turn. */
 function isTurnNotification(value, threadId, turnId) {
 	return isCodexNotificationForTurn(value, threadId, turnId);
 }
+/** Returns true when a correlated notification belongs to another active run. */
 function isCodexNotificationOutsideActiveRun(correlation) {
 	if (!Boolean(correlation.threadId || correlation.nestedTurnThreadId)) return false;
 	if (!correlation.matchesActiveThread) return true;
 	return Boolean(correlation.turnId || correlation.nestedTurnId) && correlation.matchesActiveTurn === false;
 }
+/** Checks request params that must contain the current thread and turn ids. */
 function isCurrentThreadTurnRequestParams(value, threadId, turnId) {
 	if (!isJsonObject(value)) return false;
 	return readString$6(value, "threadId") === threadId && readString$6(value, "turnId") === turnId;
 }
+/** Checks approval request params, accepting `conversationId` as thread id. */
 function isCurrentApprovalTurnRequestParams(value, threadId, turnId) {
 	if (!isJsonObject(value)) return false;
 	return (readString$6(value, "threadId") ?? readString$6(value, "conversationId")) === threadId && readString$6(value, "turnId") === turnId;
 }
+/** Checks request params where `turnId` may be omitted or null for the thread. */
 function isCurrentThreadOptionalTurnRequestParams(value, threadId, turnId) {
 	if (!isJsonObject(value) || readString$6(value, "threadId") !== threadId) return false;
 	const requestTurnId = value.turnId;
 	return requestTurnId === null || requestTurnId === void 0 || requestTurnId === turnId;
 }
+/** Returns true for app-server error notifications that will retry. */
 function isRetryableErrorNotification(value) {
 	if (!isJsonObject(value)) return false;
 	return readBoolean$1(value, "willRetry") === true || readBoolean$1(value, "will_retry") === true;
 }
+/** Returns true for terminal app-server thread status strings. */
 function isTerminalTurnStatus(status) {
 	return status === "completed" || status === "interrupted" || status === "failed";
 }
+/**
+* Detects Codex's synthetic interrupted-turn marker while ignoring the current
+* user prompt echoed through raw response events.
+*/
 function isCodexTurnAbortMarkerNotification(notification, options = {}) {
 	if (notification.method !== "rawResponseItem/completed" || !isJsonObject(notification.params)) return false;
 	const item = notification.params.item;
@@ -940,11 +1041,13 @@ function readString$6(record, key) {
 function readBoolean$1(record, key) {
 	return asBoolean(record[key]);
 }
+/** Reads a typed Codex item from notification params when id/type are present. */
 function readCodexNotificationItem(params) {
 	if (!isJsonObject(params) || !isJsonObject(params.item)) return;
 	const item = params.item;
 	return typeof item.id === "string" && typeof item.type === "string" ? item : void 0;
 }
+/** Maps Codex item types to the tool name shown in execution progress. */
 function codexExecutionToolName(item) {
 	if (item.type === "dynamicToolCall" && typeof item.tool === "string") return item.tool;
 	if (item.type === "mcpToolCall" && typeof item.tool === "string") {
@@ -960,6 +1063,10 @@ function isNonEmptyString$1(value) {
 }
 //#endregion
 //#region extensions/codex/src/app-server/attempt-notification-state.ts
+/**
+* State machine for Codex app-server turn notifications and idle-watch updates.
+*/
+/** Emits coarse execution phases exactly once from app-server notifications. */
 function reportCodexExecutionNotification(params) {
 	const { notification } = params;
 	if (notification.method === "turn/started") {
@@ -980,10 +1087,15 @@ function reportCodexExecutionNotification(params) {
 		itemId: item.id
 	});
 }
+/** Returns true when a notification ends the current app-server turn. */
 function isTerminalCodexTurnNotificationForTurn(params) {
 	if (!isTurnNotification(params.notification.params, params.threadId, params.turnId)) return false;
 	return params.notification.method === "turn/completed" || isCodexTurnAbortMarkerNotification(params.notification, { currentPromptTexts: params.currentPromptTexts });
 }
+/**
+* Applies one notification to active item tracking, idle watches, and terminal
+* turn state.
+*/
 function applyCodexTurnNotificationState(params) {
 	const { notification, turnWatches } = params;
 	const isCurrentTurnNotification = isTurnNotification(notification.params, params.threadId, params.turnId);
@@ -1058,12 +1170,18 @@ function applyCodexTurnNotificationState(params) {
 //#region extensions/codex/src/app-server/attempt-results.ts
 const CODEX_APP_SERVER_MISSING_TERMINAL_EVENT_USER_MESSAGE = "Codex stopped before confirming the turn was complete. The response may be incomplete; retry if needed.";
 const CODEX_APP_SERVER_MISSING_TERMINAL_EVENT_SIDE_EFFECT_USER_MESSAGE = "Codex stopped before confirming the turn was complete. Some work may already have been performed; verify the current state before retrying.";
+/** Joins terminal assistant text blocks into the final attempt answer. */
 function collectTerminalAssistantText(result) {
 	return result.assistantTexts.join("\n\n").trim();
 }
+/** Returns whether attempt metadata saw potential side effects. */
 function hasCodexAppServerPotentialSideEffectEvidence(result) {
 	return result.replayMetadata.hadPotentialSideEffects;
 }
+/**
+* Builds the user-facing timeout outcome when Codex stops without a terminal
+* turn event.
+*/
 function buildCodexAppServerPromptTimeoutOutcome(params) {
 	const completionIdleTimeoutHadPotentialSideEffects = hasCodexAppServerPotentialSideEffectEvidence(params.result);
 	const replayBlockedReason = resolveCodexAppServerReplayBlockedReason(params.result);
@@ -1076,12 +1194,14 @@ function buildCodexAppServerPromptTimeoutOutcome(params) {
 		} : {}
 	};
 }
+/** Explains why an incomplete app-server turn cannot be safely replayed. */
 function resolveCodexAppServerReplayBlockedReason(result) {
 	if (result.replayMetadata.hadPotentialSideEffects) return "potential_side_effect";
 	if (result.assistantTexts.some((text) => text.trim().length > 0)) return "assistant_output";
 	if (result.toolMetas.length > 0 || result.clientToolCalls || result.lastToolError || result.didSendDeterministicApprovalPrompt) return "tool_activity";
 	if (result.itemLifecycle.startedCount > 0 || result.itemLifecycle.activeCount > 0) return "active_item";
 }
+/** Builds an attempt result for failures before the app-server turn starts. */
 function buildCodexTurnStartFailureResult(params) {
 	return {
 		aborted: false,
@@ -1115,6 +1235,7 @@ function buildCodexTurnStartFailureResult(params) {
 		systemPromptReport: params.systemPromptReport
 	};
 }
+/** Detects app-server errors caused by invalid image payload data. */
 function isInvalidCodexImagePayloadError(message) {
 	if (typeof message !== "string" || !message.trim()) return false;
 	const normalizedMessage = message.replace(/[_-]+/gu, " ");
@@ -1122,6 +1243,11 @@ function isInvalidCodexImagePayloadError(message) {
 }
 //#endregion
 //#region extensions/codex/src/app-server/dynamic-tool-build.ts
+/**
+* Builds the Codex app-server dynamic tool list for one turn, including
+* OpenClaw-owned tools, Codex native-tool fallback rules, sandbox shell shims,
+* and provider allowlist normalization.
+*/
 const CODEX_NATIVE_SANDBOX_TOOL_REQUIREMENTS = [
 	"exec",
 	"process",
@@ -1131,12 +1257,14 @@ const CODEX_NATIVE_SANDBOX_TOOL_REQUIREMENTS = [
 	"apply_patch"
 ];
 const CODEX_MEMORY_FLUSH_DYNAMIC_TOOL_ALLOW = new Set(["read", "write"]);
+/** Splits sandbox and run session keys so tool calls can bind to both scopes when needed. */
 function resolveOpenClawCodingToolsSessionKeys(params, sandboxSessionKey) {
 	return {
 		sessionKey: sandboxSessionKey,
 		runSessionKey: params.sessionKey && params.sessionKey !== sandboxSessionKey ? params.sessionKey : void 0
 	};
 }
+/** Resolves the channel id that hook events should target for this Codex app-server turn. */
 function resolveCodexAppServerHookChannelId(params, sandboxSessionKey) {
 	return buildAgentHookContextChannelFields({
 		sessionKey: sandboxSessionKey,
@@ -1148,6 +1276,7 @@ function resolveCodexAppServerHookChannelId(params, sandboxSessionKey) {
 }
 const CODEX_DYNAMIC_TOOL_BUILD_WARN_TOTAL_MS = 1e3;
 const CODEX_DYNAMIC_TOOL_BUILD_WARN_STAGE_MS = 500;
+/** Creates cheap optional timing instrumentation for the dynamic-tool hot path. */
 function createCodexDynamicToolBuildStageTracker(options = {}) {
 	if (!options.enabled) return {
 		mark() {},
@@ -1180,12 +1309,15 @@ function createCodexDynamicToolBuildStageTracker(options = {}) {
 		}
 	};
 }
+/** Returns true when dynamic-tool construction is slow enough to warrant a warning log. */
 function shouldWarnCodexDynamicToolBuildStageSummary(summary) {
 	return summary.totalMs >= CODEX_DYNAMIC_TOOL_BUILD_WARN_TOTAL_MS || summary.stages.some((stage) => stage.durationMs >= CODEX_DYNAMIC_TOOL_BUILD_WARN_STAGE_MS);
 }
+/** Formats per-stage timings into the compact form used by Codex app-server logs. */
 function formatCodexDynamicToolBuildStageSummary(summary) {
 	return summary.stages.length > 0 ? summary.stages.map((stage) => `${stage.name}:${stage.durationMs}ms@${stage.elapsedMs}ms`).join(",") : "none";
 }
+/** Builds, filters, and normalizes Codex-compatible runtime tools for a single turn. */
 async function buildDynamicTools(input) {
 	const { params } = input;
 	if (params.disableTools || !supportsModelTools(params.model)) return [];
@@ -1323,6 +1455,7 @@ async function buildDynamicTools(input) {
 	}
 	return normalizedTools;
 }
+/** Preserves delivery-critical tools when a narrow allowlist would otherwise hide them. */
 function includeForcedCodexDynamicToolAllow(toolsAllow, params) {
 	if (toolsAllow === void 0 || hasWildcardCodexToolsAllow(toolsAllow)) return toolsAllow;
 	const forcedToolNames = shouldForceMessageTool(params) ? ["message"] : [];
@@ -1332,6 +1465,7 @@ function includeForcedCodexDynamicToolAllow(toolsAllow, params) {
 	const missingToolNames = forcedToolNames.filter((toolName) => !normalized.has(normalizeCodexDynamicToolName$1(toolName)));
 	return missingToolNames.length === 0 ? toolsAllow : [...toolsAllow, ...missingToolNames];
 }
+/** Decides whether Codex native code mode can own shell/file tools for this turn. */
 function shouldEnableCodexAppServerNativeToolSurface(params, sandbox, options = {}) {
 	if (isCodexMemoryFlushRun(params)) return false;
 	if (isCodexNativeExecutionBlockedByNodeExecHost(params, {
@@ -1343,6 +1477,7 @@ function shouldEnableCodexAppServerNativeToolSurface(params, sandbox, options =
 	if (toolsAllow === void 0) return canCodexAppServerNativeToolSurfaceHonorSandbox(sandbox, options);
 	return hasWildcardCodexToolsAllow(toolsAllow) && canCodexAppServerNativeToolSurfaceHonorSandbox(sandbox, options);
 }
+/** Returns true when OpenClaw policy requires the Node-owned exec/process tools instead. */
 function isCodexNativeExecutionBlockedByNodeExecHost(params, options = {}) {
 	return !resolveCodexNativeExecutionPolicy({
 		config: params.config,
@@ -1371,15 +1506,19 @@ function isCodexMemoryFlushRun(params) {
 function filterCodexMemoryFlushDynamicTools(tools) {
 	return tools.filter((tool) => CODEX_MEMORY_FLUSH_DYNAMIC_TOOL_ALLOW.has(normalizeCodexDynamicToolName$1(tool.name)));
 }
+/** Requires a Codex sandbox environment only when native tools must run inside OpenClaw sandboxing. */
 function shouldRequireCodexSandboxExecServerEnvironment(params) {
 	return Boolean(params.sandbox?.enabled && params.nativeToolSurfaceEnabled && params.sandboxExecServerEnabled);
 }
+/** Selects the sandbox exec-server environment passed through the Codex app-server protocol. */
 function resolveCodexSandboxEnvironmentSelection(environment, nativeToolSurfaceEnabled) {
 	return environment && nativeToolSurfaceEnabled ? [environment] : void 0;
 }
+/** Chooses the cwd visible to Codex native execution after sandbox exec-server setup. */
 function resolveCodexAppServerExecutionCwd(params) {
 	return params.environment && params.nativeToolSurfaceEnabled ? params.environment.cwd : params.effectiveCwd;
 }
+/** Converts OpenClaw sandbox networking into Codex's external-sandbox policy shape. */
 function resolveCodexExternalSandboxPolicyForOpenClawSandbox(sandbox) {
 	return {
 		type: "externalSandbox",
@@ -1391,6 +1530,7 @@ function codexNetworkAccessForOpenClawSandbox(sandbox) {
 	const network = sandbox?.docker?.network?.trim().toLowerCase();
 	return Boolean(network && network !== "none");
 }
+/** Returns a Codex config copy with app-server Codex plugin loading disabled for thread tools. */
 function disableCodexPluginThreadConfig(pluginConfig) {
 	const config = readCodexPluginConfig(pluginConfig);
 	return {
@@ -1401,6 +1541,7 @@ function disableCodexPluginThreadConfig(pluginConfig) {
 		}
 	};
 }
+/** Adds sandbox_exec/process aliases when native Code Mode cannot directly honor the sandbox. */
 function addSandboxShellDynamicToolsIfAvailable(filteredTools, allTools, input) {
 	if (!shouldExposeSandboxExecDynamicTool(input) || isSandboxShellDynamicToolExcluded(input.pluginConfig)) return filteredTools;
 	const execTool = allTools.find((tool) => normalizeCodexDynamicToolName$1(tool.name) === "exec");
@@ -1471,6 +1612,7 @@ function addNodeShellDynamicToolsIfNeeded(filteredTools, allTools, input) {
 	}
 	return next;
 }
+/** Applies a normalized tool allowlist while preserving sandbox shell aliases for exec/process. */
 function filterCodexDynamicToolsForAllowlist(tools, toolsAllow) {
 	if (!toolsAllow) return tools;
 	if (toolsAllow.length === 0) return [];
@@ -1481,46 +1623,57 @@ function filterCodexDynamicToolsForAllowlist(tools, toolsAllow) {
 		return allowSet.has(normalized) || normalized === "sandbox_exec" && allowSet.has("exec") || normalized === "sandbox_process" && (allowSet.has("exec") || allowSet.has("process"));
 	});
 }
+/** Detects the wildcard allowlist marker after Codex tool-name normalization. */
 function hasWildcardCodexToolsAllow(toolsAllow) {
 	return toolsAllow.some((name) => normalizeCodexDynamicToolName$1(name) === "*");
 }
+/** Forces message delivery through the message tool when the source channel requires it. */
 function shouldForceMessageTool(params) {
 	return params.disableMessageTool !== true && params.sourceReplyDeliveryMode === "message_tool_only";
 }
 //#endregion
 //#region extensions/codex/src/app-server/sandbox-exec-server/json-rpc.ts
+/** JSON-RPC error code used when a sandbox exec-server method is unknown. */
 const JSON_RPC_NOT_FOUND = -32004;
+/** Protocol-level error carrying the JSON-RPC error code to send to the client. */
 var JsonRpcProtocolError = class extends Error {
 	constructor(code, message) {
 		super(message);
 		this.code = code;
 	}
 };
+/** Parses raw WebSocket data into a JSON-RPC request object. */
 function parseRequest(data) {
 	const text = (Array.isArray(data) ? Buffer.concat(data) : Buffer.isBuffer(data) ? data : Buffer.from(data)).toString("utf8");
 	return requireObject(JSON.parse(text), "JSON-RPC request");
 }
+/** Validates that a JSON value is a non-array object. */
 function requireObject(value, label) {
 	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object.`);
 	return value;
 }
+/** Validates a non-empty string JSON-RPC parameter. */
 function requireString(value, label) {
 	if (typeof value !== "string" || !value) throw new Error(`${label} must be a non-empty string.`);
 	return value;
 }
+/** Validates a base64 payload parameter as a string; decoding happens at call sites. */
 function requireBase64String(value, label) {
 	if (typeof value !== "string") throw new Error(`${label} must be a string.`);
 	return value;
 }
+/** Validates a finite numeric JSON-RPC parameter. */
 function requireNumber(value, label) {
 	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${label} must be a finite number.`);
 	return value;
 }
+/** Validates a non-empty string-array JSON-RPC parameter. */
 function requireStringArray(value, label) {
 	if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) throw new Error(`${label} must be a string array.`);
 	if (value.length === 0) throw new Error(`${label} must not be empty.`);
 	return value;
 }
+/** Reads HTTP headers from JSON-RPC params, defaulting to an empty header list. */
 function readHttpHeaders(value) {
 	if (!Array.isArray(value)) return [];
 	return value.map((entry, index) => {
@@ -1531,6 +1684,7 @@ function readHttpHeaders(value) {
 		};
 	});
 }
+/** Sends a JSON-RPC success response over the WebSocket. */
 function sendResult(socket, id, result) {
 	socket.send(JSON.stringify({
 		jsonrpc: "2.0",
@@ -1538,6 +1692,7 @@ function sendResult(socket, id, result) {
 		result: result === void 0 ? {} : result
 	}));
 }
+/** Sends a JSON-RPC error response over the WebSocket. */
 function sendError(socket, id, code, message) {
 	socket.send(JSON.stringify({
 		jsonrpc: "2.0",
@@ -1550,9 +1705,15 @@ function sendError(socket, id, code, message) {
 }
 //#endregion
 //#region extensions/codex/src/app-server/sandbox-exec-server/fs-policy.ts
+/**
+* Resolves Codex filesystem sandbox policy payloads into OpenClaw path/glob
+* checks for sandbox exec-server filesystem operations.
+*/
+/** Resolves request-local sandbox policy and asserts each requested path has the needed access. */
 function assertFsSandboxAccess(execServer, record, requests) {
 	assertResolvedFsSandboxAccess(resolveFsSandboxPolicy(execServer, record), requests);
 }
+/** Parses a Codex managed filesystem sandbox context into normalized access entries. */
 function resolveFsSandboxPolicy(execServer, record) {
 	if (record.sandbox === void 0 || record.sandbox === null) return;
 	const sandbox = requireObject(record.sandbox, "fs sandbox context");
@@ -1633,6 +1794,7 @@ function resolveFsSpecialPath(value, cwd) {
 	if (kind === "slash_tmp" || kind === "tmpdir") return "/tmp";
 	throw new Error(`Unsupported Codex fs sandbox special path: ${kind}`);
 }
+/** Asserts access against an already resolved filesystem sandbox policy. */
 function assertResolvedFsSandboxAccess(policy, requests) {
 	if (!policy?.unrestricted && policy) for (const request of requests) {
 		const access = resolveFsAccess(policy, request.path);
@@ -1655,6 +1817,7 @@ function resolveFsAccess(policy, rawPath) {
 	}
 	return selected?.access ?? "none";
 }
+/** Rejects recursive writes/removes that would cross protected read-only descendants. */
 function assertNoReadOnlyDescendant(policy, rawPath, operation) {
 	if (!policy || policy.unrestricted) return;
 	const target = normalizeSandboxAbsolutePath(rawPath, "fs path");
@@ -1669,11 +1832,13 @@ function assertNoReadOnlyDescendant(policy, rawPath, operation) {
 		throw new Error(`Codex fs sandbox denied recursive ${operation} of ${rawPath} because ${protectedPath} is not writable.`);
 	}
 }
+/** Normalizes and validates an absolute POSIX path inside the sandbox namespace. */
 function normalizeSandboxAbsolutePath(rawPath, label) {
 	if (!rawPath || rawPath.includes("\0") || !rawPath.startsWith("/")) throw new Error(`${label} must be an absolute sandbox path.`);
 	const normalized = posix.normalize(rawPath);
 	return normalized === "//" ? "/" : normalized;
 }
+/** Returns true when target is root itself or a descendant of root. */
 function pathContains(root, target) {
 	return root === "/" || target === root || target.startsWith(`${root}/`);
 }
@@ -1751,17 +1916,20 @@ function sandboxGlobLiteralPrefix(pattern) {
 	if (slash <= 0) return "/";
 	return normalizeSandboxAbsolutePath(prefix.slice(0, slash), "fs sandbox glob prefix");
 }
+/** Safely joins a single directory entry name onto a sandbox parent path. */
 function joinSandboxChildPath(parent, child) {
 	if (!child || child === "." || child === ".." || child.includes("/") || child.includes("\0")) throw new Error(`Invalid sandbox directory entry name: ${child}`);
 	return parent.endsWith("/") ? `${parent}${child}` : `${parent}/${child}`;
 }
 //#endregion
 //#region extensions/codex/src/app-server/sandbox-exec-server/runtime.ts
+/** Returns the configured sandbox backend or fails the current JSON-RPC request. */
 function requireBackend(execServer) {
 	const backend = execServer.sandbox.backend;
 	if (!backend) throw new Error("OpenClaw sandbox backend is unavailable.");
 	return backend;
 }
+/** Returns the configured filesystem bridge or fails the current JSON-RPC request. */
 function requireFsBridge(execServer) {
 	const fsBridge = execServer.sandbox.fsBridge;
 	if (!fsBridge) throw new Error("Sandbox filesystem bridge is unavailable.");
@@ -1769,7 +1937,12 @@ function requireFsBridge(execServer) {
 }
 //#endregion
 //#region extensions/codex/src/app-server/sandbox-exec-server/filesystem.ts
+/**
+* Implements filesystem JSON-RPC handlers for the Codex sandbox exec-server
+* with OpenClaw sandbox policy checks before every bridge operation.
+*/
 const CODEX_SANDBOX_EXEC_SERVER_MAX_READ_FILE_BYTES = 512 * 1024 * 1024;
+/** Reads a sandbox file as base64 after read-policy and size checks. */
 async function readFile(execServer, params) {
 	const record = requireObject(params, "fs/readFile params");
 	const filePath = requireString(record.path, "path");
@@ -1783,6 +1956,7 @@ async function readFile(execServer, params) {
 	if (stat.type === "file" && stat.size > CODEX_SANDBOX_EXEC_SERVER_MAX_READ_FILE_BYTES) throw new Error(`file is too large to read through Codex sandbox exec-server: ${stat.size} bytes`);
 	return { dataBase64: (await fsBridge.readFile({ filePath })).toString("base64") };
 }
+/** Writes base64 data to an existing sandbox directory after write-policy checks. */
 async function writeFile(execServer, params) {
 	const record = requireObject(params, "fs/writeFile params");
 	const filePath = requireString(record.path, "path");
@@ -1798,6 +1972,7 @@ async function writeFile(execServer, params) {
 		mkdir: false
 	});
 }
+/** Creates a sandbox directory, respecting recursive and parent-directory semantics. */
 async function createDirectory(execServer, params) {
 	const record = requireObject(params, "fs/createDirectory params");
 	const filePath = requireString(record.path, "path");
@@ -1812,6 +1987,7 @@ async function createDirectory(execServer, params) {
 	}
 	await fsBridge.mkdirp({ filePath });
 }
+/** Returns normalized metadata for a sandbox path. */
 async function getMetadata(execServer, params) {
 	const record = requireObject(params, "fs/getMetadata params");
 	const filePath = requireString(record.path, "path");
@@ -1823,6 +1999,7 @@ async function getMetadata(execServer, params) {
 	if (!stat) throw new JsonRpcProtocolError(JSON_RPC_NOT_FOUND, "file not found");
 	return metadataResponse(stat);
 }
+/** Lists sandbox directory entries visible under the resolved filesystem policy. */
 async function readDirectory(execServer, params) {
 	const record = requireObject(params, "fs/readDirectory params");
 	return { entries: await listDirectoryEntries(execServer, requireString(record.path, "path"), resolveFsSandboxPolicy(execServer, record)) };
@@ -1854,6 +2031,7 @@ async function listDirectoryEntries(execServer, filePath, fsSandboxPolicy) {
 		};
 	});
 }
+/** Removes a sandbox path after rejecting writes outside policy or under read-only descendants. */
 async function removePath(execServer, params) {
 	const record = requireObject(params, "fs/remove params");
 	const filePath = requireString(record.path, "path");
@@ -1869,6 +2047,7 @@ async function removePath(execServer, params) {
 		force: record.force !== false
 	});
 }
+/** Copies sandbox files or recursive directories while enforcing source and destination policy. */
 async function copyPath(execServer, params) {
 	const record = requireObject(params, "fs/copy params");
 	const sourcePath = requireString(record.sourcePath ?? record.source, "sourcePath");
@@ -1933,7 +2112,13 @@ function metadataResponse(stat) {
 }
 //#endregion
 //#region extensions/codex/src/app-server/sandbox-exec-server/http.ts
+/**
+* Implements sandboxed HTTP requests for Codex native tools by routing network
+* access through the active OpenClaw sandbox backend.
+*/
+/** Maximum JSON-line size accepted from the streaming HTTP helper process. */
 const SANDBOX_HTTP_STREAM_LINE_MAX_CHARS = 256 * 1024;
+/** Handles one sandbox HTTP JSON-RPC request, optionally streaming response body deltas. */
 async function httpRequest(execServer, socket, params) {
 	const record = requireObject(params, "http/request params");
 	const requestId = requireString(record.requestId, "requestId");
@@ -2182,9 +2367,14 @@ function sendHttpBodyDelta(socket, params) {
 }
 //#endregion
 //#region extensions/codex/src/app-server/sandbox-exec-server/processes.ts
+/**
+* Manages subprocess lifecycle, streaming output buffers, stdin writes, and
+* termination for Codex sandbox exec-server process RPCs.
+*/
 const ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const RETAINED_PROCESS_OUTPUT_BYTES = 1024 * 1024;
 const CLOSED_PROCESS_EVICTION_MS = 6e4;
+/** Starts a sandbox-backed process and registers it in the connection-local process table. */
 async function startProcess(execServer, processes, socket, params) {
 	const record = requireObject(params, "process/start params");
 	const processId = requireString(record.processId, "processId");
@@ -2365,6 +2555,7 @@ function limitProcessChunks(chunks, maxBytes) {
 	}
 	return retained;
 }
+/** Reads buffered process output, optionally waiting for new output or process close. */
 async function readProcess(processes, params) {
 	const record = requireObject(params, "process/read params");
 	const managed = requireProcess(processes, requireString(record.processId, "processId"));
@@ -2382,6 +2573,7 @@ async function readProcess(processes, params) {
 		failure: managed.failure
 	};
 }
+/** Writes base64 stdin data to a running process when stdin is still open. */
 function writeProcess(processes, params) {
 	const record = requireObject(params, "process/write params");
 	const processId = requireString(record.processId, "processId");
@@ -2392,6 +2584,7 @@ function writeProcess(processes, params) {
 	managed.child.stdin.write(chunk);
 	return { status: "accepted" };
 }
+/** Requests process termination and reports whether it was running at call time. */
 function terminateProcess(processes, params) {
 	const processId = requireString(requireObject(params, "process/terminate params").processId, "processId");
 	const managed = processes.get(processId);
@@ -2471,7 +2664,12 @@ function readStringList(value) {
 }
 //#endregion
 //#region extensions/codex/src/app-server/sandbox-exec-server.ts
+/**
+* Hosts the local OpenClaw sandbox exec-server that Codex app-server native
+* execution can register as an external environment.
+*/
 const SANDBOX_EXEC_SERVERS = /* @__PURE__ */ new Map();
+/** Starts or reuses a sandbox exec-server and registers it with Codex app-server. */
 async function ensureCodexSandboxExecServerEnvironment(params) {
 	if (!params.sandbox?.enabled || !params.sandbox.backend) return;
 	if (!canExposeLocalExecServerToAppServer(params.appServerStartOptions)) throw new Error("OpenClaw Codex exec-server uses a local loopback URL and cannot be registered with a remote Codex app-server.");
@@ -2498,6 +2696,7 @@ async function ensureCodexSandboxExecServerEnvironment(params) {
 		cwd: params.sandbox.containerWorkdir
 	};
 }
+/** Releases the sandbox exec-server lease associated with a sandbox runtime. */
 async function releaseCodexSandboxExecServerEnvironment(sandbox) {
 	if (!sandbox?.enabled) return;
 	const server = await SANDBOX_EXEC_SERVERS.get(sandbox.runtimeId)?.catch(() => void 0);
@@ -2659,19 +2858,38 @@ async function dispatchRequest(execServer, processes, socket, request) {
 }
 //#endregion
 //#region extensions/codex/src/app-server/attempt-startup.ts
+/**
+* Startup orchestration for Codex app-server attempts, including shared-client
+* leasing, plugin thread config, sandbox execution environment, and thread
+* lifecycle binding.
+*/
 const CODEX_APP_SERVER_STARTUP_CONNECTION_CLOSE_MAX_ATTEMPTS = 3;
+/**
+* Starts or resumes the Codex app-server thread and returns the resources the
+* run loop must later release.
+*/
 async function startCodexAttemptThread(params) {
 	let pluginAppServer = params.appServer;
 	let releaseSharedClientLease;
 	let startupClientForAbandonedRequestCleanup;
 	let releaseStartupResourcesOnTimeout;
+	let startupAbandoned = false;
+	const startupAbandonController = new AbortController();
+	const abandonStartupAcquire = () => startupAbandonController.abort();
+	params.signal.addEventListener("abort", abandonStartupAcquire, { once: true });
 	try {
 		const startupResult = await withCodexStartupTimeout({
 			timeoutMs: params.startupTimeoutMs,
 			signal: params.signal,
 			onTimeout: async () => {
+				startupAbandoned = true;
+				startupAbandonController.abort();
 				await params.onStartupTimeout();
 				await releaseStartupResourcesOnTimeout?.();
+				releaseSharedClientLease?.();
+				releaseSharedClientLease = void 0;
+				await closeAbandonedStartupClient(startupClientForAbandonedRequestCleanup);
+				startupClientForAbandonedRequestCleanup = void 0;
 			},
 			operation: async () => {
 				const threadConfig = mergeCodexThreadConfigs(params.bundleMcpThreadConfig?.configPatch);
@@ -2710,20 +2928,34 @@ async function startCodexAttemptThread(params) {
 				let attemptedClient;
 				const startupAttempt = async () => {
 					let startupClientLease;
+					let startupClient;
+					let startupAttemptError;
 					let startupAttemptSucceeded = false;
 					try {
-						const startupClient = await params.attemptClientFactory(params.appServer.start, params.startupAuthProfileId, params.agentDir, params.config);
+						startupClient = await params.attemptClientFactory(params.appServer.start, params.startupAuthProfileId, params.agentDir, params.config, {
+							onStartedClient: (client) => {
+								startupClientForAbandonedRequestCleanup = client;
+								if (startupAbandoned || startupAbandonController.signal.aborted) closeAbandonedStartupClient(client);
+							},
+							abandonSignal: startupAbandonController.signal
+						});
+						const activeStartupClient = startupClient;
+						let startupClientLeaseReleased = false;
 						startupClientLease = () => {
-							releaseLeasedSharedCodexAppServerClient(startupClient);
+							if (startupClientLeaseReleased) return;
+							startupClientLeaseReleased = true;
+							releaseLeasedSharedCodexAppServerClient(activeStartupClient);
 						};
 						releaseSharedClientLease = startupClientLease;
-						attemptedClient = startupClient;
-						startupClientForAbandonedRequestCleanup = startupClient;
+						attemptedClient = activeStartupClient;
+						startupClientForAbandonedRequestCleanup = activeStartupClient;
+						if (startupAbandoned) throw new Error("codex app-server startup timed out");
+						if (startupAbandonController.signal.aborted) throw new Error("codex app-server startup aborted");
 						await ensureCodexComputerUse({
-							client: startupClient,
+							client: activeStartupClient,
 							pluginConfig: params.pluginConfig,
 							timeoutMs: params.appServer.requestTimeoutMs,
-							signal: params.signal
+							signal: startupAbandonController.signal
 						});
 						let startupSandboxEnvironment;
 						let startupSandboxEnvironmentAcquired = false;
@@ -2740,14 +2972,14 @@ async function startCodexAttemptThread(params) {
 								nativeToolSurfaceEnabled: params.nativeToolSurfaceEnabled,
 								sandboxExecServerEnabled: params.sandboxExecServerEnabled
 							}) ? await ensureCodexSandboxExecServerEnvironment({
-								client: startupClient,
+								client: activeStartupClient,
 								sandbox: params.sandbox ?? null,
 								appServerStartOptions: params.appServer.start,
 								timeoutMs: params.appServer.requestTimeoutMs,
-								signal: params.signal
+								signal: startupAbandonController.signal
 							}) : void 0;
 							startupSandboxEnvironmentAcquired = Boolean(startupSandboxEnvironment);
-							if (params.signal.aborted) {
+							if (startupAbandonController.signal.aborted) {
 								await releaseStartupSandboxEnvironment();
 								throw new Error("codex app-server startup aborted");
 							}
@@ -2763,8 +2995,8 @@ async function startCodexAttemptThread(params) {
 							nativeToolSurfaceEnabled: params.nativeToolSurfaceEnabled
 						});
 						const startupSandboxPolicy = startupSandboxEnvironment ? resolveCodexExternalSandboxPolicyForOpenClawSandbox(params.sandbox) : void 0;
-						const buildThreadLifecycleParams = () => ({
-							client: startupClient,
+						const buildThreadLifecycleParams = (signal) => ({
+							client: activeStartupClient,
 							params: params.buildAttemptParams(),
 							agentId: params.sessionAgentId,
 							cwd: startupExecutionCwd,
@@ -2782,16 +3014,16 @@ async function startCodexAttemptThread(params) {
 							mcpServersFingerprintEvaluated: params.bundleMcpThreadConfig.evaluated,
 							environmentSelection: startupEnvironmentSelection,
 							contextEngineProjection: params.contextEngineProjection,
-							signal: params.signal,
+							signal,
 							pluginThreadConfig: pluginThreadConfigRequired ? {
 								enabled: true,
 								inputFingerprint: pluginThreadConfigInputFingerprint,
 								enabledPluginConfigKeys,
 								build: () => buildCodexPluginThreadConfig({
 									pluginConfig: pluginThreadConfigPluginConfig,
-									request: (method, requestParams) => startupClient.request(method, requestParams, {
+									request: (method, requestParams) => activeStartupClient.request(method, requestParams, {
 										timeoutMs: params.appServer.requestTimeoutMs,
-										signal: params.signal
+										signal
 									}),
 									appCache: defaultCodexAppInventoryCache,
 									appCacheKey: pluginAppCacheKey
@@ -2799,21 +3031,21 @@ async function startCodexAttemptThread(params) {
 							} : void 0
 						});
 						try {
-							const startupThread = await startOrResumeThread(buildThreadLifecycleParams());
-							if (params.signal.aborted) {
+							const startupThread = await startOrResumeThread(buildThreadLifecycleParams(startupAbandonController.signal));
+							if (startupAbandonController.signal.aborted) {
 								await releaseStartupSandboxEnvironment();
 								throw new Error("codex app-server startup aborted");
 							}
 							startupSandboxEnvironmentAcquired = false;
 							startupAttemptSucceeded = true;
 							return {
-								client: startupClient,
+								client: activeStartupClient,
 								thread: startupThread,
 								sandboxEnvironment: startupSandboxEnvironment,
 								environmentSelection: startupEnvironmentSelection,
 								executionCwd: startupExecutionCwd,
 								sandboxPolicy: startupSandboxPolicy,
-								restartContextEngineCodexThread: () => startOrResumeThread(buildThreadLifecycleParams())
+								restartContextEngineCodexThread: () => startOrResumeThread(buildThreadLifecycleParams(params.signal))
 							};
 						} catch (error) {
 							await releaseStartupSandboxEnvironment();
@@ -2821,10 +3053,23 @@ async function startCodexAttemptThread(params) {
 						} finally {
 							if (releaseStartupResourcesOnTimeout === releaseStartupSandboxEnvironment) releaseStartupResourcesOnTimeout = void 0;
 						}
+					} catch (error) {
+						startupAttemptError = error;
+						throw error;
 					} finally {
 						if (!startupAttemptSucceeded) {
 							if (releaseSharedClientLease === startupClientLease) releaseSharedClientLease = void 0;
 							startupClientLease?.();
+							if (startupAbandoned || params.signal.aborted) {
+								if (startupClientForAbandonedRequestCleanup === startupClient) startupClientForAbandonedRequestCleanup = void 0;
+								await closeAbandonedStartupClient(startupClient);
+							} else if (shouldClearSharedClientAfterStartupRace(startupAttemptError) || shouldClearSharedClientAfterStartupFailure({
+								error: startupAttemptError,
+								spawnedBy: params.spawnedBy
+							})) {
+								if (startupClientForAbandonedRequestCleanup === startupClient) startupClientForAbandonedRequestCleanup = void 0;
+								await evictFailedStartupClient(startupClient);
+							}
 						}
 					}
 				};
@@ -2863,15 +3108,82 @@ async function startCodexAttemptThread(params) {
 			releaseSharedClientLease
 		};
 	} catch (error) {
-		if (params.signal.aborted || shouldClearSharedClientAfterStartupRace(error) || shouldClearSharedClientAfterStartupFailure({
+		if (params.signal.aborted || shouldClearSharedClientAfterStartupAbandon(error)) {
+			releaseSharedClientLease?.();
+			releaseSharedClientLease = void 0;
+			await closeAbandonedStartupClient(startupClientForAbandonedRequestCleanup);
+			startupClientForAbandonedRequestCleanup = void 0;
+		} else if (shouldClearSharedClientAfterStartupRace(error) || shouldClearSharedClientAfterStartupFailure({
 			error,
 			spawnedBy: params.spawnedBy
-		})) clearSharedCodexAppServerClientIfCurrent(startupClientForAbandonedRequestCleanup);
+		})) {
+			releaseSharedClientLease?.();
+			releaseSharedClientLease = void 0;
+			await evictFailedStartupClient(startupClientForAbandonedRequestCleanup);
+			startupClientForAbandonedRequestCleanup = void 0;
+		}
 		throw error;
+	} finally {
+		params.signal.removeEventListener("abort", abandonStartupAcquire);
+	}
+}
+async function closeAbandonedStartupClient(client) {
+	if (!client) return;
+	const unclaimedSharedClient = clearSharedCodexAppServerClientIfCurrentAndUnclaimed(client);
+	if (unclaimedSharedClient.closed) {
+		await closeClientAndWaitIfAvailable(client);
+		return;
+	}
+	if (unclaimedSharedClient.found) {
+		if (retireSharedCodexAppServerClientIfCurrent(client)?.closed) await closeClientAndWaitIfAvailable(client);
+		return;
+	}
+	const retiredSharedClient = retireSharedCodexAppServerClientIfCurrent(client);
+	if (retiredSharedClient) {
+		if (retiredSharedClient.closed) await closeClientAndWaitIfAvailable(client);
+		return;
+	}
+	if (clearSharedCodexAppServerClientIfCurrent(client)) {
+		await closeClientAndWaitIfAvailable(client);
+		return;
+	}
+	await closeClientAndWaitIfAvailable(client);
+}
+async function closeClientAndWaitIfAvailable(client) {
+	const closeable = client;
+	if (typeof closeable.closeAndWait === "function") {
+		await closeable.closeAndWait();
+		return;
+	}
+	closeable.close?.();
+}
+async function evictFailedStartupClient(client) {
+	if (!client) return;
+	const unclaimedSharedClient = clearSharedCodexAppServerClientIfCurrentAndUnclaimed(client);
+	if (unclaimedSharedClient.closed) {
+		await closeClientAndWaitIfAvailable(client);
+		return;
+	}
+	if (unclaimedSharedClient.found) {
+		if (retireSharedCodexAppServerClientIfCurrent(client)?.closed) await closeClientAndWaitIfAvailable(client);
+		return;
+	}
+	const retiredSharedClient = retireSharedCodexAppServerClientIfCurrent(client);
+	if (retiredSharedClient) {
+		if (retiredSharedClient.closed) await closeClientAndWaitIfAvailable(client);
+		return;
+	}
+	if (clearSharedCodexAppServerClientIfCurrent(client)) {
+		await closeClientAndWaitIfAvailable(client);
+		return;
 	}
+	await closeClientAndWaitIfAvailable(client);
+}
+function shouldClearSharedClientAfterStartupAbandon(error) {
+	return error instanceof Error && (error.message === "codex app-server startup timed out" || error.message === "codex app-server startup aborted");
 }
 function shouldClearSharedClientAfterStartupRace(error) {
-	return error instanceof Error && (error.message === "codex app-server startup timed out" || error.message === "codex app-server startup aborted" || error.message.endsWith(" timed out"));
+	return error instanceof Error && (shouldClearSharedClientAfterStartupAbandon(error) || error.message.endsWith(" timed out"));
 }
 function shouldClearSharedClientAfterStartupFailure(params) {
 	if (!(params.error instanceof Error)) return !params.spawnedBy;
@@ -2880,7 +3192,15 @@ function shouldClearSharedClientAfterStartupFailure(params) {
 }
 //#endregion
 //#region extensions/codex/src/app-server/attempt-steering.ts
+/**
+* Debounced steering queue for forwarding user text to an active Codex
+* app-server turn.
+*/
 const CODEX_STEER_ALL_DEBOUNCE_MS = 500;
+/**
+* Creates a queue that batches steer text while still serializing app-server
+* `turn/steer` requests.
+*/
 function createCodexSteeringQueue(params) {
 	let batchedTexts = [];
 	let batchTimer;
@@ -2951,9 +3271,11 @@ function createCodexSteeringQueue(params) {
 		}
 	};
 }
+/** Normalizes steer debounce milliseconds, preserving explicit zero. */
 function normalizeCodexSteerDebounceMs(value) {
 	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.floor(value) : CODEX_STEER_ALL_DEBOUNCE_MS;
 }
+/** Converts plain text into the Codex app-server user-input shape. */
 function toCodexTextInput(text) {
 	return {
 		type: "text",
@@ -2963,6 +3285,14 @@ function toCodexTextInput(text) {
 }
 //#endregion
 //#region extensions/codex/src/app-server/attempt-turn-watches.ts
+/**
+* Idle-watch controller for Codex app-server turn progress, completion, and
+* terminal-event gaps.
+*/
+/**
+* Creates a controller that arms/disarms timers as Codex app-server
+* notifications and tool handoffs progress.
+*/
 function createCodexAttemptTurnWatchController(params) {
 	let completionIdleTimer;
 	let completionIdleWatchArmed = false;
@@ -3281,8 +3611,10 @@ function createCodexAttemptTurnWatchController(params) {
 		clearAllTimers
 	};
 }
+/** Hard cap for per-call Codex dynamic tool timeout overrides. */
 const CODEX_DYNAMIC_TOOL_MAX_TIMEOUT_MS = 6e5;
 const CODEX_DYNAMIC_IMAGE_GENERATION_TOOL_TIMEOUT_MS = 12e4;
+/** Timeout for message-delivery dynamic tool calls. */
 const CODEX_DYNAMIC_MESSAGE_TOOL_TIMEOUT_MS = 12e4;
 const LOG_FIELD_MAX_LENGTH = 160;
 function normalizeLogField(value) {
@@ -3332,6 +3664,10 @@ function formatDynamicToolTimeoutDetails(params) {
 		}
 	};
 }
+/**
+* Runs a dynamic tool call with run-abort and per-call timeout handling,
+* returning a Codex protocol response instead of throwing.
+*/
 async function handleDynamicToolCallWithTimeout(params) {
 	if (params.signal.aborted) return failedDynamicToolResponse("OpenClaw dynamic tool call aborted before execution.");
 	const controller = new AbortController();
@@ -3401,12 +3737,14 @@ function failedDynamicToolResponse(message, options) {
 	});
 	return response;
 }
+/** Strips OpenClaw-only metadata before sending a dynamic tool response to Codex. */
 function toCodexDynamicToolProtocolResponse(response) {
 	return {
 		contentItems: response.contentItems,
 		success: response.success
 	};
 }
+/** Adds async-started progress details when a tool result continues out of band. */
 function toCodexDynamicToolProgressResponse(response, protocolResponse) {
 	if (response.asyncStarted !== true) return protocolResponse;
 	return {
@@ -3417,21 +3755,26 @@ function toCodexDynamicToolProgressResponse(response, protocolResponse) {
 		}
 	};
 }
+/** Decides whether a terminal dynamic tool response can release the Codex turn. */
 function shouldReleaseTurnAfterTerminalDynamicTool(state) {
 	return !state.completed && !state.aborted && state.responseSuccess && !state.currentTurnHadNonTerminalDynamicToolResult && state.activeAppServerTurnRequests === 0 && state.activeTurnItemIdsCount === 0 && state.pendingOpenClawDynamicToolCompletionIdsCount === 0;
 }
+/** Returns true when a non-async result should block terminal-release shortcuts. */
 function shouldBlockTerminalReleaseForNonTerminalDynamicToolResult(response) {
 	return response.asyncStarted !== true;
 }
+/** Resolves whether terminal diagnostic state should release, wait, or stay idle. */
 function resolveTerminalDynamicToolBatchAction(state) {
 	if (state.activeAppServerTurnRequests > 0 || state.activeTurnItemIdsCount > 0 || state.pendingOpenClawDynamicToolCompletionIdsCount > 0) return "wait";
 	if (state.currentTurnHadNonTerminalDynamicToolResult) return "clear-nonterminal-batch";
 	if (state.hasPendingTerminalDynamicToolRelease) return "release-pending-terminal";
 	return "idle";
 }
+/** Returns true for diagnostic events that terminate a dynamic tool call. */
 function isDynamicToolTerminalDiagnosticEvent(event) {
 	return event.type === "tool.execution.completed" || event.type === "tool.execution.error" || event.type === "tool.execution.blocked";
 }
+/** Matches terminal diagnostics to a specific dynamic tool call id/name. */
 function isMatchingDynamicToolTerminalDiagnostic(params) {
 	if (params.event.toolCallId !== params.call.callId || params.event.toolName !== params.call.tool) return false;
 	if (params.runId !== void 0) return params.event.runId === params.runId;
@@ -3439,6 +3782,7 @@ function isMatchingDynamicToolTerminalDiagnostic(params) {
 	if (params.sessionKey !== void 0) return params.event.sessionKey === params.sessionKey;
 	return params.event.runId === void 0 && params.event.sessionId === void 0 && params.event.sessionKey === void 0;
 }
+/** Checks pending diagnostics for a terminal event matching a tool call. */
 function hasPendingDynamicToolTerminalDiagnostic(params) {
 	return hasPendingInternalDiagnosticEvent((event) => {
 		if (!isDynamicToolTerminalDiagnosticEvent(event)) return false;
@@ -3451,6 +3795,7 @@ function hasPendingDynamicToolTerminalDiagnostic(params) {
 		});
 	});
 }
+/** Resolves per-tool timeout, applying media/message defaults and hard caps. */
 function resolveDynamicToolCallTimeoutMs(params) {
 	return clampDynamicToolTimeoutMs(readDynamicToolCallTimeoutMs(params.call.arguments) ?? readConfiguredDynamicToolTimeoutMs(params.call.tool, params.config) ?? 9e4);
 }
@@ -3485,6 +3830,7 @@ const OPENAI_CODEX_RESPONSES_API = "openai-chatgpt-responses";
 function normalizeRuntimeId(value) {
 	return value?.trim().toLowerCase() ?? "";
 }
+/** Maps local Codex runtime plans onto the provider/api pair exposed to event projection. */
 function resolveCodexLocalRuntimeAttribution(params) {
 	const authProfileProvider = normalizeRuntimeId(params.runtimePlan?.auth?.authProfileProviderForAuth);
 	if (normalizeRuntimeId(params.runtimePlan?.observability.harnessId) === "codex" && authProfileProvider !== OPENAI_PROVIDER_ID && normalizeRuntimeId(params.model.provider) === OPENAI_PROVIDER_ID && normalizeRuntimeId(params.model.api) === OPENAI_RESPONSES_API) return {
@@ -3498,9 +3844,15 @@ function resolveCodexLocalRuntimeAttribution(params) {
 }
 //#endregion
 //#region extensions/codex/src/app-server/tool-progress-normalization.ts
+/**
+* Normalizes and sanitizes Codex dynamic-tool progress payloads before they are
+* emitted into OpenClaw events or logs.
+*/
+/** Maps OpenClaw tool-progress config to the mode used by Codex progress metadata. */
 function resolveCodexToolProgressDetailMode(value) {
 	return value === "raw" ? "raw" : "explain";
 }
+/** Recursively redacts sensitive strings and handles circular values in event payloads. */
 function sanitizeCodexAgentEventValue(value, seen = /* @__PURE__ */ new WeakSet()) {
 	if (typeof value === "string") return redactToolPayloadText(value);
 	if (Array.isArray(value)) {
@@ -3517,16 +3869,20 @@ function sanitizeCodexAgentEventValue(value, seen = /* @__PURE__ */ new WeakSet(
 	}
 	return value;
 }
+/** Sanitizes a record-shaped Codex agent event payload. */
 function sanitizeCodexAgentEventRecord(value) {
 	return sanitizeCodexAgentEventValue(value);
 }
+/** Sanitizes dynamic-tool arguments before diagnostic/event emission. */
 function sanitizeCodexToolArguments(value) {
 	if (!isJsonObject(value)) return;
 	return sanitizeCodexAgentEventRecord(value);
 }
+/** Sanitizes a Codex dynamic-tool response before diagnostic/event emission. */
 function sanitizeCodexToolResponse(response) {
 	return sanitizeCodexAgentEventRecord(response);
 }
+/** Infers compact human-readable tool metadata from Codex dynamic-tool arguments. */
 function inferCodexDynamicToolMeta(call, detailMode) {
 	return inferToolMetaFromArgs(call.tool, call.arguments, { detailMode });
 }
@@ -5442,6 +5798,7 @@ function readTurn(value) {
 //#region extensions/codex/src/app-server/native-subagent-notification.ts
 const CODEX_SUBAGENT_NOTIFICATION_START = "<subagent_notification>";
 const CODEX_SUBAGENT_NOTIFICATION_END = "</subagent_notification>";
+/** Extracts trusted subagent completion payloads from a Codex server notification. */
 function extractCodexNativeSubagentCompletions(notification) {
 	const params = isJsonObject(notification.params) ? notification.params : void 0;
 	if (!params) return [];
@@ -5452,6 +5809,7 @@ function extractCodexNativeSubagentCompletions(notification) {
 	const author = readTrustedInterAgentCommunicationAuthor(item);
 	return extractCodexNativeSubagentCompletionsFromText(text).filter((completion) => completion.agentPath === author);
 }
+/** Parses one or more tagged subagent completion payloads from commentary text. */
 function extractCodexNativeSubagentCompletionsFromText(text) {
 	const completions = [];
 	let cursor = 0;
@@ -5552,11 +5910,19 @@ function normalizeStatusKey(value) {
 }
 //#endregion
 //#region extensions/codex/src/app-server/native-subagent-task-ids.ts
+/**
+* Shared identifiers for representing Codex native subagents as OpenClaw task
+* runtime rows.
+*/
+/** Task runtime namespace for Codex native subagent task rows. */
 const CODEX_NATIVE_SUBAGENT_RUNTIME = "subagent";
+/** Task kind used to distinguish native Codex subagents from other subagent runtimes. */
 const CODEX_NATIVE_SUBAGENT_TASK_KIND = "codex-native";
+/** Run id prefix for task rows keyed by Codex child thread ids. */
 const CODEX_NATIVE_SUBAGENT_RUN_ID_PREFIX = "codex-thread:";
 //#endregion
 //#region extensions/codex/src/app-server/native-subagent-task-mirror.ts
+/** Projects Codex thread and collab-agent notifications into task lifecycle updates. */
 var CodexNativeSubagentTaskMirror = class {
 	constructor(params, runtime) {
 		this.params = params;
@@ -5771,9 +6137,11 @@ var CodexNativeSubagentTaskMirror = class {
 		});
 	}
 };
+/** Converts a Codex child thread id into the OpenClaw task-runtime run id. */
 function codexNativeSubagentRunId(threadId) {
 	return `${CODEX_NATIVE_SUBAGENT_RUN_ID_PREFIX}${threadId.trim()}`;
 }
+/** Reads a subagent thread-spawn source only when it belongs to the expected parent thread. */
 function readSubagentThreadSpawnSource(source, parentThreadId) {
 	if (!source || typeof source !== "object" || !("subAgent" in source)) return;
 	const subAgent = source.subAgent;
@@ -5866,6 +6234,10 @@ function trimOptional(value) {
 }
 //#endregion
 //#region extensions/codex/src/app-server/native-subagent-monitor.ts
+/**
+* Monitors Codex native subagent threads and mirrors their lifecycle/completion
+* into OpenClaw task runtime records for parent sessions.
+*/
 const DEFAULT_TRANSCRIPT_POLL_DELAYS_MS = [
 	2e3,
 	5e3,
@@ -5891,6 +6263,7 @@ const defaultRuntime = {
 	deliverAgentHarnessTaskCompletion
 };
 const monitors = /* @__PURE__ */ new WeakMap();
+/** Registers or updates the monitor bound to a Codex app-server client. */
 function registerCodexNativeSubagentMonitor(params) {
 	let monitor = monitors.get(params.client);
 	if (!monitor) {
@@ -5904,6 +6277,7 @@ function registerCodexNativeSubagentMonitor(params) {
 		agentId: params.agentId
 	});
 }
+/** Tracks native subagent thread notifications, transcript completions, and task delivery. */
 var CodexNativeSubagentMonitor = class {
 	constructor(client, runtime = defaultRuntime, options = {}) {
 		this.runtime = runtime;
@@ -6701,6 +7075,7 @@ function minFiniteNumber(values) {
 function hasContextEngineThreadBootstrapProjection(binding) {
 	return binding.contextEngine?.projection?.mode === "thread_bootstrap";
 }
+/** Clears and drops a binding when the native Codex thread is too large to resume safely. */
 async function rotateOversizedCodexAppServerStartupBinding(params) {
 	const binding = params.binding;
 	if (!binding?.threadId) return binding;
@@ -6767,6 +7142,10 @@ async function rotateOversizedCodexAppServerStartupBinding(params) {
 }
 //#endregion
 //#region extensions/codex/src/app-server/trajectory.ts
+/**
+* Records optional Codex runtime trajectory sidecars with bounded, redacted
+* context and completion events.
+*/
 const SENSITIVE_FIELD_RE = /(?:authorization|cookie|credential|key|password|passwd|secret|token)/iu;
 const PRIVATE_PAYLOAD_FIELD_RE = /(?:image|screenshot|attachment|fileData|dataUri)/iu;
 const AUTHORIZATION_VALUE_RE = /\b(Bearer|Basic)\s+[A-Za-z0-9+/._~=-]{8,}/giu;
@@ -6774,6 +7153,7 @@ const JWT_VALUE_RE = /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]
 const COOKIE_PAIR_RE = /\b([A-Za-z][A-Za-z0-9_.-]{1,64})=([A-Za-z0-9+/._~%=-]{16,})(?=;|\s|$)/gu;
 const TRAJECTORY_RUNTIME_FILE_MAX_BYTES = 50 * 1024 * 1024;
 const TRAJECTORY_RUNTIME_EVENT_MAX_BYTES = 256 * 1024;
+/** Resolves secure create/truncate flags for trajectory pointer files. */
 function resolveCodexTrajectoryPointerFlags(constants = fsSync.constants) {
 	const noFollow = constants.O_NOFOLLOW;
 	return constants.O_CREAT | constants.O_TRUNC | constants.O_WRONLY | (typeof noFollow === "number" ? noFollow : 0);
@@ -6828,6 +7208,7 @@ function writeTrajectoryPointerBestEffort(params) {
 		}
 	} catch {}
 }
+/** Creates a trajectory recorder when trajectory capture is enabled for the environment. */
 function createCodexTrajectoryRecorder(params) {
 	const env = params.env ?? process.env;
 	if (!parseTrajectoryEnabled(env)) return null;
@@ -6877,6 +7258,7 @@ function createCodexTrajectoryRecorder(params) {
 		}
 	};
 }
+/** Records compiled prompt/tool context at the start of a Codex runtime attempt. */
 function recordCodexTrajectoryContext(recorder, params) {
 	if (!recorder) return;
 	recorder.recordEvent("context.compiled", {
@@ -6886,6 +7268,7 @@ function recordCodexTrajectoryContext(recorder, params) {
 		tools: toTrajectoryToolDefinitions(params.tools)
 	});
 }
+/** Records final Codex model completion metadata and assistant snapshots. */
 function recordCodexTrajectoryCompletion(recorder, params) {
 	if (!recorder) return;
 	recorder.recordEvent("model.completed", {
@@ -6955,6 +7338,7 @@ function sanitizeValue(value, depth = 0, key = "") {
 function redactSensitiveString(value) {
 	return value.replace(AUTHORIZATION_VALUE_RE, "$1 <redacted>").replace(JWT_VALUE_RE, "<redacted-jwt>").replace(COOKIE_PAIR_RE, "$1=<redacted>");
 }
+/** Converts arbitrary prompt errors into trajectory-safe text. */
 function normalizeCodexTrajectoryError(value) {
 	if (!value) return null;
 	if (value instanceof Error) return value.message;
@@ -6967,7 +7351,12 @@ function normalizeCodexTrajectoryError(value) {
 }
 //#endregion
 //#region extensions/codex/src/app-server/usage-limit-error.ts
+/**
+* Enriches Codex usage-limit failures with current rate-limit information and
+* marks blocked auth profiles when Codex exposes a reset time.
+*/
 const CODEX_USAGE_LIMIT_RATE_LIMIT_REFRESH_TIMEOUT_MS = 5e3;
+/** Marks a Codex auth profile blocked until the reset time advertised by rate limits. */
 async function markCodexAuthProfileBlockedFromRateLimits(params) {
 	const authProfileId = params.authProfileId?.trim();
 	if (!authProfileId || !params.params.authProfileStore) return;
@@ -6990,6 +7379,7 @@ async function markCodexAuthProfileBlockedFromRateLimits(params) {
 		});
 	}
 }
+/** Formats a turn-start usage-limit error, refreshing rate limits when needed. */
 async function formatCodexTurnStartUsageLimitError(params) {
 	return refreshCodexUsageLimitError({
 		client: params.client,
@@ -6998,6 +7388,7 @@ async function formatCodexTurnStartUsageLimitError(params) {
 		signal: params.signal
 	});
 }
+/** Refreshes a generic prompt usage-limit message into a reset-aware message. */
 async function refreshCodexUsageLimitPromptError(params) {
 	if (!shouldRefreshCodexRateLimitsForUsageLimitMessage(params.message)) return;
 	return (await refreshCodexUsageLimitError({
@@ -7107,6 +7498,11 @@ function readString$1(record, key) {
 }
 //#endregion
 //#region extensions/codex/src/app-server/user-input-bridge.ts
+/**
+* Bridges Codex item/tool user-input requests to OpenClaw messaging prompts and
+* turns replies into app-server answer payloads.
+*/
+/** Creates a per-turn bridge for pending Codex user-input requests. */
 function createCodexUserInputBridge(params) {
 	let pending;
 	const resolvePending = (value) => {
@@ -8916,7 +9312,8 @@ async function runCodexAppServerAttempt(params, options = {}) {
 				}),
 				runMaintenance: runHarnessContextEngineMaintenance,
 				config: params.config,
-				warn: (message) => embeddedAgentLog.warn(message)
+				warn: (message) => embeddedAgentLog.warn(message),
+				isHeartbeat: params.bootstrapContextRunKind === "heartbeat"
 			});
 		}
 		runAgentHarnessLlmOutputHook({