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

package/dist/src/self-relay/android-releases.mjs

@@ -0,0 +1,61 @@
+import fs from 'node:fs';
+
+const prefix = '/code-relax/android/';
+const webOrigin = 'https://www.coderelax.cn';
+
+export function readAndroidCatalog(file) {
+  const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (!Array.isArray(data.releases) || !data.releases.length) throw new Error('No Android releases');
+  const versions = new Set();
+  for (const item of data.releases) {
+    if (!Number.isSafeInteger(item.versionCode) || item.versionCode < 1 || item.versionCode > 2100000000
+      || versions.has(item.versionCode) || typeof item.versionName !== 'string' || !/^\d+\.\d+\.\d+\.\d+$/.test(item.versionName)
+      || !item.versionName.endsWith('.' + item.versionCode)
+      || !Number.isSafeInteger(item.size) || item.size <= 0 || !/^[a-f0-9]{64}$/.test(item.sha256)
+      || typeof item.objectKey !== 'string' || !/^code-relax\/android\/\d+\/[A-Za-z0-9._-]+\.apk$/.test(item.objectKey)
+      || typeof item.notes !== 'string' || item.notes.length > 10000) throw new Error('Invalid Android release catalog');
+    versions.add(item.versionCode);
+  }
+  if (!versions.has(data.latestVersionCode)) throw new Error('Latest Android release is missing');
+  return data;
+}
+
+export function createAndroidReleaseHandler({ catalogFile, signDownload, log = () => {} }) {
+  return async function handle(request, response, target) {
+    if (!target.pathname.startsWith(prefix)) return false;
+    const headers = { 'Cache-Control': 'no-store', 'Content-Type': 'application/json; charset=utf-8',
+      'X-Content-Type-Options': 'nosniff', 'Referrer-Policy': 'no-referrer',
+      'Access-Control-Allow-Origin': webOrigin, Vary: 'Origin' };
+    const reply = (code, data) => { response.writeHead(code, headers); response.end(JSON.stringify(data)); };
+    if (request.method !== 'GET') { reply(405, { error: 'Method not allowed' }); return true; }
+    if (![prefix + 'latest.json', prefix + 'download'].includes(target.pathname)) {
+      reply(404, { error: 'Not found' }); return true;
+    }
+    try {
+      if (!catalogFile || !signDownload) { reply(503, { error: 'Android release is not available' }); return true; }
+      const catalog = readAndroidCatalog(catalogFile);
+      const requested = target.searchParams.get('versionCode');
+      if (requested !== null && !/^[1-9]\d{0,9}$/.test(requested)) { reply(400, { error: 'Invalid version' }); return true; }
+      const code = target.pathname.endsWith('/latest.json') || requested === null ? catalog.latestVersionCode : Number(requested);
+      const release = catalog.releases.find(item => item.versionCode === code);
+      if (!release) { reply(404, { error: 'Release unavailable; check for updates again' }); return true; }
+      const { versionCode, versionName, size, sha256, notes } = release;
+      if (target.pathname.endsWith('/latest.json')) {
+        reply(200, { versionCode, versionName, size, sha256, notes }); return true;
+      }
+      // Sign only an explicitly published object, never a caller-supplied key or URL.
+      const ticket = await signDownload(release);
+      if (!ticket || new URL(ticket.url).protocol !== 'https:' || !Number.isSafeInteger(ticket.expiresAt) || ticket.expiresAt <= Date.now()) {
+        throw new Error('Invalid download ticket');
+      }
+      if (target.searchParams.get('redirect') === '1') {
+        response.writeHead(302, { ...headers, Location: ticket.url }); response.end();
+      } else reply(200, { versionCode, url: ticket.url, expiresAt: ticket.expiresAt });
+    } catch (error) {
+      // Provider errors may contain signed URLs or credentials. Never return or log them.
+      log({ event: 'android-release-error', type: error?.code === 'ENOENT' ? 'not-published' : 'configuration-or-storage' });
+      reply(503, { error: 'Android release is temporarily unavailable' });
+    }
+    return true;
+  };
+}

package/dist/src/self-relay/client.mjs

@@ -3,15 +3,15 @@ import WebSocket from 'ws';
 import { decode, relayAddress, send } from './wire.mjs';
 
 // Headless mobile-side adapter for the local validation. No OpenAI credentials.
