codex-overleaf-link 2.4.1 → 2.5.1

package/extension/src/content/runQueueScheduler.js

@@ -171,6 +171,25 @@
 
   function createCoordinator(options = {}) {
     let view = null;
+    const guidanceAttempts = new Map();
+    const guidanceKey = (sessionId, itemId) => JSON.stringify([sessionId, itemId]);
+    const matchesGuidanceItem = (item, identity) => item?.id === identity.itemId
+      && item.createdAt === identity.itemCreatedAt && item.text === identity.text
+      && item.clientUserMessageId === identity.clientUserMessageId;
+    const matchesGuidanceScope = expected => {
+      const scope = options.getGuideScope?.();
+      return !expected || ['projectId', 'accountScopeId', 'generation'].every(key => scope?.[key] === expected[key]);
+    };
+    const guideErrorKeys = {
+      codex_turn_not_ready: 'queuedInputGuideNotReady',
+      codex_turn_mismatch: 'queuedInputGuideTurnChanged',
+      codex_steer_empty: 'queuedInputGuideEmpty',
+      codex_steer_too_large: 'queuedInputGuideTooLarge'
+    };
+    function formatGuideError(error) {
+      const key = guideErrorKeys[error?.code];
+      return (key && options.tr?.(key)) || error?.message || options.tr?.('queuedInputGuideFailed');
+    }
     const scheduler = create({
       getQueue: sessionId => options.getSession?.(sessionId)?.pendingInputs || [],
       setQueue: (sessionId, pendingInputs) => options.setQueue?.(sessionId, pendingInputs),
@@ -226,62 +245,143 @@
       const item = (session?.pendingInputs || []).find(entry => entry.id === itemId);
       const run = options.getCurrentRun?.();
       const binding = run?.activeTurn;
-      if (!session || !item || !run || run.sessionId !== session.id || !binding?.threadId || !binding?.turnId) {
+      const initialScope = options.getGuideScope?.();
+      const guideScope = initialScope ? { ...initialScope } : null;
+      if (!session || !item || item.status !== 'queued' || !run || run.sessionId !== session.id || !binding?.threadId || !binding?.turnId) {
         options.toast?.(options.tr?.('queuedInputGuideUnavailable'), 'warning');
         return;
       }
+      const identity = { requestId: run.nativeRequestId, threadId: binding.threadId, turnId: binding.turnId,
+        projectKey: run.runProjectId, recordId: run.recordId, sessionId: session.id, sessionCreatedAt: session.createdAt,
+        itemId, itemCreatedAt: item.createdAt, text: item.text, clientUserMessageId: item.clientUserMessageId };
+      const attemptKey = guidanceKey(identity.sessionId, itemId);
+      const attempt = { identity, scope: guideScope, previewToken: null };
+      const sameScope = () => matchesGuidanceScope(guideScope);
+      const ownedSession = () => {
+        const latest = options.getSession?.(identity.sessionId);
+        return sameScope() && latest?.createdAt === identity.sessionCreatedAt ? latest : null;
+      };
+      const ownedItemSession = (allowPaused = false) => {
+        const latest = ownedSession();
+        const current = latest?.pendingInputs?.find(entry => entry.id === itemId);
+        return guidanceAttempts.get(attemptKey) === attempt
+          && (current?.status === 'steering' || (allowPaused && current?.status === 'paused'))
+          && matchesGuidanceItem(current, identity) ? latest : null;
+      };
+      function clearPreview() {
+        const token = attempt.previewToken;
+        attempt.previewToken = null;
+        if (token) options.clearGuidancePreview?.(token);
+      }
+      const assertCurrent = () => {
+        const currentRun = options.getCurrentRun?.();
+        if (options.isGuideCancelled?.() || currentRun !== run || options.getActiveSession?.()?.id !== identity.sessionId
+          || currentRun?.nativeRequestId !== identity.requestId
+          || currentRun?.recordId !== identity.recordId || currentRun?.runProjectId !== identity.projectKey
+          || currentRun?.activeTurn?.threadId !== identity.threadId || currentRun?.activeTurn?.turnId !== identity.turnId
+          || !ownedItemSession()) {
+          throw Object.assign(new Error(options.tr?.('queuedInputGuideUnavailable') || 'Guidance is no longer available for this turn.'), { code: 'codex_turn_mismatch' });
+        }
+      };
+      async function restoreUnsent(error) {
+        // No steer was dispatched. Restore only this attempt's still-owned item;
+        // a concurrent removal, replacement or scope switch must stay untouched.
+        clearPreview();
+        const latest = ownedItemSession();
+        if (latest) {
+          options.setQueue?.(identity.sessionId, Queue.returnToQueue(latest.pendingInputs, itemId));
+          render();
+          try {
+            await options.save?.({ queueMutation: { type: 'transition', sessionId: identity.sessionId, itemId } });
+          } catch (recoveryError) {
+            if (error && typeof error === 'object') error.persistenceRecoveryError = recoveryError?.message || String(recoveryError);
+          }
+        }
+      }
       options.setQueue?.(session.id, Queue.markSteering(session.pendingInputs, itemId));
-      render();
-      await options.save?.({
-        queueMutation: { type: 'transition', sessionId: session.id, itemId }
-      });
+      guidanceAttempts.set(attemptKey, attempt);
       try {
-        const response = await options.sendSteer?.({
-          requestId: run.nativeRequestId,
-          projectKey: run.runProjectId,
-          threadId: binding.threadId,
-          expectedTurnId: binding.turnId,
-          clientUserMessageId: item.clientUserMessageId,
-          input: [{ type: 'text', text: item.text }]
-        });
-        const latest = options.getSession?.(session.id);
-        options.setQueue?.(
-          session.id,
-          response?.ok
-            ? Queue.remove(latest?.pendingInputs || [], itemId)
-            : Queue.returnToQueue(latest?.pendingInputs || [], itemId, response?.error?.code || 'steer_failed')
+        try {
+          attempt.previewToken = options.previewGuidance?.(identity.text, {
+            guidanceId: itemId, sessionId: identity.sessionId, recordId: identity.recordId,
+            sessionCreatedAt: identity.sessionCreatedAt
+          });
+          render();
+          const preflight = await options.preflightGuide?.({ task: identity.text, assertCurrent });
+          assertCurrent();
+          if (preflight?.blocked) throw Object.assign(new Error('Guidance was blocked before dispatch.'), { guidanceBlocked: true });
+          await options.save?.({
+            queueMutation: { type: 'transition', sessionId: identity.sessionId, itemId }
+          });
+          assertCurrent();
+        } catch (error) {
+          await restoreUnsent(error);
+          if (error?.guidanceBlocked) return { ok: false, blocked: true };
+          throw error;
+        }
+        let response;
+        try {
+          response = await options.sendSteer?.({
+            requestId: identity.requestId,
+            projectKey: identity.projectKey,
+            threadId: identity.threadId,
+            expectedTurnId: identity.turnId,
+            clientUserMessageId: identity.clientUserMessageId,
+            input: [{ type: 'text', text: identity.text }]
+          }, { assertCurrent });
+        } catch (error) {
+          if (error?.requestDispatched === false) { await restoreUnsent(error); throw error; }
+          clearPreview();
+          const latest = ownedItemSession(true);
+          if (latest) {
+            const paused = latest.pendingInputs.map(entry => entry.id === itemId
+              ? { ...entry, status: 'paused', pauseReason: 'steer_delivery_unknown' }
+              : entry);
+            options.setQueue?.(identity.sessionId, Queue.normalizeQueue(paused));
+          }
+          options.toast?.(formatGuideError(error), 'warning');
+          render();
+          if (latest) await options.save?.({
+            queueMutation: { type: 'transition', sessionId: identity.sessionId, itemId }
+          });
+          return;
+        }
+        // Cancellation can pause the owned row while a dispatched steer is
+        // awaiting acknowledgement. A confirmed receipt also consumes that
+        // paused copy, so Resume cannot send an already accepted input again.
+        const latest = ownedItemSession(Boolean(response?.ok));
+        if (latest) options.setQueue?.(
+          identity.sessionId,
+          response?.ok ? Queue.remove(latest.pendingInputs, itemId)
+            : Queue.returnToQueue(latest.pendingInputs, itemId, response?.error?.code || 'steer_failed')
         );
         if (response?.ok) {
-          if (typeof options.appendGuidance === 'function') {
-            options.appendGuidance(item.text, {
-              guidanceId: item.id,
-              sessionId: session.id,
-              recordId: run.recordId,
-              status: 'completed'
+          if (ownedSession() && typeof options.appendGuidance === 'function') {
+            options.appendGuidance(identity.text, {
+              guidanceId: itemId, sessionId: identity.sessionId, recordId: identity.recordId,
+              sessionCreatedAt: identity.sessionCreatedAt, status: 'completed',
+              timestamp: attempt.previewToken?.event?.timestamp
             });
-          } else {
+          } else if (ownedSession() && options.getCurrentRun?.() === run) {
             options.appendEvent?.(options.tr?.('queuedInputGuided'), 'completed');
           }
         } else {
-          options.toast?.(response?.error?.message || options.tr?.('queuedInputGuideFailed'), 'warning');
+          options.toast?.(formatGuideError(response?.error), 'warning');
         }
+        clearPreview();
         render();
-        await options.save?.({
+        // A Native acknowledgement is final delivery evidence. A later local
+        // save failure must not turn it into an unknown delivery or resend it.
+        if (latest) await options.save?.({
           queueMutation: response?.ok
-            ? { type: 'remove', sessionId: session.id, itemId }
-            : { type: 'transition', sessionId: session.id, itemId }
+            ? { type: 'remove', sessionId: identity.sessionId, itemId }
+            : { type: 'transition', sessionId: identity.sessionId, itemId }
         });
-      } catch (error) {
-        const latest = options.getSession?.(session.id);
-        const paused = (latest?.pendingInputs || []).map(entry => entry.id === itemId
-          ? { ...entry, status: 'paused', pauseReason: 'steer_delivery_unknown' }
-          : entry);
-        options.setQueue?.(session.id, Queue.normalizeQueue(paused));
-        options.toast?.(error?.message || options.tr?.('queuedInputGuideFailed'), 'warning');
+        else if (response?.ok && ownedSession()) await options.save?.();
+      } finally {
+        clearPreview();
+        if (guidanceAttempts.get(attemptKey) === attempt) guidanceAttempts.delete(attemptKey);
         render();
-        await options.save?.({
-          queueMutation: { type: 'transition', sessionId: session.id, itemId }
-        });
       }
     }
 
@@ -320,9 +420,10 @@
         view = options.createView?.({
           container,
           tr: options.tr,
-          onGuide: itemId => guide(itemId).catch(error => options.toast?.(error.message, 'warning')),
+          onGuide: itemId => guide(itemId).catch(error => options.toast?.(formatGuideError(error), 'warning')),
           onRemove: remove,
-          onResume: resume
+          onResume: resume,
+          onToast: message => options.toast?.(message, 'warning')
         });
         if (view) {
           view.container = container;
@@ -330,7 +431,13 @@
       }
       const session = options.getActiveSession?.();
       const run = options.getCurrentRun?.();
-      view?.render?.(session?.pendingInputs || [], {
+      const visibleQueue = (session?.pendingInputs || []).filter(item => {
+        const attempt = guidanceAttempts.get(guidanceKey(session.id, item.id));
+        return !attempt?.previewToken || !['steering', 'paused'].includes(item.status)
+          || !matchesGuidanceScope(attempt.scope)
+          || session.createdAt !== attempt.identity.sessionCreatedAt || !matchesGuidanceItem(item, attempt.identity);
+      });
+      view?.render?.(visibleQueue, {
         running: Boolean(run),
         canGuide: Boolean(run?.activeTurn?.turnId)
       });

package/extension/src/content/runRecoveryActions.js

@@ -0,0 +1,146 @@
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) module.exports = factory();
+  else root.CodexOverleafModuleRegistry.define('RunRecoveryActions', [], factory);
+})(typeof window !== 'undefined' ? window : globalThis, function () {
+  'use strict';
+
+  function formatForceCancelOutcome(response, tx) {
+    if (response?.ok !== true) return tx('Release failed — refresh the tab, then try again.', '释放失败，请刷新页面后重试。');
+    const result = response.result || response;
+    if (result.lockReleased === true) return tx('Force-released — you can retry the run.', '已释放，可以重试本轮任务。');
+    if (result.cancelled === true) return tx('Cancellation requested. Wait for the task to stop before retrying.', '已请求取消，请等待任务停止后再重试。');
+    if (result.cancelled === false) return tx('No active task matched the release request.', '没有发现与释放请求匹配的活动任务。');
+    if (result.sent === true) return tx('Cancellation request sent; release is not yet confirmed.', '取消请求已发送，释放状态尚未确认。');
+    return tx('Release is not yet confirmed. Check the current task before retrying.', '释放状态尚未确认，请检查当前任务后再重试。');
+  }
+
+  function create(deps = {}) {
+    const { tx, failureNotice, refillComposerForRetry, openProjectFileForFailure, showNativeSetupGuidance,
+      openStorageSettings, forceCancelStuckTaskForCurrentProject } = deps;
+    const document = deps.document || globalThis.document;
+    const window = deps.window || globalThis.window;
+
+  const RETRYABLE_FAILURE_CODES = new Set([
+    'native_request_failed', 'codex_timeout', 'codex_no_usable_result',
+    'codex_output_limit', 'stale_source_changed', 'patch_anchor_not_found',
+    'target_editor_not_ready', 'write_timeout', 'partial_write_needs_review',
+    'write_operation_failed'
+  ]);
+  const NATIVE_SETUP_FAILURE_CODES = new Set([
+    'native_bridge_unavailable', 'native_protocol_incompatible'
+  ]);
+  const OPEN_FILE_FAILURE_CODES = new Set([
+    'target_file_not_active', 'target_file_open_failed', 'target_file_not_found'
+  ]);
+  const STORAGE_FAILURE_CODES = new Set([
+    'storage_quota_exceeded', 'run_state_persist_failed'
+  ]);
+  // A missing `codex` binary is fixed in the terminal, not the panel — the
+  // action opens the README troubleshooting section (PATH / login checks).
+  const CODEX_INSTALL_FAILURE_CODES = new Set(['codex_not_found']);
+  const CODEX_CLI_TROUBLESHOOTING_URL = 'https://github.com/Ghqqqq/codex-overleaf-link#faq-and-troubleshooting';
+
+  function buildRecoveryButton(failureCode, label, title) {
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.className = 'run-final-answer__recovery-action';
+    button.dataset.recoveryFor = failureCode;
+    button.textContent = label;
+    if (title) {
+      button.title = title;
+    }
+    return button;
+  }
+
+  function appendEditAndResend(report, run, actionKey) {
+    const retry = buildRecoveryButton(actionKey,
+      tx('Edit & resend', '编辑后重发'),
+      tx('Put this run\u2019s task back into the composer so you can adjust and resend it.', '把本轮任务填回输入框，修改后可直接重发。'));
+    retry.addEventListener('click', clickEvent => {
+      clickEvent.stopPropagation();
+      refillComposerForRetry(run || null);
+    });
+    report.append(retry);
+  }
+
+  function appendRecoveryActionForFailure(report, event, run) {
+    const recovery = failureNotice?.prepareRecovery(report, { openFile: openProjectFileForFailure });
+    const failure = recovery?.failure || event?.failure;
+    const failureCode = failure?.code || '';
+    if (recovery?.handled) return;
+    report = recovery?.target || report;
+    if (RETRYABLE_FAILURE_CODES.has(failureCode) && typeof refillComposerForRetry === 'function') {
+      appendEditAndResend(report, run, failureCode);
+      return;
+    }
+    if (NATIVE_SETUP_FAILURE_CODES.has(failureCode) && typeof showNativeSetupGuidance === 'function') {
+      const fix = buildRecoveryButton(failureCode,
+        tx('Fix the native host', '修复 native host'),
+        tx('Opens the install/update guidance with the copyable command.', '打开安装/更新指引（含可复制命令）。'));
+      fix.addEventListener('click', clickEvent => {
+        clickEvent.stopPropagation();
+        showNativeSetupGuidance();
+      });
+      report.append(fix);
+      return;
+    }
+    if (OPEN_FILE_FAILURE_CODES.has(failureCode) && failure?.file && typeof openProjectFileForFailure === 'function') {
+      const open = buildRecoveryButton(failureCode,
+        tx(`Open ${failure.file} in Overleaf`, `在 Overleaf 打开 ${failure.file}`), '');
+      open.addEventListener('click', clickEvent => {
+        clickEvent.stopPropagation();
+        openProjectFileForFailure(failure.file);
+      });
+      report.append(open);
+      return;
+    }
+    if (STORAGE_FAILURE_CODES.has(failureCode) && typeof openStorageSettings === 'function') {
+      const clean = buildRecoveryButton(failureCode,
+        tx('Open history & storage cleanup', '打开历史与存储清理'), '');
+      clean.addEventListener('click', clickEvent => {
+        clickEvent.stopPropagation();
+        openStorageSettings();
+      });
+      report.append(clean);
+      return;
+    }
+    if (CODEX_INSTALL_FAILURE_CODES.has(failureCode)) {
+      const guide = buildRecoveryButton(failureCode,
+        tx('Codex CLI troubleshooting guide', '查看 Codex CLI 排查指引'),
+        tx('Opens the README section on fixing a missing `codex` command (PATH / login).', '打开 README 中「找不到 codex 命令」的排查说明（PATH／登录）。'));
+      guide.addEventListener('click', clickEvent => {
+        clickEvent.stopPropagation();
+        window.open(CODEX_CLI_TROUBLESHOOTING_URL, '_blank', 'noopener');
+      });
+      report.append(guide);
+      return;
+    }
+    if (failureCode !== 'codex_project_locked') return;
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.className = 'run-final-answer__recovery-action';
+    button.dataset.recoveryFor = failureCode;
+    button.textContent = tx('Force-release the stuck task', '强制释放卡住的任务');
+    button.title = tx(
+      'Requests cancellation for this project. A sent request does not confirm that the task has stopped. Use this when refreshing the tab did not free the project.',
+      '请求取消当前项目的任务；请求已发送不代表任务已经停止。刷新页面仍未解除占用时使用。'
+    );
+    button.addEventListener('click', event => {
+      event.stopPropagation();
+      button.disabled = true;
+      button.textContent = tx('Releasing…', '正在释放…');
+      forceCancelStuckTaskForCurrentProject().then(result => {
+        button.textContent = formatForceCancelOutcome(result, tx);
+        button.disabled = result?.ok === true;
+      }).catch(() => {
+        button.disabled = false;
+        button.textContent = tx('Release failed — refresh the tab, then try again.', '释放失败，请刷新页面后重试。');
+      });
+    });
+    report.append(button);
+  }
+
+    return { buildRecoveryButton, appendRecoveryActionForFailure };
+  }
+  return { create, formatForceCancelOutcome };
+});

package/extension/src/content/runResultActions.js

@@ -1,10 +1,12 @@
-(function initCodexOverleafRunResultActions(root, factory) {
-  const api = factory();
-  if (typeof module === 'object' && module.exports) module.exports = api;
-  if (root) root.CodexOverleafRunResultActions = api;
-})(typeof window !== 'undefined' ? window : globalThis, function runResultActionsFactory() {
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) module.exports = factory(require('./runCompletionMeta'));
+  else root.CodexOverleafModuleRegistry.define('RunResultActions', ['RunCompletionMeta'], factory);
+})(typeof window !== 'undefined' ? window : globalThis, function (RunCompletionMeta) {
   'use strict';
 
+  const { splitFlatCompletionReport, projectCompletionBody, projectCompletionMeta, summarizeCompletionMeta } = RunCompletionMeta;
+
+
   function create(deps = {}) {
     const {
       tr,
@@ -107,17 +109,18 @@
       if (!copied) throw new Error('clipboard_copy_failed');
     }
 
-    return Object.freeze({ configureResultActions, projectUndoAvailability });
+    return Object.freeze({ configureResultActions, projectUndoAvailability, splitFlatCompletionReport, projectCompletionBody, projectCompletionMeta, summarizeCompletionMeta });
   }
 
+
   function projectUndoAvailability(run, projectRunSettlement) {
     const payload = run.recoveryPayload && typeof run.recoveryPayload === 'object'
       ? run.recoveryPayload : run;
     if (!Array.isArray(payload.appliedOperations)) return projectRunSettlement(run);
-    // Forward binary writes do not provide a rollback. Filter them only for
+    // Forward creation/asset writes alone do not provide a rollback. Filter them only for
     // display; preserve the canonical settlement and every real recovery field.
     const appliedOperations = payload.appliedOperations.filter(operation =>
-      operation?.type !== 'binary-create' && operation?.type !== 'overwrite-binary');
+      operation?.type !== 'create' && operation?.type !== 'binary-create' && operation?.type !== 'overwrite-binary');
     if (appliedOperations.length === payload.appliedOperations.length) return projectRunSettlement(run);
     return projectRunSettlement({
       ...run,