@walkhi/code-relax 0.1.0-beta.11 → 0.1.0-beta.13

package/dist/src/shared-app-server.mjs

@@ -4,37 +4,37 @@ import { randomUUID } from 'node:crypto';
 import events from '../shared/app-server-events.cjs';
 import serverRequests from '../shared/server-requests.cjs';
 
-const syncTokenTtlMs = 30_000;
-const syncBufferMaxBytes = 8 * 1024 * 1024;
-const historyPageMaxTurns = 8;
-const historyPageMaxBytes = 500 * 1024;
-const turnItemPageSize = 50;
-const writerConflictMessages = ['already has an active writer', 'already has a live local writer'];
-
-export class ThreadWriterConflictError extends Error {
-  constructor(threadId, message) {
-    super('该对话正在另一个 Codex 实例中使用。');
-    this.name = 'ThreadWriterConflictError';
-    this.code = 'thread_writer_owned_elsewhere';
-    this.threadId = threadId;
-    this.readOnly = true;
-    this.details = message;
-  }
-}
-
-export function isThreadWriterConflict(error) {
-  const message = String(error?.message || error).toLowerCase();
-  return error instanceof ThreadWriterConflictError || writerConflictMessages.some(text => message.includes(text));
-}
+const syncTokenTtlMs = 30_000;
+const syncBufferMaxBytes = 8 * 1024 * 1024;
+const historyPageMaxTurns = 8;
+const historyPageMaxBytes = 500 * 1024;
+const turnItemPageSize = 50;
+const writerConflictMessages = ['already has an active writer', 'already has a live local writer'];
+
+export class ThreadWriterConflictError extends Error {
+  constructor(threadId, message) {
+    super('该对话正在另一个 Codex 实例中使用。');
+    this.name = 'ThreadWriterConflictError';
+    this.code = 'thread_writer_owned_elsewhere';
+    this.threadId = threadId;
+    this.readOnly = true;
+    this.details = message;
+  }
+}
+
+export function isThreadWriterConflict(error) {
+  const message = String(error?.message || error).toLowerCase();
+  return error instanceof ThreadWriterConflictError || writerConflictMessages.some(text => message.includes(text));
+}
 
 // Connect to the Desktop's existing execution service; never spawn or adopt a task.
 export class SharedAppServer extends EventEmitter {
   constructor(url) {
     super();
     const address = new URL(url);
-    if (address.protocol !== 'ws:' || address.hostname !== '127.0.0.1') throw new Error('Codex 内核必须使用本机回环 WebSocket。');
-    this.url = url;
-    this.serverVersion = '';
+    if (address.protocol !== 'ws:' || address.hostname !== '127.0.0.1') throw new Error('Codex 内核必须使用本机回环 WebSocket。');
+    this.url = url;
+    this.serverVersion = '';
     this.epoch = randomUUID();
     this.sequence = 0;
     this.pending = new Map();
@@ -42,10 +42,10 @@ export class SharedAppServer extends EventEmitter {
     this.threads = new Map();
     this.contexts = new Map();
     this.settingsNotifications = new Map();
-    this.permissionOptions = new events.PermissionOptionsCache();
-    this.subscriptions = new Map();
-    this.operationGroups = new Map();
-    this.usageCache = new events.UsageCache(value => this.emit('usage', value));
+    this.permissionOptions = new events.PermissionOptionsCache();
+    this.subscriptions = new Map();
+    this.operationGroups = new Map();
+    this.usageCache = new events.UsageCache(value => this.emit('usage', value));
   }
 
   async connect() {
@@ -57,9 +57,9 @@ export class SharedAppServer extends EventEmitter {
 
   async open() {
     const socket = new WebSocket(this.url, { handshakeTimeout: 5000 });
-    this.socket = socket;
-    this.ready = false;
-    this.serverVersion = '';
+    this.socket = socket;
+    this.ready = false;
+    this.serverVersion = '';
     this.serverRequests.reset(randomUUID());
     socket.on('message', bytes => {
       let message;
@@ -70,25 +70,25 @@ export class SharedAppServer extends EventEmitter {
       if (!pending) return;
       this.pending.delete(message.id);
       clearTimeout(pending.timer);
-      if (message.error) {
-        const text = String(message.error.message || 'app-server 请求失败');
-        pending.reject(writerConflictMessages.some(value => text.toLowerCase().includes(value))
-          ? new ThreadWriterConflictError(pending.threadId, text)
-          : Object.assign(new Error(text), { rpcCode: message.error.code, details: message.error.data }));
-      }
+      if (message.error) {
+        const text = String(message.error.message || 'app-server 请求失败');
+        pending.reject(writerConflictMessages.some(value => text.toLowerCase().includes(value))
+          ? new ThreadWriterConflictError(pending.threadId, text)
+          : Object.assign(new Error(text), { rpcCode: message.error.code, details: message.error.data }));
+      }
       else pending.resolve(message.result);
     });
-    socket.on('close', () => {
-      this.ready = false;
-      this.serverVersion = '';
+    socket.on('close', () => {
+      this.ready = false;
+      this.serverVersion = '';
       for (const pending of this.pending.values()) {
         clearTimeout(pending.timer);
-        pending.reject(new Error('Codex 内核连接断开；发送结果可能未确认，请检查对话后再操作。'));
+        pending.reject(new Error('Codex 内核连接断开；发送结果可能未确认，请检查对话后再操作。'));
       }
-      this.pending.clear();
-      this.serverRequests.reset(randomUUID());
-      this.threads.clear();
-      this.operationGroups.clear();
+      this.pending.clear();
+      this.serverRequests.reset(randomUUID());
+      this.threads.clear();
+      this.operationGroups.clear();
       for (const slot of this.subscriptions.values()) clearTimeout(slot.expiry);
       this.subscriptions.clear();
       this.contexts.clear();
@@ -100,10 +100,10 @@ export class SharedAppServer extends EventEmitter {
     socket.on('error', () => {}); // open/request reports the connection error to the caller.
     await new Promise((resolve, reject) => { socket.once('open', resolve); socket.once('error', reject); });
     try {
-      const initialized = await this.request('initialize', { clientInfo: { name: 'codex_remote_shared', version: '1.0.0' }, capabilities: { experimentalApi: true } });
-      // The first user-agent product reports the running server build, not the
-      // selected executable that may only take effect after a future restart.
-      this.serverVersion = String(initialized?.userAgent || '').match(/^[^\s/]+\/([^\s]+)/)?.[1] || '';
+      const initialized = await this.request('initialize', { clientInfo: { name: 'codex_remote_shared', version: '1.0.0' }, capabilities: { experimentalApi: true } });
+      // The first user-agent product reports the running server build, not the
+      // selected executable that may only take effect after a future restart.
+      this.serverVersion = String(initialized?.userAgent || '').match(/^[^\s/]+\/([^\s]+)/)?.[1] || '';
       socket.send(JSON.stringify({ method: 'initialized' }));
       this.ready = true;
       this.usageCache.read(() => this.request('account/rateLimits/read')).catch(error => this.emit('usage-error', error));
@@ -117,7 +117,7 @@ export class SharedAppServer extends EventEmitter {
         this.pending.delete(id);
         reject(new Error(`${method} 超时；不会自动重发，请先检查对话。`));
       }, 30000);
-      this.pending.set(id, { resolve, reject, timer, threadId: params?.threadId });
+      this.pending.set(id, { resolve, reject, timer, threadId: params?.threadId });
       this.socket.send(JSON.stringify({ id, method, params }), error => {
         if (!error || !this.pending.delete(id)) return;
         clearTimeout(timer); reject(error);
@@ -130,26 +130,26 @@ export class SharedAppServer extends EventEmitter {
     return events.readProjects((method, params) => this.request(method, params));
   }
 
-  async send(args) {
-    await this.connect();
-    this.requireWritable(args.threadId);
+  async send(args) {
+    await this.connect();
+    this.requireWritable(args.threadId);
     // Reading the live thread checks this service owns it without resume changing settings.
-    const { thread } = await this.request('thread/read', { threadId: args.threadId, includeTurns: false });
-    const status = typeof thread.status === 'string' ? thread.status : thread.status?.type;
-    if (status === 'active') {
-      const page = await this.request('thread/turns/list', {
-        threadId: args.threadId, limit: 1, sortDirection: 'desc', itemsView: 'summary',
-      });
-      const active = page.data?.[0];
-      if (active?.status !== 'inProgress') throw new Error('活动轮次已变化，请刷新后再发送。');
+    const { thread } = await this.request('thread/read', { threadId: args.threadId, includeTurns: false });
+    const status = typeof thread.status === 'string' ? thread.status : thread.status?.type;
+    if (status === 'active') {
+      const page = await this.request('thread/turns/list', {
+        threadId: args.threadId, limit: 1, sortDirection: 'desc', itemsView: 'summary',
+      });
+      const active = page.data?.[0];
+      if (active?.status !== 'inProgress') throw new Error('活动轮次已变化，请刷新后再发送。');
       return this.request('turn/steer', { threadId: args.threadId, expectedTurnId: active.id, input: args.input, ...(args.clientUserMessageId ? { clientUserMessageId: args.clientUserMessageId } : {}) });
     }
     return this.request('turn/start', args);
   }
 
-  respondApproval(threadId, body) {
-    if (!this.ready || this.socket?.readyState !== WebSocket.OPEN) throw new Error('Codex 内核未就绪');
-    this.requireWritable(threadId);
+  respondApproval(threadId, body) {
+    if (!this.ready || this.socket?.readyState !== WebSocket.OPEN) throw new Error('Codex 内核未就绪');
+    this.requireWritable(threadId);
     return this.serverRequests.respond(threadId, body, message => new Promise((resolve, reject) => {
       this.socket.send(JSON.stringify(message), error => error ? reject(error) : resolve());
     }));
@@ -172,20 +172,20 @@ export class SharedAppServer extends EventEmitter {
     if (method === 'thread/tokenUsage/updated') {
       this.contexts.set(id, { ...this.contexts.get(id), tokenUsage: params.tokenUsage });
       return;
-    }
-    const record = this.threads.get(id);
-    if (!record) return;
-    const current = params.turn?.id ? record.thread.turns?.find(turn => turn.id === params.turn.id) : null;
-    const groupedHistory = current?.items?.some(item => item?.type === 'lazyOperationGroup');
-    const appliedParams = groupedHistory && method === 'turn/completed' && Array.isArray(params.turn?.items)
-      ? { ...params, turn: { ...params.turn,
-        items: params.turn.items.filter(item => ['userMessage', 'agentMessage'].includes(item?.type)) } }
-      : params;
-    const turn = events.applyNotification(record.thread, method, appliedParams);
-    if (turn) {
-      const sequence = ++record.sequence;
+    }
+    const record = this.threads.get(id);
+    if (!record) return;
+    const current = params.turn?.id ? record.thread.turns?.find(turn => turn.id === params.turn.id) : null;
+    const groupedHistory = current?.items?.some(item => item?.type === 'lazyOperationGroup');
+    const appliedParams = groupedHistory && method === 'turn/completed' && Array.isArray(params.turn?.items)
+      ? { ...params, turn: { ...params.turn,
+        items: params.turn.items.filter(item => ['userMessage', 'agentMessage'].includes(item?.type)) } }
+      : params;
+    const turn = events.applyNotification(record.thread, method, appliedParams);
+    if (turn) {
+      const sequence = ++record.sequence;
       record.changes.set(turn.id, { sequence, turn });
-      record.changeBytes += Buffer.byteLength(JSON.stringify({ method, params: appliedParams }));
+      record.changeBytes += Buffer.byteLength(JSON.stringify({ method, params: appliedParams }));
       if (record.changeBytes > syncBufferMaxBytes) {
         record.recoverAfter = sequence;
         record.changes.clear(); record.changeBytes = 0;
@@ -196,51 +196,51 @@ export class SharedAppServer extends EventEmitter {
     if (method === 'turn/completed') record.thread.turns = record.thread.turns.slice(-10);
   }
 
-  async timeline(threadId, pageOptions = {}) {
+  async timeline(threadId, pageOptions = {}) {
     await this.connect();
     const slot = this.slot(threadId);
     const task = slot.tail.then(async () => {
-      let record = this.threads.get(threadId);
-      if (record?.readOnly) {
-        this.threads.delete(threadId);
-        this.contexts.delete(threadId);
-        record = null;
-      }
-      if (!record) {
-        let result;
-        try {
-          result = await this.request('thread/resume', { threadId, excludeTurns: true,
-            initialTurnsPage: { limit: 1, sortDirection: 'desc', itemsView: 'summary' } });
-        } catch (error) {
-          if (!isThreadWriterConflict(error)) throw error;
-          const [read, page] = await Promise.all([
-            this.request('thread/read', { threadId, includeTurns: false }),
-            this.request('thread/turns/list', {
-              threadId, limit: historyPageMaxTurns, sortDirection: 'desc', itemsView: 'summary',
-            }),
-          ]);
-          const compact = await Promise.all([...(page.data || [])].reverse().map(turn => this.compactTurn(threadId, turn)));
-          const turns = this.fitTurns({ thread: read.thread }, compact, pageOptions);
-          const thread = { ...read.thread, turns, readOnly: true,
-            readOnlyReason: '该对话正在另一个 Codex 实例中使用。' };
-          record = { thread, nextCursor: page.nextCursor ?? null, sequence: 0, recoverAfter: 0,
-            changes: new Map(), changeBytes: 0, tokens: new Map(), readOnly: true };
-          this.threads.set(threadId, record);
-          result = null;
-        }
-        if (result) {
-          if (!Array.isArray(result.initialTurnsPage?.data)) throw new Error('Codex 内核未返回分页历史。');
-          const compact = await Promise.all([...result.initialTurnsPage.data].reverse().map(turn => this.compactTurn(threadId, turn)));
-          const thread = { ...result.thread, turns: compact };
-          record = { thread, nextCursor: result.initialTurnsPage.nextCursor ?? null, sequence: 0,
-            recoverAfter: 0, changes: new Map(), changeBytes: 0, tokens: new Map() };
-          this.threads.set(threadId, record);
-          this.contexts.set(threadId, { ...this.contexts.get(threadId), model: result.model, thinking: result.reasoningEffort, serviceTier: result.serviceTier ?? null,
-            cwd: result.cwd, ...events.permissionState(result) });
-          await this.extendHistoryRecord(threadId, record, pageOptions);
-        }
-      }
-      const id = randomUUID(), expires = Date.now() + syncTokenTtlMs;
+      let record = this.threads.get(threadId);
+      if (record?.readOnly) {
+        this.threads.delete(threadId);
+        this.contexts.delete(threadId);
+        record = null;
+      }
+      if (!record) {
+        let result;
+        try {
+          result = await this.request('thread/resume', { threadId, excludeTurns: true,
+            initialTurnsPage: { limit: 1, sortDirection: 'desc', itemsView: 'summary' } });
+        } catch (error) {
+          if (!isThreadWriterConflict(error)) throw error;
+          const [read, page] = await Promise.all([
+            this.request('thread/read', { threadId, includeTurns: false }),
+            this.request('thread/turns/list', {
+              threadId, limit: historyPageMaxTurns, sortDirection: 'desc', itemsView: 'summary',
+            }),
+          ]);
+          const compact = await Promise.all([...(page.data || [])].reverse().map(turn => this.compactTurn(threadId, turn)));
+          const turns = this.fitTurns({ thread: read.thread }, compact, pageOptions);
+          const thread = { ...read.thread, turns, readOnly: true,
+            readOnlyReason: '该对话正在另一个 Codex 实例中使用。' };
+          record = { thread, nextCursor: page.nextCursor ?? null, sequence: 0, recoverAfter: 0,
+            changes: new Map(), changeBytes: 0, tokens: new Map(), readOnly: true };
+          this.threads.set(threadId, record);
+          result = null;
+        }
+        if (result) {
+          if (!Array.isArray(result.initialTurnsPage?.data)) throw new Error('Codex 内核未返回分页历史。');
+          const compact = await Promise.all([...result.initialTurnsPage.data].reverse().map(turn => this.compactTurn(threadId, turn)));
+          const thread = { ...result.thread, turns: compact };
+          record = { thread, nextCursor: result.initialTurnsPage.nextCursor ?? null, sequence: 0,
+            recoverAfter: 0, changes: new Map(), changeBytes: 0, tokens: new Map() };
+          this.threads.set(threadId, record);
+          this.contexts.set(threadId, { ...this.contexts.get(threadId), model: result.model, thinking: result.reasoningEffort, serviceTier: result.serviceTier ?? null,
+            cwd: result.cwd, ...events.permissionState(result) });
+          await this.extendHistoryRecord(threadId, record, pageOptions);
+        }
+      }
+      const id = randomUUID(), expires = Date.now() + syncTokenTtlMs;
       record.tokens.set(id, { sequence: record.sequence, expires });
       this.scheduleCleanup(threadId, slot);
       return { thread: record.thread, nextCursor: record.nextCursor,
@@ -277,15 +277,15 @@ export class SharedAppServer extends EventEmitter {
     if (record?.tokens.size) { this.scheduleCleanup(threadId, slot); return; }
     slot.tail = slot.tail.then(async () => {
       if (slot.users || this.threads.get(threadId)?.tokens.size) return;
-      this.threads.delete(threadId); this.contexts.delete(threadId); this.permissionOptions.delete(threadId);
-      this.operationGroups.delete(threadId);
+      this.threads.delete(threadId); this.contexts.delete(threadId); this.permissionOptions.delete(threadId);
+      this.operationGroups.delete(threadId);
       this.subscriptions.delete(threadId); clearTimeout(slot.expiry);
-      if (this.ready && !record?.readOnly) await this.request('thread/unsubscribe', { threadId });
-      this.serverRequests.forget(threadId);
+      if (this.ready && !record?.readOnly) await this.request('thread/unsubscribe', { threadId });
+      this.serverRequests.forget(threadId);
     }).catch(error => this.emit('subscription-error', error));
   }
 
-  async acquire(threadId, requested) {
+  async acquire(threadId, requested) {
     const slot = this.slot(threadId);
     let record = this.threads.get(threadId), token;
     if (record && requested?.epoch === this.epoch && requested.id && Number.isSafeInteger(requested.after)) {
@@ -294,7 +294,7 @@ export class SharedAppServer extends EventEmitter {
     }
     let snapshot = false, catchup;
     if (!record || !token) {
-      const fresh = await this.timeline(threadId);
+      const fresh = await this.timeline(threadId);
       record = this.threads.get(threadId); token = record.tokens.get(fresh.sync.id);
       requested = { id: fresh.sync.id, epoch: fresh.sync.epoch, after: fresh.sync.seq };
       snapshot = true;
@@ -319,145 +319,145 @@ export class SharedAppServer extends EventEmitter {
       snapshot, catchup, release };
   }
 
-  pageSettings(options = {}) {
-    return {
-      maxTurns: Math.max(1, Math.min(historyPageMaxTurns, Number(options.maxTurns) || historyPageMaxTurns)),
-      maxBytes: Math.max(1, Number(options.maxBytes) || historyPageMaxBytes),
-      measure: typeof options.measure === 'function' ? options.measure : value => Buffer.byteLength(JSON.stringify(value)),
-    };
-  }
-
-  async compactTurn(threadId, turn) {
-    const compact = events.compactTurn(turn);
-    if (!turn?.id) return compact;
-    const batches = [];
-    let cursor;
-    do {
-      const page = await this.request('thread/items/list', {
-        threadId, turnId: turn.id, ...(cursor ? { cursor } : {}),
-        limit: 100, sortDirection: 'desc',
-      });
-      if (!Array.isArray(page.data)) throw new Error('Codex 内核未返回单轮条目索引。');
-      batches.push(page.data.map(entry => events.compactItem(entry.item)));
-      cursor = page.nextCursor ?? null;
-    } while (cursor);
-    const items = batches.reverse().flatMap(batch => batch.reverse());
-    const groups = new Map(), skeleton = [];
-    let operationItems = [];
-    const flushOperations = () => {
-      if (!operationItems.length) return;
-      const visibleItems = operationItems.filter(item => item?.type !== 'reasoning');
-      operationItems = [];
-      if (!visibleItems.length) return;
-      const subAgentItems = visibleItems.filter(isSubAgentItem);
-      const detailItems = visibleItems.filter(item => !isSubAgentItem(item));
-      if (detailItems.length) {
-        const groupId = `g${groups.size + 1}`;
-        groups.set(groupId, detailItems);
-        skeleton.push({ type: 'lazyOperationGroup', id: `${turn.id}:${groupId}`,
-          turnId: turn.id, groupId,
-          operationTypes: [...new Set(detailItems.map(item => item.type).filter(Boolean))] });
-      }
-      skeleton.push(...subAgentItems);
-    };
-    for (const item of items) {
-      if (['userMessage', 'agentMessage', 'imageGeneration'].includes(item?.type)) {
-        flushOperations();
-        skeleton.push(item);
-      } else operationItems.push(item);
-    }
-    flushOperations();
-    let threadGroups = this.operationGroups.get(threadId);
-    if (!threadGroups) { threadGroups = new Map(); this.operationGroups.set(threadId, threadGroups); }
-    threadGroups.set(turn.id, groups);
-    return { ...compact, items: skeleton };
-  }
-
-  async operationGroupItems(threadId, turnId, groupId, offset) {
-    await this.connect();
-    const items = this.operationGroups.get(threadId)?.get(turnId)?.get(groupId);
-    if (!items) throw new Error('操作组已失效，请重新打开对话。');
-    const start = Math.max(0, Number(offset) || 0);
-    const pageItems = items.slice(start, start + turnItemPageSize);
-    const nextOffset = start + pageItems.length < items.length ? start + pageItems.length : null;
-    return { turnId, groupId, items: pageItems, nextOffset, total: items.length };
-  }
-
-  async turnContext(threadId, turnId) {
-    await this.connect();
-    if (!threadId || !turnId) throw new Error('缺少图片所属的对话或轮次。');
-    return this.compactTurn(threadId, { id: turnId });
-  }
-
-  fitTurns(base, turns, options = {}) {
-    const settings = this.pageSettings(options), accepted = [];
-    let firstOversized = false;
-    for (let index = turns.length - 1; index >= 0 && accepted.length < settings.maxTurns; index--) {
-      const candidate = [turns[index], ...accepted];
-      const candidateBytes = settings.measure({ ...base, thread: { ...base.thread, turns: candidate } });
-      if (accepted.length >= 2 && candidateBytes > settings.maxBytes) break;
-      accepted.unshift(turns[index]);
-      if (accepted.length === 1) firstOversized = candidateBytes > settings.maxBytes;
-      if (firstOversized || (accepted.length >= 2 && candidateBytes > settings.maxBytes)) break;
-    }
-    return accepted;
-  }
-
-  async extendHistoryRecord(threadId, record, options = {}) {
-    const settings = this.pageSettings(options);
-    if (!record.nextCursor || !record.thread.turns.length) return;
-    const firstOversized = settings.measure({ thread: record.thread, nextCursor: record.nextCursor }) > settings.maxBytes;
-    if (firstOversized) return;
-    while (record.nextCursor && record.thread.turns.length < settings.maxTurns) {
-      const cursor = record.nextCursor;
-      const page = await this.request('thread/turns/list', {
-        threadId, cursor, limit: 1, sortDirection: 'desc', itemsView: 'summary',
-      });
-      if (!Array.isArray(page.data) || !page.data.length) {
-        record.nextCursor = page.nextCursor ?? null;
-        break;
-      }
-      const candidate = [await this.compactTurn(threadId, page.data[0]), ...record.thread.turns];
-      const value = { thread: { ...record.thread, turns: candidate }, nextCursor: page.nextCursor ?? null };
-      if (record.thread.turns.length >= 2 && settings.measure(value) > settings.maxBytes) break;
-      record.thread.turns = candidate;
-      record.nextCursor = page.nextCursor ?? null;
-      if (record.thread.turns.length >= 2 && settings.measure(value) > settings.maxBytes) break;
-    }
-  }
-
-  async history(threadId, cursor, options = {}) {
-    await this.connect();
-    if (!cursor) throw new Error('缺少历史分页游标。');
-    const settings = this.pageSettings(options), turns = [];
-    let firstOversized = false;
-    let nextCursor = cursor;
-    while (nextCursor && turns.length < settings.maxTurns) {
-      const pageCursor = nextCursor;
-      const page = await this.request('thread/turns/list', {
-        threadId, cursor: pageCursor, limit: 1, sortDirection: 'desc', itemsView: 'summary',
-      });
-      if (!Array.isArray(page.data) || !page.data.length) {
-        nextCursor = page.nextCursor ?? null;
-        break;
-      }
-      const compact = await this.compactTurn(threadId, page.data[0]);
-      const candidate = [compact, ...turns];
-      const value = { thread: { id: threadId, turns: candidate }, nextCursor: page.nextCursor ?? null };
-      const candidateBytes = settings.measure(value);
-      if (turns.length >= 2 && candidateBytes > settings.maxBytes) break;
-      turns.unshift(compact);
-      nextCursor = page.nextCursor ?? null;
-      if (turns.length === 1) firstOversized = candidateBytes > settings.maxBytes;
-      if (firstOversized || (turns.length >= 2 && candidateBytes > settings.maxBytes)) break;
-    }
-    return { thread: { id: threadId, turns }, nextCursor };
-  }
-
-  async interrupt(threadId, turnId) {
-    await this.connect();
-    this.requireWritable(threadId);
-    return this.request('turn/interrupt', { threadId, turnId });
+  pageSettings(options = {}) {
+    return {
+      maxTurns: Math.max(1, Math.min(historyPageMaxTurns, Number(options.maxTurns) || historyPageMaxTurns)),
+      maxBytes: Math.max(1, Number(options.maxBytes) || historyPageMaxBytes),
+      measure: typeof options.measure === 'function' ? options.measure : value => Buffer.byteLength(JSON.stringify(value)),
+    };
+  }
+
+  async compactTurn(threadId, turn) {
+    const compact = events.compactTurn(turn);
+    if (!turn?.id) return compact;
+    const batches = [];
+    let cursor;
+    do {
+      const page = await this.request('thread/items/list', {
+        threadId, turnId: turn.id, ...(cursor ? { cursor } : {}),
+        limit: 100, sortDirection: 'desc',
+      });
+      if (!Array.isArray(page.data)) throw new Error('Codex 内核未返回单轮条目索引。');
+      batches.push(page.data.map(entry => events.compactItem(entry.item)));
+      cursor = page.nextCursor ?? null;
+    } while (cursor);
+    const items = batches.reverse().flatMap(batch => batch.reverse());
+    const groups = new Map(), skeleton = [];
+    let operationItems = [];
+    const flushOperations = () => {
+      if (!operationItems.length) return;
+      const visibleItems = operationItems.filter(item => item?.type !== 'reasoning');
+      operationItems = [];
+      if (!visibleItems.length) return;
+      const subAgentItems = visibleItems.filter(isSubAgentItem);
+      const detailItems = visibleItems.filter(item => !isSubAgentItem(item));
+      if (detailItems.length) {
+        const groupId = `g${groups.size + 1}`;
+        groups.set(groupId, detailItems);
+        skeleton.push({ type: 'lazyOperationGroup', id: `${turn.id}:${groupId}`,
+          turnId: turn.id, groupId,
+          operationTypes: [...new Set(detailItems.map(item => item.type).filter(Boolean))] });
+      }
+      skeleton.push(...subAgentItems);
+    };
+    for (const item of items) {
+      if (['userMessage', 'agentMessage', 'imageGeneration', 'imageView'].includes(item?.type)) {
+        flushOperations();
+        skeleton.push(item);
+      } else operationItems.push(item);
+    }
+    flushOperations();
+    let threadGroups = this.operationGroups.get(threadId);
+    if (!threadGroups) { threadGroups = new Map(); this.operationGroups.set(threadId, threadGroups); }
+    threadGroups.set(turn.id, groups);
+    return { ...compact, items: skeleton };
+  }
+
+  async operationGroupItems(threadId, turnId, groupId, offset) {
+    await this.connect();
+    const items = this.operationGroups.get(threadId)?.get(turnId)?.get(groupId);
+    if (!items) throw new Error('操作组已失效，请重新打开对话。');
+    const start = Math.max(0, Number(offset) || 0);
+    const pageItems = items.slice(start, start + turnItemPageSize);
+    const nextOffset = start + pageItems.length < items.length ? start + pageItems.length : null;
+    return { turnId, groupId, items: pageItems, nextOffset, total: items.length };
+  }
+
+  async turnContext(threadId, turnId) {
+    await this.connect();
+    if (!threadId || !turnId) throw new Error('缺少图片所属的对话或轮次。');
+    return this.compactTurn(threadId, { id: turnId });
+  }
+
+  fitTurns(base, turns, options = {}) {
+    const settings = this.pageSettings(options), accepted = [];
+    let firstOversized = false;
+    for (let index = turns.length - 1; index >= 0 && accepted.length < settings.maxTurns; index--) {
+      const candidate = [turns[index], ...accepted];
+      const candidateBytes = settings.measure({ ...base, thread: { ...base.thread, turns: candidate } });
+      if (accepted.length >= 2 && candidateBytes > settings.maxBytes) break;
+      accepted.unshift(turns[index]);
+      if (accepted.length === 1) firstOversized = candidateBytes > settings.maxBytes;
+      if (firstOversized || (accepted.length >= 2 && candidateBytes > settings.maxBytes)) break;
+    }
+    return accepted;
+  }
+
+  async extendHistoryRecord(threadId, record, options = {}) {
+    const settings = this.pageSettings(options);
+    if (!record.nextCursor || !record.thread.turns.length) return;
+    const firstOversized = settings.measure({ thread: record.thread, nextCursor: record.nextCursor }) > settings.maxBytes;
+    if (firstOversized) return;
+    while (record.nextCursor && record.thread.turns.length < settings.maxTurns) {
+      const cursor = record.nextCursor;
+      const page = await this.request('thread/turns/list', {
+        threadId, cursor, limit: 1, sortDirection: 'desc', itemsView: 'summary',
+      });
+      if (!Array.isArray(page.data) || !page.data.length) {
+        record.nextCursor = page.nextCursor ?? null;
+        break;
+      }
+      const candidate = [await this.compactTurn(threadId, page.data[0]), ...record.thread.turns];
+      const value = { thread: { ...record.thread, turns: candidate }, nextCursor: page.nextCursor ?? null };
+      if (record.thread.turns.length >= 2 && settings.measure(value) > settings.maxBytes) break;
+      record.thread.turns = candidate;
+      record.nextCursor = page.nextCursor ?? null;
+      if (record.thread.turns.length >= 2 && settings.measure(value) > settings.maxBytes) break;
+    }
+  }
+
+  async history(threadId, cursor, options = {}) {
+    await this.connect();
+    if (!cursor) throw new Error('缺少历史分页游标。');
+    const settings = this.pageSettings(options), turns = [];
+    let firstOversized = false;
+    let nextCursor = cursor;
+    while (nextCursor && turns.length < settings.maxTurns) {
+      const pageCursor = nextCursor;
+      const page = await this.request('thread/turns/list', {
+        threadId, cursor: pageCursor, limit: 1, sortDirection: 'desc', itemsView: 'summary',
+      });
+      if (!Array.isArray(page.data) || !page.data.length) {
+        nextCursor = page.nextCursor ?? null;
+        break;
+      }
+      const compact = await this.compactTurn(threadId, page.data[0]);
+      const candidate = [compact, ...turns];
+      const value = { thread: { id: threadId, turns: candidate }, nextCursor: page.nextCursor ?? null };
+      const candidateBytes = settings.measure(value);
+      if (turns.length >= 2 && candidateBytes > settings.maxBytes) break;
+      turns.unshift(compact);
+      nextCursor = page.nextCursor ?? null;
+      if (turns.length === 1) firstOversized = candidateBytes > settings.maxBytes;
+      if (firstOversized || (turns.length >= 2 && candidateBytes > settings.maxBytes)) break;
+    }
+    return { thread: { id: threadId, turns }, nextCursor };
+  }
+
+  async interrupt(threadId, turnId) {
+    await this.connect();
+    this.requireWritable(threadId);
+    return this.request('turn/interrupt', { threadId, turnId });
   }
 
   async models() {
@@ -476,16 +476,16 @@ export class SharedAppServer extends EventEmitter {
     return this.usageCache.read(() => this.request('account/rateLimits/read'));
   }
 
-  async settings(threadId, model, effort, serviceTier) {
-    await this.connect();
-    this.requireWritable(threadId);
+  async settings(threadId, model, effort, serviceTier) {
+    await this.connect();
+    this.requireWritable(threadId);
     await events.updateSettings((method, params) => this.request(method, params), this.contexts, this.settingsNotifications, threadId, model, effort, serviceTier);
     return this.context(threadId);
   }
 
-  async permissions(threadId, mode) {
-    await this.connect();
-    this.requireWritable(threadId);
+  async permissions(threadId, mode) {
+    await this.connect();
+    this.requireWritable(threadId);
     await events.updatePermissions((method, params) => this.request(method, params), this.contexts, this.settingsNotifications, this.permissionOptions, threadId, mode);
     return this.context(threadId);
   }
@@ -496,21 +496,21 @@ export class SharedAppServer extends EventEmitter {
     return this.context(threadId);
   }
 
-  context(threadId) {
+  context(threadId) {
     const context = this.permissionOptions.context(threadId, this.contexts.get(threadId) || {}), usage = context.tokenUsage;
     const usedTokens = usage?.last?.totalTokens, contextWindow = usage?.modelContextWindow;
     return { ...context, available: Boolean(contextWindow), usedTokens, contextWindow,
       usedPercent: contextWindow ? 100 * usedTokens / contextWindow : 0 };
-  }
-
-  requireWritable(threadId) {
-    const record = this.threads.get(threadId);
-    if (record?.readOnly) throw new ThreadWriterConflictError(threadId, record.thread.readOnlyReason);
-  }
-
-  close() { this.socket?.close(); }
-}
-
-function isSubAgentItem(item) {
-  return item?.type === 'collabAgentToolCall' || item?.type === 'subAgentActivity';
-}
+  }
+
+  requireWritable(threadId) {
+    const record = this.threads.get(threadId);
+    if (record?.readOnly) throw new ThreadWriterConflictError(threadId, record.thread.readOnlyReason);
+  }
+
+  close() { this.socket?.close(); }
+}
+
+function isSubAgentItem(item) {
+  return item?.type === 'collabAgentToolCall' || item?.type === 'subAgentActivity';
+}