codex-overleaf-link 2.5.1 → 2.6.5

package/native-host/src/bootstrapUpdate.js

@@ -12,6 +12,7 @@ const Contract = require('./bootstrapMigrationContract');
 const { updateError } = require('./updateTrust');
 
 const BOOTSTRAP_DEADLINE_MS = 120000;
+const MAX_AUTOMATIC_ROLLBACK_ATTEMPTS = 3;
 const BOOTSTRAP_STATES = new Set(['bootstrap_pending', 'bootstrap_rolling_back']);
 const backupRoot = context => path.join(context.updatesRoot, 'bootstrap-migrations');
 const hash = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
@@ -157,7 +158,7 @@ function restoreBootstrap(context, journal) {
     if (journal.bootstrapMigration && journal.bootstrapMigration.phase !== 'pending') {
       throw updateError('update_bootstrap_record_missing', 'Bootstrap recovery material is missing.');
     }
-    if (journal.bootstrapMigration) return assertSourceBootstrap(context, journal);
+    if (journal.bootstrapMigration) return untouchedBootstrap(context, journal);
   }
   return plan ? Files.restoreBootstrapMigration(plan) : null;
 }
@@ -169,29 +170,64 @@ function bootstrapEvidence(context, journal, expected) {
       || journal.bootstrapMigration.phase === 'restored' && journal.bootstrapMigration.sourceUnchanged === true)) {
       throw updateError('update_bootstrap_record_missing', 'Bootstrap recovery material is missing.');
     }
-    return assertSourceBootstrap(context, journal);
+    return untouchedBootstrap(context, journal);
   }
   return plan ? Files.verifyBootstrapMigration(plan, { expected }) : null;
 }
 
