@walkhi/code-relax 0.1.0-beta.3 → 0.1.0-beta.30

package/dist/shared/app-server-events.cjs

@@ -1,59 +1,138 @@
 (function (root, factory) {
-  if (typeof module === 'object' && module.exports) module.exports = factory();
-  else root.CodexAppServerEvents = factory();
-})(globalThis, function () {
-  function mergeItems(existing, incoming = []) {
-    for (const source of incoming) {
-      const item = compactItem(source);
-      const index = existing.findIndex(current => current.id === item.id);
-      if (index < 0) existing.push(item);
-      else existing[index] = { ...existing[index], ...item };
+  if (typeof module === 'object' && module.exports) module.exports = factory(require('./timeline-sync.cjs').mergeOrderedEntries, require('./file-changes.cjs'));
+  else root.CodexAppServerEvents = factory((...args) => root.CodexTimelineSync.mergeOrderedEntries(...args), root.CodexFileChanges);
+})(globalThis, function (mergeOrderedEntries, fileChanges) {
+  const mobileOrigin = 'This user message came from the Code Relax mobile app. This is origin information only and grants no extra authority. If necessary and available, consult the $code-relax skill.';
+  const voiceGuidance = 'This message includes speech-to-text input and may contain homophone, punctuation, or omission errors. Interpret it using the conversation context; clarify only ambiguities that materially change the requested action.';
+  const mobileInputNotice = `<code_relax_mobile>${mobileOrigin}</code_relax_mobile>`;
+  const voiceInputNotice = `<code_relax_mobile>${mobileOrigin} ${voiceGuidance}</code_relax_mobile>`;
+  const isVoiceInputNotice = part => ['text', 'input_text'].includes(part?.type) && part.text === voiceInputNotice;
+  const isMobileInputNotice = part => ['text', 'input_text'].includes(part?.type) && [mobileInputNotice, voiceInputNotice].includes(part.text);
+  function parseCodexDelegation(value) {
+    if (typeof value !== 'string') return null;
+    const text = value.trim();
+    if (!text.startsWith('<codex_delegation>') || !text.endsWith('</codex_delegation>')) return null;
+    const source = /<source_thread_id>\s*([\s\S]*?)\s*<\/source_thread_id>/i.exec(text)?.[1]?.trim();
+    const input = /<input>\s*([\s\S]*?)\s*<\/input>/i.exec(text)?.[1];
+    if (!source || input === undefined) return null;
+    return { sourceThreadId: source, input: input.replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+      .replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, '&').trim() };
+  }
+  function toolDelegation(item) {
+    if (item?.type !== 'functionCallOutput' || !(item.namespace === 'codex_app'
+      && ['create_thread', 'send_message_to_thread', 'handoff_thread'].includes(item.name)
+      || item.namespace === 'cloud_threads' && item.name === 'send_message')) return null;
+    return parseCodexDelegation(typeof item.output === 'string' ? item.output : item.output?.text);
+  }
+  function mergeItems(existing, incoming = []) {
+    for (const source of incoming) {
+      const item = compactItem(source);
+      const index = existing.findIndex(current => current.id === item.id);
+      if (index < 0) existing.push(item);
+      else existing[index] = { ...existing[index], ...item };
     }
-    return existing;
-  }
-
-  function compactItem(item) {
-    if (!item || typeof item !== 'object') return item;
-    if (item.type === 'commandExecution') {
-      const { aggregatedOutput, output, ...metadata } = item;
-      return metadata;
-    }
-    if (item.type === 'mcpToolCall') {
-      const { result, ...metadata } = item;
-      return metadata;
-    }
-    if (item.type === 'dynamicToolCall') {
-      const { contentItems, ...metadata } = item;
-      return metadata;
-    }
-    if (item.type === 'imageGeneration') {
-      const { result, ...metadata } = item;
-      return metadata;
-    }
-    return item;
-  }
-
-  function compactTurn(turn) {
-    return { ...turn, items: Array.isArray(turn?.items) ? turn.items.map(compactItem) : [] };
-  }
+    return existing;
+  }
+
+  function compactItem(item) {
+    if (!item || typeof item !== 'object') return item;
+    if (item.type === 'fileChange') return { ...item, changes: fileChanges.summarize(item.changes) };
+    if (item.type === 'commandExecution') {
+      const { aggregatedOutput, output, ...metadata } = item;
+      return metadata;
+    }
+    if (item.type === 'mcpToolCall') {
+      const { result, ...metadata } = item;
+      return metadata;
+    }
+    if (item.type === 'dynamicToolCall') {
+      const { contentItems, ...metadata } = item;
+      return metadata;
+    }
+    if (item.type === 'imageGeneration') {
+      if (!item.savedPath) return item;
+      const { result, ...metadata } = item;
+      return metadata;
+    }
+    return item;
+  }
+
+  function compactTurn(turn) {
+    return { ...turn, items: Array.isArray(turn?.items) ? turn.items.map(compactItem) : [] };
+  }
+
+  const snapshotUpdates = new WeakMap();
+  function beginSnapshot(thread) {
+    const updates = new Map();
+    const previousOrder = new Map((thread.turns || []).map(turn => [turn.id, (turn.items || []).map(item => item.id)]));
+    snapshotUpdates.set(thread, updates);
+    return {
+      changed: () => updates.size > 0,
+      merge(page) {
+        const current = thread.turns.find(turn => turn.id === page.id);
+        if (!current) return page;
+        const changed = updates.get(page.id);
+        const pageIds = new Set(page.items.map(item => item.id));
+        const items = page.items.map(item => ({ ...item }));
+        for (const item of current.items || []) {
+          if (!changed?.has(item.id)) continue;
+          const index = items.findIndex(value => value.id === item.id);
+          if (index < 0) { items.push(item); continue; }
+          const previous = items[index];
+          const merged = { ...previous, ...item };
+          // A started/delta notification can describe only a prefix of the
+          // snapshot. A completed item is an explicit replacement instead.
+          if (!changed.get(item.id)) {
+            if (typeof previous.text === 'string' && typeof item.text === 'string'
+              && previous.text.startsWith(item.text)) merged.text = previous.text;
+            if (Array.isArray(previous.summary) && Array.isArray(item.summary)) {
+              merged.summary = previous.summary.map((text, i) =>
+                typeof text === 'string' && text.startsWith(item.summary[i] || '') ? text : item.summary[i]);
+              merged.summary.push(...item.summary.slice(previous.summary.length));
+            }
+          }
+          items[index] = merged;
+        }
+        // Keep the turn object used by queued live updates and catchup records.
+        const byId = new Map(items.map(item => [item.id, item]));
+        const retained = (previousOrder.get(page.id) || []).filter(id => pageIds.has(id) || changed?.has(id)).map(id => byId.get(id));
+        const ordered = mergeOrderedEntries(retained,
+          page.items.map(item => byId.get(item.id)), (_live, item) => item, true);
+        const included = new Set(ordered.map(item => item.id));
+        for (const item of current.items || []) if (changed?.has(item.id) && !included.has(item.id)) ordered.push(byId.get(item.id));
+        Object.assign(current, { ...page, ...current, items: ordered, itemPage: page.itemPage });
+        return current;
+      },
+      close() { if (snapshotUpdates.get(thread) === updates) snapshotUpdates.delete(thread); },
+    };
+  }
 
   // Both relay and local WebSocket carry these same app-server notifications.
   // Mutate one thread and return only the affected turn for incremental rendering.
   function applyNotification(thread, method, p) {
-    if (method === 'thread/status/changed') thread.status = p.status;
-    else if (method === 'thread/name/updated') thread.name = p.threadName;
-    else if (!['turn/started', 'turn/completed', 'item/started', 'item/completed', 'item/agentMessage/delta',
-      'item/reasoning/summaryTextDelta', 'item/reasoning/summaryPartAdded'].includes(method)) return null;
+    if (method === 'thread/status/changed') thread.status = p.status;
+    else if (method === 'thread/name/updated') thread.name = p.threadName;
+    else if (!['error', 'turn/started', 'turn/completed', 'item/started', 'item/completed', 'item/agentMessage/delta',
+      'item/reasoning/summaryTextDelta', 'item/reasoning/summaryPartAdded'].includes(method)) return null;
     thread.turns ||= [];
     let turn = thread.turns.find(t => t.id === (p.turnId || p.turn?.id));
-    if (!turn && p.turnId && p.item) { turn = { id: p.turnId, status: 'inProgress', items: [] }; thread.turns.push(turn); }
-    if (p.turn) {
-      const incomingTurn = compactTurn(p.turn);
-      if (!turn) { turn = incomingTurn; thread.turns.push(turn); }
-      else Object.assign(turn, { ...incomingTurn, items: mergeItems(turn.items || [], incomingTurn.items) });
-      thread.status = method === 'turn/started' ? 'active' : method === 'turn/completed' ? 'idle' : thread.status;
-    }
-    if (p.item && turn) mergeItems(turn.items, [compactItem(p.item)]);
+    if (method === 'error') {
+      if (!turn) return null;
+      turn.runtimeNotice = { ...p.error, willRetry: p.willRetry === true };
+      if (!p.willRetry) turn.error = p.error;
+      return turn;
+    }
+    if (!turn && p.turnId && p.item) { turn = { id: p.turnId, status: 'inProgress', items: [] }; thread.turns.push(turn); }
+    if (p.turn) {
+      const incomingTurn = compactTurn(p.turn);
+      if (!turn) { turn = incomingTurn; thread.turns.push(turn); }
+      else Object.assign(turn, { ...incomingTurn, items: mergeItems(turn.items || [], incomingTurn.items) });
+      thread.status = method === 'turn/started' ? 'active' : method === 'turn/completed' ? 'idle' : thread.status;
+      const updatedAt = method === 'turn/completed' ? p.turn.completedAt : method === 'turn/started' ? p.turn.startedAt : null;
+      if (Number(updatedAt) > 0) thread.updatedAt = Math.max(Number(thread.updatedAt) || 0, Math.floor(Number(updatedAt)));
+    }
+    if (turn && (method.startsWith('item/') || method === 'turn/completed' || method === 'turn/started')) turn.runtimeNotice = null;
+    if (p.item && turn) mergeItems(turn.items, [compactItem(p.item)]);
     const item = turn?.items.find(item => item.id === p.itemId);
     if (item) {
       if (method === 'item/agentMessage/delta') item.text = (item.text || '') + p.delta;
@@ -61,8 +140,16 @@
         item.summary ||= []; item.summary[p.summaryIndex] = (item.summary[p.summaryIndex] || '') + p.delta;
       }
       if (method === 'item/reasoning/summaryPartAdded') { item.summary ||= []; item.summary[p.summaryIndex] ??= ''; }
-    }
-    return turn || (['thread/status/changed', 'thread/name/updated'].includes(method) ? thread.turns.at(-1) : null);
+    }
+    const updates = snapshotUpdates.get(thread);
+    if (turn && updates) {
+      if (!updates.has(turn.id)) updates.set(turn.id, new Map());
+      const changed = updates.get(turn.id);
+      for (const id of [p.item?.id, p.itemId, ...(p.turn?.items || []).map(value => value.id)]) {
+        if (id) changed.set(id, changed.get(id) || method === 'item/completed' || method === 'turn/completed');
+      }
+    }
+    return turn || (['thread/status/changed', 'thread/name/updated'].includes(method) ? thread.turns.at(-1) : null);
   }
   function mergeAvailable(previous, incoming) {
     const result = { ...previous };
@@ -86,11 +173,11 @@
     constructor(changed = () => {}) { this.changed = changed; this.generation = 0; this.reset(); }
     reset() { this.generation++; this.value = null; this.pending = null; this.updates = []; this.changed(null); }
     update(params) {
-      if (!this.value) { this.updates.push(params); return; }
+      if (!this.value || this.pending) this.updates.push(params);
+      if (!this.value) return;
       this.value = mergeUsage(this.value, params); this.changed(this.value);
     }
     read(fetchSnapshot) {
-      if (this.value) return Promise.resolve(this.value);
       if (this.pending) return this.pending;
       const generation = this.generation;
       const job = Promise.resolve().then(fetchSnapshot).then(snapshot => {
@@ -98,7 +185,9 @@
         if (!snapshot?.rateLimits) throw new Error('电脑未返回用量数据');
         this.value = this.updates.reduce(mergeUsage, snapshot); this.updates = [];
         this.changed(this.value); return this.value;
-      }).finally(() => { if (this.pending === job) this.pending = null; });
+      }).finally(() => {
+        if (this.pending === job) { this.pending = null; if (this.value) this.updates = []; }
+      });
       this.pending = job; return job;
     }
   }
