@iislee/opencodex 2.11.0 → 2.35.0

package/src/adapters/cursor.ts

@@ -3,19 +3,42 @@ import type { AdapterEvent, OcxProviderConfig } from "../types";
 import type { ProviderAdapter } from "./base";
 import { isTranslatorBudgetExceededError } from "../lib/translator-budget";
 import { cursorExecDeniedMessage, cursorRequestDeclaresFullAccess } from "./cursor/exec-policy";
-import { isCursorBenignCancelError, isCursorInvalidArgumentError, safeCursorErrorMessage } from "./cursor/cursor-errors";
-import { isCursorExternalWireModel } from "./cursor/discovery";
+import { isCursorBenignCancelError, isCursorInvalidArgumentError, safeCursorErrorMessage, type CursorSizeContext } from "./cursor/cursor-errors";
+import { cursorCheckpointModelAffinityId, inferCursorContextWindow, isCursorExternalWireModel } from "./cursor/discovery";
 import { createCursorKvStore, type CursorKvStore } from "./cursor/kv-store";
 import { mapCursorServerMessage } from "./cursor/message-mapper";
-import { createCursorRequest } from "./cursor/request-builder";
+import {
+  createCursorRequest,
+  cursorClientThreadOwner,
+  cursorCoveredPrefixDigest,
+  cursorInstructionDigest,
+} from "./cursor/request-builder";
 import {
   createLiveCursorTransport,
   CursorMissingCredentialError,
   rekeyCursorContextUsage,
   resolveCursorToken,
+  capturedCursorCheckpointBytes,
 } from "./cursor/live-transport";
+import {
+  commitCursorCheckpoint,
+  cursorCheckpointRefHash,
+  invalidateCursorCheckpoint,
+} from "./cursor/checkpoint-store";
+import { debugProviderDiagnostic } from "../lib/debug";
+import { estimateTokens } from "../lib/token-estimate";
 import { rememberCursorThreadConversation } from "./cursor/thread-continuity";
 import { runCursorTurnWithRetry } from "./cursor/transport-retry";
