annotatable-html 1.38.3 → 1.45.3

package/lib/claude.js

@@ -0,0 +1,242 @@
+'use strict';
+
+var fs = require('fs'), path = require('path'), os = require('os'), util = require('util');
+var processes = require('./duty-process');
+var canonical = value => path.resolve(value).replace(/\\/g, '/').toLowerCase();
+function registrations(home, sessionId) {
+  var dir = path.join(home, 'sessions');
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter(n => /^\d+\.json$/.test(n)).flatMap(n => {
+    try { var r = JSON.parse(fs.readFileSync(path.join(dir, n), 'utf8')); return (!sessionId || r.sessionId === sessionId) ? [r] : []; } catch (_) { return []; }
+  });
+}
+async function liveRegistrations(home, id) {
+  var live = [];
+  for (var r of registrations(home, id)) {
+    var p = await processes.processInfo(r.pid);
+    if (p && /^claude(?:\.exe)?$/i.test(p.Name) && Number(p.CreationDate.replace(/\/Date\((\d+)\)\//, '$1')) <= r.startedAt + 2000) live.push({ registration: r, process: p });
+  }
+  return live;
+}
+function transcript(home, id) {
+  var dir = path.join(home, 'projects');
+  var found = fs.existsSync(dir) ? fs.readdirSync(dir).map(n => path.join(dir, n, id + '.jsonl')).filter(n => fs.existsSync(n)) : [];
+  if (found.length !== 1) throw new Error('无法唯一定位指定 Claude 会话记录');
+  return found[0];
+}
+function savedTurn(file, id) {
+  var rows = processes.tailRows(file).filter(r => r.sessionId === id && !r.isSidechain);
+  var user = rows.findLast(r => r.type === 'user' && r.permissionMode);
+  var assistant = rows.findLast(r => r.type === 'assistant' && r.message && r.message.model);
+  if (!user || !assistant || !user.cwd) throw new Error('Claude 会话缺少可核对的模型、目录或权限');
+  return { model: assistant.message.model, cwd: user.cwd, permissionMode: user.permissionMode };
+}
+function resumeFlags(argv, cwd) {
+  var values = ['--allowedTools', '--allowed-tools', '--disallowedTools', '--disallowed-tools', '--add-dir', '--tools', '--settings', '--setting-sources', '--effort', '--agent', '--mcp-config', '--append-system-prompt', '--system-prompt', '--plugin-dir', '--betas'];
+  var boolean = ['--strict-mcp-config']; var result = [], files = [];
+  for (var i = 1; i < argv.length; i++) {
+    if (boolean.includes(argv[i])) { result.push(argv[i]); continue; }
+    var flag = argv[i].split('=')[0]; if (!values.includes(flag)) continue;
+    var inline = argv[i].includes('='), items = inline ? [argv[i].slice(flag.length + 1)] : [];
+    if (!inline && argv[i + 1] && !argv[i + 1].startsWith('-')) items.push(argv[++i]);
+    if (['--allowedTools', '--allowed-tools', '--disallowedTools', '--disallowed-tools', '--add-dir', '--tools', '--mcp-config', '--betas'].includes(flag)) {
+      while (!inline && argv[i + 1] && !argv[i + 1].startsWith('-')) items.push(argv[++i]);
+    }
+    if (!items.length) throw new Error('原 Claude 参数缺少值：' + flag);
+    if (flag === '--settings') {
+      items = items.map(value => {
+        if (value.trim().startsWith('{')) {
+          var parsed = JSON.parse(value);
+          if (parsed.env) {
+            if (Object.keys(parsed.env).some(k => process.env[k] !== String(parsed.env[k]))) throw new Error('请在原 Claude 会话内注册，以保留临时环境设置');
+            delete parsed.env; // Credentials stay in inherited memory, never in the binding file.
+          }
+          return JSON.stringify(parsed);
+        }
+        var file = path.resolve(cwd, value); files.push(file); return file;
+      });
+    }
+    if (flag === '--mcp-config') items = items.map(value => {
+      if (value.trim().startsWith('{')) throw new Error('临时内联 MCP 配置可能含凭据；请使用配置文件后在原会话重新注册');
+      var file = path.resolve(cwd, value); files.push(file); return file;
+    });
+    result.push(flag, ...items);
+  }
+  return { args: result, files: files };
+}
+function profileFiles(home, cwd, extra) {
+  return processes.configStamps(cwd, ['.claude/settings.json', '.claude/settings.local.json'], [path.join(home, 'settings.json')].concat(extra || []));
+}
+function providerContext(env) {
+  var base = new URL(env.ANTHROPIC_BASE_URL || 'https://api.anthropic.com');
+  if (base.username || base.password || base.search || base.hash) throw new Error('Claude 提供方地址不能含内嵌凭据或查询参数');
+  return { baseURL: base.href, bedrock: env.CLAUDE_CODE_USE_BEDROCK || '', vertex: env.CLAUDE_CODE_USE_VERTEX || '',
+    foundry: env.CLAUDE_CODE_USE_FOUNDRY || '', region: env.AWS_REGION || env.AWS_DEFAULT_REGION || '',
+    vertexProject: env.ANTHROPIC_VERTEX_PROJECT_ID || '', vertexRegion: env.CLOUD_ML_REGION || '' };
+}
+var hookStatus = 'annotatable-html duty listener';
+function hookCommand() {
+  return [process.execPath, path.join(__dirname, '../bin/cli.js'), 'duty', '--claude', '--hook'].map(value =>
+    "'" + value.replace(/\\/g, '/').replace(/'/g, "'\"'\"'") + "'").join(' ');
+}
+function updateHooks(binding, install) {
+  var core = require('./core'), file = path.join(binding.settings.cwd, '.claude', 'settings.local.json');
+  return core.withDocLock(file, function () {
+    var before = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null, config = before ? JSON.parse(before) : {};
+    if (!config || Array.isArray(config) || typeof config !== 'object') throw new Error('Claude 项目设置必须为 JSON 对象');
+    if (install && (config.disableAllHooks || config.allowManagedHooksOnly)) throw new Error('原项目策略禁用了本地钩子，无法自动接回通知');
+    var events = ['SessionStart', 'Stop'], command = hookCommand(), changed = false;
+    config.hooks = config.hooks || {};
+    for (var event of events) {
+      var entries = config.hooks[event] || [], next = [];
+      for (var entry of entries) {
+        var hooks = entry.hooks.filter(h => !(h.type === 'command' && h.statusMessage === hookStatus));
+        if (hooks.length !== entry.hooks.length) changed = true;
+        if (hooks.length) next.push(Object.assign({}, entry, { hooks: hooks }));
+      }
+      if (install) {
+        var entry = { hooks: [{ type: 'command', command: command, asyncRewake: true, timeout: 2147483, statusMessage: hookStatus }] };
+        if (event === 'SessionStart') entry.matcher = 'startup|resume';
+        next.push(entry); changed = true;
+      }
+      if (next.length) config.hooks[event] = next; else delete config.hooks[event];
+    }
+    if (!Object.keys(config.hooks).length) delete config.hooks;
+    if (changed) {
+      var text = JSON.stringify(config, null, 2) + '\n';
+      if (before !== text) core.writeDocAtomic(file, text);
+    }
+    return { file: file, command: command };
+  });
+}
+function installResumeHooks(binding) {
+  binding.claude.resumeHook = updateHooks(binding, true);
+  binding.claude.files = binding.claude.files.map(x => processes.fileStamp(x.file));
+}
+function removeResumeHooks(binding) {
+  if (!binding.claude || !binding.claude.resumeHook) return;
+  var dir = path.dirname(binding.lockFile), duty = require('./duty');
+  for (var name of fs.existsSync(dir) ? fs.readdirSync(dir) : []) {
+    if (!/^duty-claude-[a-f0-9-]+\.lock$/i.test(name) || path.join(dir, name) === binding.lockFile) continue;
+    var lock = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8'));
+    if (duty.alive(lock.pid)) return; // A project uses one pair of hooks for all its registered sessions.
+  }
+  updateHooks(binding, false);
+}
+async function resumeHook(input) {
+  if (!input || !['SessionStart', 'Stop'].includes(input.hook_event_name) || !/^[a-f0-9]{8}-(?:[a-f0-9]{4}-){3}[a-f0-9]{12}$/i.test(input.session_id || '') || !input.cwd) return;
+  if (process.env.ANNOTATABLE_DUTY_HEADLESS_SESSION === input.session_id) return;
+  var lockFile = path.join(input.cwd, '.annotatable', 'duty-claude-' + input.session_id + '.lock');
+  if (!fs.existsSync(lockFile)) return;
+  var lock = JSON.parse(fs.readFileSync(lockFile, 'utf8')), duty = require('./duty');
+  if (!duty.alive(lock.pid) || !lock.bindingFile || !fs.existsSync(lock.bindingFile)) return;
+  var binding = JSON.parse(fs.readFileSync(lock.bindingFile, 'utf8'));
+  if (binding.host !== 'claude' || binding.threadId !== input.session_id || binding.stopRequested ||
+      !binding.claude.resumeHook || canonical(binding.settings.cwd) !== canonical(input.cwd) ||
+      canonical(binding.lockFile) !== canonical(lockFile) || canonical(duty.pathsFor(binding.file).binding) !== canonical(lock.bindingFile)) return;
+  var deadline = Date.now() + 10000, connected;
+  for (;;) {
+    try { connected = await duty.listen(binding.file, { claudeSession: input.session_id, events: true, nativeHook: true }); break; }
+    catch (error) { if (Date.now() >= deadline) throw error; await new Promise(resolve => setTimeout(resolve, 200)); }
+  }
+  if (!connected.stopped && !connected.alreadyListening) await duty.events(binding.file, { exitCode: 2, hook: true });
+}
+async function dutyBinding(file, options) {
+  var home = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+  var id = options.claudeSession || process.env.CLAUDE_CODE_SESSION_ID || process.env.CLAUDE_SESSION_ID;
+  if (!id) {
+    var chain = await processes.parents(process.pid);
+    var candidates = registrations(home).filter(r => chain.some(p => p.ProcessId === r.pid));
+    if (candidates.length === 1) id = candidates[0].sessionId;
+  }
+  if (!/^[a-f0-9]{8}-(?:[a-f0-9]{4}-){3}[a-f0-9]{12}$/i.test(id || '')) throw new Error('Claude 续接需要明确的原会话编号；使用 --claude-session ID');
+  var matches = await liveRegistrations(home, id);
+  if (matches.length !== 1) throw new Error('请在原 Claude 会话仍运行时注册，无法确认唯一处理进程');
+  var owner = matches[0], record = transcript(home, id), saved = savedTurn(record, id);
+  var ancestry = chain || await processes.parents(process.pid), originalIndex = ancestry.findIndex(p => p.ProcessId === owner.process.ProcessId);
+  if (options.events && originalIndex < 0) throw new Error('请从原 Claude 会话的后台命令工具接上通知');
+  var bash = ancestry.slice(1, originalIndex < 0 ? 1 : originalIndex).find(p => /^bash(?:\.exe)?$/i.test(p.Name));
+  if (canonical(saved.cwd) !== canonical(owner.registration.cwd)) throw new Error('Claude 会话目录不一致');
+  var flags = resumeFlags(await processes.argumentsFor(owner.process.ProcessId), saved.cwd);
+  return { threadId: id, binary: options.claudeBin || owner.process.ExecutablePath, settings: saved,
+    claude: { home: home, transcript: record, args: flags.args, gitBashPath: bash && bash.ExecutablePath || process.env.CLAUDE_CODE_GIT_BASH_PATH || null,
+      provider: providerContext(process.env), files: profileFiles(home, saved.cwd, flags.files), owners: [processes.identity(owner.process)] } };
+}
+class ClaudeRpc extends processes.JsonProcess {
+  constructor(binding, options) {
+    var env = processes.agentEnv({ CLAUDE_CONFIG_DIR: binding.claude.home });
+    if (options && options.headless) env.ANNOTATABLE_DUTY_HEADLESS_SESSION = binding.threadId;
+    if (binding.claude.gitBashPath) env.CLAUDE_CODE_GIT_BASH_PATH = binding.claude.gitBashPath;
+    super(binding.binary, ['-p', options && options.fresh ? '--session-id' : '--resume', binding.threadId, '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose',
+      '--permission-prompt-tool', 'stdio', ...binding.claude.args, '--model', binding.settings.model, '--permission-mode', binding.settings.permissionMode], {
+      cwd: binding.settings.cwd, env: env,
+      protocol: { request: (id, subtype, params) => ({ type: 'control_request', request_id: id, request: Object.assign({ subtype: subtype }, params) }),
+        response: m => m.type === 'control_response' ? { id: m.response.request_id, result: m.response.response, error: m.response.subtype === 'error' ? m.response.error : null } : null,
+        isRequest: m => m.type === 'control_request' }
+    });
+  }
+}
+async function runHeadless(binding, hit, options) {
+  options = options || {};
+  if (!util.isDeepStrictEqual(savedTurn(binding.claude.transcript, binding.threadId), binding.settings) ||
+      !util.isDeepStrictEqual(binding.claude.files.map(x => processes.fileStamp(x.file)), binding.claude.files)) throw new Error('Claude 模型、权限或配置已改变，请重新注册');
+  if (!(await options.released()).released) throw new Error('原 Claude 进程尚未退出');
+  var rpc = options.rpc || new ClaudeRpc(binding, { headless: true }), record = { host: 'claude', threadId: binding.threadId, pid: rpc.child.pid, startedAt: Date.now() }, timer;
+  if (options.onStart) options.onStart(record);
+  var refusal, complete;
+  var done = new Promise((resolve, reject) => { complete = { resolve: resolve, reject: reject }; }); done.catch(function () {});
+  rpc.on('serverRequest', message => {
+    record.approval = { subtype: message.request.subtype, tool: message.request.tool_name || null };
+    rpc.send({ type: 'control_response', response: { subtype: 'success', request_id: message.request_id,
+      response: { behavior: 'deny', message: '无人值守保留待办，不扩大权限' } } });
+    refusal = 'Claude 需要人工审批或原宿主工具，保留待办'; rpc.request('interrupt', {}).catch(function () {});
+  });
+  rpc.on('notification', message => {
+    if (message.session_id && message.session_id !== binding.threadId) { complete.reject(new Error('Claude 返回其他会话')); return; }
+    if (message.type === 'system' && message.subtype === 'init') {
+      record.restored = { model: message.model, cwd: message.cwd, permissionMode: message.permissionMode };
+      record.shellTools = (message.tools || []).filter(name => ['Bash', 'PowerShell'].includes(name));
+      if (message.model !== binding.settings.model || message.permissionMode !== binding.settings.permissionMode || canonical(message.cwd) !== canonical(binding.settings.cwd)) { refusal = 'Claude 恢复设置不一致'; rpc.request('interrupt', {}).catch(function () {}); }
+    }
+    if (message.type === 'result') complete.resolve(message);
+  });
+  rpc.on('exit', () => complete.reject(new Error('Claude 在回复结束前退出')));
+  try {
+    await rpc.request('initialize', {});
+    var settings = await rpc.request('get_settings', {});
+    if (!settings.applied || settings.applied.model !== binding.settings.model || settings.errors && settings.errors.length) throw new Error('Claude 配置或模型预检失败');
+    if (binding.claude.provider && !util.isDeepStrictEqual(providerContext(Object.assign({}, process.env, settings.effective && settings.effective.env)), binding.claude.provider)) throw new Error('Claude 提供方不一致，保留待办');
+    if (!(await options.released(rpc.child.pid)).released) throw new Error('原 Claude 会话已重开，暂停无头执行');
+    record.effectivePermissions = settings.effective && settings.effective.permissions;
+    var turnPrompt = require('./duty').prompt(binding, hit, { headless: true });
+    if (binding.claude.gitBashPath) turnPrompt += '原会话使用 Bash；继续用 Bash 运行上述 node 命令，不切换命令工具。';
+    rpc.send({ type: 'user', session_id: binding.threadId, parent_tool_use_id: null,
+      message: { role: 'user', content: turnPrompt } });
+    timer = setTimeout(() => { refusal = 'Claude 回复超时'; rpc.request('interrupt', {}).catch(function () {}); complete.reject(new Error(refusal)); }, options.timeoutMs || 300000);
+    var result = await done;
+    if (refusal || !record.restored || result.is_error || result.subtype !== 'success') throw new Error(refusal || 'Claude 未成功完成回复');
+    record.outcome = 'completed'; return record;
+  } catch (error) { record.outcome = 'failed'; record.error = error.message; throw Object.assign(error, { dutyRun: record }); }
+  finally { clearTimeout(timer); await rpc.close(); record.finishedAt = Date.now(); }
+}
+function createDutyAdapter(getBinding, updateBinding) {
+  async function live() { var b = getBinding(); return liveRegistrations(b.claude.home, b.threadId); }
+  async function released(excludePid) {
+    var matches = (await live()).filter(x => x.process.ProcessId !== excludePid);
+    if (matches.length) return { released: false, reason: 'claude-session-process-alive' };
+    return processes.ownersExited(getBinding().claude.owners);
+  }
+  return {
+    online: async () => {
+      var b = getBinding(), matches = await live(); if (matches.length !== 1) return null;
+      if (!processes.sameProcess(b.claude.owners[0], matches[0].process)) updateBinding(Object.assign({}, b, { claude: Object.assign({}, b.claude, { owners: [processes.identity(matches[0].process)] }) }));
+      var connected = b.bridge && processes.sameProcess(b.bridge, await processes.processInfo(b.bridge.ProcessId));
+      return { available: true, active: !connected, notify: async () => {} }; // The original host consumes its own background task output.
+    },
+    released: released, run: (hit, onStart) => runHeadless(getBinding(), hit, { onStart: onStart, released: released }),
+    close: () => { var b = getBinding(); if (b.stopRequested) removeResumeHooks(b); }
+  };
+}
+module.exports = { dutyBinding: dutyBinding, createDutyAdapter: createDutyAdapter, ClaudeRpc: ClaudeRpc,
+  runHeadless: runHeadless, savedTurn: savedTurn, resumeFlags: resumeFlags, liveRegistrations: liveRegistrations,
+  installResumeHooks: installResumeHooks, removeResumeHooks: removeResumeHooks, resumeHook: resumeHook };

package/lib/codex-desktop.js

@@ -0,0 +1,130 @@
+'use strict';
+
+// The Windows desktop app owns a separate stdio app-server. Use its inherited
+// app-tools pipe instead of resuming the same thread in an unrelated daemon.
+var net = require('net');
+var os = require('os');
+var crypto = require('crypto');
+var MAX_FRAME = 8 * 1024 * 1024;
+
+class DesktopRpc {
+  constructor(pipePath) {
+    this.pipePath = pipePath;
+    this.pending = new Map();
+    this.nextId = 0;
+    this.buffer = Buffer.alloc(0);
+  }
+  async open() {
+    await new Promise((resolve, reject) => {
+      var timer = setTimeout(() => { this.close(); reject(new Error('Codex 桌面连接超时')); }, 10000);
+      this.socket = net.createConnection(this.pipePath);
+      this.socket.once('connect', () => { clearTimeout(timer); resolve(); });
+      this.socket.on('data', chunk => this.receive(chunk));
+      this.socket.on('error', error => { clearTimeout(timer); this.abort(error); reject(error); });
+      this.socket.on('close', () => {
+        clearTimeout(timer);
+        var error = new Error('Codex 桌面连接已关闭；请在当前桌面会话重挂监听');
+        this.abort(error); reject(error);
+      });
+    });
+  }
+  abort(error) {
+    if (!this.failure) this.failure = error;
+    for (const pending of this.pending.values()) { clearTimeout(pending.timer); pending.reject(error); }
+    this.pending.clear();
+    if (this.socket) this.socket.destroy();
+  }
+  receive(chunk) {
+    this.buffer = Buffer.concat([this.buffer, chunk]);
+    while (this.buffer.length >= 4) {
+      var size = os.endianness() === 'LE' ? this.buffer.readUInt32LE(0) : this.buffer.readUInt32BE(0);
+      if (size > MAX_FRAME) { this.abort(new Error('Codex 桌面响应超过大小限制')); return; }
+      if (this.buffer.length < size + 4) return;
+      var message;
+      try { message = JSON.parse(this.buffer.subarray(4, size + 4).toString('utf8')); }
+      catch (_) { this.abort(new Error('Codex 桌面返回无效 JSON')); return; }
+      this.buffer = this.buffer.subarray(size + 4);
+      var pending = this.pending.get(message.id);
+      if (!pending) continue;
+      this.pending.delete(message.id); clearTimeout(pending.timer);
+      if (message.error) pending.reject(new Error('Codex 桌面接口失败：' + message.error.message));
+      else pending.resolve(message.result);
+    }
+  }
+  request(method, params) {
+    if (this.failure) return Promise.reject(this.failure);
+    return new Promise((resolve, reject) => {
+      var id = ++this.nextId;
+      var body = Buffer.from(JSON.stringify({ id: id, jsonrpc: '2.0', method: method, params: params }));
+      if (body.length > MAX_FRAME) { reject(new Error('Codex 桌面请求超过大小限制')); return; }
+      var header = Buffer.alloc(4);
+      if (os.endianness() === 'LE') header.writeUInt32LE(body.length); else header.writeUInt32BE(body.length);
+      var timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error('Codex 桌面 ' + method + ' 超时；结果不确定，请先核对会话，不要重复发送'));
+      }, 15000);
+      this.pending.set(id, { resolve: resolve, reject: reject, timer: timer });
+      try { this.socket.write(Buffer.concat([header, body])); }
+      catch (error) { this.pending.delete(id); clearTimeout(timer); reject(error); }
+    });
+  }
+  async call(tool, args, context) {
+    var result = await this.request('tools/call', {
+      callerSource: 'codex', namespace: 'codex_app', hostId: 'local',
+      callId: 'annotatable-' + crypto.randomUUID(), threadId: context.threadId,
+      turnId: context.turnId, tool: tool, arguments: args
+    });
+    if (!result || result.success !== true) throw new Error('Codex 桌面工具 ' + tool + ' 未成功；批注仍保留在文档中');
+    var item = (result.contentItems || []).find(item => item.type === 'inputText');
+    if (!item) throw new Error('Codex 桌面工具 ' + tool + ' 缺少结果');
+    try { return JSON.parse(item.text); }
+    catch (_) { throw new Error('Codex 桌面工具 ' + tool + ' 返回无效结果'); }
+  }
+  close() { this.abort(new Error('Codex 桌面连接已结束')); }
+}
+
+class DesktopNotifier {
+  constructor(pipePath, threadId, turnId) {
+    if (!pipePath || !threadId || !turnId) throw new Error('Codex 桌面通知缺少连接、会话或来源轮次');
+    this.rpc = new DesktopRpc(pipePath);
+    this.context = { threadId: threadId, turnId: turnId };
+    this.kind = 'desktop';
+  }
+  async open() {
+    await this.rpc.open();
+    var result = await this.rpc.request('tools/list', { threadStartKind: 'all' });
+    for (const name of ['read_thread', 'send_message_to_thread']) {
+      if (!(result.tools || []).some(tool => tool.namespace === 'codex_app' && tool.name === name)) {
+        throw new Error('Codex 桌面不提供 ' + name + '；无法恢复自动通知');
+      }
+    }
+    return this.read();
+  }
+  async read() {
+    var result = await this.rpc.call('read_thread', {
+      threadId: this.context.threadId, hostId: 'local', turnLimit: 1,
+      includeOutputs: false, maxOutputCharsPerItem: 0
+    }, this.context);
+    if (!result.thread || result.thread.id !== this.context.threadId || result.thread.hostId !== 'local') {
+      throw new Error('Codex 桌面返回了其他会话；停止监听');
+    }
+    return result;
+  }
+  async notify(hit, options) {
+    var prompt = '【批注工具自动通知】用户指定的页面收到待回应批注。请按 annotatable-html 工作流读取完整批注并回复，完成后重新挂同一页面的监听。\n' +
+      '这条消息由本机监听程序发出，不是用户新输入。\nPOLL_HIT ' + JSON.stringify(hit);
+    if (options && options.managed) {
+      prompt = '【指定页面批注自动续接】请读取并回复用户已指定页面的待回应批注。\n' +
+        '后台续接程序负责后续监听，不要重挂 poll 或启动另一个控制器。长回复通过 UTF-8 JSON 文件交给批注 CLI，完成后核对落盘。\n' +
+        'POLL_HIT ' + JSON.stringify(hit);
+    }
+    var result = await this.rpc.call('send_message_to_thread', {
+      threadId: this.context.threadId, hostId: 'local', prompt: prompt
+    }, this.context);
+    if (result.threadId !== this.context.threadId) throw new Error('Codex 桌面未确认目标会话收到通知');
+    return { threadId: result.threadId, transport: this.kind };
+  }
+  close() { this.rpc.close(); }
+}
+
+module.exports = { DesktopRpc: DesktopRpc, DesktopNotifier: DesktopNotifier };