-function assertSourceBootstrap(context, journal) {
-  for (const [relative, expected] of Object.entries(Contract.BOOTSTRAP_MIGRATION_BASELINE)) {
-    const filename = path.join(context.extensionRoot, relative);
-    if (expected === null ? fs.existsSync(filename)
-      : !fs.existsSync(filename) || !fs.lstatSync(filename).isFile() || hash(fs.readFileSync(filename)) !== expected) {
-      throw updateError('update_bootstrap_source_mismatch', 'Bootstrap source bytes cannot be confirmed.');
+// Without a file plan this transaction never wrote Bootstrap, so recovery only
+// leaves it in place. Published source bytes keep the baseline digest; any other
+// installed bytes (an earlier release candidate or local build) are recorded as
+// observed. Later reads compare the same digest, so changes still block.
+function untouchedBootstrap(context, journal) {
+  let knownSource = true;
+  const entries = Object.entries(Contract.BOOTSTRAP_MIGRATION_BASELINE).sort((a, b) => a[0].localeCompare(b[0]))
+    .map(([relative, expected]) => {
+      const actual = readBootstrapFileHash(context, relative);
+      if (actual !== expected) knownSource = false;
+      return [relative, actual];
+    });
+  return { transactionId: journal.id, migrationId: 'bootstrap-v3.1-from-2.5.0',
+    state: 'restored', expected: 'source', digest: hash(JSON.stringify(entries)), unmodified: true, knownSource };
+}
+
+function readBootstrapFileHash(context, relative) {
+  const filename = path.join(context.extensionRoot, relative);
+  if (!fs.existsSync(filename)) return null;
+  if (!fs.lstatSync(filename).isFile()) {
+    throw updateError('update_bootstrap_source_mismatch', 'Bootstrap source bytes cannot be confirmed.');
+  }
+  return hash(fs.readFileSync(filename));
+}
+
+// Runs before staging and in the update check. A signed migration starts only
+// from the exact source bytes it names; other installations need a full
+// reinstall instead of a transaction that cannot finish. This reads only the
+// descriptor's file list, so later migration contracts use the same check.
+function assertMigrationSource(context, manifest, sourceVersion) {
+  const descriptor = manifest?.bootstrapMigration;
+  if (!descriptor || !Array.isArray(descriptor.sourceVersions) || !descriptor.sourceVersions.includes(sourceVersion)
+    || !Array.isArray(descriptor.files)) return;
+  for (const file of descriptor.files) {
+    const relative = String(file?.path || '');
+    if (!/^bootstrap\/[A-Za-z0-9._-]+$/.test(relative)) {
+      throw updateError('update_bootstrap_manifest_mismatch', 'Bootstrap migration file identity is invalid.');
+    }
+    if (readBootstrapFileHash(context, relative) !== (file.sourceSha256 ?? null)) {
+      throw updateError('update_bootstrap_source_mismatch',
+        'The installed startup files do not match the published source of this update.');
     }
   }
-  const entries = Object.entries(Contract.BOOTSTRAP_MIGRATION_BASELINE).sort((a, b) => a[0].localeCompare(b[0]));
-  return { transactionId: journal.id, migrationId: 'bootstrap-v3.1-from-2.5.0',
-    state: 'restored', expected: 'source', digest: hash(JSON.stringify(entries)), unmodified: true };
 }
 
 function bootstrapExpired(journal, { recoveryRequested = false, context } = {}) {
   const migration = journal?.bootstrapMigration;
   if (!migration || !['bootstrap_pending', 'bootstrap_rolling_back', 'awaiting_health'].includes(journal.state)) return false;
-  return journal.state === 'bootstrap_rolling_back'
-    || (migration.deadline && Date.now() >= migration.deadline)
+  // Automatic retries are bounded; an explicit update.rollback still runs.
+  if (journal.state === 'bootstrap_rolling_back') {
+    return Number(journal.rollbackFailure?.attempts || 0) < MAX_AUTOMATIC_ROLLBACK_ATTEMPTS;
+  }
+  return (migration.deadline && Date.now() >= migration.deadline)
     || (recoveryRequested && migration.phase !== 'pending' && !watchdogAlive(migration, context, journal));
 }
 
@@ -228,6 +264,6 @@ function startWatchdog(context, journal, token) {
 
 function readJson(filename) { try { return JSON.parse(fs.readFileSync(filename, 'utf8')); } catch (_) { return null; } }
 
-module.exports = { BOOTSTRAP_DEADLINE_MS, BOOTSTRAP_STATES, migrationHint, bindBootstrapMigration,
-  advanceBootstrapMigration, assertBootstrapConfirmation, restoreBootstrap, bootstrapEvidence,
-  bootstrapExpired, watchdogAlive };
+module.exports = { BOOTSTRAP_DEADLINE_MS, BOOTSTRAP_STATES, MAX_AUTOMATIC_ROLLBACK_ATTEMPTS, migrationHint,
+  bindBootstrapMigration, advanceBootstrapMigration, assertBootstrapConfirmation, assertMigrationSource,
+  restoreBootstrap, bootstrapEvidence, bootstrapExpired, watchdogAlive };

package/native-host/src/chatBridgeRequest.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const crypto = require('node:crypto');
+const { providerError } = require('./providerProfile');
 
 const {
   applyReasoningControl,
@@ -58,7 +59,15 @@ function appendResponsesInput(messages, input, { replayReasoning = false, toolKi
   }
   if (!Array.isArray(input)) return;
   let pendingToolCalls = [];
+  let pendingToolOutputContent = [];
   let pendingReasoning = '';
+  const flushToolOutputContent = () => {
+    if (!pendingToolOutputContent.length) return;
+    // Chat tool messages accept text only. Attach images after the complete
+    // tool-result group so a user message cannot split parallel tool results.
+    messages.push({ role: 'user', content: pendingToolOutputContent });
+    pendingToolOutputContent = [];
+  };
   const flushToolCalls = () => {
     if (!pendingToolCalls.length) return;
     const assistant = {
@@ -73,6 +82,9 @@ function appendResponsesInput(messages, input, { replayReasoning = false, toolKi
   };
   for (const item of input) {
     if (!item || typeof item !== 'object') continue;
+    const isToolOutput = item.type === 'function_call_output' || item.type === 'custom_tool_call_output'
+      || item.type === 'computer_call_output' || item.type === 'tool_search_output';
+    if (!isToolOutput && item.type !== 'reasoning') flushToolOutputContent();
     if (item.type === 'reasoning') {
       flushToolCalls();
       pendingReasoning = extractReasoningText(item);
@@ -83,12 +95,22 @@ function appendResponsesInput(messages, input, { replayReasoning = false, toolKi
       continue;
     }
     flushToolCalls();
-    if (item.type === 'function_call_output' || item.type === 'custom_tool_call_output' || item.type === 'computer_call_output' || item.type === 'tool_search_output') {
+    if (isToolOutput) {
+      const callId = normalizeText(item.call_id) || normalizeText(item.id);
+      const imageContent = translateImageToolOutput(item.output);
       messages.push({
         role: 'tool',
-        tool_call_id: normalizeText(item.call_id) || normalizeText(item.id),
-        content: normalizeToolOutput(item.output)
+        tool_call_id: callId,
+        content: imageContent
+          ? 'The tool output, including images, is attached after the tool results.'
+          : normalizeToolOutput(item.output)
       });
+      if (imageContent) {
+        pendingToolOutputContent.push(
+          { type: 'text', text: `Output from tool call ${callId}:` },
+          ...imageContent
+        );
+      }
       continue;
     }
     if (item.type === 'message' || item.role) {
@@ -105,6 +127,38 @@ function appendResponsesInput(messages, input, { replayReasoning = false, toolKi
     }
   }
   flushToolCalls();
+  flushToolOutputContent();
+}
+
+function translateImageToolOutput(output) {
+  const parts = Array.isArray(output) ? output : [output];
+  if (!parts.some(isImagePart)) return null;
+  return parts.map(part => {
+    if (isImagePart(part)) {
+      const image = translateImagePart(part);
+      if (!image) {
+        throw providerError('provider_request_invalid', 'A tool image requires an image URL or data URL for Chat Completions.');
+      }
+      return image;
+    }
+    const text = ['input_text', 'output_text', 'text'].includes(part?.type)
+      ? normalizeText(part.text)
+      : normalizeToolOutput(part);
+    return { type: 'text', text };
+  });
+}
+
+function isImagePart(part) {
+  return part?.type === 'input_image' || part?.type === 'image_url' || part?.type === 'computer_screenshot';
+}
+
+function translateImagePart(part) {
+  const url = normalizeText(part.image_url?.url || part.image_url || part.url);
+  if (!url) return null;
+  const detail = normalizeText(part.image_url?.detail || part.detail);
+  const image = { type: 'image_url', image_url: { url } };
+  if (['auto', 'low', 'high'].includes(detail)) image.image_url.detail = detail;
+  return image;
 }
 
 function extractReasoningText(item) {
@@ -142,10 +196,10 @@ function translateMessageContent(content) {
     if (part.type === 'input_text' || part.type === 'output_text' || part.type === 'text') {
       parts.push({ type: 'text', text: normalizeText(part.text) });
     } else if (part.type === 'input_image' || part.type === 'image_url') {
-      const url = normalizeText(part.image_url?.url || part.image_url || part.url);
-      if (url) {
+      const image = translateImagePart(part);
+      if (image) {
         hasStructuredPart = true;
-        parts.push({ type: 'image_url', image_url: { url } });
+        parts.push(image);
       }
     }
   }

package/native-host/src/chatBridgeResponse.js

@@ -2,9 +2,11 @@
 
 const crypto = require('node:crypto');
 const { requiresReasoningContentReplay } = require('./providerReasoning');
+const { isContextLimitError } = require('./providerContextError');
 const MAX_STREAM_BUFFER_BYTES = 8 * 1024 * 1024;
 
 function convertChatResponse(chat = {}, context = {}) {
+  if (chat.error) throwUpstreamError(chat.error);
   const choice = Array.isArray(chat.choices) ? chat.choices[0] || {} : {};
   const message = choice.message || {};
   assertNoLeakedToolControlTokens(message);
@@ -131,7 +133,7 @@ function writeConvertedResponseAsSse(res, converted, context = {}, onComplete =
 
 function processChatChunk(state, res, chunk) {
   if (!chunk || typeof chunk !== 'object') return;
-  if (chunk.error) throw new Error(normalizeText(chunk.error.message) || 'Upstream provider returned an error.');
+  if (chunk.error) throwUpstreamError(chunk.error);
   if (chunk.id && !state.upstreamId) {
     state.upstreamId = chunk.id;
   }
@@ -491,6 +493,13 @@ function mapChatFinishReason(value) {
   return { status: 'completed', incompleteReason: null };
 }
 
+function throwUpstreamError(detail) {
+  throw responseError(
+    normalizeText(detail?.message) || normalizeText(detail) || 'Upstream provider returned an error.',
+    isContextLimitError(detail) ? 'context_length_exceeded' : 'provider_upstream_error'
+  );
+}
+
 function responseError(message, code = 'provider_response_invalid') {
   const error = new Error(message);
   error.code = code;

package/native-host/src/chatCompletionsBridge.js

@@ -13,6 +13,7 @@ const { classifyResponsesRoute } = require('./providerBridgeRoutes');
 const { providerError } = require('./providerProfile');
 const { fetchProvider, readProviderText, readProviderJson } = require('./providerHttp');
 const { sanitizeProviderMessage } = require('./providerRedaction');
+const { isContextLimitError } = require('./providerContextError');
 const { logDebug } = require('./debugLog');
 const {
   createProviderStreamLifecycle,
@@ -174,7 +175,7 @@ async function handleRequest({
     }, launch);
     lifecycle.touch();
     if (!upstream.ok) {
-      await forwardUpstreamError(upstream, res, launch.apiKey, lifecycle.touch);
+      await forwardUpstreamError(upstream, res, launch.apiKey, lifecycle.touch, requestBody.stream !== false);
       return;
     }
     const context = {
@@ -255,6 +256,10 @@ async function handleRequest({
     if (controller.signal.aborted) {
       throw providerError('provider_connection_timeout', 'The provider request was cancelled or timed out.');
     }
+    if (error?.code === 'context_length_exceeded' && !res.headersSent) {
+      sendContextLimitError(res, sanitizeProviderMessage(error.message, [launch.apiKey]), requestBody.stream !== false);
+      return;
+    }
     throw error;
   } finally {
     lifecycle.dispose();
@@ -382,6 +387,7 @@ function normalizeBridgeErrorCode(value) {
     'provider_reasoning_continuation_exhausted',
     'provider_stream_tool_parse_failed',
     'provider_protocol_incompatible',
+    'context_length_exceeded',
     'provider_upstream_error'
   ].includes(value) ? value : 'provider_bridge_failed';
 }
@@ -392,16 +398,37 @@ function bridgeErrorMessage(code) {
     : 'The local provider bridge failed.';
 }
 
-async function forwardUpstreamError(upstream, res, apiKey, onActivity) {
+async function forwardUpstreamError(upstream, res, apiKey, onActivity, clientStream) {
   const text = (await readProviderText(upstream, onActivity)).slice(0, MAX_ERROR_BYTES);
   let message = `Provider returned HTTP ${upstream.status}.`;
+  let error;
   try {
     const parsed = JSON.parse(text);
+    error = parsed?.error || parsed;
     message = parsed?.error?.message || parsed?.message || message;
   } catch (_error) {}
+  if ([400, 413, 422].includes(upstream.status) && isContextLimitError(error || text)) {
+    sendContextLimitError(res, sanitizeProviderMessage(error ? message : text, [apiKey]), clientStream);
+    return;
+  }
   sendJsonError(res, upstream.status, 'provider_upstream_error', sanitizeProviderMessage(message, [apiKey]));
 }
 
+function sendContextLimitError(res, message, stream) {
+  const error = { type: 'invalid_request_error', code: 'context_length_exceeded', message };
+  if (!stream) {
+    sendJson(res, 400, { error });
+    return;
+  }
+  // Non-2xx JSON is a generic HTTP failure to the installed Codex client.
+  // Its typed context recovery consumes a Responses failure event instead.
+  res.writeHead(200, { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-store' });
+  res.end(`event: response.failed\ndata: ${JSON.stringify({
+    type: 'response.failed', sequence_number: 0,
+    response: { id: `resp_${crypto.randomUUID()}`, object: 'response', status: 'failed', error }
+  })}\n\n`);
+}
+
 function rememberHistory(history, responseId, messages, metadata = {}) {
   history.delete(responseId);
   history.set(responseId, { messages, ...metadata });

package/native-host/src/codexPromptAssembly.js

@@ -2,84 +2,87 @@
 
 const { truncateText } = require('./debugLog');
 const { formatOverleafWorkspaceRules } = require('./overleafWorkspaceRules');
+const { buildReadProgressRules } = require('./readProgressGuard');
 
 const PROJECT_CUSTOM_INSTRUCTIONS_MAX_CHARS = 12000;
 const NATIVE_MESSAGE_PROMPT_MAX_CHARS = 1024 * 1024;
 
-/**
- * Build the full Codex turn prompt from run parameters.
- * @param {Object} options
- * @param {string} options.task - User task text.
- * @param {string} options.customInstructions - Project custom instructions (may be empty).
- * @param {Array} options.skills - Array of { id, name, content } loaded skill objects.
- * @param {Object|null} options.skillInvocation - { skillId, forced } if slash-selected.
- * @param {Array} options.attachments - Array of { name, relativePath } staged attachment refs.
- * @param {string} options.activePath - Currently focused file path.
- * @param {Array<string>} options.contextFiles - Selected context file paths.
- * @param {Object} options.compileContext - { enabled, logSummary } compile context.
- * @returns {{ systemPrompt: string, userPrompt: string }}
- */
+/** Stable parent-thread guidance; the active mode and task belong to the turn. */
+function buildCodexDeveloperInstructions(options = {}) {
+  const params = options.params && typeof options.params === 'object' ? options.params : options;
+  const locale = (options.locale ?? params.locale) === 'zh' ? 'Chinese (zh)' : 'English (en)';
+  const skillInvocation = options.skillInvocation || params.skillInvocation;
+  return [
+    'You are Codex working inside the Codex Overleaf Link panel, helping an academic author with their LaTeX project in Overleaf. The user reads your answer in a narrow (~380px) side panel.',
+    [
+      'Reply language and style:',
+      `- Reply in the language of the user's latest request. If unclear, use the UI language: ${locale}. Keep LaTeX source, file paths, and identifiers unchanged.`,
+      '- Lead with the answer or outcome. Use short paragraphs and lists; avoid wide tables and long code dumps. Do not restate the request.',
+      '- Complete the requested analysis or edit within this turn. Do not end with only a plan or a promise to act later.',
+      '- For edits, summarize what changed per file with citations. The panel already shows written files, diffs, and Undo; do not paste whole diffs.'
+    ].join('\n'),
+    ...(isSkillInstallerInvocation(skillInvocation) ? [] : [formatOverleafWorkspaceRules()]),
+    ['Project location citation rules:', formatProjectLocationCitationRules()].join('\n'),
+    ['Answer formatting:', formatMathOutputRules()].join('\n'),
+    [
+      'Academic integrity:',
+      '- Never invent citations, BibTeX entries, data, results, or quotations.',
+      '- When a claim needs a source you cannot verify in the project, say so and suggest what kind of source is needed instead of adding one.'
+    ].join('\n'),
+    [
+      'Editing discipline for writable turns:',
+      '- Change only what the request needs. Keep unrelated text, whitespace, and formatting untouched; small diffs keep Overleaf tracked changes and Undo reviewable.',
+      '- Keep \\label, \\ref, and \\cite keys and file names stable unless asked to change them.',
+      '- Keep the document compilable, with balanced braces and environments.'
+    ].join('\n'),
+    [
+      'Modes:',
+      '- Each turn states its active mode. These modes govern project work; explicit skill-install turns follow their separate installation scope.',
+      '- Ask is read-only: inspect and explain. When suggesting edits, show short LaTeX snippets with citations and mention that Auto mode can apply them.',
+      '- Auto may edit the local workspace. The browser bridge handles authorization, deletion approval, and syncing to Overleaf.'
+    ].join('\n'),
+    buildReadProgressRules()
+  ].join('\n\n');
+}
+
+/** Build dynamic per-turn context and the current user request. */
 function buildCodexTurnPrompt(options = {}) {
   const context = normalizePromptOptions(options);
-
-  const systemPrompt = [
-    'Same Codex Overleaf session context:',
-    `Session id: ${context.session.id || 'none'}`,
-    '',
-    'Recent turns in this UI session:',
-    formatSessionHistory(context.session.history),
-    '',
-    'Current Overleaf workspace:',
-    `- Project: ${context.projectKey || context.projectId || 'unknown'}`,
-    ...formatWorkspaceSnapshotContext(context.unreadFiles),
-    ...(isSkillInstallerInvocation(context.skillInvocation) ? [] : ['', formatOverleafWorkspaceRules()]),
-    '',
-    'Project location citation rules:',
-    formatProjectLocationCitationRules(),
-    formatMathOutputRules(),
-    '',
-    'Focused project file inventory:',
-    formatFocusedProjectFileInventory(context.focusFiles),
-    '',
-    'Focus files:',
-    formatFocusFiles(context.focusFiles),
-    '',
-    'Compilation context (@compile-log):',
-    formatCompileLogContext(context),
-    '',
-    'Project custom instructions:',
-    formatCustomInstructionsContext(context.customInstructions),
-    '',
-    'Project local skills:',
-    formatProjectLocalSkillsContext(context),
-    '',
-    'Codex skill loading:',
-    formatCodexSkillLoadingContext(context),
-    '',
-    'Selected Codex skill:',
-    formatSkillInvocationContext(context),
-    '',
-    'Attachments for this turn:',
-    formatTurnAttachmentsContext(context.attachments),
-    '',
-    'Mode for this turn:',
-    `- ${context.mode}`,
-    '- ask: inspect and explain only; do not edit files.',
-    '- auto: edit the local workspace directly when the request calls for changes. The browser bridge handles authorization, deletion approval, and syncing back to Overleaf.',
-    '',
-    'Write expectation for this turn:',
-    formatWriteExpectation({
-      mode: context.mode,
-      task: context.userTask,
-      skillInvocation: context.skillInvocation
-    })
-  ].join('\n');
-
-  const userPrompt = [
-    'Current user request:',
-    context.userTask || '(empty request)'
-  ].join('\n');
-
+  const sections = [
+    `Mode for this turn: ${context.mode}`,
+    ['Write expectation for this turn:', formatWriteExpectation(context)].join('\n')
+  ];
+  if (!isSkillInstallerInvocation(context.skillInvocation)) {
+    sections.push([
+      'Current Overleaf workspace:',
+      ...(context.projectKey || context.projectId ? [`- Project: ${context.projectKey || context.projectId}`] : []),
+      ...formatWorkspaceSnapshotContext(context.unreadFiles)
+    ].join('\n'));
+  }
+  if (!context.threadId && Array.isArray(context.session.history) && context.session.history.length) {
+    sections.push(['Recent turns in this UI session:', formatSessionHistory(context.session.history)].join('\n'));
+  }
+  if (context.focusFiles.length) {
+    sections.push(['Focus files:', formatFocusFiles(context.focusFiles)].join('\n'));
+  }
+  if (String(context.compileLog || '').trim()) {
+    sections.push(['Compilation context (@compile-log):', formatCompileLogContext(context)].join('\n'));
+  }
+  if (String(context.customInstructions || '').trim()) {
+    sections.push(['Project custom instructions:', formatCustomInstructionsContext(context.customInstructions)].join('\n'));
+  }
+  if (context.selectedSkillIds.length && (context.projectLocalSkills.skills?.length || context.projectLocalSkills.missing?.length)) {
+    sections.push(['Project local skills:', formatProjectLocalSkillsContext(context)].join('\n'));
+  }
+  if (normalizeSkillInvocation(context.skillInvocation) || normalizeSkillInvocation(context.codexSkillInvocationContext?.invocation)
+      || context.codexSkillInvocationContext?.ignored?.length || context.codexSkillInvocationContext?.missing?.length) {
+    sections.push(['Selected Codex skill:', formatSkillInvocationContext(context)].join('\n'));
+  }
+  if (context.attachments.length) {
+    sections.push(['Attachments for this turn:', formatTurnAttachmentsContext(context.attachments)].join('\n'));
+  }
+  const systemPrompt = sections.join('\n\n');
+  const userPrompt = ['Current user request:', context.userTask || '(empty request)'].join('\n');
   return { systemPrompt, userPrompt };
 }
 
@@ -87,10 +90,12 @@ function buildCodexTurnPrompt(options = {}) {
  * Validate prompt size against native messaging limits.
  * @param {string} systemPrompt
  * @param {string} userPrompt
+ * @param {string} developerInstructions
  * @returns {{ ok: boolean, totalChars: number, exceedsLimit: boolean }}
  */
-function validatePromptSize(systemPrompt, userPrompt) {
-  const totalChars = String(systemPrompt || '').length + String(userPrompt || '').length;
+function validatePromptSize(systemPrompt, userPrompt, developerInstructions = '') {
+  const totalChars = String(systemPrompt || '').length + String(userPrompt || '').length
+    + String(developerInstructions || '').length;
   const exceedsLimit = totalChars > NATIVE_MESSAGE_PROMPT_MAX_CHARS;
   return {
     ok: !exceedsLimit,
@@ -127,6 +132,7 @@ function normalizePromptOptions(options = {}) {
   return {
     params,
     session,
+    threadId: String(options.threadId ?? params.threadId ?? '').trim(),
     projectKey: mirror.projectKey || options.projectKey || params.projectId || params.project?.id || params.project?.projectId,
     projectId: options.projectId || params.projectId || params.project?.id || params.project?.projectId,
     workspacePath: mirror.workspacePath || options.workspacePath || '',
@@ -156,8 +162,7 @@ function normalizePromptOptions(options = {}) {
 
 function formatWorkspaceSnapshotContext(unreadFiles) {
   if (!unreadFiles.length) return [
-    '- The local workspace was synced from Overleaf immediately before this turn.',
-    '- If the recent session history conflicts with the files in the workspace, trust the files.'
+    '- The local workspace was synced from Overleaf before this turn; trust the files over conflicting session history.'
   ];
   return [
     '- The readable project files were synced from Overleaf before this turn.',
@@ -196,7 +201,7 @@ function formatTurnAttachmentsContext(attachments = []) {
   ].join('\n');
 }
 
-function formatWriteExpectation({ mode = 'auto', task = '', skillInvocation = null } = {}) {
+function formatWriteExpectation({ mode = 'auto', skillInvocation = null } = {}) {
   if (isSkillInstallerInvocation(skillInvocation)) {
     return [
       '- This is a skill-install turn.',
@@ -208,29 +213,7 @@ function formatWriteExpectation({ mode = 'auto', task = '', skillInvocation = nu
   if (mode === 'ask') {
     return '- This is read-only. Inspect and explain; do not edit files.';
   }
-  if (requestImpliesFileChanges(task)) {
-    const lines = [
-      '- The request asks for file changes. You must edit the local workspace when you find concrete fixes.',
-      '- Do not stop at a suggestion list or say you will not modify files unless no safe concrete edit exists.',
-      '- If you intentionally leave files unchanged, explain the specific blocker in the final answer.'
-    ];
-    if (requestTargetsAbstract(task)) {
-      lines.push('- The request targets the abstract/summary. Locate the LaTeX abstract environment or summary paragraph and edit that local project file directly.');
-    }
-    return lines.join('\n');
-  }
-  return [
-    '- This mode can write. If the request asks for corrections, revisions, fixes, polishing, updates, or implementation, edit the local workspace directly.',
-    '- If the request is purely an inspection question, report findings without inventing unnecessary edits.'
-  ].join('\n');
-}
-
-function requestImpliesFileChanges(task = '') {
-  return /修正|修复|修改|改[一-龥]*|完善|补全|补充|润色|重写|改写|整理|调整|应用|写入|fix|correct|repair|revise|edit|update|rewrite|polish|improve|apply/i.test(String(task || ''));
-}
-
-function requestTargetsAbstract(task = '') {
-  return /摘要|abstract|summary/i.test(String(task || ''));
+  return '- Decide from the request whether it asks for changes. If it asks you to fix, revise, polish, rewrite, apply or otherwise change the project, edit the workspace files directly instead of only suggesting; if it asks a question, answer it without editing. If you intentionally leave files unchanged for a change request, explain the blocker.';
 }
 
 function normalizeFocusFiles(value) {
@@ -271,8 +254,8 @@ function normalizeProjectPath(value) {
 
 function formatProjectLocationCitationRules() {
   return [
-    '- In any user-visible output, cite project locations using only Overleaf project-relative paths from the project file inventory below.',
-    '- Use path:LINE[:COLUMN] (for example, path/to/file.tex:12:3).',
+    '- In any user-visible output, cite project locations using only Overleaf project-relative paths of files in this workspace.',
+    '- Use path:LINE[:COLUMN] for a position and path:START-END for a span (for example, path/to/file.tex:12:3 or main.tex:12-20).',
     '- Do not wrap project location citations in backticks or inline code; write main.tex:28 as normal text so the browser can turn it into a jump button.',
     '- Do not cite local absolute paths, temporary workspace paths, file:// URLs, or markdown links to local files.',
     '- If a line number is uncertain, cite only the project-relative file path.'
@@ -289,14 +272,6 @@ function formatMathOutputRules() {
   ].join('\n');
 }
 
-function formatFocusedProjectFileInventory(files) {
-  const focusFiles = normalizeFocusFiles(files);
-  if (!focusFiles.length) {
-    return '- none selected.';
-  }
-  return focusFiles.map(filePath => `- ${filePath}`).join('\n');
-}
-
 function formatFocusFiles(files) {
   if (!files.length) {
     return '- none; use the whole project when needed.';
@@ -396,13 +371,6 @@ function formatProjectLocalSkillsContext(context = {}) {
   return sections.length ? sections.join('\n\n') : '- none loaded.';
 }
 
-function formatCodexSkillLoadingContext(context = {}) {
-  return [
-    `- Codex local skills: ${context.loadCodexLocalSkills === false ? 'disabled' : 'enabled'}`,
-    `- Codex Overleaf skills: ${context.loadCodexOverleafSkills === false ? 'disabled' : 'enabled'}`
-  ].join('\n');
-}
-
 function formatSkillInvocationContext(context = {}) {
   const invocation = normalizeSkillInvocation(context.skillInvocation);
   const codexSkillInvocationContext = context.codexSkillInvocationContext || {};
@@ -514,4 +482,4 @@ function formatSessionHistory(history) {
   }).join('\n');
 }
 
-module.exports = { buildCodexTurnPrompt, validatePromptSize };
+module.exports = { buildCodexDeveloperInstructions, buildCodexTurnPrompt, validatePromptSize };