orbit-codex-bridge 0.0.0-stage → 0.1.1

package/lib/desktop.mjs

@@ -0,0 +1,404 @@
+import net from 'node:net';
+import crypto from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import { messageFromItem } from './store.mjs';
+
+const maxFrame = 32 * 1024 * 1024;
+const versions = { initialize: 0, 'thread-owner-discovery': 1, 'thread-follower-read-model-settings': 1, 'thread-follower-update-thread-settings': 2, 'thread-follower-start-turn': 2, 'thread-follower-steer-turn': 1, 'thread-follower-interrupt-turn': 4, 'thread-follower-command-approval-decision': 1, 'thread-follower-file-approval-decision': 1, 'thread-follower-submit-user-input': 1, 'thread-follower-permissions-request-approval-response': 1 };
+const approvalMethods = new Map([
+  ['item/commandExecution/requestApproval', 'thread-follower-command-approval-decision'],
+  ['item/fileChange/requestApproval', 'thread-follower-file-approval-decision'],
+  ['item/tool/requestUserInput', 'thread-follower-submit-user-input'],
+  ['item/permissions/requestApproval', 'thread-follower-permissions-request-approval-response']
+]);
+
+export class DesktopUnavailableError extends Error {
+  constructor(message, code = 'DESKTOP_THREAD_UNAVAILABLE') {
+    super(message);
+    this.code = code;
+  }
+}
+
+export function applyDesktopPatches(state, patches) {
+  if (!Array.isArray(patches) || patches.length > 10000) throw new Error('桌面补丁格式不兼容。');
+  state = structuredClone(state);
+  for (const patch of patches) {
+    if (!['add', 'replace', 'remove'].includes(patch.op) || !Array.isArray(patch.path) || patch.path.length > 64) throw new Error('桌面补丁格式不兼容。');
+    if (patch.path.some(key => !['string', 'number'].includes(typeof key) || ['__proto__', 'prototype', 'constructor'].includes(String(key)))) throw new Error('已拒绝不安全的补丁路径。');
+    if (!patch.path.length) {
+      if (patch.op === 'remove') throw new Error('不可移除桌面状态根节点。');
+      state = patch.value;
+      continue;
+    }
+    let target = state;
+    for (const key of patch.path.slice(0, -1)) {
+      if (!target || typeof target !== 'object' || !Object.hasOwn(target, key)) throw new Error('桌面补丁基线不匹配。');
+      target = target[key];
+    }
+    const key = patch.path.at(-1);
+    if (!target || typeof target !== 'object') throw new Error('桌面补丁基线不匹配。');
+    if (Array.isArray(target)) {
+      if (!/^(0|[1-9]\d*)$/.test(String(key)) || !Number.isSafeInteger(Number(key)) || Number(key) > target.length || (patch.op !== 'add' && Number(key) >= target.length)) throw new Error('桌面补丁索引不兼容。');
+      if (patch.op === 'add') target.splice(Number(key), 0, patch.value);
+      else if (patch.op === 'remove') target.splice(Number(key), 1);
+      else target[key] = patch.value;
+    } else {
+      if (patch.op !== 'add' && !Object.hasOwn(target, key)) throw new Error('桌面补丁路径不存在。');
+      if (patch.op === 'remove') delete target[key]; else target[key] = patch.value;
+    }
+  }
+  return state;
+}
+
+export function desktopTurns(state) {
+  const history = state?.turnHistory?.history;
+  if (state?.turnHistory?.kind === 'canonical' && history) return (history.islands || []).flatMap(island => (island.entries || []).map(entry => history.entitiesByKey?.[entry.value]).filter(Boolean));
+  return state?.turns || [];
+}
+
+export function desktopMessages(state) {
+  return desktopTurns(state).slice(-8).flatMap(turn => (turn.items || []).flatMap(item => {
+    const message = messageFromItem(item, turn.turnStartedAtMs || null);
+    return message?.id && (message.text || message.role === 'activity') ? [{ ...message, live: turn.status === 'inProgress' }] : [];
+  })).slice(-160);
+}
+
+export function desktopContext(state) {
+  const info = state?.latestTokenUsageInfo;
+  const usedTokens = info?.last?.totalTokens;
+  const windowTokens = info?.modelContextWindow;
+  if (!Number.isSafeInteger(usedTokens) || usedTokens < 0) return null;
+  return {
+    usedTokens,
+    windowTokens: Number.isSafeInteger(windowTokens) && windowTokens > 0 ? windowTokens : null,
+    cachedTokens: Number.isSafeInteger(info.last.cachedInputTokens) && info.last.cachedInputTokens >= 0 ? info.last.cachedInputTokens : null
+  };
+}
+
+export class DesktopRpc extends EventEmitter {
+  constructor({ pipePath = process.env.ORBIT_DESKTOP_PIPE || (process.platform === 'win32' ? '\\\\.\\pipe\\codex-ipc' : ''), timeout = 6000 } = {}) {
+    super();
+    this.mode = 'desktop';
+    this.pipePath = pipePath;
+    this.timeout = timeout;
+    this.connected = false;
+    this.clientId = 'initializing-client';
+    this.threads = new Map();
+    this.approvals = new Map();
+    this.pending = new Map();
+    this.attaching = new Map();
+    this.starting = new Set();
+    this.updatingSettings = new Set();
+    this.buffer = Buffer.alloc(0);
+  }
+
+  async connect() {
+    if (this.connected) return;
+    if (this.connecting) return this.connecting;
+    if (!this.pipePath) throw new Error('未配置受支持的桌面 IPC 路径，未启动独立执行器。');
+    this.connecting = (async () => {
+      const socket = net.createConnection(this.pipePath);
+      this.socket = socket;
+      socket.on('error', () => this.disconnect(new Error('桌面 IPC 不可用，请保持 Codex 桌面打开。'), socket));
+      socket.on('close', () => this.disconnect(new Error('桌面连接断开；未重发任何指令，请重新授权。'), socket));
+      socket.on('data', chunk => {
+        if (this.socket !== socket) return;
+        try { this.receive(chunk); } catch { this.disconnect(new Error('桌面协议不兼容，已停止接管。'), socket); }
+      });
+      await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { socket.destroy(); reject(new Error('连接桌面超时。')); }, this.timeout);
+        socket.once('connect', () => { clearTimeout(timer); resolve(); });
+        socket.once('error', () => { clearTimeout(timer); reject(new Error('找不到 Codex 桌面 IPC；不会回退到独立接续。')); });
+      });
+      const result = await this.request('initialize', { clientType: 'orbit' });
+      if (typeof result.clientId !== 'string') throw new Error('桌面 IPC 初始化响应不兼容。');
+      this.clientId = result.clientId;
+      this.connected = true;
+      this.emit('event', { method: 'orbit/engine', params: { connected: true, mode: 'desktop' } });
+    })();
+    try { await this.connecting; } catch (error) { this.disconnect(error); throw error; }
+    finally { this.connecting = null; }
+  }
+
+  send(message) {
+    if (!this.socket?.writable) throw new Error('桌面 IPC 未连接。');
+    const payload = Buffer.from(JSON.stringify(message));
+    if (payload.length > maxFrame) throw new Error('桌面请求过大。');
+    const frame = Buffer.alloc(payload.length + 4);
+    frame.writeUInt32LE(payload.length);
+    payload.copy(frame, 4);
+    this.socket.write(frame);
+  }
+
+  request(method, params, targetClientId) {
+    if (!Object.hasOwn(versions, method)) return Promise.reject(new Error('此桌面操作未在白名单中。'));
+    const requestId = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { this.pending.delete(requestId); reject(new Error('桌面响应超时；操作结果未知，绝不自动重发。请检查桌面记录。')); }, this.timeout);
+      this.pending.set(requestId, { resolve, reject, timer, method, targetClientId, conversationId: params?.conversationId, thread: this.threads.get(params?.conversationId) });
+      try { this.send({ type: 'request', requestId, sourceClientId: this.clientId, method, version: versions[method], params, targetClientId, timeoutMs: this.timeout - 100 }); }
+      catch (error) { clearTimeout(timer); this.pending.delete(requestId); reject(error); }
+    });
+  }
+
+  receive(chunk) {
+    this.buffer = Buffer.concat([this.buffer, chunk]);
+    while (this.buffer.length >= 4) {
+      const length = this.buffer.readUInt32LE();
+      if (!length || length > maxFrame) throw new Error('无效桌面帧。');
+      if (this.buffer.length < length + 4) return;
+      const message = JSON.parse(this.buffer.subarray(4, length + 4).toString('utf8'));
+      this.buffer = this.buffer.subarray(length + 4);
+      this.dispatch(message);
+    }
+  }
+
+  dispatch(message) {
+    if (message.type === 'response') {
+      const pending = this.pending.get(message.requestId);
+      if (!pending) return;
+      clearTimeout(pending.timer); this.pending.delete(message.requestId);
+      if (message.resultType !== 'success') {
+        const reason = typeof message.error === 'string' ? message.error : message.error?.code || 'unknown error';
+        if (/^no-client-found(?::|$)/.test(reason)) {
+          const error = new DesktopUnavailableError('这条原会话尚未在 Codex 桌面加载，或原连接已失效。请在电脑上打开这条原会话，再点击“重新连接”。');
+          if (pending.conversationId && this.threads.get(pending.conversationId) === pending.thread) this.detach(pending.conversationId, error.message, error.code);
+          pending.reject(error);
+        } else pending.reject(new Error(`桌面拒绝操作：${reason}`));
+      }
+      else if (message.method !== pending.method || (pending.targetClientId && message.handledByClientId !== pending.targetClientId)) {
+        const error = new DesktopUnavailableError('桌面执行者或协议发生变化，已拒绝响应。请重新连接并授权。', 'DESKTOP_OWNER_CHANGED');
+        if (pending.conversationId && this.threads.get(pending.conversationId) === pending.thread) this.detach(pending.conversationId, error.message, error.code);
+        pending.reject(error);
+      }
+      else pending.resolve({ ...message.result, ownerClientId: message.handledByClientId });
+      return;
+    }
+    if (message.type === 'client-discovery-request') {
+      this.send({ type: 'client-discovery-response', requestId: message.requestId, response: { canHandle: false } });
+      return;
+    }
+    if (message.type === 'request') {
+      this.send({ type: 'response', requestId: message.requestId, resultType: 'error', error: 'no-handler-for-request' });
+      return;
+    }
+    if (message.type !== 'broadcast' || (message.targetClientIds && !message.targetClientIds.includes(this.clientId))) return;
+    if (message.method === 'client-status-changed' && message.params?.status === 'disconnected') {
+      for (const [id, thread] of this.threads) if (thread.ownerClientId === message.params.clientId) this.detach(id, '桌面执行者已离线，请重新打开会话并授权。');
+    }
+    if (message.method !== 'thread-stream-state-changed' || message.version !== 11 || message.params?.hostId !== 'local') return;
+    const { conversationId: id, change } = message.params;
+    const thread = this.threads.get(id);
+    if (!thread || thread.ownerClientId !== message.sourceClientId) return;
+    try {
+      if (change.type === 'snapshot') {
+        if (change.conversationState?.id !== id || !Number.isSafeInteger(change.revision)) throw new Error('桌面快照不匹配。');
+        if (thread.state && change.revision < thread.revision) return;
+        thread.state = change.conversationState;
+      } else if (change.type === 'patches') {
+        if (!thread.state || thread.revision !== change.baseRevision || change.revision <= change.baseRevision) throw new Error('桌面状态版本缺口。');
+        thread.state = applyDesktopPatches(thread.state, change.patches);
+      } else throw new Error('未知桌面状态类型。');
+      thread.revision = change.revision;
+      thread.turnId = desktopTurns(thread.state).findLast(turn => turn.status === 'inProgress')?.turnId || null;
+      this.syncApprovals(id, thread);
+      this.emit('state', id);
+      this.publish(id);
+    } catch {
+      thread.state = null;
+      thread.turnId = null;
+      this.emit('lost', id);
+      this.publish(id);
+      if (!thread.resyncing) {
+        thread.resyncing = true;
+        this.follow(id, thread.ownerClientId, false);
+        this.follow(id, thread.ownerClientId, true);
+        setTimeout(() => { if (this.threads.get(id) === thread) { thread.resyncing = false; if (!thread.state) this.detach(id, '桌面状态恢复失败，请重新连接。'); } }, this.timeout).unref();
+      }
+    }
+  }
+
+  follow(id, ownerClientId, following) {
+    this.send({ type: 'broadcast', method: 'thread-stream-following-changed', sourceClientId: this.clientId, version: 1, params: { conversationId: id, hostId: 'local', following }, targetClientIds: [ownerClientId] });
+  }
+
+  async attach(id) {
+    await this.connect();
+    const current = this.threads.get(id);
+    if (current?.state) {
+      try { await this.assertOwner(id); return this.runtime(id); }
+      catch (error) { if (this.threads.get(id) === current) this.detach(id, error.message); throw error; }
+    }
+    if (this.attaching.has(id)) return this.attaching.get(id);
+    const operation = (async () => {
+      const owner = await this.request('thread-owner-discovery', { conversationId: id, hostId: 'local' });
+      if (!owner.ownerClientId) throw new DesktopUnavailableError('这条原会话尚未在 Codex 桌面加载。请在电脑上打开它，再点击“重新连接”。');
+      const result = await this.request('thread-follower-read-model-settings', { conversationId: id }, owner.ownerClientId);
+      if (result.settings?.resumeState !== 'resumed') throw new Error('桌面会话尚未就绪，请先在 Codex 中打开。');
+      this.threads.set(id, { ownerClientId: owner.ownerClientId, state: null, revision: null, turnId: null });
+      await new Promise((resolve, reject) => {
+        const cleanup = () => { clearTimeout(timer); this.off('state', listener); this.off('lost', failed); };
+        const listener = updated => { if (updated === id && this.threads.get(id)?.state) { cleanup(); resolve(); } };
+        const failed = lost => { if (lost === id) { cleanup(); reject(new Error('桌面会话连接已失效。')); } };
+        const timer = setTimeout(() => { cleanup(); reject(new Error('未收到桌面实时快照，不开放控制。')); }, this.timeout);
+        this.on('state', listener); this.on('lost', failed);
+        try { this.follow(id, owner.ownerClientId, true); } catch (error) { cleanup(); reject(error); }
+      });
+      return this.runtime(id);
+    })();
+    this.attaching.set(id, operation);
+    try { return await operation; } catch (error) { this.detach(id, error.message); throw error; }
+    finally { this.attaching.delete(id); }
+  }
+
+  runtime(id) {
+    const thread = this.threads.get(id);
+    const state = thread?.state;
+    return {
+      threadId: id, attached: Boolean(this.connected && state), mode: 'desktop',
+      ownerClientId: thread?.ownerClientId || null, connectionId: this.connected ? this.clientId : null,
+      turnId: thread?.turnId || null, revision: thread?.revision ?? null,
+      permissionMode: state?.currentPermissions?.sandboxPolicy?.type || state?.latestThreadSettings?.sandboxPolicy?.type || 'desktop-inherited',
+      model: state?.latestThreadSettings?.model || state?.latestModel || null,
+      effort: state?.latestThreadSettings?.effort ?? state?.latestReasoningEffort ?? null,
+      context: desktopContext(state),
+      messages: state ? desktopMessages(state) : [],
+      approvals: [...this.approvals.values()].filter(request => request.params.threadId === id).map(request => ({ ...request.params, requestId: String(request.id), method: request.method }))
+    };
+  }
+
+  publish(id) { this.emit('event', { method: 'orbit/desktop', params: this.runtime(id) }); }
+
+  syncApprovals(id, thread) {
+    const previous = new Set([...this.approvals.values()].filter(request => request.params.threadId === id).map(request => request.id));
+    for (const request of Object.values(thread.state.requests || {})) {
+      if (!approvalMethods.has(request.method) || request.id === undefined || request.params?.threadId !== id) continue;
+      const key = `${id}:${request.id}`;
+      previous.delete(key);
+      this.approvals.set(key, { ...request, originalId: request.id, id: key });
+    }
+    for (const key of previous) this.approvals.delete(key);
+  }
+
+  async assertOwner(id) {
+    const thread = this.threads.get(id);
+    if (!this.connected || !thread?.state) throw new Error('桌面实时状态未就绪，请重新连接并授权。');
+    let owner;
+    try { owner = await this.request('thread-owner-discovery', { conversationId: id, hostId: 'local' }); }
+    catch (error) {
+      if (this.threads.get(id) === thread) this.detach(id, error.message, error.code);
+      throw error;
+    }
+    if (owner.ownerClientId !== thread.ownerClientId || this.threads.get(id) !== thread || !thread.state) {
+      const error = new DesktopUnavailableError('会话执行者发生变化，未发送指令。请重新连接并授权。', 'DESKTOP_OWNER_CHANGED');
+      this.detach(id, error.message, error.code);
+      throw error;
+    }
+    return thread;
+  }
+
+  async startTurn(id, text) { return this.writeMessage(id, text, false); }
+  async steer(id, text, expectedTurnId) { return this.writeMessage(id, text, true, expectedTurnId); }
+
+  async updateThreadSettings(id, model, effort, expectedModel, expectedEffort) {
+    if (this.starting.has(id) || this.updatingSettings.has(id)) throw new Error('会话正在处理另一项操作，请稍后重试。');
+    this.updatingSettings.add(id);
+    try {
+      const thread = await this.assertOwner(id);
+      if (thread.turnId) throw new Error('当前任务正在执行，请将参数排到下一轮。');
+      const currentModel = thread.state.latestThreadSettings?.model || thread.state.latestModel || null;
+      const currentEffort = thread.state.latestThreadSettings?.effort ?? thread.state.latestReasoningEffort ?? null;
+      if (currentModel !== expectedModel || currentEffort !== expectedEffort) throw new Error('模型设置已变化，请刷新后重试。');
+      const result = await this.request('thread-follower-update-thread-settings', {
+        conversationId: id, threadSettings: { model, effort }, activeTurnId: null,
+        condition: { ifModelEquals: thread.state.latestModel || currentModel, ifEffortEquals: thread.state.latestReasoningEffort ?? null }
+      }, thread.ownerClientId);
+      if (result.applied !== true) throw new Error('桌面模型设置已变化，未应用选择，请刷新后重试。');
+      const confirmed = await this.request('thread-follower-read-model-settings', { conversationId: id }, thread.ownerClientId);
+      if (confirmed.settings?.model !== model || confirmed.settings?.reasoningEffort !== effort) {
+        throw new Error('桌面尚未确认模型设置，请刷新会话核对后再发送。');
+      }
+      return { model, effort, applied: true };
+    } finally { this.updatingSettings.delete(id); }
+  }
+
+  async writeMessage(id, text, steering, expectedTurnId) {
+    if (this.starting.has(id) || this.updatingSettings.has(id)) throw new Error('此会话正在处理其他操作，请勿并发提交。');
+    this.starting.add(id);
+    try {
+      const thread = await this.assertOwner(id);
+      if (steering ? !expectedTurnId || thread.turnId !== expectedTurnId : Boolean(thread.turnId)) throw new Error('任务状态已变化，请刷新后选择续聊或追加指令。');
+      const messageId = crypto.randomUUID();
+      const input = [{ type: 'text', text, text_elements: [] }];
+      const restoreMessage = { id: messageId, text, cwd: thread.state.cwd, createdAt: Date.now(), context: { prompt: text, addedFiles: [], fileAttachments: [], imageAttachments: [], ideContext: null, workspaceRoots: [thread.state.cwd] } };
+      let result;
+      if (steering) result = await this.request('thread-follower-steer-turn', { conversationId: id, input, restoreMessage, clientUserMessageId: messageId, attachments: [] }, thread.ownerClientId);
+      else result = await this.request('thread-follower-start-turn', { conversationId: id, turnStart: { request: { threadId: id, input, clientUserMessageId: messageId, turnTrigger: 'composer' }, context: { restoreMessage } } }, thread.ownerClientId);
+      const response = result.result || result;
+      const turnId = response.turnId || response.turn?.id || this.threads.get(id)?.turnId || null;
+      return { threadId: id, turnId, completed: typeof response.completed === 'boolean' ? response.completed : Boolean(!steering && !turnId), steering, sharedExecution: true };
+    } finally { this.starting.delete(id); }
+  }
+
+  async interrupt(id, expectedTurnId) {
+    const thread = await this.assertOwner(id);
+    if (!expectedTurnId || thread.turnId !== expectedTurnId) throw new Error('活动任务已变化，未停止其他任务。');
+    const result = await this.request('thread-follower-interrupt-turn', { conversationId: id, mode: 'user-stop', expectedTurnId }, thread.ownerClientId);
+    return result;
+  }
+
+  async replyApproval(key, body) {
+    const request = this.approvals.get(String(key));
+    if (!request) throw new Error('审批已被桌面处理或已失效。');
+    const thread = await this.assertOwner(request.params.threadId);
+    if (this.approvals.get(String(key)) !== request) throw new Error('审批状态已变化，请刷新。');
+    let payload;
+    if (request.method === 'item/tool/requestUserInput') {
+      const answers = {};
+      for (const question of request.params.questions || []) {
+        const answer = body.answers?.[question.id];
+        if (typeof answer !== 'string' || !answer.trim() || answer.length > 4000) throw new Error('请回答所有问题。');
+        answers[question.id] = { answers: [answer] };
+      }
+      payload = { response: { answers } };
+    } else if (request.method === 'item/permissions/requestApproval') {
+      if (body.decision !== 'decline') throw new Error('扩大环境权限仍需在桌面处理。');
+      payload = { response: { permissions: {}, scope: 'turn' } };
+    } else {
+      if (!['accept', 'decline'].includes(body.decision)) throw new Error('无效审批决定。');
+      payload = { decision: body.decision };
+    }
+    await this.request(approvalMethods.get(request.method), { conversationId: request.params.threadId, requestId: request.originalId, ...payload }, thread.ownerClientId);
+    this.approvals.delete(String(key));
+    this.publish(request.params.threadId);
+    return { resolved: true };
+  }
+
+  detach(id, reason, reasonCode = 'DESKTOP_THREAD_UNAVAILABLE') {
+    const thread = this.threads.get(id);
+    if (!thread) return;
+    if (this.socket?.writable) {
+      try { this.follow(id, thread.ownerClientId, false); } catch {}
+    }
+    this.threads.delete(id);
+    for (const [key, request] of this.approvals) if (request.params.threadId === id) this.approvals.delete(key);
+    this.emit('lost', id, reason, reasonCode);
+    this.emit('event', { method: 'orbit/desktop', params: { threadId: id, mode: 'desktop', attached: false, turnId: null, reason, reasonCode } });
+  }
+
+  disconnect(error, socket = this.socket) {
+    if (socket && socket !== this.socket) return;
+    this.connected = false;
+    this.socket = null;
+    socket?.destroy();
+    for (const pending of this.pending.values()) { clearTimeout(pending.timer); pending.reject(error); }
+    this.pending.clear();
+    for (const id of this.threads.keys()) this.detach(id, error.message);
+    this.approvals.clear();
+    this.buffer = Buffer.alloc(0);
+    this.clientId = 'initializing-client';
+    this.emit('event', { method: 'orbit/engine', params: { connected: false, mode: 'desktop' } });
+  }
+
+  close() { this.disconnect(new Error('Orbit 已断开；桌面任务继续执行。')); }
+}