package/lib/codex-headless.js

@@ -0,0 +1,129 @@
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+var JsonProcess = require('./duty-process').JsonProcess;
+var util = require('util');
+
+function canonicalPath(value) { return path.resolve(value).replace(/\\/g, '/').toLowerCase(); }
+function readSettings(thread) {
+  if (!thread || !thread.id || !thread.path || !thread.modelProvider || !thread.model) throw new Error('会话缺少可核对的续接设置');
+  var fd = fs.openSync(thread.path, 'r'), size, buffer;
+  try {
+    size = fs.fstatSync(fd).size; buffer = Buffer.alloc(Math.min(size, 4 * 1024 * 1024));
+    fs.readSync(fd, buffer, 0, buffer.length, size - buffer.length);
+  } finally { fs.closeSync(fd); }
+  var tail = buffer.toString('utf8').split(/\r?\n/);
+  var context;
+  for (var line of tail) {
+    try { var row = JSON.parse(line); if (row.type === 'turn_context') context = row.payload; } catch (_) {}
+  }
+  if (!context || !context.permission_profile || !context.sandbox_policy || !context.approval_policy) {
+    throw new Error('无法核对会话原有权限；保留批注，不启动无头模型');
+  }
+  if (canonicalPath(context.cwd) !== canonicalPath(thread.cwd) || context.model !== thread.model) {
+    throw new Error('会话元数据与最近轮次设置不一致');
+  }
+  return { model: thread.model, modelProvider: thread.modelProvider, cwd: thread.cwd,
+    reasoningEffort: context.effort || thread.reasoningEffort || null,
+    approvalPolicy: context.approval_policy, approvalsReviewer: context.approvals_reviewer || 'user',
+    sandbox: context.sandbox_policy, permissionProfile: context.permission_profile, rolloutPath: thread.path };
+}
+function normalizeSandbox(policy, cwd) {
+  var type = { 'workspace-write': 'workspaceWrite', 'read-only': 'readOnly', 'danger-full-access': 'dangerFullAccess', 'external-sandbox': 'externalSandbox' }[policy.type] || policy.type;
+  var result = { type: type, network: policy.networkAccess === undefined ? policy.network_access || false : policy.networkAccess };
+  if (type === 'workspaceWrite') {
+    result.roots = Array.from(new Set([cwd].concat(policy.writableRoots || policy.writable_roots || []).map(canonicalPath))).sort();
+    result.excludeTmp = !!(policy.excludeTmpdirEnvVar || policy.exclude_tmpdir_env_var);
+    result.excludeSlash = !!(policy.excludeSlashTmp || policy.exclude_slash_tmp);
+  }
+  return result;
+}
+function assertRestored(saved, restored) {
+  var valid = restored.thread && restored.thread.id && restored.model === saved.model && restored.modelProvider === saved.modelProvider &&
+    canonicalPath(restored.cwd) === canonicalPath(saved.cwd) &&
+    util.isDeepStrictEqual(saved.approvalPolicy, restored.approvalPolicy) && saved.approvalsReviewer === restored.approvalsReviewer &&
+    util.isDeepStrictEqual(normalizeSandbox(saved.sandbox, saved.cwd), normalizeSandbox(restored.sandbox, restored.cwd));
+  if (!valid) throw new Error('无头恢复后的模型、目录或权限不一致；未启动回复轮次');
+}
+
+class StdioRpc extends JsonProcess {
+  constructor(binary, home, cwd) {
+    var env = require('./duty-process').agentEnv({ CODEX_HOME: home });
+    super(binary, ['app-server', '--stdio'], { cwd: cwd, env: env });
+  }
+  async open() {
+    await this.request('initialize', { clientInfo: { name: 'annotatable_duty', version: require('../package.json').version }, capabilities: { experimentalApi: true } });
+    this.send({ method: 'initialized', params: {} });
+  }
+}
+
+async function runHeadless(binding, hit, options) {
+  options = options || {};
+  if (binding.settings.rolloutPath) {
+    var latest = readSettings({ id: binding.threadId, path: binding.settings.rolloutPath, model: binding.settings.model,
+      modelProvider: binding.settings.modelProvider, cwd: binding.settings.cwd });
+    if (!util.isDeepStrictEqual(latest, binding.settings)) throw new Error('注册后会话设置已改变；请重新注册，不自动覆盖原设置');
+  }
+  var released = await (options.checkReleased || require('./duty-process').released)(binding.desktop.owners);
+  if (!released.released) throw new Error('桌面运行时尚未确认退出；不启动第二份会话');
+  var rpc = options.rpc || new StdioRpc(binding.binary, binding.codexHome, binding.settings.cwd);
+  var record = { startedAt: Date.now(), threadId: binding.threadId, pid: rpc.child && rpc.child.pid, outcome: 'starting', events: [] };
+  if (options.onStart) options.onStart(record);
+  var turnId;
+  var requestError;
+  var terminal;
+  var timeout;
+  var finished = new Promise((resolve, reject) => { terminal = { resolve: resolve, reject: reject }; });
+  // Avoid an unhandled rejection while initialization is still in progress.
+  finished.catch(function () {});
+  function interrupt(reason) {
+    requestError = reason;
+    if (turnId) rpc.request('turn/interrupt', { threadId: binding.threadId, turnId: turnId }).catch(function () {});
+  }
+  rpc.on('serverRequest', message => {
+    if (message.method === 'item/tool/call') {
+      rpc.send({ id: message.id, result: { success: false, contentItems: [{ type: 'inputText', text: '当前为无头宿主，桌面动态工具不可用。使用内置命令执行工具运行本地批注 CLI；不要申请扩大权限。' }] } });
+      record.events.push({ kind: 'desktop-tool-unavailable', tool: message.params.tool });
+    } else if (/requestApproval$/.test(message.method)) {
+      rpc.send({ id: message.id, result: { decision: 'decline' } });
+      interrupt('需要人工审批；批注保留待处理');
+    } else {
+      rpc.send({ id: message.id, error: { code: -32601, message: 'Unattended request requires a user or an unavailable host' } });
+      interrupt('无头宿主无法处理 ' + message.method);
+    }
+  });
+  rpc.on('notification', message => {
+    if (message.params && message.params.threadId && message.params.threadId !== binding.threadId) return;
+    if (message.method === 'turn/completed') {
+      record.turnStatus = message.params.turn.status;
+      terminal.resolve(message.params.turn);
+    }
+    if (message.method === 'item/completed' && message.params.item && message.params.item.type === 'agentMessage') {
+      record.finalMessage = message.params.item.text;
+    }
+  });
+  rpc.on('exit', () => terminal.reject(new Error('无头进程在轮次完成前退出')));
+  try {
+    await rpc.open();
+    var restored = await rpc.request('thread/resume', { threadId: binding.threadId, excludeTurns: true, model: binding.settings.model });
+    if (!restored.thread || restored.thread.id !== binding.threadId) throw new Error('恢复到了其他会话');
+    assertRestored(binding.settings, restored);
+    record.restored = { model: restored.model, modelProvider: restored.modelProvider, cwd: restored.cwd,
+      approvalPolicy: restored.approvalPolicy, approvalsReviewer: restored.approvalsReviewer, sandbox: restored.sandbox };
+    if (!(await (options.checkReleased || require('./duty-process').released)(binding.desktop.owners)).released) throw new Error('桌面已重开；不启动无头回复轮次');
+    var prompt = require('./duty').prompt(binding, hit, { headless: true });
+    var started = await rpc.request('turn/start', { threadId: binding.threadId, input: [{ type: 'text', text: prompt }], effort: binding.settings.reasoningEffort || undefined });
+    turnId = started.turn.id; record.turnId = turnId;
+    if (requestError) interrupt(requestError);
+    timeout = setTimeout(() => { interrupt('无头处理超时，保留待办'); setTimeout(() => terminal.reject(new Error(requestError)), 10000).unref(); }, options.timeoutMs || 300000);
+    var turn = await finished;
+    if (requestError || turn.status !== 'completed') throw new Error(requestError || '无头轮次未完成：' + turn.status);
+    record.outcome = 'completed';
+    return record;
+  } catch (error) { record.outcome = 'failed'; record.error = error.message; throw Object.assign(error, { dutyRun: record }); }
+  finally { clearTimeout(timeout); await rpc.close(); record.finishedAt = Date.now(); if (options.onFinish) options.onFinish(record); }
+}
+
+module.exports = { readSettings: readSettings, normalizeSandbox: normalizeSandbox, assertRestored: assertRestored,
+  StdioRpc: StdioRpc, runHeadless: runHeadless, canonicalPath: canonicalPath };