@walkhi/code-relax 0.1.0-beta.10 → 0.1.0-beta.100

package/dist/src/hosted-history-app-server.mjs

@@ -0,0 +1,103 @@
+import { SharedAppServer } from './shared-app-server.mjs';
+import { historyCacheScope, completedHistory, turnMetadata } from './hosted-history-cache.mjs';
+
+// Hosted history uses a disk range cache; local kernel history retains its own storage.
+export class HostedHistoryAppServer extends SharedAppServer {
+  constructor(url, historyCache) {
+    super(url);
+    this.historyCache = historyCache;
+    this.historyHeadKey = 'latest';
+    this.diskHeads = new Map(); this.invalidatedTurns = new Set(); this.windowSaves = new Map();
+    this.historyVersions = new Map();
+    this.on('disconnected', () => { this.diskHeads.clear(); this.invalidatedTurns.clear(); this.historyVersions.clear(); });
+  }
+
+  historyScope(threadId) { return historyCacheScope(this.historyIdentity, this.historySource, threadId); }
+  historyVersion(threadId) { return `${this.epoch}:${this.historyVersions.get(threadId) || 0}`; }
+
+  async restoreHistoryHead(threadId) {
+    const scope = this.historyScope(threadId);
+    const result = await this.historyCache?.get(scope, this.historyHeadKey);
+    if (scope !== this.historyScope(threadId)) throw new Error('云端账号连接已变化，请重新读取历史。');
+    return result;
+  }
+
+  saveHistoryWindow(threadId, immediate = false) {
+    const record = this.threads.get(threadId), scope = this.historyScope(threadId);
+    if (!this.historyCache || !scope || !record || record.hydrating || record.needsReload
+      || record.historyTrimmed || record.metadataOnly || record.readOnly || !completedHistory(record.thread.turns)) return;
+    const value = structuredClone({ updatedAt: record.thread.updatedAt, turns: record.thread.turns,
+      nextCursor: record.nextCursor, revision: record.thread.chatRevision,
+      ...(record.approvalBeforeMs !== undefined ? { approvalBeforeMs: record.approvalBeforeMs } : {}) });
+    const pending = this.windowSaves.get(scope);
+    if (pending) { clearTimeout(pending); this.windowSaves.delete(scope); }
+    const save = () => { this.windowSaves.delete(scope); return this.historyCache.put(scope, this.historyHeadKey, value); };
+    if (immediate) return save();
+    const timer = setTimeout(save, 200); timer.unref(); this.windowSaves.set(scope, timer);
+  }
+
+  invalidateHistory(method, params) {
+    const id = params.threadId || params.thread?.id, scope = this.historyScope(id);
+    if (!scope || !this.historyCache) return;
+    const turnId = params.turnId || params.turn?.id;
+    const whole = ['thread/deleted', 'thread/compacted'].includes(method);
+    if (!whole && (!turnId || !/^(?:item\/|turn\/)/.test(method))) return;
+    this.historyVersions.set(id, (this.historyVersions.get(id) || 0) + 1);
+    clearTimeout(this.windowSaves.get(scope)); this.windowSaves.delete(scope);
+    const key = `${scope}:${turnId}`;
+    if (whole || !this.invalidatedTurns.has(key)) {
+      this.invalidatedTurns.add(key); this.diskHeads.delete(id);
+      void this.historyCache.invalidate(scope, whole ? undefined : turnId);
+    }
+    if (whole) {
+      const record = this.threads.get(id);
+      if (record) record.needsReload = true;
+      this.emit('history-invalidated', id);
+    }
+    if (method === 'turn/completed') this.invalidatedTurns.delete(key);
+  }
+
+  async compactTurn(threadId, turn, cursor = null, apply, limit = 100) {
+    const scope = this.historyScope(threadId), candidate = this.diskHeads.get(threadId);
+    const version = this.historyVersion(threadId);
+    if (cursor && !turn.status && this.historyCache) {
+      const final = await this.historyCache.get(scope, `turn:${turn.id}`);
+      if (scope !== this.historyScope(threadId)) throw new Error('云端账号连接已变化，请重新读取历史。');
+      if (final) turn = { ...final.turns[0], ...turn };
+    }
+    const saved = !cursor && candidate?.head?.turns.find(value => value.id === turn.id);
+    if (scope && this.historyCache && saved && candidate.scope === scope && candidate.updatedAt != null
+      && candidate.head.updatedAt === candidate.updatedAt && completedHistory([saved])
+      && turnMetadata(saved) === turnMetadata(turn)) {
+      const result = { ...saved, ...turn, items: saved.items, itemPage: saved.itemPage };
+      apply?.(result); return result;
+    }
+    const result = await super.compactTurn(threadId, turn, cursor, apply, limit);
+    if (this.historyCache && scope === this.historyScope(threadId) && version === this.historyVersion(threadId)
+      && completedHistory([{ ...turn, items: [] }])) {
+      const { items, itemPage, ...metadata } = turn;
+      await this.historyCache.put(scope, `turn:${turn.id}`, { turns: [metadata] });
+    }
+    return result;
+  }
+
+  async history(threadId, cursor, options = {}) {
+    await this.connect();
+    let position;
+    try { position = JSON.parse(cursor); } catch { position = null; }
+    if (position?.threadId !== threadId) return super.history(threadId, cursor, options);
+    const scope = this.historyScope(threadId);
+    const version = this.historyVersion(threadId);
+    const key = JSON.stringify(['history', position.turnId, position.itemCursor, position.turnCursor, options.itemLimit ?? 100]);
+    const cached = await this.historyCache?.get(scope, key);
+    if (scope !== this.historyScope(threadId)) throw new Error('云端账号连接已变化，请重新读取历史。');
+    if (cached && version === this.historyVersion(threadId)) return { thread: { id: threadId, turns: cached.turns },
+      nextCursor: cached.position ? JSON.stringify(cached.position) : null };
+    const result = await super.history(threadId, cursor, options);
+    if (scope === this.historyScope(threadId) && version === this.historyVersion(threadId) && completedHistory(result.thread.turns)) {
+      const next = result.nextCursor ? JSON.parse(result.nextCursor) : null;
+      await this.historyCache?.put(scope, key, { turns: result.thread.turns, position: next });
+    }
+    return result;
+  }
+}