package/lib/device-auth.mjs

@@ -0,0 +1,69 @@
+import crypto from 'node:crypto';
+
+const digest = value => crypto.createHash('sha256').update(value).digest('hex');
+
+export class DeviceAuthorization {
+  constructor({ lifetime = 5 * 60 * 1000, now = Date.now } = {}) {
+    this.lifetime = lifetime;
+    this.now = now;
+    this.pending = new Map();
+    this.codes = new Map();
+  }
+
+  cleanup() {
+    for (const [key, value] of this.pending) {
+      if (value.expiresAt > this.now()) continue;
+      this.pending.delete(key);
+      this.codes.delete(value.userCode);
+    }
+  }
+
+  start(name) {
+    this.cleanup();
+    if (typeof name !== 'string' || !name.trim() || name.length > 120 || /[\u0000-\u001f\u007f]/.test(name)) {
+      throw new Error('电脑名称格式无效。');
+    }
+    if (this.pending.size >= 1000) throw Object.assign(new Error('连接请求过多，请稍后再试。'), {status:429});
+    const deviceCode = crypto.randomBytes(32).toString('base64url');
+    let userCode;
+    do { userCode = crypto.randomBytes(5).toString('hex').toUpperCase(); } while (this.codes.has(userCode));
+    const key = digest(deviceCode);
+    const entry = {name:name.trim(), userCode, expiresAt:this.now() + this.lifetime, result:null};
+    this.pending.set(key, entry);
+    this.codes.set(userCode, key);
+    return {deviceCode, userCode, expiresIn:Math.floor(this.lifetime / 1000), interval:2};
+  }
+
+  preview(userCode) {
+    this.cleanup();
+    if (typeof userCode !== 'string') return null;
+    const entry = this.pending.get(this.codes.get(userCode));
+    return entry && !entry.result ? {name:entry.name, userCode:entry.userCode, expiresAt:entry.expiresAt} : null;
+  }
+
+  approve(userCode, issue) {
+    if (!this.preview(userCode)) throw Object.assign(new Error('连接请求已失效，请在电脑重新运行 orbit login。'), {status:410});
+    const entry = this.pending.get(this.codes.get(userCode));
+    entry.result = issue(entry.name);
+  }
+
+  poll(deviceCode) {
+    this.cleanup();
+    if (typeof deviceCode !== 'string' || !/^[a-zA-Z0-9_-]{43}$/.test(deviceCode)) return {status:410};
+    const key = digest(deviceCode);
+    const entry = this.pending.get(key);
+    if (!entry) return {status:410};
+    if (!entry.result) return {status:202};
+    return {status:200, result:structuredClone(entry.result)};
+  }
+
+  acknowledge(deviceCode) {
+    if (typeof deviceCode !== 'string' || !/^[a-zA-Z0-9_-]{43}$/.test(deviceCode)) return false;
+    const key = digest(deviceCode);
+    const entry = this.pending.get(key);
+    if (!entry?.result) return false;
+    this.pending.delete(key);
+    this.codes.delete(entry.userCode);
+    return true;
+  }
+}