+import { cursorRequestHasShellAlias, cursorRequestUsesCodeMode } from "./cursor/tool-definitions";
+import {
+  CURSOR_ECHO_RETRY_CONTINUATION_TEXT,
+  CURSOR_ROUTING_COMMENTARY_RETRY_TEXT,
+  CursorEnvelopeEchoSniffer,
+  CursorMidstreamEchoObserver,
+  CursorRoutingCommentaryError,
+  CursorRoutingCommentarySniffer,
+  CursorToolResultEchoError,
+} from "./cursor/envelope-echo";
 import {
   createDisabledCursorTransport,
   CursorTransportDisabledError,
@@ -42,16 +65,29 @@ export interface CursorAdapterDeps {
   rekeyContextUsage?: (fromConversationId: string, toConversationId: string) => void;
 }
 
-function safeCursorTransportError(err: unknown): string {
+function safeCursorTransportError(err: unknown, sizeContext?: CursorSizeContext): string {
   if (err instanceof CursorTransportDisabledError) return CURSOR_TRANSPORT_DISABLED_MESSAGE;
   if (err instanceof CursorMissingCredentialError) {
     return "Cursor live transport is enabled, but no Cursor access token is configured. Set provider.apiKey or OPENCODEX_CURSOR_TEST_TOKEN.";
   }
   const message = err instanceof Error ? err.message : typeof err === "string" ? err : undefined;
-  if (message) return safeCursorErrorMessage(message);
+  if (message) return safeCursorErrorMessage(message, sizeContext);
   return "Cursor upstream error: transport failed before completion.";
 }
 
+/**
+ * Size prior for bare resource_exhausted classification (devlog 260): a rough input
+ * estimate over the outgoing text vs the model's context window. Only used to keep
+ * SMALL requests on the 429 class — unknown/large stays on the overflow mapping.
+ */
+function cursorRequestSizeContext(request: { modelId: string; system: string[]; messages: { content: string }[] }): CursorSizeContext {
+  const text = [...request.system, ...request.messages.map(message => message.content)].join("\n");
+  return {
+    estimatedInputTokens: estimateTokens(text, request.modelId),
+    contextWindow: inferCursorContextWindow(request.modelId),
+  };
+}
+
 export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAdapterDeps = {}): ProviderAdapter {
   return {
     name: "cursor",
@@ -77,6 +113,9 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
         emit({ type: "error", message: "Cursor turn was aborted before start." });
         return;
       }
+      // Captured after createCursorRequest so the catch block can apply the bare-RE
+      // size prior (devlog 260) even though `request` is scoped inside the try.
+      let requestSizeContext: CursorSizeContext | undefined;
       try {
         const makeTransport = deps.createTransport ?? createLiveCursorTransport;
         const kv = deps.kv ?? createCursorKvStore({}, incoming.translatorBudget);
@@ -96,8 +135,10 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
             /* Missing credential is handled by the live transport path below. */
           }
         }
+        const inheritedCheckpointRef = _parsed._providerContinuation?.cursor?.checkpointRef;
         const previousConversationId = _parsed._cursorConversationId;
         let request = createCursorRequest(_parsed);
+        requestSizeContext = cursorRequestSizeContext(request);
         // The builder may derive a stable provider id from the client thread when Responses state
         // is unavailable. Rekey only existing state; there is nothing to migrate on a fresh turn,
         // and isolated helper/compaction turns must never inherit or donate the parent's usage state.
@@ -112,8 +153,115 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
         let emittedOutput = false;
         let replayUnsafe = false;
         const lastRawIsToolResult = _parsed.context.messages.at(-1)?.role === "toolResult";
+        let completedNormally = false;
+        let lastTransport: { captured?: Uint8Array } | undefined;
+        let emittedClientTool = false;
+        // Ordering proof for tool-suspended checkpoints: true only when the newest captured
+        // checkpoint bytes arrived AFTER the turn emitted a client tool call, i.e. upstream
+        // serialized its suspended-on-tool-call state. Only that snapshot can safely resume
+        // with the covered-prefix + trailing-toolResult path (devlog 260826 050).
+        let capturedAfterClientTool = false;
+
+        const commitCapturedCheckpoint = (activeRequest: ReturnType<typeof createCursorRequest>): void => {
+          const toolSuspendedCommit =
+            emittedClientTool
+            && capturedAfterClientTool
+            && isCursorExternalWireModel(activeRequest.modelId);
+          if (
+            replayUnsafe
+            || (emittedClientTool && !toolSuspendedCommit)
+            || activeRequest.contextUsageStoreCheckpoints === false
+            || !lastTransport?.captured
+            || lastTransport.captured.byteLength === 0
+          ) {
+            // Refusal diagnostics (devlog 260826 050/080): name the exact guard so a live
+            // missing_ref chain can be attributed without instrumented rebuilds.
+            debugProviderDiagnostic("cursor", "checkpoint-commit-refused", {
+              replayUnsafe,
+              emittedClientTool,
+              capturedAfterClientTool,
+              externalModel: isCursorExternalWireModel(activeRequest.modelId),
+              storeCheckpoints: activeRequest.contextUsageStoreCheckpoints !== false,
+              capturedBytes: lastTransport?.captured?.byteLength ?? 0,
+            });
+            return;
+          }
+          const previousRef = _parsed._providerContinuation?.cursor?.checkpointRef;
+          const coveredMessageCount = _parsed.context.messages.length;
+          const checkpointRef = commitCursorCheckpoint({
+            conversationId: activeRequest.conversationId,
+            identityScope: _parsed._cursorIdentityScope,
+            modelId: cursorCheckpointModelAffinityId(activeRequest.modelId),
+            checkpointBytes: lastTransport.captured,
+            coveredMessageCount,
+            prefixDigest: cursorCoveredPrefixDigest(_parsed, coveredMessageCount),
+            systemDigest: cursorInstructionDigest(_parsed),
+          });
+          if (!checkpointRef) return;
+          if (previousRef && previousRef !== checkpointRef) invalidateCursorCheckpoint(previousRef);
+          _parsed._providerContinuation = {
+            ...(_parsed._providerContinuation ?? {}),
+            cursor: {
+              ...(_parsed._providerContinuation?.cursor ?? {}),
+              conversationId: activeRequest.conversationId,
+              // A tool-suspended checkpoint is only usable by the immediate trailing-toolResult
+              // continuation; the request-builder guard keys on checkpointUsable=false for that.
+              checkpointUsable: !toolSuspendedCommit,
+              checkpointRef,
+            },
+          };
+          debugProviderDiagnostic("cursor", "checkpoint-continuation", {
+            mode: activeRequest.continuationMode ?? "full-replay",
+            conversationHash: activeRequest.conversationId.slice(0, 16),
+            checkpointRefHash: cursorCheckpointRefHash(checkpointRef),
+            checkpointBytes: lastTransport.captured.byteLength,
+            wireModel: activeRequest.modelId,
+            ...(toolSuspendedCommit ? { toolSuspended: true } : {}),
+          });
+        };
 
         const runOnce = async (activeRequest: ReturnType<typeof createCursorRequest>) => {
+          // Envelope echo quarantine (devlog 260826 gap-10): external full-replay continuations
+          // whose trailing input is a tool result sometimes ECHO the replayed "[Tool Result]"
+          // envelope as assistant text (kimi-k3 ~30-40% of multi-round probes). Hold the first
+          // text deltas until they provably diverge from the markers; a completed marker turns
+          // the turn into a retryable semantic failure BEFORE any client-visible delta escapes.
+          // Armed for ANY external turn whose replayed history contains a tool result — echo
+          // priming was observed live on user-action rounds too (the envelope lives in the
+          // flattened history regardless of which role ends the input).
+          const armEchoSniffer =
+            isCursorExternalWireModel(activeRequest.modelId)
+            && (_parsed.context.messages ?? []).some(message => message.role === "toolResult");
+          const echoSniffer = armEchoSniffer ? new CursorEnvelopeEchoSniffer() : undefined;
+          // Mid-stream observer (devlog 260828 F1/F2): diagnostic-only; armed with the
+          // prefix sniffer because both fire on flattened tool-result replay priming.
+          const midstreamObserver = armEchoSniffer ? new CursorMidstreamEchoObserver() : undefined;
+          const armRoutingCommentarySniffer =
+            isCursorExternalWireModel(activeRequest.modelId)
+            && (
+              cursorRequestUsesCodeMode(activeRequest.tools, activeRequest.toolChoice)
+              || cursorRequestHasShellAlias(activeRequest.tools)
+            );
+          const routingCommentarySniffer = armRoutingCommentarySniffer
+            ? new CursorRoutingCommentarySniffer()
+            : undefined;
+          let guardHeld: AdapterEvent[] = [];
+          // Exactly-once observation: every client-bound text delta passes through here
+          // exactly once — held deltas only on release, ordinary deltas at emit time.
+          const emitTextObserved = (event: AdapterEvent): void => {
+            if (event.type === "text_delta") midstreamObserver?.feed(event.text);
+            emit(event);
+          };
+          const releaseGuardHeld = () => {
+            for (const held of guardHeld) {
+              if (held.type !== "heartbeat") emittedOutput = true;
+              emitTextObserved(held);
+            }
+            guardHeld = [];
+          };
+          const guardsSettled = () =>
+            (!echoSniffer || echoSniffer.settled)
+            && (!routingCommentarySniffer || routingCommentarySniffer.settled);
           await runCursorTurnWithRetry(
             makeTransport,
             {
@@ -121,6 +269,8 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
               headers: incoming.headers,
               translatorBudget: incoming.translatorBudget,
               requestDeclaresFullAccess: cursorRequestDeclaresFullAccess(activeRequest),
+              sessionId: activeRequest.conversationId,
+              ...(incoming.providerFetch ? { fetch: incoming.providerFetch } : {}),
             },
             activeRequest,
             incoming.abortSignal,
@@ -130,15 +280,89 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
                 return;
               }
               if (message.type === "local_side_effect") replayUnsafe = true;
-              const events = mapCursorServerMessage(message, {
-                kv,
-                writeClient: clientMessage => {
-                  void activeTransport.writeClient(clientMessage);
-                },
-              });
-              for (const event of events) {
+              if (message.type === "done") completedNormally = true;
+              if (message.type === "tool_call_end") emittedClientTool = true;
+              const captured = capturedCursorCheckpointBytes(activeTransport);
+              if (captured) {
+                if (captured !== lastTransport?.captured) capturedAfterClientTool = emittedClientTool;
+                lastTransport = { captured };
+              }
+             const events = mapCursorServerMessage(message, {
+               kv,
+               writeClient: clientMessage => {
+                 void activeTransport.writeClient(clientMessage);
+               },
+             });
+             for (const event of events) {
+                if (!guardsSettled()) {
+                  if (event.type === "text_delta") {
+                    guardHeld.push(event);
+                    if (echoSniffer && !echoSniffer.settled) {
+                      const decision = echoSniffer.feed(event.text);
+                      if (decision.kind === "echo") {
+                        guardHeld = [];
+                        throw new CursorToolResultEchoError(decision.marker);
+                      }
+                    }
+                    if (routingCommentarySniffer && !routingCommentarySniffer.settled) {
+                      const decision = routingCommentarySniffer.feed(event.text);
+                      if (decision.kind === "hallucination") {
+                        guardHeld = [];
+                        throw new CursorRoutingCommentaryError();
+                      }
+                    }
+                    if (guardsSettled()) releaseGuardHeld();
+                    continue;
+                  } else if (event.type === "thinking_delta" || event.type === "heartbeat") {
+                    // Reasoning before first text stays ordered; liveness still passes through.
+                    if (event.type === "thinking_delta") {
+                      guardHeld.push(event);
+                      continue;
+                    }
+                  } else {
+                    // A tool call, done, or error closes the text quarantine. Re-check the full
+                    // held first line before release so a fragmented routing claim cannot leak.
+                    echoSniffer?.finish();
+                    const routingDecision = routingCommentarySniffer?.finish();
+                    if (routingDecision?.kind === "hallucination") {
+                      guardHeld = [];
+                      throw new CursorRoutingCommentaryError();
+                    }
+                    releaseGuardHeld();
+                  }
+                }
                 if (event.type !== "heartbeat") emittedOutput = true;
-                emit(event);
+                if (event.type === "done") {
+                  for (const finding of midstreamObserver?.findings() ?? []) {
+                    debugProviderDiagnostic("cursor", "midstream-envelope-echo", {
+                      wireModel: activeRequest.modelId,
+                      conversationHash: activeRequest.conversationId.slice(0, 16),
+                      marker: finding.marker,
+                      offset: finding.offset,
+                      callIdCorrupt: finding.callIdCorrupt,
+                    });
+                  }
+                  commitCapturedCheckpoint(activeRequest);
+                  const inheritedCursor = _parsed._providerContinuation?.cursor;
+                  const isolatedOrCompaction =
+                    _parsed._cursorIsolateConversation === true
+                    || activeRequest.contextUsageStoreCheckpoints === false;
+                  const providerState = inheritedCursor
+                    ? {
+                        cursor: isolatedOrCompaction
+                          ? {
+                              conversationId: activeRequest.conversationId,
+                              ...(inheritedCursor.checkpointUsable !== undefined
+                                ? { checkpointUsable: inheritedCursor.checkpointUsable }
+                                : {}),
+                            }
+                          : { ...inheritedCursor, conversationId: activeRequest.conversationId },
+                      }
+                    : undefined;
+                  emit(providerState ? { ...event, providerState } : event);
+                } else {
+                  emitTextObserved(event);
+                }
               }
             },
           );
@@ -147,35 +371,108 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
         try {
           await runOnce(request);
         } catch (err) {
-          // One-shot fallback for external-model Connect invalid_argument before any
-          // non-heartbeat output. Retries apply only to safe plain-user turns; tool-result
-          // resumes, local exec/MCP side effects, and already-emitted output fail closed.
+          const outputGuardRetryText =
+            err instanceof CursorToolResultEchoError
+              ? CURSOR_ECHO_RETRY_CONTINUATION_TEXT
+              : err instanceof CursorRoutingCommentaryError
+                ? CURSOR_ROUTING_COMMENTARY_RETRY_TEXT
+                : undefined;
+          // One-shot corrective retry for guarded external output (devlog 260826 gap-10/11).
+          // The quarantine guarantees no client-visible delta escaped, so a fresh-conversation
+          // retry is safe. A second rejection propagates as an error rather than looping.
           if (
-            !isCursorInvalidArgumentError(err)
-            || !isCursorExternalWireModel(request.modelId)
-            || lastRawIsToolResult
-            || emittedOutput
-            || replayUnsafe
-            || incoming.abortSignal?.aborted
+            outputGuardRetryText
+            && !emittedOutput
+            && !replayUnsafe
+            && !incoming.abortSignal?.aborted
           ) {
-            throw err;
-          }
-          const failedConversationId = request.conversationId;
-          _parsed._cursorConversationId = undefined;
-          request = createCursorRequest(_parsed, { forceFreshConversation: true });
-          rekeyContextUsage(failedConversationId, request.conversationId);
-          _parsed._cursorConversationId = request.conversationId;
-          // Persist recovery for store:false clients that only send a parent thread id, so the
-          // next turn does not recompute the stale deterministic thread hash. Isolated helper /
-          // compaction turns must not park their throwaway id under the parent thread key.
-          if (_parsed._clientThreadId && _parsed._cursorIsolateConversation !== true) {
-            rememberCursorThreadConversation(
-              _parsed._clientThreadId,
-              request.conversationId,
-              _parsed._cursorIdentityScope,
+            debugProviderDiagnostic(
+              "cursor",
+              err instanceof CursorToolResultEchoError
+                ? "envelope-echo-retry"
+                : "routing-commentary-retry",
+              {
+              wireModel: request.modelId,
+              conversationHash: request.conversationId.slice(0, 16),
+              },
             );
+            const echoedConversationId = request.conversationId;
+            lastTransport = undefined;
+            _parsed._cursorConversationId = undefined;
+            request = {
+              ...createCursorRequest(_parsed, { forceFreshConversation: true }),
+              echoRetryContinuationText: outputGuardRetryText,
+            };
+            rekeyContextUsage(echoedConversationId, request.conversationId);
+            _parsed._cursorConversationId = request.conversationId;
+            const echoThreadOwner = cursorClientThreadOwner(_parsed);
+            if (echoThreadOwner && _parsed._cursorIsolateConversation !== true) {
+              rememberCursorThreadConversation(
+                echoThreadOwner,
+                request.conversationId,
+                _parsed._cursorIdentityScope,
+              );
+            }
+            await runOnce(request);
+          } else {
+            // One-shot fallback for external-model Connect invalid_argument before any
+            // non-heartbeat output. Retries apply only to safe plain-user turns; tool-result
+            // resumes, local exec/MCP side effects, and already-emitted output fail closed.
+            if (
+              !isCursorInvalidArgumentError(err)
+              || !isCursorExternalWireModel(request.modelId)
+              || lastRawIsToolResult
+              || emittedOutput
+              || replayUnsafe
+              || incoming.abortSignal?.aborted
+            ) {
+              throw err;
+            }
+            const failedConversationId = request.conversationId;
+            lastTransport = undefined;
+            _parsed._cursorConversationId = undefined;
+            request = createCursorRequest(_parsed, { forceFreshConversation: true });
+            rekeyContextUsage(failedConversationId, request.conversationId);
+            _parsed._cursorConversationId = request.conversationId;
+            // Persist recovery for store:false clients that send any stable Cursor thread owner, so
+            // the next turn does not recompute the stale deterministic thread hash. Isolated helper /
+            // compaction turns must not park their throwaway id under the parent or Desktop owner.
+            const threadOwner = cursorClientThreadOwner(_parsed);
+            if (threadOwner && _parsed._cursorIsolateConversation !== true) {
+              rememberCursorThreadConversation(
+                threadOwner,
+                request.conversationId,
+                _parsed._cursorIdentityScope,
+              );
+            }
+            await runOnce(request);
+          }
+        }
+        if (
+          request.checkpointInvalidationReason
+          && request.checkpointInvalidationReason !== "missing_ref"
+        ) {
+          invalidateCursorCheckpoint(inheritedCheckpointRef);
+          debugProviderDiagnostic("cursor", "checkpoint-invalidated", {
+            reason: request.checkpointInvalidationReason,
+          });
+        } else if (!completedNormally && request.checkpointInvalidationReason) {
+          debugProviderDiagnostic("cursor", "checkpoint-invalidated", {
+            reason: request.checkpointInvalidationReason,
+          });
+        }
+        if (
+          _parsed._cursorIsolateConversation === true
+          || request.contextUsageStoreCheckpoints === false
+        ) {
+          const inherited = _parsed._providerContinuation?.cursor;
+          if (inherited) {
+            const { checkpointRef: _ignoredCheckpointRef, ...cursorWithoutCheckpointRef } = inherited;
+            _parsed._providerContinuation = {
+              ...(_parsed._providerContinuation ?? {}),
+              cursor: cursorWithoutCheckpointRef,
+            };
           }
-          await runOnce(request);
         }
       } catch (err) {
         if (isCursorBenignCancelError(err)) return;
@@ -184,7 +481,7 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
           type: "error",
           message: isTranslatorBudgetExceededError(err)
             ? "upstream translation buffer exceeded the safe limit"
-            : safeCursorTransportError(err),
+            : safeCursorTransportError(err, requestSizeContext),
           ...(isTranslatorBudgetExceededError(err)
             ? { status: 502, errorType: "upstream_error", code: "translation_buffer_limit" }
             : {}),

package/src/adapters/exec-tool-result-normalize.ts

@@ -0,0 +1,99 @@
+/**
+ * Provider-neutral empty-exec-output normalization.
+ *
+ * A code-mode `exec` cell that never calls `text()`/`notify()` returns nothing: the last
+ * expression value is NOT echoed automatically. The routed model reads a blank tool result,
+ * concludes its earlier output was lost, and burns turns re-running the same call or restarting
+ * the task from scratch. Naming that state explicitly is what breaks the loop.
+ *
+ * This module owns the shared detection so every adapter reports the same thing. Cursor keeps its
+ * own wrapper (`normalizeCursorToolResultText`) for Computer Use precedence and isError policy;
+ * Kiro consumes this helper directly.
+ */
+
+/**
+ * Matches exec wrappers whose only payload is an empty-output marker.
+ *
+ * `Script failed` is deliberately NOT in this set. A failed cell with no captured output is still
+ * a FAILURE, and the success guidance below ("not a blocked tool", "do not re-run") would erase the
+ * only signal that anything went wrong — reachable through Responses history, where
+ * `function_call_output` is parsed with `isError: false`. Cursor keeps its own broader regex for
+ * Computer Use, where a failed wrapper is separately marked `isError`.
+ */
+export const EMPTY_EXEC_OUTPUT_REGEX = /^(?:(?:Script completed|Command finished|Execution finished)[^\n]*\n+)?(?:Wall time[^\n]*\n+)?(?:Output:\s*)?(?:<empty>)?\s*$/;
+
+/** Wrapper for a cell that FAILED without emitting output: empty, but not a success. */
+export const FAILED_EXEC_OUTPUT_REGEX = /^Script failed[^\n]*\n*(?:Wall time[^\n]*\n*)?(?:Output:\s*)?(?:<empty>)?\s*$/;
+
+/** Guidance for a failed cell whose output was empty: the failure must survive normalization. */
+export const FAILED_EXEC_OUTPUT_MESSAGE =
+  "[exec failed with no captured output: the cell raised before emitting anything. This is a real failure, not an empty success — inspect the call for a thrown error or syntax problem before retrying.]";
+
+/**
+ * The guidance itself. Worded to close all three wrong conclusions a model draws from a blank
+ * result: that context was lost, that the tool is blocked, and that retrying will differ.
+ */
+export const EMPTY_EXEC_OUTPUT_MESSAGE =
+  "[empty output: the exec cell completed but emitted nothing. This is NOT lost context and NOT a blocked tool — in code mode call text(...) or notify(...) on any value you need to see (a bare await tools.exec_command(...) is not echoed automatically); in shell mode the command simply printed nothing. Do not re-run the same call expecting different output.]";
+
+/**
+ * The SAME rule stated BEFORE the first call, for the code-mode tool-catalog nudge.
+ *
+ * `EMPTY_EXEC_OUTPUT_MESSAGE` above is a repair: it fires only after a model has already spent a
+ * call and read a blank result. That recovers the turn but cannot prevent the wasted round trip,
+ * and the model still has to guess whether its command failed or its output was merely dropped.
+ * Stating the echo rule up front removes the failure instead of explaining it afterwards.
+ *
+ * Kept beside the recovery text on purpose: the two are one pair guarding one defect, and wording
+ * that drifts apart is how a model gets told two different things about the same isolate.
+ */
+export const CODE_MODE_RESULT_ECHO_SENTENCE =
+  "Nothing in the isolate is echoed automatically: a bare trailing `await tools.<name>(...)` or final expression value is DISCARDED, and the cell reports empty output. Pass anything you need to read to `text(...)` (or `notify(...)`) in the same cell — for example `text(JSON.stringify(await tools.exec_command({cmd: \"ls\"})))` — and treat an empty result as your own missing `text(...)` call rather than a failed command or lost context.";
+
+/**
+ * Codex exec / shell-bridge tool names (flat and MCP-prefixed display aliases). An empty result
+ * here is almost always a code-mode cell that never called text()/notify().
+ */
+export function isCodexExecBridgeTool(toolName?: string, toolNamespace?: string): boolean {
+  if (toolNamespace && toolNamespace.includes("opencodex-responses")) return true;
+  if (!toolName) return false;
+  const lower = toolName.toLowerCase();
+  return (
+    lower === "exec"
+    || lower === "exec_command"
+    || lower === "shell_command"
+    // Codex CLI/desktop native tool names: the multi-round "이전 출력이 비어 있어 처음부터"
+    // restart loop reproduced via codex exec because `shell` was not in this set
+    // (devlog 260826 gap-8 QA round 2).
+    || lower === "shell"
+    || lower === "local_shell"
+    || lower === "container.exec"
+    || lower.startsWith("mcp_opencodex-responses_")
+    || lower.startsWith("mcp__opencodex-responses__")
+  );
+}
+
+/** True when this result is an exec-bridge call that produced no usable output. */
+export function isEmptyExecToolResult(
+  text: string,
+  options: { toolName?: string; toolNamespace?: string } = {},
+): boolean {
+  return isCodexExecBridgeTool(options.toolName, options.toolNamespace)
+    && EMPTY_EXEC_OUTPUT_REGEX.test(text.trim());
+}
+
+/**
+ * Returns the guidance text when this is an empty exec-bridge result, else `undefined` so the
+ * caller keeps its own fallback. Undefined rather than the original text: an adapter must be able
+ * to tell "not my case" from "normalized to the same string".
+ */
+export function normalizeEmptyExecToolResultText(
+  text: string,
+  options: { toolName?: string; toolNamespace?: string } = {},
+): string | undefined {
+  if (!isCodexExecBridgeTool(options.toolName, options.toolNamespace)) return undefined;
+  const trimmed = text.trim();
+  // Failure first: a failed wrapper must never be described as an empty success.
+  if (FAILED_EXEC_OUTPUT_REGEX.test(trimmed)) return FAILED_EXEC_OUTPUT_MESSAGE;
+  return EMPTY_EXEC_OUTPUT_REGEX.test(trimmed) ? EMPTY_EXEC_OUTPUT_MESSAGE : undefined;
+}