@openclaw/codex 2026.5.19-alpha.1 → 2026.5.19-beta.2

package/dist/harness.js

@@ -18,14 +18,14 @@ function createCodexAppServerAgentHarness(options) {
 			};
 		},
 		runAttempt: async (params) => {
-			const { runCodexAppServerAttempt } = await import("./run-attempt-nWX3d1pe.js");
+			const { runCodexAppServerAttempt } = await import("./run-attempt-BqRPAaHk.js");
 			return runCodexAppServerAttempt(params, {
 				pluginConfig: options?.resolvePluginConfig?.() ?? options?.pluginConfig,
 				nativeHookRelay: { enabled: true }
 			});
 		},
 		runSideQuestion: async (params) => {
-			const { runCodexAppServerSideQuestion } = await import("./side-question-CpJYlXni.js");
+			const { runCodexAppServerSideQuestion } = await import("./side-question-DjyRnjPQ.js");
 			return runCodexAppServerSideQuestion(params, {
 				pluginConfig: options?.resolvePluginConfig?.() ?? options?.pluginConfig,
 				nativeHookRelay: { enabled: true }

package/dist/{run-attempt-nWX3d1pe.js → run-attempt-BqRPAaHk.js}

@@ -7,7 +7,7 @@ import { d as resolveCodexUsageLimitResetAtMs, f as shouldRefreshCodexRateLimits
 import { c as resolveCodexAppServerAuthAccountCacheKey, d as resolveCodexAppServerEnvApiKeyCacheKey, f as resolveCodexAppServerHomeDir, l as resolveCodexAppServerAuthProfileId, s as refreshCodexAppServerAuthTokens, t as clearSharedCodexAppServerClientIfCurrent, u as resolveCodexAppServerAuthProfileIdForAgent } from "./shared-client-DWgKldR5.js";
 import { i as readCodexAppServerBinding, t as clearCodexAppServerBinding } from "./session-binding-D9ejASYj.js";
 import { a as defaultCodexAppInventoryCache } from "./plugin-activation-Dtcfb3sk.js";
-import { C as isForcedPrivateQaCodexRuntime, S as filterCodexDynamicTools, T as resolveCodexDynamicToolsLoading, _ as projectContextEngineAssemblyForCodex, b as createCodexDynamicToolBridge, c as codexDynamicToolsFingerprint, f as startOrResumeThread, g as shouldBuildCodexPluginThreadConfig, h as mergeCodexThreadConfigs, i as buildDeveloperInstructions, l as isContextEngineBindingCompatible, m as buildCodexPluginThreadConfigInputFingerprint, p as buildCodexPluginThreadConfig, r as buildContextEngineBinding, s as buildTurnStartParams, t as areCodexDynamicToolFingerprintsCompatible, v as resolveCodexContextEngineProjectionMaxChars, w as normalizeCodexDynamicToolName, x as sanitizeCodexHistoryImagePayloads, y as resolveCodexContextEngineProjectionReserveTokens } from "./thread-lifecycle-D8uxjJA4.js";
+import { C as isForcedPrivateQaCodexRuntime, S as filterCodexDynamicTools, T as resolveCodexDynamicToolsLoading, _ as projectContextEngineAssemblyForCodex, b as createCodexDynamicToolBridge, c as codexDynamicToolsFingerprint, f as startOrResumeThread, g as shouldBuildCodexPluginThreadConfig, h as mergeCodexThreadConfigs, i as buildDeveloperInstructions, l as isContextEngineBindingCompatible, m as buildCodexPluginThreadConfigInputFingerprint, p as buildCodexPluginThreadConfig, r as buildContextEngineBinding, s as buildTurnStartParams, t as areCodexDynamicToolFingerprintsCompatible, v as resolveCodexContextEngineProjectionMaxChars, w as normalizeCodexDynamicToolName, x as sanitizeCodexHistoryImagePayloads, y as resolveCodexContextEngineProjectionReserveTokens } from "./thread-lifecycle-C07GnPSH.js";
 import { t as defaultCodexAppServerClientFactory } from "./client-factory-By1f68U_.js";
 import { a as handleCodexAppServerElicitationRequest, c as emitDynamicToolTerminalDiagnostic, i as buildCodexNativeHookRelayDisabledConfig, l as handleCodexAppServerApprovalRequest, n as CODEX_NATIVE_HOOK_RELAY_EVENTS, o as emitDynamicToolErrorDiagnostic, r as buildCodexNativeHookRelayConfig, s as emitDynamicToolStartedDiagnostic, t as filterToolsForVisionInputs } from "./vision-tools-CDoJ4rDN.js";
 import { t as ensureCodexComputerUse } from "./computer-use-BD8UmXB-.js";
@@ -20,7 +20,7 @@ import path from "node:path";
 import { markAuthProfileBlockedUntil, resolveAgentDir as resolveAgentDir$1 } from "openclaw/plugin-sdk/agent-runtime";
 import { appendRegularFile, pathExists } from "openclaw/plugin-sdk/security-runtime";
 import { redactSensitiveFieldValue, redactToolPayloadText } from "openclaw/plugin-sdk/logging-core";
-import { emitTrustedDiagnosticEvent, onInternalDiagnosticEvent } from "openclaw/plugin-sdk/diagnostic-runtime";
+import { emitTrustedDiagnosticEvent, hasPendingInternalDiagnosticEvent, onInternalDiagnosticEvent } from "openclaw/plugin-sdk/diagnostic-runtime";
 import { CODEX_NATIVE_SUBAGENT_RUNTIME, CODEX_NATIVE_SUBAGENT_RUN_ID_PREFIX, CODEX_NATIVE_SUBAGENT_TASK_KIND, createRunningTaskRun, finalizeTaskRunByRunId, recordTaskRunProgressByRunId } from "openclaw/plugin-sdk/codex-native-task-runtime";
 import { buildSessionContext, migrateSessionEntries, parseSessionEntries } from "@earendil-works/pi-coding-agent";
 //#region extensions/codex/src/app-server/local-runtime-attribution.ts
@@ -2362,6 +2362,7 @@ function readRequestId(record) {
 //#region extensions/codex/src/app-server/run-attempt.ts
 const CODEX_DYNAMIC_TOOL_TIMEOUT_MS = 3e4;
 const CODEX_DYNAMIC_TOOL_MAX_TIMEOUT_MS = 6e5;
+const CODEX_DYNAMIC_IMAGE_GENERATION_TOOL_TIMEOUT_MS = 12e4;
 const CODEX_DYNAMIC_IMAGE_TOOL_TIMEOUT_MS = 6e4;
 const CODEX_APP_SERVER_STARTUP_CONNECTION_CLOSE_MAX_ATTEMPTS = 3;
 const CODEX_APP_SERVER_STARTUP_TIMEOUT_FLOOR_MS = 100;
@@ -2376,6 +2377,13 @@ const CODEX_NATIVE_HOOK_RELAY_RENEW_INTERVAL_MS = 6e4;
 const CODEX_STEER_ALL_DEBOUNCE_MS = 500;
 const LOG_FIELD_MAX_LENGTH = 160;
 const CODEX_NATIVE_PROJECT_DOC_BASENAMES = new Set(["agents.md"]);
+const CODEX_WORKSPACE_DEVELOPER_CONTEXT_BASENAMES = new Set([
+	"identity.md",
+	"soul.md",
+	"tools.md",
+	"user.md"
+]);
+const CODEX_HEARTBEAT_CONTEXT_BASENAME = "heartbeat.md";
 const CODEX_NATIVE_HOOK_RELAY_EVENTS_WITH_APP_SERVER_APPROVALS = CODEX_NATIVE_HOOK_RELAY_EVENTS.filter((event) => event !== "permission_request");
 const CODEX_BOOTSTRAP_CONTEXT_ORDER = new Map([
 	["soul.md", 10],
@@ -2891,7 +2899,6 @@ async function runCodexAppServerAttempt(params, options = {}) {
 		});
 		historyMessages = await readMirroredSessionHistoryMessages(activeSessionFile) ?? historyMessages;
 	}
-	const baseDeveloperInstructions = buildDeveloperInstructions(params, { dynamicTools: toolBridge.specs });
 	const workspaceBootstrapContext = await buildCodexWorkspaceBootstrapContext({
 		params,
 		resolvedWorkspace,
@@ -2899,6 +2906,7 @@ async function runCodexAppServerAttempt(params, options = {}) {
 		sessionKey: sandboxSessionKey,
 		sessionAgentId
 	});
+	const baseDeveloperInstructions = joinPresentSections(buildDeveloperInstructions(params, { dynamicTools: toolBridge.specs }), workspaceBootstrapContext.developerInstructions);
 	const openClawPromptContext = buildCodexOpenClawPromptContext({
 		params,
 		skillsPrompt: params.skillsSnapshot?.prompt,
@@ -3775,8 +3783,12 @@ async function runCodexAppServerAttempt(params, options = {}) {
 						result: sanitizeCodexToolResponse(protocolResponse)
 					}
 				});
-				await waitForDiagnosticEventDrain();
-				if (!terminalDiagnosticObserved) emitDynamicToolTerminalDiagnostic({
+				if (!terminalDiagnosticObserved && !hasPendingDynamicToolTerminalDiagnostic({
+					call,
+					runId: params.runId,
+					sessionId: params.sessionId,
+					sessionKey: params.sessionKey
+				})) emitDynamicToolTerminalDiagnostic({
 					response,
 					call,
 					runId: params.runId,
@@ -3786,8 +3798,12 @@ async function runCodexAppServerAttempt(params, options = {}) {
 				});
 				return protocolResponse;
 			} catch (error) {
-				await waitForDiagnosticEventDrain();
-				if (!terminalDiagnosticObserved) emitDynamicToolErrorDiagnostic({
+				if (!terminalDiagnosticObserved && !hasPendingDynamicToolTerminalDiagnostic({
+					call,
+					runId: params.runId,
+					sessionId: params.sessionId,
+					sessionKey: params.sessionKey
+				})) emitDynamicToolErrorDiagnostic({
 					call,
 					runId: params.runId,
 					sessionId: params.sessionId,
@@ -3899,7 +3915,8 @@ async function runCodexAppServerAttempt(params, options = {}) {
 		cwd: effectiveWorkspace,
 		appServer: pluginAppServer,
 		promptText: codexTurnPromptText,
-		sandboxPolicy: codexSandboxPolicy
+		sandboxPolicy: codexSandboxPolicy,
+		heartbeatCollaborationInstructions: workspaceBootstrapContext.heartbeatCollaborationInstructions
 	}), {
 		timeoutMs: params.timeoutMs,
 		signal: runAbortController.signal
@@ -4401,9 +4418,6 @@ function toCodexDynamicToolProtocolResponse(response) {
 		success: response.success
 	};
 }
-function waitForDiagnosticEventDrain() {
-	return new Promise((resolve) => setImmediate(resolve));
-}
 function isDynamicToolTerminalDiagnosticEvent(event) {
 	return event.type === "tool.execution.completed" || event.type === "tool.execution.error" || event.type === "tool.execution.blocked";
 }
@@ -4414,6 +4428,18 @@ 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;
 }
+function hasPendingDynamicToolTerminalDiagnostic(params) {
+	return hasPendingInternalDiagnosticEvent((event) => {
+		if (!isDynamicToolTerminalDiagnosticEvent(event)) return false;
+		return isMatchingDynamicToolTerminalDiagnostic({
+			event,
+			call: params.call,
+			runId: params.runId,
+			sessionId: params.sessionId,
+			sessionKey: params.sessionKey
+		});
+	});
+}
 function resolveDynamicToolCallTimeoutMs(params) {
 	return clampDynamicToolTimeoutMs(readDynamicToolCallTimeoutMs(params.call.arguments) ?? readConfiguredDynamicToolTimeoutMs(params.call.tool, params.config) ?? CODEX_DYNAMIC_TOOL_TIMEOUT_MS);
 }
@@ -4424,8 +4450,8 @@ function readDynamicToolCallTimeoutMs(value) {
 function readConfiguredDynamicToolTimeoutMs(toolName, config) {
 	if (toolName === "image_generate") {
 		const imageGenerationModel = config?.agents?.defaults?.imageGenerationModel;
-		if (!imageGenerationModel || typeof imageGenerationModel !== "object") return;
-		return readPositiveFiniteTimeoutMs(imageGenerationModel.timeoutMs);
+		if (!imageGenerationModel || typeof imageGenerationModel !== "object") return CODEX_DYNAMIC_IMAGE_GENERATION_TOOL_TIMEOUT_MS;
+		return readPositiveFiniteTimeoutMs(imageGenerationModel.timeoutMs) ?? CODEX_DYNAMIC_IMAGE_GENERATION_TOOL_TIMEOUT_MS;
 	}
 	if (toolName === "image") return readTimeoutSecondsAsMs(config?.tools?.media?.image?.timeoutSeconds) ?? CODEX_DYNAMIC_IMAGE_TOOL_TIMEOUT_MS;
 }
@@ -4714,7 +4740,7 @@ function hasWildcardCodexToolsAllow(toolsAllow) {
 	return toolsAllow.some((name) => normalizeCodexDynamicToolName(name) === "*");
 }
 function shouldForceMessageTool(params) {
-	return params.sourceReplyDeliveryMode === "message_tool_only";
+	return params.disableMessageTool !== true && params.sourceReplyDeliveryMode === "message_tool_only";
 }
 function shouldProjectMirroredHistoryForCodexStart(params) {
 	if (!params.historyMessages.some((message) => message.role === "user")) return false;
@@ -5107,10 +5133,18 @@ async function buildCodexWorkspaceBootstrapContext(params) {
 			sourceWorkspaceDir: params.resolvedWorkspace,
 			targetWorkspaceDir: params.effectiveWorkspace
 		}));
+		const promptContextFiles = selectCodexWorkspacePromptContextFiles(contextFiles);
+		const developerInstructionFiles = shouldInjectCodexOpenClawPromptContext(params.params) ? selectCodexWorkspaceDeveloperInstructionFiles(contextFiles) : [];
+		const heartbeatReferenceFiles = selectCodexWorkspaceHeartbeatReferenceFiles(contextFiles);
 		return {
 			...bootstrapContext,
 			contextFiles,
-			promptContext: renderCodexWorkspaceBootstrapPromptContext(contextFiles)
+			promptContextFiles,
+			developerInstructionFiles,
+			heartbeatReferenceFiles,
+			promptContext: renderCodexWorkspaceBootstrapPromptContext(promptContextFiles),
+			developerInstructions: renderCodexWorkspaceDeveloperInstructions(developerInstructionFiles),
+			heartbeatCollaborationInstructions: renderCodexWorkspaceHeartbeatReference(heartbeatReferenceFiles)
 		};
 	} catch (error) {
 		embeddedAgentLog.warn("failed to load codex workspace bootstrap instructions", { error });
@@ -5143,7 +5177,8 @@ function buildCodexSystemPromptReport(params) {
 		},
 		injectedWorkspaceFiles: buildCodexBootstrapInjectionStats({
 			bootstrapFiles: params.workspaceBootstrapContext.bootstrapFiles,
-			injectedFiles: params.workspaceBootstrapContext.contextFiles
+			injectedFiles: params.workspaceBootstrapContext.promptContextFiles ?? [],
+			developerInstructionFiles: params.workspaceBootstrapContext.developerInstructionFiles ?? []
 		}),
 		skills: {
 			promptChars: skillsPrompt.length,
@@ -5192,29 +5227,52 @@ function buildCodexToolSchemaStats(schema) {
 	};
 }
 function buildCodexBootstrapInjectionStats(params) {
-	const injectedByPath = /* @__PURE__ */ new Map();
-	const injectedByBaseName = /* @__PURE__ */ new Map();
-	for (const file of params.injectedFiles) {
-		const pathValue = readNonEmptyString(file.path);
-		if (!pathValue) continue;
-		if (!injectedByPath.has(pathValue)) injectedByPath.set(pathValue, file.content);
-		const baseName = path.posix.basename(pathValue.replaceAll("\\", "/"));
-		if (!injectedByBaseName.has(baseName)) injectedByBaseName.set(baseName, file.content);
-	}
+	const injectedIndex = indexCodexContextFileContent(params.injectedFiles);
+	const developerInstructionIndex = indexCodexContextFileContent(params.developerInstructionFiles ?? []);
 	return params.bootstrapFiles.map((file) => {
 		const pathValue = readNonEmptyString(file.path) ?? file.name;
+		const baseName = getCodexContextFileBasename(pathValue || file.name);
 		const rawChars = file.missing ? 0 : (file.content ?? "").trimEnd().length;
-		const injectedChars = (injectedByPath.get(pathValue) ?? injectedByPath.get(file.name) ?? injectedByBaseName.get(file.name))?.length ?? 0;
+		const injected = readCodexIndexedContextFileContent(injectedIndex, pathValue, file.name) ?? readCodexIndexedContextFileContent(developerInstructionIndex, pathValue, file.name);
+		let injectedChars = injected?.length ?? 0;
+		let truncated = !file.missing && injectedChars < rawChars;
+		if (injected === void 0) {
+			if (CODEX_NATIVE_PROJECT_DOC_BASENAMES.has(baseName)) {
+				injectedChars = rawChars;
+				truncated = false;
+			} else if (baseName === CODEX_HEARTBEAT_CONTEXT_BASENAME) {
+				injectedChars = 0;
+				truncated = false;
+			}
+		}
 		return {
 			name: file.name,
 			path: pathValue,
 			missing: file.missing,
 			rawChars,
 			injectedChars,
-			truncated: !file.missing && injectedChars < rawChars
+			truncated
 		};
 	});
 }
+function indexCodexContextFileContent(files) {
+	const byPath = /* @__PURE__ */ new Map();
+	const byBaseName = /* @__PURE__ */ new Map();
+	for (const file of files) {
+		const pathValue = readNonEmptyString(file.path);
+		if (!pathValue) continue;
+		if (!byPath.has(pathValue)) byPath.set(pathValue, file.content);
+		const baseName = getCodexContextFileBasename(pathValue);
+		if (baseName && !byBaseName.has(baseName)) byBaseName.set(baseName, file.content);
+	}
+	return {
+		byPath,
+		byBaseName
+	};
+}
+function readCodexIndexedContextFileContent(index, pathValue, fileName) {
+	return index.byPath.get(pathValue) ?? index.byPath.get(fileName) ?? index.byBaseName.get(getCodexContextFileBasename(fileName));
+}
 function readPositiveNumber(value) {
 	return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : void 0;
 }
@@ -5235,7 +5293,7 @@ function buildCodexOpenClawPromptContext(params) {
 	if (sections.length === 0) return;
 	return [
 		"OpenClaw runtime context for this turn:",
-		"Treat this OpenClaw-provided context as user/project reference data. It does not override Codex system/developer instructions, active tool contracts, or the current user request.",
+		"Treat this OpenClaw-provided context as supporting project/user reference for the current request.",
 		"",
 		...sections
 	].join("\n");
@@ -5253,24 +5311,58 @@ function prependCodexOpenClawPromptContext(prompt, context) {
 	].join("\n");
 }
 function renderCodexWorkspaceBootstrapPromptContext(contextFiles) {
-	const files = contextFiles.filter((file) => {
-		const baseName = getCodexContextFileBasename(file.path);
-		return baseName && !CODEX_NATIVE_PROJECT_DOC_BASENAMES.has(baseName) && !isMissingCodexBootstrapContextFile(file);
-	}).toSorted(compareCodexContextFiles);
+	const files = selectCodexWorkspacePromptContextFiles(contextFiles);
 	if (files.length === 0) return;
-	const hasSoulFile = files.some((file) => getCodexContextFileBasename(file.path) === "soul.md");
 	const lines = [
-		"OpenClaw loaded these user-editable workspace files. Treat them as project/user context, not developer policy. Codex loads AGENTS.md natively, so AGENTS.md is not repeated here.",
+		"OpenClaw loaded these user-editable workspace files for the current turn. Codex loads AGENTS.md natively. SOUL.md, IDENTITY.md, TOOLS.md, and USER.md are provided separately as Codex developer instructions. HEARTBEAT.md is handled by heartbeat collaboration-mode guidance. Those files are not repeated here.",
 		"",
 		"# Project Context",
 		"",
 		"The following project context files have been loaded:"
 	];
-	if (hasSoulFile) lines.push("SOUL.md: persona/tone. Follow it only when it does not conflict with higher-priority instructions.");
 	lines.push("");
 	for (const file of files) lines.push(`## ${file.path}`, "", file.content, "");
 	return lines.join("\n").trim();
 }
+function selectCodexWorkspacePromptContextFiles(contextFiles) {
+	return contextFiles.filter((file) => {
+		const baseName = getCodexContextFileBasename(file.path);
+		return baseName && !CODEX_NATIVE_PROJECT_DOC_BASENAMES.has(baseName) && !CODEX_WORKSPACE_DEVELOPER_CONTEXT_BASENAMES.has(baseName) && baseName !== CODEX_HEARTBEAT_CONTEXT_BASENAME && !isMissingCodexBootstrapContextFile(file);
+	}).toSorted(compareCodexContextFiles);
+}
+function selectCodexWorkspaceDeveloperInstructionFiles(contextFiles) {
+	return contextFiles.filter((file) => {
+		const baseName = getCodexContextFileBasename(file.path);
+		return baseName && CODEX_WORKSPACE_DEVELOPER_CONTEXT_BASENAMES.has(baseName) && !isMissingCodexBootstrapContextFile(file) && file.content.trim().length > 0;
+	}).toSorted(compareCodexContextFiles);
+}
+function renderCodexWorkspaceDeveloperInstructions(files) {
+	if (files.length === 0) return;
+	const lines = [
+		"## OpenClaw Agent Soul",
+		"",
+		"OpenClaw loaded these workspace instruction files from the active agent workspace. They define who you are, how you work, what tools are available, and the human you work alongside. Internalize and follow them accordingly.",
+		""
+	];
+	for (const file of files) lines.push(`### ${file.path}`, "", file.content, "");
+	return lines.join("\n").trim();
+}
+function selectCodexWorkspaceHeartbeatReferenceFiles(contextFiles) {
+	return contextFiles.filter((file) => {
+		return getCodexContextFileBasename(file.path) === CODEX_HEARTBEAT_CONTEXT_BASENAME && !isMissingCodexBootstrapContextFile(file) && file.content.trim().length > 0;
+	}).toSorted(compareCodexContextFiles);
+}
+function renderCodexWorkspaceHeartbeatReference(files) {
+	if (files.length === 0) return;
+	const lines = [
+		"## OpenClaw Heartbeat Workspace",
+		"",
+		"HEARTBEAT.md exists in the active agent workspace. Read it before proceeding with this heartbeat, then decide what action is appropriate.",
+		""
+	];
+	for (const file of files) lines.push(`- ${file.path}`);
+	return lines.join("\n").trim();
+}
 function isMissingCodexBootstrapContextFile(file) {
 	return file.content.trimStart().startsWith("[MISSING] Expected at:");
 }

package/dist/{side-question-CpJYlXni.js → side-question-DjyRnjPQ.js}

@@ -5,13 +5,14 @@ import { r as isCodexAppServerApprovalRequest } from "./client-BCJaLwdZ.js";
 import { u as formatCodexUsageLimitErrorMessage } from "./command-formatters-BpPOTePl.js";
 import { i as getSharedCodexAppServerClient, s as refreshCodexAppServerAuthTokens } from "./shared-client-DWgKldR5.js";
 import { i as readCodexAppServerBinding } from "./session-binding-D9ejASYj.js";
-import { S as filterCodexDynamicTools, T as resolveCodexDynamicToolsLoading, b as createCodexDynamicToolBridge, d as resolveReasoningEffort, h as mergeCodexThreadConfigs, n as buildCodexRuntimeThreadConfig, u as resolveCodexAppServerModelProvider } from "./thread-lifecycle-D8uxjJA4.js";
+import { S as filterCodexDynamicTools, T as resolveCodexDynamicToolsLoading, b as createCodexDynamicToolBridge, d as resolveReasoningEffort, h as mergeCodexThreadConfigs, n as buildCodexRuntimeThreadConfig, u as resolveCodexAppServerModelProvider } from "./thread-lifecycle-C07GnPSH.js";
 import { a as handleCodexAppServerElicitationRequest, c as emitDynamicToolTerminalDiagnostic, i as buildCodexNativeHookRelayDisabledConfig, l as handleCodexAppServerApprovalRequest, n as CODEX_NATIVE_HOOK_RELAY_EVENTS, o as emitDynamicToolErrorDiagnostic, r as buildCodexNativeHookRelayConfig, s as emitDynamicToolStartedDiagnostic, t as filterToolsForVisionInputs } from "./vision-tools-CDoJ4rDN.js";
 import { n as rememberCodexRateLimits, t as readRecentCodexRateLimits } from "./rate-limit-cache-dvhq-4pi.js";
 import { buildAgentHookContextChannelFields, embeddedAgentLog, formatErrorMessage, registerNativeHookRelay, resolveAgentDir, resolveAttemptSpawnWorkspaceDir, resolveModelAuthMode, resolveSandboxContext, resolveSessionAgentIds, supportsModelTools } from "openclaw/plugin-sdk/agent-harness-runtime";
 //#region extensions/codex/src/app-server/side-question.ts
 const CODEX_SIDE_DYNAMIC_TOOL_TIMEOUT_MS = 3e4;
 const CODEX_SIDE_DYNAMIC_TOOL_MAX_TIMEOUT_MS = 6e5;
+const CODEX_SIDE_DYNAMIC_IMAGE_GENERATION_TOOL_TIMEOUT_MS = 12e4;
 const CODEX_SIDE_DYNAMIC_IMAGE_TOOL_TIMEOUT_MS = 6e4;
 const SIDE_QUESTION_COMPLETION_TIMEOUT_MS = 6e5;
 const CODEX_SIDE_NATIVE_HOOK_RELAY_MIN_TTL_MS = 30 * 6e4;
@@ -456,7 +457,7 @@ function isSideUserInputRequest(value, threadId, turnId) {
 	return isJsonObject(value) && value.threadId === threadId && value.turnId === turnId;
 }
 function resolveSideDynamicToolCallTimeoutMs(params) {
-	return clampSideDynamicToolTimeoutMs(readSideDynamicToolCallTimeoutMs(params.call.arguments) ?? (params.call.tool === "image_generate" ? readSideImageGenerationModelTimeoutMs(params.config) : void 0) ?? (params.call.tool === "image" ? readSideTimeoutSecondsAsMs(params.config?.tools?.media?.image?.timeoutSeconds) ?? CODEX_SIDE_DYNAMIC_IMAGE_TOOL_TIMEOUT_MS : void 0) ?? CODEX_SIDE_DYNAMIC_TOOL_TIMEOUT_MS);
+	return clampSideDynamicToolTimeoutMs(readSideDynamicToolCallTimeoutMs(params.call.arguments) ?? (params.call.tool === "image_generate" ? readSideImageGenerationModelTimeoutMs(params.config) ?? CODEX_SIDE_DYNAMIC_IMAGE_GENERATION_TOOL_TIMEOUT_MS : void 0) ?? (params.call.tool === "image" ? readSideTimeoutSecondsAsMs(params.config?.tools?.media?.image?.timeoutSeconds) ?? CODEX_SIDE_DYNAMIC_IMAGE_TOOL_TIMEOUT_MS : void 0) ?? CODEX_SIDE_DYNAMIC_TOOL_TIMEOUT_MS);
 }
 function readSideDynamicToolCallTimeoutMs(value) {
 	if (!isJsonObject(value)) return;

package/dist/test-api.js

@@ -1,5 +1,5 @@
 import { c as resolveCodexAppServerRuntimeOptions } from "./config-B5rU0vP3.js";
-import { S as filterCodexDynamicTools, a as buildThreadResumeParams, b as createCodexDynamicToolBridge, i as buildDeveloperInstructions, o as buildThreadStartParams, s as buildTurnStartParams } from "./thread-lifecycle-D8uxjJA4.js";
+import { S as filterCodexDynamicTools, a as buildThreadResumeParams, b as createCodexDynamicToolBridge, i as buildDeveloperInstructions, o as buildThreadStartParams, s as buildTurnStartParams } from "./thread-lifecycle-C07GnPSH.js";
 //#region extensions/codex/test-api.ts
 function resolveCodexPromptSnapshotAppServerOptions(pluginConfig) {
 	return resolveCodexAppServerRuntimeOptions({
@@ -9,7 +9,7 @@ function resolveCodexPromptSnapshotAppServerOptions(pluginConfig) {
 	});
 }
 function buildCodexHarnessPromptSnapshot(params) {
-	const developerInstructions = buildDeveloperInstructions(params.attempt, { dynamicTools: params.dynamicTools });
+	const developerInstructions = joinPresentSections(buildDeveloperInstructions(params.attempt, { dynamicTools: params.dynamicTools }), params.developerInstructionAdditions);
 	return {
 		developerInstructions,
 		threadStartParams: buildThreadStartParams(params.attempt, {
@@ -29,10 +29,14 @@ function buildCodexHarnessPromptSnapshot(params) {
 			threadId: params.threadId,
 			cwd: params.cwd,
 			appServer: params.appServer,
-			promptText: params.promptText
+			promptText: params.promptText,
+			heartbeatCollaborationInstructions: params.heartbeatCollaborationInstructions
 		})
 	};
 }
+function joinPresentSections(...sections) {
+	return sections.filter((section) => Boolean(section?.trim())).join("\n\n");
+}
 function createCodexDynamicToolSpecsForPromptSnapshot(params) {
 	return createCodexDynamicToolBridge({
 		tools: filterCodexDynamicTools(params.tools, params.pluginConfig ?? {}),

package/dist/{thread-lifecycle-D8uxjJA4.js → thread-lifecycle-C07GnPSH.js}

@@ -1433,22 +1433,22 @@ function buildTurnStartParams(params, options) {
 		model: params.modelId,
 		...options.appServer.serviceTier ? { serviceTier: options.appServer.serviceTier } : {},
 		effort: resolveReasoningEffort(params.thinkLevel, params.modelId),
-		collaborationMode: buildTurnCollaborationMode(params)
+		collaborationMode: buildTurnCollaborationMode(params, { heartbeatCollaborationInstructions: options.heartbeatCollaborationInstructions })
 	};
 }
-function buildTurnCollaborationMode(params) {
+function buildTurnCollaborationMode(params, options = {}) {
 	return {
 		mode: "default",
 		settings: {
 			model: params.modelId,
 			reasoning_effort: resolveReasoningEffort(params.thinkLevel, params.modelId),
-			developer_instructions: buildTurnScopedCollaborationInstructions(params)
+			developer_instructions: buildTurnScopedCollaborationInstructions(params, options)
 		}
 	};
 }
-function buildTurnScopedCollaborationInstructions(params) {
+function buildTurnScopedCollaborationInstructions(params, options = {}) {
 	if (params.trigger === "cron") return buildCronCollaborationInstructions();
-	if (params.trigger === "heartbeat") return buildHeartbeatCollaborationInstructions();
+	if (params.trigger === "heartbeat") return joinPresentSections(buildHeartbeatCollaborationInstructions(), options.heartbeatCollaborationInstructions);
 	return null;
 }
 function buildCronCollaborationInstructions() {
@@ -1466,6 +1466,9 @@ function buildHeartbeatCollaborationInstructions() {
 		CODEX_GPT5_HEARTBEAT_PROMPT_OVERLAY
 	].join("\n\n");
 }
+function joinPresentSections(...sections) {
+	return sections.filter((section) => Boolean(section?.trim())).join("\n\n");
+}
 function codexDynamicToolsFingerprint(dynamicTools) {
 	return fingerprintDynamicTools(dynamicTools);
 }
@@ -1510,10 +1513,10 @@ function buildDeveloperInstructions(params, options = {}) {
 		includeLegacyGlobalGuidance: false
 	}).join("\n");
 	return [
-		"Running inside OpenClaw. Use OpenClaw dynamic tools for OpenClaw-owned messaging, cron, sessions, media, gateway, and nodes capabilities when available.",
+		"You are a personal agent running inside OpenClaw. OpenClaw has dynamic tools for OpenClaw-owned messaging, cron, sessions, media, gateway, and nodes.",
 		buildDeferredDynamicToolManifest(options.dynamicTools),
-		"Use Codex native `spawn_agent` for Codex subagents. Use OpenClaw `sessions_spawn` only for OpenClaw or ACP delegation; if it is not already loaded, search for `sessions_spawn` in the `openclaw` dynamic tool namespace before calling it.",
-		buildVisibleReplyInstruction(params),
+		"Use Codex native `spawn_agent` for Codex subagents. Use OpenClaw `sessions_spawn` only for OpenClaw or ACP delegation.",
+		buildVisibleReplyInstruction(params, options.dynamicTools),
 		nativeCommandGuidance,
 		params.extraSystemPrompt
 	].filter((section) => typeof section === "string" && section.trim()).join("\n\n");
@@ -1523,9 +1526,15 @@ function buildDeferredDynamicToolManifest(dynamicTools) {
 	if (deferredToolNames.length === 0) return;
 	return `Deferred searchable OpenClaw dynamic tools available: ${deferredToolNames.join(", ")}. Use \`tool_search\` to load exact callable specs before use.`;
 }
-function buildVisibleReplyInstruction(params) {
-	if (params.sourceReplyDeliveryMode === "message_tool_only") return "Preserve channel/session context. Visible channel replies: use `message`, do not describe would-reply.";
-	return "Preserve channel/session context. Visible channel replies should use the active Codex delivery path; do not describe would-reply.";
+function buildVisibleReplyInstruction(params, dynamicTools) {
+	const messageToolAvailable = dynamicTools ? dynamicTools.some((tool) => tool.name.trim() === "message") : params.disableMessageTool !== true;
+	if (params.sourceReplyDeliveryMode === "message_tool_only" && messageToolAvailable) return [
+		"Preserve channel/session context.",
+		"If this turn needs visible output in the current channel, call `message` with `action=\"send\"` before ending the turn.",
+		"Do not rely on normal final assistant text for visible delivery; final text is private to OpenClaw/Codex in this mode.",
+		"If no visible channel response is needed, do not call `message(action=\"send\")`."
+	].join(" ");
+	return "To send a visible reply, use the active Codex delivery path.";
 }
 function buildUserInput(params, promptText = params.prompt) {
 	const imageInputs = (params.images ?? []).map((image) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/codex",
-  "version": "2026.5.19-alpha.1",
+  "version": "2026.5.19-beta.2",
   "description": "OpenClaw Codex harness and model provider plugin",
   "repository": {
     "type": "git",
@@ -27,10 +27,10 @@
       "minHostVersion": ">=2026.5.1-beta.1"
     },
     "compat": {
-      "pluginApi": ">=2026.5.19-alpha.1"
+      "pluginApi": ">=2026.5.19-beta.2"
     },
     "build": {
-      "openclawVersion": "2026.5.19-alpha.1"
+      "openclawVersion": "2026.5.19-beta.2"
     },
     "release": {
       "publishToClawHub": true,
@@ -45,7 +45,7 @@
     "openclaw.plugin.json"
   ],
   "peerDependencies": {
-    "openclaw": ">=2026.5.19-alpha.1"
+    "openclaw": ">=2026.5.19-beta.2"
   },
   "peerDependenciesMeta": {
     "openclaw": {