-export function connectRelayClient({ relayUrl, room, code, credential, clientId, observe = false }) {
+export function connectRelayClient({ relayUrl, room, code, credential, clientId, accountToken, observe = false }) {
   relayAddress(relayUrl);
   const events = new EventEmitter(), pending = new Map();
-  const socket = new WebSocket(relayUrl, { maxPayload: 64 * 1024 * 1024, perMessageDeflate: true });
-  let serial = 0, connected = false, pairedCredential = credential, pairedClientId = clientId;
+  const socket = new WebSocket(relayUrl, { maxPayload: 64 * 1024 * 1024, perMessageDeflate: true });
+  let serial = 0, connected = false, pairedCredential = credential, pairedClientId = clientId;
   const ready = new Promise((resolve, reject) => {
     const timer = setTimeout(() => { reject(new Error('Relay connection timeout')); socket.terminate(); }, 7000);
-    socket.on('open', () => send(socket, observe ? { type: 'observe', room, credential, clientId }
-      : code ? { type: 'pair', room, code, credential, clientId } : { type: 'resume', room, credential, clientId }));
+    socket.on('open', () => send(socket, observe ? { type: 'observe', room, credential, clientId, accountToken }
+      : code ? { type: 'pair', room, code, credential, clientId, accountToken } : { type: 'resume', room, credential, clientId, accountToken }));
     socket.on('error', error => { reject(error); events.emit('diagnostic', error.message); });
     socket.on('close', () => {
       clearTimeout(timer); connected = false; reject(new Error('Relay connection closed'));
@@ -21,14 +21,14 @@ export function connectRelayClient({ relayUrl, room, code, credential, clientId,
     socket.on('message', (bytes, binary) => {
       try {
         const message = decode(bytes, binary);
-        if (message.type === 'paired') { if (message.credential) pairedCredential = message.credential; if (message.clientId) pairedClientId = message.clientId; }
-        else if (message.type === 'observing') { clearTimeout(timer); connected = true; events.emit('observing', message); resolve({ room, credential: pairedCredential, clientId: pairedClientId }); }
-        else if (message.type === 'computer-info') events.emit('computer-info', { hostName: message.hostName });
-        else if (message.type === 'lan-candidates') events.emit('lan-candidates', message.candidates);
-        else if (message.type === 'official-computer') events.emit('official-computer', message.computer);
-        else if (message.type === 'official-computer-saved') events.emit('official-computer-saved', message.computer);
-        else if (message.type === 'announcement') events.emit('announcement', message.announcement);
-        else if (message.type === 'ready') { clearTimeout(timer); connected = true; resolve({ room, credential: pairedCredential, clientId: pairedClientId }); }
+        if (message.type === 'paired') { if (message.credential) pairedCredential = message.credential; if (message.clientId) pairedClientId = message.clientId; }
+        else if (message.type === 'observing') { clearTimeout(timer); connected = true; events.emit('observing', message); resolve({ room, credential: pairedCredential, clientId: pairedClientId }); }
+        else if (message.type === 'computer-info') events.emit('computer-info', { hostName: message.hostName });
+        else if (message.type === 'lan-candidates') events.emit('lan-candidates', message.candidates);
+        else if (message.type === 'official-computer') events.emit('official-computer', message.computer);
+        else if (message.type === 'official-computer-saved') events.emit('official-computer-saved', message.computer);
+        else if (message.type === 'announcement') events.emit('announcement', message.announcement);
+        else if (message.type === 'ready') { clearTimeout(timer); connected = true; resolve({ room, credential: pairedCredential, clientId: pairedClientId }); }
         else if (message.type === 'data') {
           const body = decode(message.payload, false), request = pending.get(body.id);
           if (body.type === 'response' && request) { clearTimeout(request.timer); pending.delete(body.id); request.resolve(body); }
@@ -50,12 +50,12 @@ export function connectRelayClient({ relayUrl, room, code, credential, clientId,
         }
       });
     },
-    send(message) { if (!connected) throw new Error('Relay not ready'); return send(socket, { type: 'data', payload: JSON.stringify(message) }); },
-    routeDirect() { if (!connected) throw new Error('Relay not ready'); return send(socket, { type: 'p2p-route', direct: 1 }); },
-    recordOfficialComputer(computer) {
-      if (!connected || !observe) throw new Error('Metadata channel not ready');
-      return send(socket, { type: 'official-computer', ...computer });
-    },
+    send(message) { if (!connected) throw new Error('Relay not ready'); return send(socket, { type: 'data', payload: JSON.stringify(message) }); },
+    routeDirect() { if (!connected) throw new Error('Relay not ready'); return send(socket, { type: 'p2p-route', direct: 1 }); },
+    recordOfficialComputer(computer) {
+      if (!connected || !observe) throw new Error('Metadata channel not ready');
+      return send(socket, { type: 'official-computer', ...computer });
+    },
     close() { socket.terminate(); },
   };
 }

package/dist/src/self-relay/connector.mjs

@@ -1,32 +1,224 @@
 import { randomUUID } from 'node:crypto';
 import { EventEmitter } from 'node:events';
+import fs from 'node:fs';
 import WebSocket from 'ws';
-import { decode, loopbackUrl, relayAddress, send } from './wire.mjs';
+import { decode, loopbackUrl, relayAddress, send } from './wire.mjs';
+import { routedFileBytes, parseFileBytes } from './file-wire.mjs';
+import { attachRtcFile } from './rtc-file-bridge.mjs';
 import { createP2pProbe, validProbeSignal } from './p2p-probe.mjs';
 import { createWindowsRouteHelper } from './windows-route-helper.mjs';
 
 // Reuse the actual LAN dispatcher, including its normal/shared capability boundary.
 // The LAN token never travels to the relay. No requests are replayed after a close.
-export function connectBridgeRelay({ relayUrl, hostKey, bridgeUrl, bridgeToken, identity, bridgeConnection, hostName = 'Codex-PC', lanCandidates = [], p2pProbe = false, iceServers = [], p2pWindowsRouteHelper = false, p2pWindowsRouteHelperToken = '' }) {
+export function connectBridgeRelay({ relayUrl, hostKey, bridgeUrl, bridgeToken, identity, bridgeConnection, usageCacheFile,
+  hostName = 'Codex-PC', lanCandidates = [], p2pProbe = false, iceServers = [], p2pWindowsRouteHelper = false, p2pWindowsRouteHelperToken = '' }) {
   relayAddress(relayUrl); loopbackUrl(bridgeUrl, '/api/socket');
-  if (!bridgeToken) throw new Error('Bridge token required');
+  if (!bridgeToken) throw new Error('Desktop service credential required');
   const events = new EventEmitter();
   const remote = new WebSocket(relayUrl, { maxPayload: 64 * 1024 * 1024, perMessageDeflate: {
     serverNoContextTakeover: true, clientNoContextTakeover: true,
     threshold: 1024, zlibDeflateOptions: { level: 3 },
   } });
   const locals = new Map();
-  let heartbeat, operation, lastClose;
+  const fileLocals = new Map();
+  const activeTurns = new Map();
+  const completedTurns = new Map();
+  const trackedTurns = new Map();
+  if (usageCacheFile) {
+    try {
+      const saved = JSON.parse(fs.readFileSync(usageCacheFile, 'utf8'));
+      if (saved.version === 1 && Array.isArray(saved.turns)) {
+        for (const item of saved.turns.slice(0, 128)) {
+          if (typeof item.threadId === 'string' && item.threadId.length <= 80 &&
+              typeof item.turnId === 'string' && item.turnId.length <= 80) trackedTurns.set(item.threadId, item.turnId);
+        }
+      }
+    } catch (error) { if (error.code !== 'ENOENT') events.emit('diagnostic', `Usage task cache: ${error.message}`); }
+  }
+  function saveTrackedTurns() {
+    if (!usageCacheFile) return;
+    try {
+      const temp = `${usageCacheFile}.tmp`;
+      fs.writeFileSync(temp, JSON.stringify({ version: 1, turns: [...trackedTurns].map(([threadId, turnId]) => ({ threadId, turnId })) }), { mode: 0o600 });
+      fs.renameSync(temp, usageCacheFile);
+    } catch (error) { events.emit('diagnostic', `Usage task cache: ${error.message}`); }
+  }
+  let fileRemote, fileRetryTimer, turnLocal, turnRetryTimer, turnPulseTimer, turnObserverReady = false,
+    queueTurnResync = () => {}, verifyActiveTurns = () => {}, heartbeat, operation, lastClose, closing = false;
   const alive = () => { clearTimeout(heartbeat); heartbeat = setTimeout(() => remote.terminate(), 75000); };
   remote.on('open', alive); remote.on('ping', alive); remote.on('message', alive);
   function dropLocal(session) {
     const current = locals.get(session);
     if (!current) return;
-    locals.delete(session); clearTimeout(current.timer); current.socket?.terminate();
+    locals.delete(session); clearTimeout(current.timer);
+    if (current.ready && current.socket?.readyState === WebSocket.OPEN && current.usageRequests.size &&
+        remote.readyState === WebSocket.OPEN && !closing) {
+      // Keep only the in-flight submission receipt; no late response goes to the phone.
+      current.detached = true;
+      current.detachedTimer = setTimeout(() => current.socket?.terminate(), 35000);
+    } else current.socket?.terminate();
     current.probe?.then(probe => probe.close());
+    current.fileProbe?.then(probe => probe.close());
+    current.diagnosticProbe?.then(probe => probe.close());
   }
   function dropLocals() {
     for (const session of [...locals.keys()]) dropLocal(session);
+    for (const socket of fileLocals.values()) socket.terminate();
+    fileLocals.clear(); clearTimeout(fileRetryTimer); fileRemote?.terminate(); fileRemote = undefined;
+    clearTimeout(turnRetryTimer); clearInterval(turnPulseTimer); turnLocal?.terminate(); turnLocal = undefined;
+    turnObserverReady = false; activeTurns.clear(); completedTurns.clear(); verifyActiveTurns = () => {};
+  }
+  function startTurnReceiver() {
+    if (closing || remote.readyState !== WebSocket.OPEN) return;
+    let connection;
+    try { connection = bridgeConnection?.() || { url: bridgeUrl, token: bridgeToken }; loopbackUrl(connection.url, '/api/socket'); }
+    catch { turnRetryTimer = setTimeout(startTurnReceiver, 3000); return; }
+    const socket = turnLocal = new WebSocket(connection.url, { maxPayload: 64 * 1024, perMessageDeflate: false });
+    const resyncPending = new Map();
+    const pulsePending = new Map();
+    let resyncId = 1, resyncQueue = [];
+    function resyncNext() {
+      if (!turnObserverReady || turnLocal !== socket) return;
+      while (resyncPending.size < 8 && resyncQueue.length) {
+        const [threadId, turnId] = resyncQueue.shift();
+        if (trackedTurns.get(threadId) !== turnId) continue;
+        const id = ++resyncId;
+        resyncPending.set(id, { threadId, turnId });
+        send(socket, { type: 'request', id, method: 'GET', path: `/api/threads/${encodeURIComponent(threadId)}/active-turn` });
+      }
+    }
+    queueTurnResync = (threadId, turnId) => { resyncQueue.push([threadId, turnId]); resyncNext(); };
+    verifyActiveTurns = () => {
+      if (!turnObserverReady || turnLocal !== socket) return;
+      for (const [threadId, turnId] of trackedTurns) {
+        if (activeTurns.get(threadId) !== turnId) continue;
+        if (pulsePending.size >= 8) break;
+        if ([...pulsePending.values()].some(pending => pending.threadId === threadId)) continue;
+        const id = ++resyncId;
+        pulsePending.set(id, { threadId, turnId });
+        send(socket, { type: 'request', id, method: 'GET', path: `/api/threads/${encodeURIComponent(threadId)}/active-turn` });
+      }
+    };
+    socket.on('open', () => send(socket, { type: 'auth', token: connection.token }));
+    socket.on('error', error => events.emit('diagnostic', `Local turn observer: ${error.message}`));
+    socket.on('close', () => {
+      if (turnLocal !== socket) return;
+      turnLocal = undefined;
+      if (turnObserverReady) send(remote, { type: 'usage-observer-lost' });
+      turnObserverReady = false;
+      queueTurnResync = () => {};
+      verifyActiveTurns = () => {};
+      activeTurns.clear(); completedTurns.clear();
+      if (!closing && remote.readyState === WebSocket.OPEN) turnRetryTimer = setTimeout(startTurnReceiver, 3000);
+    });
+    socket.on('message', (bytes, binary) => {
+      if (binary || turnLocal !== socket) return socket.terminate();
+      try {
+        const message = decode(bytes, false);
+        if (message.type === 'ready') { send(socket, { type: 'subscribe', id: 1, path: '/api/turn-events' }); return; }
+        if (message.type === 'subscribed' && message.id === 1) {
+          turnObserverReady = true; resyncQueue = [...trackedTurns]; resyncNext(); return;
+        }
+        if (message.type === 'response' && pulsePending.has(message.id)) {
+          const { threadId, turnId } = pulsePending.get(message.id);
+          pulsePending.delete(message.id);
+          if (trackedTurns.get(threadId) !== turnId || activeTurns.get(threadId) !== turnId) return;
+          if (message.status === 200 && message.body?.turnId === turnId) {
+            send(remote, { type: 'usage-turn', method: 'heartbeat', threadId, turnId });
+          } else if (message.status === 200 || message.status === 404) {
+            activeTurns.delete(threadId);
+            if (trackedTurns.get(threadId) === turnId) { trackedTurns.delete(threadId); saveTrackedTurns(); }
+            send(remote, { type: 'usage-turn', method: 'inactive', threadId, turnId });
+          } else socket.close();
+          return;
+        }
+        if (message.type === 'response' && resyncPending.has(message.id)) {
+          const { threadId, turnId } = resyncPending.get(message.id);
+          resyncPending.delete(message.id);
+          if (trackedTurns.get(threadId) === turnId) {
+            if (message.status === 200 && message.body?.turnId === turnId) {
+              activeTurns.set(threadId, turnId);
+              send(remote, { type: 'usage-turn', method: 'resume', threadId, turnId });
+            } else if (message.status === 200 || message.status === 404) {
+              trackedTurns.delete(threadId); saveTrackedTurns();
+            } else { socket.close(); return; }
+          }
+          resyncNext(); return;
+        }
+        if (message.type === 'event' && message.id === 1 && message.event === 'turn') {
+          const { method, threadId, turnId } = message.data || {};
+          if (!['turn/started', 'turn/completed'].includes(method) || typeof threadId !== 'string' || typeof turnId !== 'string') return;
+          const key = `${threadId}:${turnId}`;
+          const tracked = trackedTurns.get(threadId) === turnId;
+          // Keep local event state for a phone submission receipt arriving later.
+          // Only registered usage turns need cloud updates or periodic verification.
+          if (method === 'turn/started') activeTurns.set(threadId, turnId);
+          else {
+            if (activeTurns.get(threadId) === turnId) activeTurns.delete(threadId);
+            if (trackedTurns.get(threadId) === turnId) { trackedTurns.delete(threadId); saveTrackedTurns(); }
+            completedTurns.set(key, Date.now());
+            if (completedTurns.size > 100) completedTurns.delete(completedTurns.keys().next().value);
+          }
+          if (tracked) send(remote, { type: 'usage-turn', method, threadId, turnId });
+        } else if (message.type === 'end' || (message.type === 'response' && message.status >= 400)) socket.close();
+      } catch (error) { events.emit('diagnostic', error.message); socket.terminate(); }
+    });
+  }
+  function startFileReceiver() {
+    if (!identity || closing || remote.readyState !== WebSocket.OPEN) return;
+    const receiver = fileRemote = new WebSocket(relayUrl, { maxPayload: 512 * 1024, perMessageDeflate: false });
+    receiver.on('open', () => send(receiver, { type: 'file-host', deviceId: identity.id, deviceSecret: identity.secret }));
+    receiver.on('error', error => events.emit('diagnostic', `File receiver: ${error.message}`));
+    receiver.on('close', () => {
+      for (const socket of fileLocals.values()) socket.terminate();
+      fileLocals.clear();
+      if (fileRemote === receiver) {
+        fileRemote = undefined;
+        if (!closing && remote.readyState === WebSocket.OPEN) fileRetryTimer = setTimeout(startFileReceiver, 3000);
+      }
+    });
+    receiver.on('message', (bytes, binary) => {
+      try {
+        if (binary) {
+          const { session, data } = parseFileBytes(bytes);
+          const socket = fileLocals.get(session);
+          if (socket?.readyState === WebSocket.OPEN) {
+            if (socket.bufferedAmount > 1024 * 1024) { socket.close(1013, 'File receiver too slow'); return; }
+            socket.send(data);
+          }
+          return;
+        }
+        const message = decode(bytes, binary);
+        if (message.type === 'file-host-ready') return;
+        if (message.type === 'file-open') {
+          const connection = bridgeConnection?.() || { url: bridgeUrl, token: bridgeToken };
+          const url = new URL(connection.url); url.pathname = '/api/file-transfer';
+          loopbackUrl(url.href, '/api/file-transfer');
+          const socket = new WebSocket(url.href, { maxPayload: 512 * 1024, perMessageDeflate: false });
+          fileLocals.set(message.session, socket);
+          socket.on('open', () => send(socket, { type: 'auth', token: connection.token, purpose: message.purpose }));
+          socket.on('error', error => events.emit('diagnostic', `Local file receiver: ${error.message}`));
+          socket.on('close', () => {
+            if (fileLocals.get(message.session) !== socket) return;
+            fileLocals.delete(message.session);
+            send(receiver, { type: 'file-close', session: message.session });
+          });
+          socket.on('message', (data, isBinary) => {
+            if (fileLocals.get(message.session) !== socket) return socket.terminate();
+            if (receiver.readyState !== WebSocket.OPEN || receiver.bufferedAmount > 1024 * 1024) return socket.close(1013, 'File receiver too slow');
+            if (isBinary) receiver.send(routedFileBytes(message.session, data));
+            else send(receiver, { type: 'file-frame', session: message.session, payload: data.toString() });
+          });
+        } else if (message.type === 'file-frame') {
+          const socket = fileLocals.get(message.session);
+          if (socket?.readyState === WebSocket.OPEN) {
+            if (socket.bufferedAmount > 1024 * 1024) { socket.close(1013, 'File receiver too slow'); return; }
+            socket.send(message.payload);
+          }
+        } else if (message.type === 'file-close') fileLocals.get(message.session)?.terminate();
+        else throw new Error('Invalid file receiver frame');
+      } catch (error) { events.emit('diagnostic', error.message); receiver.close(1008, 'Invalid file frame'); }
+    });
   }
   const ready = new Promise((resolve, reject) => {
     let registered = false;
@@ -44,9 +236,15 @@ export function connectBridgeRelay({ relayUrl, hostKey, bridgeUrl, bridgeToken,
     remote.on('message', (bytes, binary) => {
       try {
         const message = decode(bytes, binary);
-        if (message.type === 'registered' && !registered) { registered = true; clearTimeout(timer); resolve(message); return; }
+        if (message.type === 'registered' && !registered) {
+          registered = true; clearTimeout(timer); startFileReceiver(); startTurnReceiver();
+          turnPulseTimer = setInterval(() => {
+            verifyActiveTurns();
+          }, 10000);
+          resolve(message); return;
+        }
         if (!registered) throw new Error('Relay not registered');
-        if (message.type === 'pair-code' || message.type === 'revoked' || message.type === 'status') {
+        if (['pair-code', 'revoked', 'status', 'invite-create', 'invite-list', 'invite-revoke'].includes(message.type)) {
           if (operation && message.commandId === operation.id && message.type === operation.responseType) {
             clearTimeout(operation.timer); const pending = operation; operation = undefined;
             message.error ? pending.reject(new Error(message.error)) : pending.resolve(message);
@@ -59,8 +257,8 @@ export function connectBridgeRelay({ relayUrl, hostKey, bridgeUrl, bridgeToken,
         if (message.type === 'attach') {
           events.emit('attached', { session: message.session, clientId: message.clientId });
           dropLocal(message.session);
-          const current = { socket: undefined, ready: false, timer: undefined, p2pProbe: p2pProbe && message.p2pProbe === 1,
-            bridgeOutbound: Promise.resolve() };
+          const current = { socket: undefined, ready: false, timer: undefined, p2pProbe: p2pProbe && message.p2pProbe === 1,
+            bridgeOutbound: Promise.resolve(), healthRequests: new Set(), usageRequests: new Map(), detached: false, detachedTimer: undefined };
           locals.set(message.session, current);
           let connection;
           try {
@@ -68,77 +266,155 @@ export function connectBridgeRelay({ relayUrl, hostKey, bridgeUrl, bridgeToken,
             loopbackUrl(connection.url, '/api/socket');
           } catch {
             send(remote, { type: 'detach', session: message.session }); dropLocal(message.session); events.emit('detached', { session: message.session });
-            events.emit('diagnostic', 'Local Bridge connection not ready'); return;
+            events.emit('diagnostic', 'Local desktop service connection not ready'); return;
           }
-          const socket = current.socket = new WebSocket(connection.url, { maxPayload: 64 * 1024 * 1024, perMessageDeflate: false });
-          current.forwardToBridge = payload => {
-            if (locals.get(message.session) !== current || !current.ready) throw new Error('Local Bridge connection not ready');
-            const request = decode(payload, false);
-            if (!['request', 'subscribe', 'unsubscribe'].includes(request.type)) throw new Error('Unsupported LAN message');
-            send(socket, request);
-          };
+          const socket = current.socket = new WebSocket(connection.url, { maxPayload: 64 * 1024 * 1024, perMessageDeflate: false });
+          current.forwardToBridge = payload => {
+            if (locals.get(message.session) !== current || !current.ready) throw new Error('Local desktop service connection not ready');
+            const request = decode(payload, false);
+            if (!['request', 'subscribe', 'unsubscribe', 'response-ack', 'cancel'].includes(request.type)) throw new Error('Unsupported LAN message');
+            if (request.type === 'request' && request.method === 'GET' && request.path === '/api/health' && Number.isSafeInteger(request.id)) {
+              current.healthRequests.add(request.id);
+            }
+            if (request.type === 'cancel') current.healthRequests.delete(request.id);
+            if (request.type === 'request' && request.method === 'POST' && Number.isSafeInteger(request.id)) {
+              const path = (request.path || '').split('?')[0];
+              const existing = /^\/api\/threads\/([^/?]+)\/(?:messages|queue)$/.exec(path);
+              const created = /^\/api\/projects\/[^/?]+\/threads$/.test(path);
+              if (existing || created) {
+                const threadId = existing ? decodeURIComponent(existing[1]) : null;
+                const messageKey = typeof request.body?.clientUserMessageId === 'string' && request.body.clientUserMessageId.length <= 64
+                  ? request.body.clientUserMessageId : `${message.session}:${request.id}`;
+                current.usageRequests.set(request.id, { threadId, messageKey, created });
+                send(remote, { type: 'usage-arm', session: message.session, requestId: request.id, threadId });
+              }
+            }
+            send(socket, request);
+          };
           current.timer = setTimeout(() => socket.terminate(), 5000);
           socket.on('open', () => send(socket, { type: 'auth', token: connection.token }));
-          socket.on('error', error => events.emit('diagnostic', `Local Bridge: ${error.message}`));
+          socket.on('error', error => events.emit('diagnostic', `Local desktop service: ${error.message}`));
           socket.on('close', () => {
+            clearTimeout(current.detachedTimer);
             if (locals.get(message.session)?.socket !== socket) return;
             send(remote, { type: 'detach', session: message.session }); dropLocal(message.session); events.emit('detached', { session: message.session });
           });
           socket.on('message', (data, isBinary) => {
-            if (locals.get(message.session)?.socket !== socket) return;
+            if (locals.get(message.session)?.socket !== socket && !current.detached) return;
             try {
               const response = decode(data, isBinary);
               if (!current.ready) {
-                if (response.type !== 'ready') throw new Error('Local Bridge authentication failed');
+                if (response.type !== 'ready') throw new Error('Local desktop service authentication failed');
                 clearTimeout(current.timer); current.ready = true; send(remote, { type: 'ready', session: message.session });
-              } else {
-                const payload = data.toString();
-                current.bridgeOutbound = current.bridgeOutbound.then(async () => {
-                  const probe = await current.probe;
-                  if (locals.get(message.session) !== current || !current.ready) return;
-                  if (!probe?.send?.(payload)) send(remote, { type: 'data', session: message.session, payload });
-                });
-                void current.bridgeOutbound.catch(error => { events.emit('diagnostic', error.message); socket.terminate(); });
-              }
+              } else {
+                const usage = response.type === 'response' ? current.usageRequests.get(response.id) : null;
+                if (usage) {
+                  current.usageRequests.delete(response.id);
+                  const threadId = usage.threadId || response.body?.threadId;
+                  if (response.status >= 200 && response.status < 300 && typeof threadId === 'string') {
+                    const turnId = usage.created ? response.body?.turnId : response.body?.usage?.turnId;
+                    const turnKind = usage.created ? 'start' : response.body?.usage?.kind;
+                    send(remote, { type: 'usage-message', session: message.session, requestId: response.id,
+                      threadId, messageKey: usage.messageKey, turnId, turnKind,
+                      completed: completedTurns.has(`${threadId}:${turnId}`), observerReady: turnObserverReady,
+                      active: activeTurns.get(threadId) === turnId });
+                    if (['start', 'steer'].includes(turnKind) && typeof turnId === 'string' &&
+                        !completedTurns.has(`${threadId}:${turnId}`)) {
+                      trackedTurns.set(threadId, turnId); saveTrackedTurns();
+                      if (turnObserverReady && !activeTurns.has(threadId)) queueTurnResync(threadId, turnId);
+                    }
+                  } else send(remote, { type: 'usage-cancel', session: message.session, requestId: response.id });
+                }
+                if (current.detached) {
+                  if (!current.usageRequests.size) socket.terminate();
+                  return;
+                }
+                const payload = data.toString();
+                // Native health probes use the relay socket. Keep their replies on that
+                // route, outside the RTC queue shared by chat and file downloads.
+                if (response.type === 'response' && current.healthRequests.delete(response.id)) {
+                  send(remote, { type: 'data', session: message.session, payload });
+                  return;
+                }
+                current.bridgeOutbound = current.bridgeOutbound.then(async () => {
+                  const probe = await current.probe;
+                  if (locals.get(message.session) !== current || !current.ready) return;
+                  if (!probe?.send?.(payload)) send(remote, { type: 'data', session: message.session, payload });
+                });
+                void current.bridgeOutbound.catch(error => { events.emit('diagnostic', error.message); socket.terminate(); });
+              }
             } catch (error) { events.emit('diagnostic', error.message); socket.terminate(); }
           });
         } else if (message.type === 'p2p-probe' && locals.has(message.session)) {
           const current = locals.get(message.session);
           if (!current.ready || !current.p2pProbe || !validProbeSignal(message)) throw new Error('Invalid probe signal');
-          if (message.kind === 'start' && current.probeId !== message.probeId) {
-            void current.probe?.then(probe => probe.close());
-            current.probeId = message.probeId;
-            current.routeSignals = Promise.resolve();
+          if (message.purpose === 'diagnostic') {
+            if (message.kind === 'start' && current.diagnosticProbeId !== message.probeId) {
+              void current.diagnosticProbe?.then(probe => probe.close());
+              current.diagnosticProbeId = message.probeId;
+              const probeId = message.probeId;
+              current.diagnosticProbe = createP2pProbe({ iceServers,
+                signal: signal => {
+                  if (locals.get(message.session) === current && current.diagnosticProbeId === probeId) {
+                    send(remote, { type: 'p2p-probe', purpose: 'diagnostic', session: message.session,
+                      version: 1, probeId, ...signal });
+                  }
+                },
+                report: (state, diagnostic) => events.emit('p2p-probe', { state, diagnostic })
+              }).catch(() => {
+                if (locals.get(message.session) === current && current.diagnosticProbeId === probeId) {
+                  send(remote, { type: 'p2p-probe', purpose: 'diagnostic', session: message.session,
+                    version: 1, probeId, kind: 'close' });
+                }
+                return { receive() {}, close() {} };
+              });
+            } else if (current.diagnosticProbe && current.diagnosticProbeId === message.probeId) {
+              void current.diagnosticProbe.then(probe => probe.receive(message));
+            }
+            return;
+          }
+          if (message.purpose && message.purpose !== 'file') throw new Error('Invalid probe purpose');
+          const file = message.purpose === 'file';
+          const probeField = file ? 'fileProbe' : 'probe', idField = file ? 'fileProbeId' : 'probeId';
+          const signalsField = file ? 'fileRouteSignals' : 'routeSignals', helperField = file ? 'fileRouteHelper' : 'routeHelper';
+          if (message.kind === 'start' && current[idField] !== message.probeId) {
+            void current[probeField]?.then(probe => probe.close());
+            current[idField] = message.probeId;
+            current[signalsField] = Promise.resolve();
             const probeId = message.probeId;
-            current.routeHelper = createWindowsRouteHelper({ enabled: p2pWindowsRouteHelper, token: p2pWindowsRouteHelperToken, iceServers,
+            current[helperField] = createWindowsRouteHelper({ enabled: p2pWindowsRouteHelper, token: p2pWindowsRouteHelperToken, iceServers,
               report: (event, details) => events.emit('diagnostic', `${event};count=${details.count}`) });
-            current.probe = current.routeHelper.prepare().then(() => createP2pProbe({ iceServers,
+            current[probeField] = current[helperField].prepare().then(() => createP2pProbe({ iceServers, purpose: file ? 'file' : '',
               signal: signal => {
-                if (locals.get(message.session) === current && current.probeId === probeId) send(remote, { type: 'p2p-probe', session: message.session,
+                if (locals.get(message.session) === current && current[idField] === probeId) send(remote, { type: 'p2p-probe', session: message.session, ...(file ? { purpose: 'file' } : {}),
                   version: 1, probeId, ...signal });
-              },
-              onData: payload => current.forwardToBridge(payload),
-              report: (state, diagnostic) => events.emit('p2p-probe', { state, diagnostic })
+              },
+              onData: file ? undefined : payload => current.forwardToBridge(payload),
+              onFileChannel: file ? channel => attachRtcFile(channel, bridgeConnection?.() || { url: bridgeUrl, token: bridgeToken },
+                () => locals.get(message.session) === current && current.ready && current[idField] === probeId && remote.readyState === WebSocket.OPEN) : undefined,
+              report: (state, diagnostic) => events.emit('p2p-probe', { state, diagnostic, purpose: file ? 'file' : 'chat' })
             })).catch(() => {
               events.emit('diagnostic', p2pWindowsRouteHelper ? 'Windows RTC 路由辅助不可用' : 'WebRTC probe initialization failed');
+              if (locals.get(message.session) === current && current[idField] === probeId) send(remote, {
+                type: 'p2p-probe', session: message.session, version: 1, probeId, ...(file ? { purpose: 'file' } : {}), kind: 'close' });
               return { receive() {}, close() {} };
             });
-          } else if (current.probe && current.probeId === message.probeId) {
-            const pending = current.probe;
-            current.routeSignals ||= Promise.resolve();
-            current.routeSignals = current.routeSignals.then(async () => {
-              await current.routeHelper?.include(message);
+          } else if (current[probeField] && current[idField] === message.probeId) {
+            const pending = current[probeField];
+            current[signalsField] ||= Promise.resolve();
+            current[signalsField] = current[signalsField].then(async () => {
+              await current[helperField]?.include(message);
               const probe = await pending;
-              if (locals.get(message.session) === current && current.probeId === message.probeId) probe.receive(message);
+              if (locals.get(message.session) === current && current[idField] === message.probeId) probe.receive(message);
             });
-            void current.routeSignals
+            void current[signalsField]
               .catch(() => { events.emit('diagnostic', 'WebRTC probe negotiation failed'); void pending.then(probe => probe.close()); });
           }
         } else if (message.type === 'detach' && locals.has(message.session)) { dropLocal(message.session); events.emit('detached', { session: message.session }); }
         else if (message.type === 'data' && locals.has(message.session)) {
           const current = locals.get(message.session);
           if (!current.ready) { send(remote, { type: 'detach', session: message.session }); dropLocal(message.session); return; }
-          current.forwardToBridge(message.payload);
+          current.forwardToBridge(message.payload);
         }
       } catch (error) { events.emit('diagnostic', error.message); remote.close(1008, 'Invalid relay message'); }
     });
@@ -157,6 +433,6 @@ export function connectBridgeRelay({ relayUrl, hostKey, bridgeUrl, bridgeToken,
     updateLanCandidates(candidates) {
       if (!send(remote, { type: 'lan-candidates', candidates })) throw new Error('中继未连接');
     },
-    close() { clearTimeout(heartbeat); dropLocals(); remote.terminate(); }
+    close() { closing = true; clearTimeout(heartbeat); dropLocals(); remote.terminate(); }
   };
 }