@@ -125,9 +214,9 @@
     let index = 0;
     return projects.map(project => project.hostId === 'local' ? local[index++] : project);
   }
-  function threadProjectId(thread, projects) {
-    if (Object.hasOwn(thread, 'projectId')) return thread.projectId || null;
-    const cwd = projectRootKey(thread.cwd);
+  function threadProjectId(thread, projects) {
+    if (Object.hasOwn(thread, 'projectId')) return thread.projectId || null;
+    const cwd = projectRootKey(thread.cwd);
     let match = null, length = -1;
     for (const project of projects) for (const root of project.roots) {
       const key = projectRootKey(root.path);
@@ -135,20 +224,28 @@
         match = project.id; length = key.length;
       }
     }
-    return match;
-  }
-  function projectlessThreadTarget(cwd = '') {
-    return { projectId: null, runtimeWorkspaceRoots: [], ...(cwd ? { cwd } : {}) };
-  }
-  async function updateSettings(request, contexts, notifications, threadId, model, effort, serviceTier) {
+    return match;
+  }
+  function catalogThreadProjectId(thread, projects) {
+    if (thread.projectId) return thread.projectId;
+    const local = thread.environments?.find(environment => environment.environmentId === 'local');
+    if (local && Array.isArray(local.runtimeWorkspaceRoots)) {
+      for (const root of local.runtimeWorkspaceRoots) {
+        const projectId = threadProjectId({ cwd: root }, projects);
+        if (projectId) return projectId;
+      }
+      return null;
+    }
+    return threadProjectId({ cwd: thread.cwd }, projects);
+  }
+  function projectlessThreadTarget(cwd = '') {
+    return { projectId: null, runtimeWorkspaceRoots: [], ...(cwd ? { cwd } : {}) };
+  }
+  async function updateSettings(request, contexts, threadId, model, effort, serviceTier) {
     if (serviceTier !== undefined && serviceTier !== null && !['priority', 'fast'].includes(serviceTier)) throw new Error('不支持的快速模式设置');
-    const previous = notifications.get(threadId);
     await request('thread/settings/update', { threadId, model, effort, ...(serviceTier !== undefined ? { serviceTier } : {}) });
-    // The RPC acknowledges the update. Prefer any settings notification already received,
-    // but do not wait for a second acknowledgement or require exact normalized field values.
-    if (notifications.get(threadId) === previous) {
-      contexts.set(threadId, { ...contexts.get(threadId), model, thinking: effort, ...(serviceTier !== undefined ? { serviceTier } : {}) });
-    }
+    // The RPC only acknowledges queuing. Current settings come from
+    // thread/settings/updated, including any server-normalized values.
     return contexts.get(threadId);
   }
   const permissionPresets = {
@@ -238,14 +335,22 @@
     }
     return optionsCache.context(threadId, contexts.get(threadId));
   }