package/dist/src/hosted-history-cache.mjs

@@ -0,0 +1,113 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+
+const threadBudget = 8 * 1024 * 1024;
+const totalBudget = 128 * 1024 * 1024;
+const digest = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+
+// Store confirmed ranges, not connection tokens, execution context or image bytes.
+export function historyCacheScope(identity, source, threadId) {
+  return identity?.accountId && threadId ? digest([identity.accountId, identity.userId || '', source, threadId]) : null;
+}
+
+export function completedHistory(turns) {
+  if (!turns?.length || turns.some(turn => !['completed', 'failed', 'interrupted'].includes(turn.status)
+    || turn.cacheStub || turn.items?.some(item => item.dotsStreaming
+      || item.type === 'imageGeneration' && !item.savedPath && item.result))) return false;
+  // Signed media addresses and embedded bytes must be reread/refreshed, not replayed from disk.
+  const media = value => value && typeof value === 'object' && Object.entries(value).some(([key, part]) =>
+    typeof part === 'string' && (/^data:/.test(part) || /[?&](?:X-Amz-|X-Goog-|signature=|sig=|token=)/i.test(part))
+    || key === 'imageBytes' || media(part));
+  return !media(turns);
+}
+
+export function turnMetadata(turn) {
+  return digest(Object.entries(turn || {}).filter(([key]) => !['items', 'itemPage', 'cacheStub'].includes(key))
+    .sort(([a], [b]) => a.localeCompare(b)));
+}
+
+export class HostedHistoryCache {
+  constructor(stateRoot, { report = error => console.error(`托管历史缓存失败：${error.message}`), maxThreadBytes = threadBudget, maxTotalBytes = totalBudget } = {}) {
+    this.directory = path.join(stateRoot, 'hosted-history');
+    this.report = report; this.maxThreadBytes = maxThreadBytes; this.maxTotalBytes = maxTotalBytes;
+    this.tail = Promise.resolve();
+  }
+
+  async record(scope) {
+    try {
+      const record = JSON.parse(await fs.readFile(path.join(this.directory, `${scope}.json`), 'utf8'));
+      if (record.version !== 1 || !record.entries || Array.isArray(record.entries) || typeof record.entries !== 'object') {
+        throw new Error('历史缓存结构无效，需重新读取云端历史。');
+      }
+      if (Object.values(record.entries).some(entry => !Number.isFinite(entry.at) || !entry.value
+        || !Array.isArray(entry.value.turns) && !Array.isArray(entry.value.data))) {
+        throw new Error('历史缓存页结构无效，需重新读取云端历史。');
+      }
+      return record;
+    } catch (error) { if (error.code !== 'ENOENT') this.report(error); return { version: 1, entries: {} }; }
+  }
+
+  run(operation, fallback) {
+    const work = this.tail.then(operation).catch(error => { this.report(error); return fallback; });
+    this.tail = work.then(() => {}); return work;
+  }
+
+  get(scope, key) {
+    if (!scope) return Promise.resolve(null);
+    return this.run(async () => (await this.record(scope)).entries?.[key]?.value ?? null, null);
+  }
+
+  put(scope, key, value) {
+    if (!scope) return Promise.resolve();
+    // Freeze before queuing; live events may mutate the source window during disk I/O.
+    const snapshot = structuredClone(value);
+    return this.run(async () => {
+      const record = await this.record(scope);
+      record.entries ||= {};
+      record.entries[key] = { at: Date.now(), value: snapshot };
+      let text = JSON.stringify(record);
+      for (const [oldKey] of Object.entries(record.entries).sort((a, b) => a[1].at - b[1].at)) {
+        if (Buffer.byteLength(text) <= this.maxThreadBytes) break;
+        delete record.entries[oldKey]; text = JSON.stringify(record);
+      }
+      await this.write(scope, text);
+      await this.prune(scope);
+    });
+  }
+
+  invalidate(scope, turnId) {
+    if (!scope) return Promise.resolve();
+    return this.run(async () => {
+      const record = await this.record(scope);
+      for (const [key, entry] of Object.entries(record.entries || {})) {
+        if (!turnId || entry.value.turnIds?.includes(turnId) || entry.value.turns?.some(turn => turn.id === turnId)
+          || entry.value.thread?.turns?.some(turn => turn.id === turnId)) delete record.entries[key];
+      }
+      await this.write(scope, JSON.stringify(record));
+    });
+  }
+
+  async write(scope, text) {
+    if (!/^[a-f0-9]{64}$/.test(scope)) throw new Error('历史缓存身份无效');
+    await fs.mkdir(this.directory, { recursive: true, mode: 0o700 });
+    const file = path.join(this.directory, `${scope}.json`), temporary = `${file}.tmp`;
+    try {
+      await fs.writeFile(temporary, text, { mode: 0o600 });
+      await fs.rename(temporary, file);
+    } finally {
+      try { await fs.unlink(temporary); } catch (error) { if (error.code !== 'ENOENT') this.report(error); }
+    }
+  }
+
+  async prune(current) {
+    const files = await Promise.all((await fs.readdir(this.directory)).filter(name => /^[a-f0-9]{64}\.json$/.test(name))
+      .map(async name => ({ name, ...await fs.stat(path.join(this.directory, name)) })));
+    let bytes = files.reduce((sum, file) => sum + file.size, 0);
+    for (const file of files.sort((a, b) => a.mtimeMs - b.mtimeMs)) {
+      if (bytes <= this.maxTotalBytes) break;
+      if (file.name === `${current}.json`) continue;
+      await fs.unlink(path.join(this.directory, file.name)); bytes -= file.size;
+    }
+  }
+}

