@iislee/opencodex 2.31.0 → 2.35.0

package/src/adapters/cursor.ts

@@ -9,6 +9,7 @@ import { createCursorKvStore, type CursorKvStore } from "./cursor/kv-store";
 import { mapCursorServerMessage } from "./cursor/message-mapper";
 import {
   createCursorRequest,
+  cursorClientThreadOwner,
   cursorCoveredPrefixDigest,
   cursorInstructionDigest,
 } from "./cursor/request-builder";
@@ -28,6 +29,16 @@ 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,
@@ -145,15 +156,36 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
         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
+            || (emittedClientTool && !toolSuspendedCommit)
             || activeRequest.contextUsageStoreCheckpoints === false
             || !lastTransport?.captured
             || lastTransport.captured.byteLength === 0
-          ) return;
+          ) {
+            // 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({
@@ -172,7 +204,9 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
             cursor: {
               ...(_parsed._providerContinuation?.cursor ?? {}),
               conversationId: activeRequest.conversationId,
-              checkpointUsable: true,
+              // 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,
             },
           };
@@ -182,10 +216,52 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
             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,
             {
@@ -207,16 +283,65 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
               if (message.type === "done") completedNormally = true;
               if (message.type === "tool_call_end") emittedClientTool = true;
               const captured = capturedCursorCheckpointBytes(activeTransport);
-              if (captured) lastTransport = { captured };
-              const events = mapCursorServerMessage(message, {
-                kv,
-                writeClient: clientMessage => {
-                  void activeTransport.writeClient(clientMessage);
-                },
-              });
-              for (const event of events) {
+              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;
                 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 =
@@ -236,7 +361,7 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
                     : undefined;
                   emit(providerState ? { ...event, providerState } : event);
                 } else {
-                  emit(event);
+                  emitTextObserved(event);
                 }
               }
             },
@@ -246,36 +371,82 @@ 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;
-          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 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);
           }
-          await runOnce(request);
         }
         if (
           request.checkpointInvalidationReason

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;
+}