-  async function createThread(request, target, input, settings) {
+  async function createThread(request, target, input, settings, additionalContext) {
     const { thread } = await request('thread/start', target);
-    await request('turn/start', { threadId:thread.id, input,
+    const started = await request('turn/start', { threadId:thread.id, input,
+      ...mobileTurnSource(settings.clientUserMessageId, settings.containsVoiceInput),
+      ...(additionalContext ? { additionalContext: { ...additionalContext,
+        ...mobileTurnSource(settings.clientUserMessageId, settings.containsVoiceInput).additionalContext } } : {}),
       ...(settings.clientUserMessageId ? { clientUserMessageId:settings.clientUserMessageId } : {}),
       ...(settings.model ? { model:settings.model } : {}),
       ...(settings.thinking ? { effort:settings.thinking } : {}),
       ...(settings.serviceTier !== undefined ? { serviceTier:settings.serviceTier } : {}) });
-    return { threadId:thread.id };
+    return { threadId:thread.id, turnId:started?.turn?.id || null };
+  }
+  function projectThreadTarget(project) {
+    const roots = project.roots.map(root => root.path);
+    return { projectId: project.id || project.projectId, runtimeWorkspaceRoots: roots,
+      ...(roots.length ? { cwd: roots[0] } : {}) };
   }
   async function readQueueItems(request, threadId) {
     const items = []; let cursor = null;
@@ -258,13 +363,14 @@
   async function readQueue(request, threadId) {
     const items = await readQueueItems(request, threadId);
     return { items: items.map(item => ({ id: item.id, clientUserMessageId: item.clientUserMessageId,
-      prompt: item.input.filter(part => part.type === 'text').map(part => part.text).join('\n') || '图片',
-      text: item.input.filter(part => part.type === 'text').map(part => part.text).join('\n'),
+      prompt: item.input.filter(part => part.type === 'text' && !isMobileInputNotice(part)).map(part => part.text).join('\n') || '图片',
+      text: item.input.filter(part => part.type === 'text' && !isMobileInputNotice(part)).map(part => part.text).join('\n'),
       attachments: item.input.filter(part => ['image', 'localImage'].includes(part.type)).map(part => part.type === 'image'
         ? { type:'image', available:true, url:part.url } : { type:'image', available:false, remotePath:part.path }),
       createdAt: item.createdAt ?? '', error: '', native: true })) };
   }
-  async function addQueue(request, threadId, input, clientUserMessageId) {
+  async function addQueue(request, threadId, input, clientUserMessageId, containsVoiceInput = false) {
+    input = [...input, { type: 'text', text: containsVoiceInput === true ? voiceInputNotice : mobileInputNotice }];
     await request('thread/queue/add', { threadId, input, clientUserMessageId });
     return readQueue(request, threadId);
   }
@@ -272,10 +378,14 @@
     if (action === 'steer') {
       const item = (await readQueueItems(request, threadId)).find(item => item.id === queuedSubmissionId);
       if (!item) throw new Error('该排队消息已不在队列中');
-      const { thread } = await request('thread/read', { threadId, includeTurns: true });
-      const active = thread.turns.findLast(turn => turn.status === 'inProgress');
-      if (active) {
-        await request('turn/steer', { threadId, expectedTurnId: active.id, input: item.input,
+      const page = await request('thread/turns/list', {
+        threadId, limit: 1, sortDirection: 'desc', itemsView: 'summary',
+      });
+      const active = page.data?.[0];
+      if (active?.status === 'inProgress') {
+        const { turnTrigger, ...source } = mobileTurnSource(item.clientUserMessageId, item.input.some(isVoiceInputNotice));
+        await request('turn/steer', { threadId, expectedTurnId: active.id, input: item.input.filter(part => !isMobileInputNotice(part)),
+          ...source,
           clientUserMessageId: item.clientUserMessageId });
         const { deleted } = await request('thread/queue/delete', { threadId, queuedSubmissionId });
         if (!deleted) throw new Error('引导已提交，但原排队消息未删除，请检查队列，勿重复引导');
@@ -287,6 +397,16 @@
     }
     return readQueue(request, threadId);
   }
-  return { createThread, readQueue, addQueue, changeQueue, compactItem, compactTurn, mergeItems, applyNotification, mergeUsage, UsageCache, readProjects, orderDesktopProjects, threadProjectId, projectlessThreadTarget, updateSettings,
-    permissionState, availablePermissionModes, PermissionOptionsCache, updatePermissions };
+  function mobileTurnSource(clientUserMessageId, containsVoiceInput = false) {
+    return {
+      turnTrigger: 'code_relax_mobile',
+      responsesapiClientMetadata: { code_relax_client: 'mobile', ...(containsVoiceInput === true ? { code_relax_input: 'speech_to_text' } : {}) },
+      additionalContext: { code_relax_mobile: {
+        kind: 'application',
+        value: `${mobileOrigin} Client message ID: ${clientUserMessageId || 'unknown'}.${containsVoiceInput === true ? ` ${voiceGuidance}` : ''}`,
+      } },
+    };
+  }
+  return { isMobileInputNotice, parseCodexDelegation, toolDelegation, projectThreadTarget, createThread, readQueue, addQueue, changeQueue, compactItem, compactTurn, beginSnapshot, mergeItems, applyNotification, mergeUsage, UsageCache, readProjects, orderDesktopProjects, threadProjectId, catalogThreadProjectId, projectlessThreadTarget, updateSettings,
+    permissionState, availablePermissionModes, PermissionOptionsCache, updatePermissions, mobileTurnSource };
 });

package/dist/shared/code-browser.cjs

@@ -0,0 +1,159 @@
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) module.exports = factory();
+  else root.CodeBrowserProtocol = factory();
+})(globalThis, function () {
+  const maxBytes = 1024 * 1024, maxEntries = 4000, maxLines = 20000;
+  const maxFileBytes = 20 * 1024 * 1024, imageChunkBytes = 3 * 1024 * 1024;
+  const mediaTypes = { jpg:'image/jpeg', jpeg:'image/jpeg', png:'image/png', webp:'image/webp', gif:'image/gif', bmp:'image/bmp', heic:'image/heic', heif:'image/heif', avif:'image/avif', tif:'image/tiff', tiff:'image/tiff', svg:'image/svg+xml', ico:'image/x-icon', mp4:'video/mp4', m4v:'video/mp4', mov:'video/quicktime', webm:'video/webm', mkv:'video/x-matroska', avi:'video/x-msvideo', '3gp':'video/3gpp', '3g2':'video/3gpp2', mpg:'video/mpeg', mpeg:'video/mpeg', m2ts:'video/mp2t', flv:'video/x-flv', wmv:'video/x-ms-wmv' };
+  const mediaMime = file => file.mimeType || (/^(image|video)\//.test(file.type || '') ? file.type : '') || mediaTypes[(file.name || file.path || '').split('.').at(-1).toLowerCase()] || '';
+  const mediaKind = file => file.mediaKind || (/^image\//.test(mediaMime(file)) ? 'image' : /^video\//.test(mediaMime(file)) ? 'video' : '');
+  function imageMime(bytes) {
+    const ascii = (start, count) => String.fromCharCode(...bytes.slice(start, start + count));
+    if (bytes[0] === 137 && ascii(1, 3) === 'PNG' && bytes[4] === 13 && bytes[5] === 10 && bytes[6] === 26 && bytes[7] === 10) return 'image/png';
+    if (bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255) return 'image/jpeg';
+    if (['GIF87a', 'GIF89a'].includes(ascii(0, 6))) return 'image/gif';
+    if (ascii(0, 4) === 'RIFF' && ascii(8, 4) === 'WEBP') return 'image/webp';
+    fail('不支持此图片格式，当前支持 PNG、JPEG、GIF、WebP。', 415);
+  }
+  function fail(message, statusCode = 400) { throw Object.assign(new Error(message), { statusCode }); }
+  function canonical(value) {
+    return String(value || '').replaceAll('\\', '/').replace(/\/+$/, '');
+  }
+  function key(value) {
+    const p = canonical(value);
+    return /^[a-z]:\//i.test(p) || p.startsWith('//') ? p.toLowerCase() : p;
+  }
+  function inside(base, candidate) {
+    const a = key(base), b = key(candidate);
+    return b === a || b.startsWith(a + '/');
+  }
+  function relative(base, candidate) {
+    if (!inside(base, candidate)) return null;
+    return canonical(candidate).slice(canonical(base).length).replace(/^\//, '');
+  }
+  function child(base, value = '') {
+    if (typeof value !== 'string' || /[\\:\x00-\x1f]/.test(value) || value.startsWith('/') ||
+        value.split('/').some(p => p === '..' || p === '.' || (p && /[. ]$/.test(p)))) fail('无效的项目相对路径。');
+    return canonical(base) + (value ? '/' + value : '') || '/';
+  }
+  async function context(rpc, query) {
+    const threadId = query.get('threadId'), projectId = query.get('projectId');
+    let thread, project;
+    if (threadId) ({ thread } = await rpc('thread/read', { threadId, includeTurns: false }));
+    const id = thread?.projectId || (!threadId && projectId);
+    if (id && id !== '__unassigned__') ({ project } = await rpc('project/read', { projectId: id }));
+    const roots = [];
+    const add = (p, source) => {
+      if (typeof p !== 'string' || !p || roots.some(r => key(r.path) === key(p))) return;
+      roots.push({ path: p, source });
+    };
+    for (const r of project?.roots || []) add(r.path, '项目');
+    const environments = thread?.environments || [];
+    const local = environments.find(e => e.environmentId === 'local');
+    if (environments.length && !local) fail('当前会话使用远程执行环境，暂不支持本机文件浏览。', 409);
+    const cwd = local?.cwd || thread?.cwd || '';
+    // Runtime access roots include tool output directories, not project membership.
+    if (!project && cwd) add(cwd, '工作目录');
+    if (!roots.length) fail('请先选择一个项目或对话。', 404);
+    return { roots, cwd, projectName: project?.name || '', threadId };
+  }
+  function selectedRoot(context, query) {
+    const root = context.roots.find(r => key(r.path) === key(query.get('root')));
+    if (!root) fail('目录不属于当前项目或会话，请刷新后重试。', 403);
+    return root.path;
+  }
+  function directory(result) {
+    if (!Array.isArray(result.entries)) fail('工作站没有返回目录条目。', 502);
+    if (result.entries.length > maxEntries) fail('此目录超过 4000 项，暂不支持浏览。', 413);
+    const entries = result.entries.map(e => {
+      if (!e.fileName || /[/\\:\x00-\x1f]/.test(e.fileName) || ['.', '..'].includes(e.fileName)) fail('目录条目名称无效。', 502);
+      return { name: e.fileName, directory: e.isDirectory === true, file: e.isFile === true };
+    });
+    entries.sort((a, b) => Number(b.directory) - Number(a.directory) || a.name.localeCompare(b.name));
+    return { entries };
+  }
+  function decode(bytes) {
+    if (bytes.length > maxBytes) fail('文件超过只读预览上限（1 MiB）。', 413);
+    let encoding = 'utf-8';
+    if (bytes[0] === 255 && bytes[1] === 254) encoding = 'utf-16le';
+    else if (bytes[0] === 254 && bytes[1] === 255) encoding = 'utf-16be';
+    let text;
+    try { text = new TextDecoder(encoding, { fatal: true }).decode(bytes); }
+    catch { fail('此文件不是可识别的 UTF-8/UTF-16 文本，暂不支持预览。', 415); }
+    if (/[\x00-\x08\x0e-\x1f]/.test(text)) fail('此文件包含二进制内容，暂不支持文本预览。', 415);
+    if (text.split('\n').length > maxLines) fail('文件超过 20000 行，暂不支持预览。', 413);
+    return { text, encoding, size: bytes.length };
+  }
+  function fromBase64(value) {
+    if (typeof value !== 'string') fail('工作站没有返回文件内容。', 502);
+    if (value.length > Math.ceil(maxBytes / 3) * 4) fail('文件超过只读预览上限（1 MiB）。', 413);
+    const { encoding, size } = decode(Uint8Array.from(atob(value), c => c.charCodeAt(0)));
+    return { dataBase64: value, encoding, size };
+  }
+  function diffLines(text) {
+    let old = 0, newer = 0, oldLeft = 0, newLeft = 0;
+    return text.replace(/\r\n/g, '\n').split('\n').map(text => {
+      const row = { text, old: '', newer: '', kind: '' };
+      const hunk = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/.exec(text);
+      if (hunk) {
+        old = Number(hunk[1]); oldLeft = Number(hunk[2] ?? 1);
+        newer = Number(hunk[3]); newLeft = Number(hunk[4] ?? 1); row.kind = 'hunk';
+      } else if (text.startsWith('+') && newLeft > 0) {
+        row.newer = newer++; newLeft--; row.kind = 'add';
+      } else if (text.startsWith('-') && oldLeft > 0) {
+        row.old = old++; oldLeft--; row.kind = 'remove';
+      } else if (text.startsWith(' ') && oldLeft > 0 && newLeft > 0) {
+        row.old = old++; row.newer = newer++; oldLeft--; newLeft--;
+      } else if (!text.startsWith('\\')) { oldLeft = 0; newLeft = 0; }
+      return row;
+    });
+  }
+  async function change(rpc, query) {
+    const threadId = query.get('threadId'), turnId = query.get('turnId');
+    const itemId = query.get('itemId'), path = query.get('path');
+    if (!threadId || !turnId || !itemId || !path) fail('缺少文件修改记录的定位信息。');
+    let cursor;
+    do {
+      // Only an explicit detail click reads raw items, within the selected turn.
+      const page = await rpc('thread/items/list', { threadId, turnId, limit: 100,
+        sortDirection: 'desc', ...(cursor ? { cursor } : {}) });
+      const item = page.data?.find(entry => entry.turnId === turnId && entry.item?.id === itemId)?.item;
+      if (item) {
+        const file = item.type === 'fileChange' && item.changes?.find(value => value.path === path);
+        if (!file) fail('这条修改记录中没有该文件。', 404);
+        const diff = typeof file.diff === 'string' ? file.diff : file.diff?.text;
+        if (typeof diff !== 'string') fail('此条目未提供真实 diff。', 404);
+        if (new TextEncoder().encode(diff).length > maxBytes || diff.split('\n').length > maxLines) fail('此项 diff 超过预览上限。', 413);
+        return { diff, turnId };
+      }
+      if (page.nextCursor && page.nextCursor === cursor) fail('修改记录分页位置未推进。', 502);
+      cursor = page.nextCursor;
+    } while (cursor);
+    fail('未找到这条文件修改记录。', 404);
+  }
+  async function changes(rpc, query) {
+    const threadId = query.get('threadId');
+    if (!threadId) fail('请先选择对话以查看修改记录。');
+    const cursor = query.get('cursor');
+    const page = await rpc('thread/items/list', { threadId, limit: 20, sortDirection: 'desc', ...(cursor ? { cursor } : {}) });
+    const changes = []; let diffBytes = 0;
+    for (const entry of page.data || []) {
+      if (entry.item?.type !== 'fileChange') continue;
+      for (const change of entry.item.changes || []) {
+        const diff = typeof change.diff === 'string' ? change.diff : change.diff?.text;
+        const bytes = typeof diff === 'string' ? new TextEncoder().encode(diff).length : 0;
+        const tooLarge = typeof diff === 'string' && (bytes + diffBytes > maxBytes || diff.split('\n').length > maxLines);
+        if (!tooLarge) diffBytes += bytes;
+        changes.push({ path: change.path, kind: change.kind, turnId: entry.turnId, itemId: entry.item.id,
+          diff: tooLarge ? null : diff ?? null, error: tooLarge ? '此项 diff 超过预览上限。' : '' });
+      }
+    }
+    // Return an explicit page even when it has no file changes. Never scan a whole thread implicitly.
+    return { changes, nextCursor: page.nextCursor || null, scope: '对话文件修改记录（按操作展示）' };
+  }
+  function isTextFile(name) {
+    const base = String(name || '').replaceAll('\\', '/').split('/').at(-1);
+    return !base.includes('.') || (base.startsWith('.') && !base.slice(1).includes('.')) || /\.(txt|log|md|markdown|rst|csv|tsv|json5?|jsonl|ipynb|ya?ml|toml|ini|cfg|conf|config|xml|xaml|svg|html?|css|scss|less|[cm]?js|jsx|ts|tsx|ets|py|rs|go|java|kt|kts|c|cc|cpp|cxx|h|hpp|cs|swift|m|mm|sh|bash|zsh|ps1|bat|cmd|sql|r|rb|php|vue|svelte|gradle|properties|cmake|make|diff|patch)$/i.test(base);
+  }
+  return { isTextFile, maxBytes, maxEntries, maxLines, maxFileBytes, mediaMime, mediaKind, imageChunkBytes, imageMime, fail, key, inside, relative, child, context, selectedRoot, directory, decode, fromBase64, diffLines, change, changes };
+});

package/dist/shared/file-changes.cjs

@@ -0,0 +1,31 @@
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) module.exports = factory();
+  else root.CodexFileChanges = factory();
+})(globalThis, function () {
+  function lineCounts(change) {
+    const diff = typeof change.diff === 'string' ? change.diff : change.diff?.text;
+    if (typeof diff !== 'string') return { added: change.lineCounts?.added || 0, removed: change.lineCounts?.removed || 0 };
+    const kind = typeof change.kind === 'string' ? change.kind : change.kind?.type;
+    if (kind === 'add' || kind === 'delete') {
+      // app-server sends the full file content, not a unified diff, for add/delete.
+      const lines = diff ? diff.split('\n').length - Number(diff.endsWith('\n')) : 0;
+      return { added: kind === 'add' ? lines : 0, removed: kind === 'delete' ? lines : 0 };
+    }
+    let added = 0, removed = 0, oldLeft = 0, newLeft = 0;
+    for (const line of diff.split(/\r?\n/)) {
+      const hunk = /^@@ -\d+(?:,(\d+))? \+\d+(?:,(\d+))? @@/.exec(line);
+      if (hunk) { oldLeft = Number(hunk[1] ?? 1); newLeft = Number(hunk[2] ?? 1); }
+      else if (line.startsWith('+') && newLeft > 0) { added++; newLeft--; }
+      else if (line.startsWith('-') && oldLeft > 0) { removed++; oldLeft--; }
+      else if (line.startsWith(' ') && oldLeft > 0 && newLeft > 0) { oldLeft--; newLeft--; }
+      else if (!line.startsWith('\\')) { oldLeft = 0; newLeft = 0; }
+    }
+    return { added, removed };
+  }
+  function summarize(changes) {
+    return (Array.isArray(changes) ? changes : []).map(change => ({
+      path: change.path, kind: change.kind, lineCounts: lineCounts(change),
+    }));
+  }
+  return { lineCounts, summarize };
+});