package/dist/src/lan-socket-server.mjs

@@ -1,35 +1,185 @@
 import { EventEmitter } from 'node:events';
 import crypto from 'node:crypto';
 import { WebSocketServer, WebSocket } from 'ws';
+import timelineSync from '../shared/timeline-sync.cjs';
+import { createFileUploadSession, FILE_CHUNK_BYTES, MAX_FILE_BYTES, MAX_FILE_COUNT, MAX_TOTAL_BYTES } from './file-upload-session.mjs';
+import { FILE_READ_LIMIT } from './file-transfer-range.mjs';
 
 // One authenticated connection carries requests and explicitly owned subscriptions.
 // The dispatcher is shared business routing, not an HTTP loopback proxy.
-export function attachLanSocket(server, { token, dispatch, authorizeDevice = () => false }) {
-  // Allow four individually valid images to reach the aggregate-size validator,
-  // so an oversized composition returns an error instead of dropping the connection.
-  const wss = new WebSocketServer({ noServer: true, maxPayload: 48 * 1024 * 1024, perMessageDeflate: false });
+export function attachLanSocket(server, { token, dispatch, authorizeDevice = () => false, onDeviceAuthorizationsChanged, onDeviceConnected,
+  onPhoneConnected, onPhoneDisconnected, uploadsRoot }) {
+  // Allow four individually valid images to reach the aggregate-size validator,
+  // so an oversized composition returns an error instead of dropping the connection.
+  const wss = new WebSocketServer({ noServer: true, maxPayload: 48 * 1024 * 1024, perMessageDeflate: false });
+  const uploadWss = new WebSocketServer({ noServer: true, maxPayload: 512 * 1024, perMessageDeflate: false });
+  const activeUploads = new Map();
+  const uploadSessions = new Map();
+  let closing = false;
+  const expireUpload = async (id, entry) => {
+    if (uploadSessions.get(id) !== entry) return;
+    uploadSessions.delete(id);
+    clearTimeout(entry.timer);
+    await entry.session.close();
+  };
+  const deviceConnections = new Map();
+  const stopWatching = onDeviceAuthorizationsChanged?.(() => {
+    for (const connection of deviceConnections.values()) {
+      if (!authorizeDevice(connection.clientId, connection.credential)) connection.revoke();
+    }
+  });
   server.on('upgrade', (request, socket, head) => {
     const origin = request.headers.origin;
-    let allowed = request.url === '/api/socket';
-    // Packaged ArkWeb pages have an opaque ("null") origin; device authentication remains required.
-    if (origin && origin !== 'null') {
-      try {
-        const originUrl = new URL(origin);
-        const requestUrl = new URL(`http://${request.headers.host}`);
-        const nativeClient = request.headers['x-code-relax-native'] === '1';
-        allowed &&= ['http:', 'https:'].includes(originUrl.protocol) &&
-          (originUrl.host === request.headers.host || (nativeClient && originUrl.hostname === requestUrl.hostname));
-      }
-      catch { allowed = false; }
+    const upload = request.url === '/api/file-transfer' && Boolean(uploadsRoot);
+    let allowed = request.url === '/api/socket' || upload;
+    // Packaged ArkWeb pages have an opaque ("null") origin; device authentication remains required.
+    if (origin && origin !== 'null') {
+      try {
+        const originUrl = new URL(origin);
+        const requestUrl = new URL(`http://${request.headers.host}`);
+        const nativeClient = request.headers['x-code-relax-native'] === '1';
+        allowed &&= ['http:', 'https:'].includes(originUrl.protocol) &&
+          (originUrl.host === request.headers.host || (nativeClient && originUrl.hostname === requestUrl.hostname));
+      }
+      catch { allowed = false; }
     }
     if (!allowed) { socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n'); return; }
-    wss.handleUpgrade(request, socket, head, ws => wss.emit('connection', ws));
+    const target = upload ? uploadWss : wss;
+    target.handleUpgrade(request, socket, head, ws => target.emit('connection', ws));
+  });
+  uploadWss.on('connection', ws => {
+    let authenticated = false, stopped = false, identity = '', upload, purpose, chunk, uploadEntry, uploadId, fileRelay = false;
+    let release, discardUpload = false;
+    const released = new Promise(resolve => { release = resolve; });
+    let queued = 0;
+    let pending = Promise.resolve();
+    const authTimer = setTimeout(() => ws.close(1008, 'Authentication required'), 5000);
+    const reply = value => { if (!stopped && ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(value)); };
+    ws.on('error', () => {});
+    const stop = () => {
+      if (stopped) return;
+      stopped = true;
+      deviceConnections.delete(ws);
+      clearTimeout(authTimer);
+      void pending.finally(async () => {
+        activeUploads.delete(ws);
+        if (uploadEntry) {
+          uploadEntry.ws = null;
+          if (discardUpload || closing) await expireUpload(uploadId, uploadEntry);
+          else {
+            uploadEntry.timer = setTimeout(() => { void expireUpload(uploadId, uploadEntry); }, 5 * 60 * 1000);
+            uploadEntry.timer.unref();
+          }
+        }
+        release();
+      });
+    };
+    ws.on('close', stop);
+    ws.on('message', (bytes, binary) => {
+      if (stopped || ws.readyState !== WebSocket.OPEN) return;
+      // Three upload chunks may be in flight, each with a header and binary frame.
+      if (++queued > 8) { stop(); ws.close(1013, 'File request queue exceeded'); return; }
+      pending = pending.then(async () => {
+        if (stopped || ws.readyState !== WebSocket.OPEN) return;
+        if (binary) {
+          if (!authenticated || purpose !== 'upload' || !chunk || bytes.length !== chunk.length) throw new Error('无效的文件分片');
+          const current = chunk; chunk = undefined;
+          reply(await upload.receive({ ...current, data: bytes }, { relayed: fileRelay })); return;
+        }
+        if (bytes.length > 16 * 1024 || chunk) throw new Error('无效的文件请求');
+        const message = JSON.parse(bytes.toString());
+        if (!authenticated) {
+          purpose = message.purpose;
+          if (!['upload', 'download'].includes(purpose)) throw new Error('文件通道用途无效');
+          if (message?.type === 'device-auth' && typeof message.clientId === 'string' &&
+              authorizeDevice(message.clientId, message.credential) === true) identity = `device:${message.clientId}`;
+          else if (token && message?.type === 'auth' && typeof message.token === 'string') {
+            const supplied = Buffer.from(message.token), expected = Buffer.from(token || '');
+            if (supplied.length === expected.length && crypto.timingSafeEqual(supplied, expected)) {
+              identity = typeof message.relayClientId === 'string' && message.relayClientId.length <= 200
+                ? `relay:${message.relayClientId}` : 'local-token';
+              fileRelay = message.fileRelay === true;
+            }
+          }
+          if (identity && purpose === 'upload') {
+            uploadId = message.uploadSessionId;
+            if (typeof uploadId !== 'string' || !/^[a-f0-9-]{36}$/.test(uploadId)) throw new Error('上传批次编号无效');
+            const entry = uploadSessions.get(uploadId);
+            if (entry) {
+              if (entry.identity !== identity) throw new Error('上传批次身份不一致');
+              if (entry.ws) { entry.ws.terminate(); await entry.released; }
+              if (uploadSessions.get(uploadId) !== entry) throw new Error('上传批次已失效，无法确认原批次状态');
+            } else if (message.resumeUpload) throw new Error('上传断点已过期或工作站已重启，请重新发送');
+          }
+          // Taking over a connection can await an in-flight disk write. The new
+          // socket and its authorization must still be live when that finishes.
+          if (stopped || closing || ws.readyState !== WebSocket.OPEN) return;
+          if (message.type === 'device-auth' && !authorizeDevice(message.clientId, message.credential)) throw new Error('设备授权已失效');
+          const same = [...activeUploads.values()].filter(item => item.identity === identity && item.purpose === purpose);
+          if (!identity || (purpose === 'download' && same.length >= 3) || activeUploads.size >= 8) throw new Error('文件身份无效或文件任务过多');
+          if (message.type === 'device-auth') deviceConnections.set(ws, {
+            clientId: message.clientId, credential: message.credential,
+            revoke() { discardUpload = true; stop(); ws.close(4401, 'Device authorization revoked'); },
+          });
+          activeUploads.set(ws, { identity, purpose }); authenticated = true; clearTimeout(authTimer);
+          if (message.type === 'device-auth') onDeviceConnected?.(message.clientId, message);
+          if (purpose === 'upload') {
+            uploadEntry = uploadSessions.get(uploadId);
+            if (!uploadEntry) {
+              if (uploadSessions.size >= 32) {
+                const oldest = [...uploadSessions].find(([, entry]) => entry.committed && !entry.ws);
+                if (!oldest) throw new Error('上传批次过多，请稍后再试');
+                await expireUpload(...oldest);
+              }
+              if (stopped || closing || ws.readyState !== WebSocket.OPEN) return;
+              uploadEntry = { identity, session: createFileUploadSession(uploadsRoot) };
+              uploadSessions.set(uploadId, uploadEntry);
+            }
+            clearTimeout(uploadEntry.timer);
+            Object.assign(uploadEntry, { ws, released });
+            upload = uploadEntry.session;
+          }
+          reply({ type: 'ready', version: 5, purpose, maxDownloadBytes: fileRelay ? FILE_READ_LIMIT : null, maxFileBytes: fileRelay ? MAX_FILE_BYTES : null, maxFileCount: MAX_FILE_COUNT,
+            maxTotalBytes: fileRelay ? MAX_TOTAL_BYTES : null, chunkBytes: FILE_CHUNK_BYTES, uploadSessionId: uploadId });
+          return;
+        }
+        if (purpose === 'download') {
+          if (message.type !== 'read' || typeof message.path !== 'string' || message.path.length > 12000 ||
+              !/^\/api\/(?:images\/[a-f0-9]{64}|files\/(?:local|[a-f0-9]{64})|code\/(?:image|binary)|desktop\/frames\/[a-f0-9]{32})(?:\?|$)/.test(message.path) || message.path.includes('#')) throw new Error('无效的文件读取请求');
+          await dispatch({ method: 'GET', url: message.path, headers: {}, socketRequest: true, fileTransfer: true }, {
+            json(status, body) { reply({ type: 'error', status, error: body?.error || '文件读取失败' }); },
+            filePart(metadata, data) {
+              if (stopped || ws.readyState !== WebSocket.OPEN) return;
+              if (fileRelay && metadata.size > FILE_READ_LIMIT) throw new Error('服务器转发仅支持下载不超过 20 MiB 的文件，请使用局域网或 RTC 直连');
+              if (!Buffer.isBuffer(data) || data.length > FILE_CHUNK_BYTES || ws.bufferedAmount > 1024 * 1024) throw new Error('文件接收过慢或分片无效');
+              reply({ type: 'part', ...metadata, length: data.length });
+              ws.send(data);
+            },
+          });
+          return;
+        }
+        if (message.type === 'chunk') {
+          if (!Number.isSafeInteger(message.length) || message.length < 1 || message.length > FILE_CHUNK_BYTES) throw new Error('文件分片大小无效');
+          chunk = message; return;
+        }
+        reply(await upload.receive(message, { relayed: fileRelay }));
+        if (message.type === 'commit') uploadEntry.committed = true;
+        if (message.type === 'cancel') {
+          await expireUpload(uploadId, uploadEntry);
+          uploadEntry = null;
+        }
+      }).catch(error => { reply({ type: 'error', error: error.message }); discardUpload = true; stop(); ws.close(1008, 'File request rejected'); })
+        .finally(() => { queued--; });
+    });
   });
   wss.on('connection', ws => {
-    let authenticated = false, alive = true;
+    let authenticated = false, alive = true, stopped = false;
+    let phone, reported = false;
+    const connectionId = crypto.randomUUID();
+    const controlLifetime = new AbortController();
     const active = new Map();
     const send = value => {
-      if (ws.readyState !== WebSocket.OPEN) return;
+      if (stopped || ws.readyState !== WebSocket.OPEN) return;
       if (ws.bufferedAmount > 64 * 1024 * 1024) { ws.close(1013, 'Client too slow'); return; }
       ws.send(JSON.stringify(value));
     };
@@ -40,70 +190,153 @@ export function attachLanSocket(server, { token, dispatch, authorizeDevice = ()
     }, 30000);
     ws.on('pong', () => { alive = true; });
     ws.on('error', () => {}); // close rejects requests and releases every subscription.
-    ws.on('close', () => {
+    const stop = () => {
+      if (stopped) return;
+      stopped = true;
+      controlLifetime.abort();
+      deviceConnections.delete(ws);
       clearTimeout(authTimer); clearInterval(heartbeat);
+      if (reported) onPhoneDisconnected?.(connectionId);
       for (const reply of active.values()) reply.end();
       active.clear();
-    });
+    };
+    ws.on('close', stop);
     ws.on('message', async (bytes, binary) => {
+      if (stopped || ws.readyState !== WebSocket.OPEN) return;
       let message;
       try { if (binary) throw new Error(); message = JSON.parse(bytes.toString()); }
       catch { ws.close(1008, 'Invalid JSON'); return; }
       if (!message || typeof message !== 'object') { ws.close(1008, 'Invalid message'); return; }
-      if (!authenticated) {
-        let accepted = false;
-        if (message.type === 'device-auth') {
-          accepted = authorizeDevice(message.clientId, message.credential) === true;
-        } else if (message.type === 'auth') {
-          const supplied = Buffer.from(typeof message.token === 'string' ? message.token : '');
-          const expected = Buffer.from(token || '');
-          accepted = supplied.length === expected.length && crypto.timingSafeEqual(supplied, expected);
-        }
-        if (!accepted) {
-          ws.close(1008, 'Authentication failed'); return;
-        }
+      if (!authenticated) {
+        let accepted = false;
+        if (message.type === 'device-auth') {
+          accepted = authorizeDevice(message.clientId, message.credential) === true;
+        } else if (message.type === 'auth') {
+          const supplied = Buffer.from(typeof message.token === 'string' ? message.token : '');
+          const expected = Buffer.from(token || '');
+          accepted = supplied.length === expected.length && crypto.timingSafeEqual(supplied, expected);
+        }
+        if (!accepted) {
+          ws.close(1008, 'Authentication failed'); return;
+        }
+        if (message.type === 'device-auth') phone = { clientId: message.clientId, mode: 'lan' };
+        else if (typeof message.relayClientId === 'string' && /^[\w-]{16,128}$/.test(message.relayClientId)) {
+          phone = { clientId: message.relayClientId, mode: 'self-relay' };
+        }
+        if (message.type === 'device-auth') onDeviceConnected?.(message.clientId, message);
+        if (message.type === 'device-auth') deviceConnections.set(ws, {
+          clientId: message.clientId, credential: message.credential,
+          revoke() { stop(); ws.close(4401, 'Device authorization revoked'); },
+        });
         authenticated = true; clearTimeout(authTimer); send({ type: 'ready', version: 1 }); return;
       }
       const { id, type } = message;
       if (!Number.isSafeInteger(id) || id < 1) { ws.close(1008, 'Invalid request id'); return; }
+      if (type === 'response-ack') { active.get(id)?.acknowledge?.(message.batch); return; }
+      if (type === 'cancel') { active.get(id)?.end(); return; }
       if (type === 'unsubscribe') { const reply = active.get(id); if (reply?.subscription) reply.end(); return; }
       if (!['request', 'subscribe'].includes(type) || active.has(id)) { ws.close(1008, 'Invalid request'); return; }
       const subscription = type === 'subscribe';
       const path = message.path;
-      const isStream = typeof path === 'string' && /^\/api\/(?:usage-events|shared-recovery\/events|threads\/[^/?]+\/events)(?:\?|$)/.test(path);
-      if (active.size >= 32 || (subscription && [...active.values()].filter(r => r.subscription).length >= 4)) {
+      const isStream = typeof path === 'string' && /^\/api\/(?:usage-events|thread-events|turn-events|health\/events|shared-recovery\/events|threads\/[^/?]+\/(?:events|dots-activity-events))(?:\?|$)/.test(path);
+      // Native recovery, usage, catalog, current chat, and the main Dot's sidebar
+      // share one station connection (including when viewing a delegated task).
+      if (active.size >= 32 || (subscription && [...active.values()].filter(r => r.subscription).length >= 5)) {
         send({ type: 'response', id, status: 429, body: { error: '同时进行的请求过多' } }); return;
       }
       if (typeof path !== 'string' || !path.startsWith('/api/') || path.includes('#') ||
           path.startsWith('/api/attachments/') || path === '/api/socket' || path === '/api/uploads' ||
-          subscription !== isStream || !['GET', 'POST', 'DELETE'].includes(message.method || 'GET') ||
+          subscription !== isStream || !['GET', 'POST', 'PUT', 'DELETE'].includes(message.method || 'GET') ||
           (subscription && message.method && message.method !== 'GET') ||
           (message.body !== undefined && (!message.body || typeof message.body !== 'object' || Array.isArray(message.body)))) {
         send({ type: 'response', id, status: 400, body: { error: '无效的连接请求' } }); return;
       }
+      // Health probes, management and file sockets are not chat connections.
+      // Three message sources share this catalog/events entry point.
+      if (phone && !reported && /^\/api\/(?:threads(?:\?|$)|thread-events(?:\?|$)|threads\/[^/?]+\/(?:events|dots-activity-events)(?:\?|$))/.test(path)) {
+        reported = true;
+        onPhoneConnected?.(connectionId, phone.clientId, phone.mode);
+      }
       const reply = new EventEmitter();
+      let waiting, batch = 0;
+      const sendPart = (pieces, pageEnd = false) => new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error('历史接收确认超时')), 20000);
+        waiting = { resolve, reject, timer, batch: ++batch };
+        send({ type: subscription ? 'event-part' : 'response-part', id, batch, pieces, ...(pageEnd ? { pageEnd: true } : {}) });
+      });
+      const sendTimeline = async (status, body, event) => {
+        if (event) batch = 0;
+        try {
+          for (const pieces of timelineSync.timelineBatches(body)) {
+            if (reply.writableEnded) return;
+            await sendPart(pieces);
+          }
+          if (!reply.writableEnded) {
+            send(event ? { type: 'event', id, event, streamed: true } : { type: 'response', id, status, streamed: true });
+            if (!event) reply.end();
+          }
+        } catch (error) {
+          if (!reply.writableEnded) {
+            send(event ? { type: 'event', id, event: 'bridge-error', data: { error: error.message } }
+              : { type: 'response', id, status: 500, body: { error: error.message } });
+            reply.end();
+          }
+        }
+      };
       Object.assign(reply, {
         subscription, headersSent: false, writableEnded: false, destroyed: false,
+        async historyPage(page) {
+          const parts = timelineSync.timelineBatches(page);
+          let part = parts.next();
+          while (!part.done) {
+            if (this.writableEnded) throw new Error('历史读取已取消');
+            const next = parts.next();
+            await sendPart(part.value, next.done);
+            part = next;
+          }
+        },
         json(status, body) {
           if (this.writableEnded) return;
+          if (status < 400 && body?.schemaVersion === 1 && Array.isArray(body.turns)) {
+            void sendTimeline(status, body); return;
+          }
           send({ type: 'response', id, status, body }); this.end();
         },
+        acknowledge(sequence) {
+          if (!waiting || sequence !== waiting.batch) return;
+          const completed = waiting; waiting = null; clearTimeout(completed.timer);
+          this.emit('progress'); completed.resolve();
+        },
         startEvents() {
           if (this.writableEnded) return;
           this.headersSent = true; send({ type: 'subscribed', id });
         },
-        event(event, data) { if (!this.writableEnded) send({ type: 'event', id, event, data }); },
+        event(event, data) {
+          if (this.writableEnded) return;
+          if (event === 'update' && data?.schemaVersion === 1) return sendTimeline(200, data, event);
+          send({ type: 'event', id, event, data });
+        },
         end() {
           if (this.writableEnded) return;
           this.writableEnded = this.destroyed = true; active.delete(id);
+          if (waiting) { clearTimeout(waiting.timer); waiting.reject(new Error('历史读取已取消')); waiting = null; }
           if (subscription) send({ type: 'end', id });
           this.emit('close');
         },
       });
       active.set(id, reply);
-      try { await dispatch({ method: message.method || 'GET', url: path, body: message.body || {}, headers: {}, socketRequest: true }, reply); }
+      const requestLifetime = new AbortController();
+      reply.once('close', () => requestLifetime.abort());
+      try { await dispatch({ method: message.method || 'GET', url: path, body: message.body || {}, headers: {}, socketRequest: true,
+        controlContext: { owner: connectionId, signal: controlLifetime.signal, requestSignal: requestLifetime.signal } }, reply); }
       catch (error) { reply.json(500, { error: error.message }); }
     });
   });
-  return { close() { for (const ws of wss.clients) ws.terminate(); wss.close(); } };
+  return { close() {
+    closing = true;
+    stopWatching?.();
+    for (const ws of wss.clients) ws.terminate(); wss.close();
+    for (const ws of uploadWss.clients) ws.terminate(); uploadWss.close();
+    for (const [id, entry] of uploadSessions) if (!entry.ws) void expireUpload(id, entry);
+  } };
 }