@harness-mix/cli 0.1.3

package/src/main/native/updater.js

@@ -0,0 +1,394 @@
+// Harness Mix auto-update.
+// - git channel: fast-forward the local checkout from its upstream, reinstall
+//   dependencies and rebuild native artifacts when their inputs changed.
+// - npm channel: compare the installed version with the registry and apply via
+//   `npm install -g`, with lock, retries, pending and crash-loop rollback.
+// - State/lock/semver live in ./update-state. Failures never block launch.
+const { execFileSync, spawn, spawnSync } = require('node:child_process');
+const path = require('node:path');
+const fs = require('node:fs');
+const {
+  acquireLock, compareVersions, detectChannel, readState, writeState,
+} = require('./update-state');
+
+function makeGit(root, exec = spawnSync) {
+  return (args, timeout = 20000) => {
+    const result = exec('git', args, {
+      cwd: root,
+      encoding: 'utf8',
+      timeout,
+      windowsHide: true,
+      env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+    });
+    if (result.error) throw result.error;
+    if (result.status !== 0) throw new Error(String(result.stderr || `git ${args[0]} failed`).trim());
+    return String(result.stdout).trim();
+  };
+}
+
+// remoteState classifies the checkout relative to its upstream:
+// current | ahead | diverged | dirty | available (fast-forward possible).
+function remoteState(root, git = makeGit(root)) {
+  const head = git(['rev-parse', 'HEAD']);
+  let upstream = 'origin/main';
+  try {
+    upstream = git(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}']);
+  } catch { /* no upstream configured: fall back to origin/main */ }
+  git(['fetch', '--quiet', ...upstream.split('/')], 30000);
+  const remote = git(['rev-parse', upstream]);
+  if (remote === head) return { state: 'current', head, remote, upstream };
+  const base = git(['merge-base', 'HEAD', upstream]);
+  if (base === remote) return { state: 'ahead', head, remote, upstream };
+  if (base !== head) return { state: 'diverged', head, remote, upstream };
+  const dirty = git(['status', '--porcelain', '--untracked-files=no']).length > 0;
+  if (dirty) return { state: 'dirty', head, remote, upstream };
+  return { state: 'available', head, remote, upstream };
+}
+
+function defaultHooks(root) {
+  return {
+    install() {
+      const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+      execFileSync(npm, ['install'], { cwd: root, stdio: 'inherit', windowsHide: true });
+    },
+    build() {
+      execFileSync(process.execPath, [path.join(root, 'scripts/build-native.cjs')], { cwd: root, stdio: 'inherit', windowsHide: true });
+    },
+  };
+}
+
+function applyUpdate(root, state, git = makeGit(root), hooks = defaultHooks(root)) {
+  git(['merge', '--ff-only', state.upstream]);
+  const changed = git(['diff', '--name-only', state.head, state.remote]).split('\n').filter(Boolean);
+  const install = changed.some(file => file === 'package.json' || file === 'package-lock.json');
+  const rebuild = install || changed.some(file => file.startsWith('src/') || file.startsWith('scripts/'));
+  try {
+    if (install) hooks.install();
+    if (rebuild) hooks.build();
+  } catch (error) {
+    // A failed install/build would leave a half-updated tree behind; restore it.
+    try { git(['reset', '--hard', state.head]); } catch { /* keep the original failure */ }
+    throw error;
+  }
+  return {
+    updated: true,
+    from: state.head.slice(0, 8),
+    to: state.remote.slice(0, 8),
+    changed: changed.length,
+    installed: install,
+    rebuilt: rebuild,
+  };
+}
+
+async function autoUpdate({ root, log = console.log, exec, hooks } = {}) {
+  const git = makeGit(root, exec);
+  let state;
+  try {
+    state = remoteState(root, git);
+  } catch (error) {
+    log(`[Harness Mix] 自动更新检查失败（不影响启动）：${error.message}`);
+    return { updated: false, failed: true };
+  }
+  switch (state.state) {
+    case 'current':
+      log('[Harness Mix] 已是最新版本');
+      return { updated: false, state: state.state };
+    case 'ahead':
+      log('[Harness Mix] 本地提交领先远端，跳过自动更新');
+      return { updated: false, state: state.state };
+    case 'diverged':
+      log('[Harness Mix] 本地与远端已分叉，请手动处理后重启，跳过自动更新');
+      return { updated: false, state: state.state };
+    case 'dirty':
+      log('[Harness Mix] 工作区存在未提交改动，跳过自动更新');
+      return { updated: false, state: state.state };
+    default: {
+      log(`[Harness Mix] 发现新版本 ${state.head.slice(0, 8)} → ${state.remote.slice(0, 8)}，正在更新…`);
+      let outcome;
+      try {
+        outcome = applyUpdate(root, state, git, hooks || defaultHooks(root));
+      } catch (error) {
+        log(`[Harness Mix] 更新失败并已回退（不影响启动）：${error.message}`);
+        return { updated: false, failed: true };
+      }
+      log(`[Harness Mix] 更新完成：${outcome.changed} 个文件` +
+        `${outcome.installed ? '，依赖已重装' : ''}${outcome.rebuilt ? '，原生组件已重建' : ''}`);
+      return outcome;
+    }
+  }
+}
+
+/* ---------------- npm channel ---------------- */
+
+const REGISTRY_CACHE_FILE = 'update-registry-cache.json';
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+function npmCommand() {
+  return process.platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+
+function resolveRegistry({ env = process.env, run = spawnSync } = {}) {
+  if (env.HARNESS_MIX_UPDATE_REGISTRY) return env.HARNESS_MIX_UPDATE_REGISTRY;
+  if (env.npm_config_registry) return env.npm_config_registry;
+  const result = run(npmCommand(), ['config', 'get', 'registry'], { encoding: 'utf8', windowsHide: true, timeout: 10000 });
+  const value = result && result.status === 0 ? String(result.stdout || '').trim() : '';
+  return value && value !== 'undefined' && value !== 'null' ? value : 'https://registry.npmjs.org/';
+}
+
+async function fetchLatestVersion({ registry, dataDir, fetchImpl = fetch, timeoutMs = 5000 } = {}) {
+  const url = `${String(registry).replace(/\/+$/, '')}/harness-mix`;
+  const cacheFile = dataDir ? path.join(dataDir, REGISTRY_CACHE_FILE) : null;
+  const cache = cacheFile ? readJson(cacheFile) : null;
+  const headers = { accept: 'application/vnd.npm.install-v1+json' };
+  if (cache && cache.etag) headers['if-none-match'] = cache.etag;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetchImpl(url, { headers, signal: controller.signal });
+    if (response.status === 304 && cache && cache.version) return cache.version;
+    if (!response.ok) throw new Error(`registry HTTP ${response.status}`);
+    const body = await response.json();
+    const version = body && body['dist-tags'] && body['dist-tags'].latest;
+    if (!version) throw new Error('registry response has no dist-tags.latest');
+    if (cacheFile) {
+      try {
+        fs.mkdirSync(dataDir, { recursive: true });
+        fs.writeFileSync(cacheFile, JSON.stringify({ etag: response.headers && response.headers.get ? response.headers.get('etag') : null, version, at: Date.now() }));
+      } catch { /* cache is best-effort */ }
+    }
+    return version;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function npmGlobalRoot({ run = spawnSync } = {}) {
+  const result = run(npmCommand(), ['root', '-g'], { encoding: 'utf8', windowsHide: true, timeout: 10000 });
+  return result && result.status === 0 ? String(result.stdout || '').trim() : null;
+}
+
+function isGlobalInstall(root, deps = {}) {
+  const globalRoot = npmGlobalRoot(deps);
+  if (!globalRoot) return false;
+  const normalize = value => path.resolve(value).toLowerCase().replace(/[\\/]+$/, '');
+  return normalize(root).startsWith(normalize(globalRoot));
+}
+
+async function npmInstallGlobal(version, { run = spawnSync, log = () => {}, delay = ms => new Promise(resolve => setTimeout(resolve, ms)) } = {}) {
+  const args = ['install', '-g', `harness-mix@${version}`, '--no-audit', '--no-fund'];
+  let last = '';
+  for (let attempt = 1; attempt <= 3; attempt += 1) {
+    const result = run(npmCommand(), args, { encoding: 'utf8', windowsHide: true, timeout: 180000, env: { ...process.env, npm_config_update_notifier: 'false' } });
+    if (result && result.status === 0) return { ok: true, attempts: attempt };
+    last = result ? String(result.error || result.stderr || `exit ${result.status}`).trim() : 'npm run failed';
+    log(`[Harness Mix] npm 安装失败（第 ${attempt}/3 次）：${last.split('\n').pop()}`);
+    if (attempt < 3) await delay(2000);
+  }
+  return { ok: false, attempts: 3, error: last };
+}
+
+// Runs `scripts/launch-codex.cjs` from the (possibly just updated) checkout and
+// forwards its exit code. HARNESS_MIX_UPDATED guards against update loops.
+function reexecLauncher(root, args = []) {
+  return new Promise(resolve => {
+    const child = spawn(process.execPath, [path.join(root, 'scripts', 'launch-codex.cjs'), ...args], {
+      env: { ...process.env, HARNESS_MIX_UPDATED: '1' },
+      stdio: 'inherit',
+      windowsHide: true,
+    });
+    child.on('error', () => resolve(1));
+    child.on('exit', code => resolve(code === null ? 0 : code));
+  });
+}
+
+/* ---------------- orchestration ---------------- */
+
+// One launch-time update pass. Returns:
+//   { updated, restartRequired, repaired, rolledBack, pending, failed, ... }
+// restartRequired tells the caller to re-exec the launcher so new code loads.
+async function runUpdateFlow({ root, dataDir, log = console.log, stopDesktop = async () => {}, mode = 'apply', deps = {} } = {}) {
+  const {
+    gitExec,
+    run = spawnSync,
+    fetchImpl = fetch,
+    delay = ms => new Promise(resolve => setTimeout(resolve, ms)),
+    env = process.env,
+  } = deps;
+  const halt = async () => { await stopDesktop(); await delay(3000); };
+
+  const currentVersion = (readJson(path.join(root, 'package.json')) || {}).version || '0.0.0';
+  const channel = detectChannel(root);
+  let state = readState(dataDir);
+
+  if (channel === 'portable') {
+    log('[Harness Mix] 当前安装形态不支持自动更新（portable 通道未实现）');
+    return { updated: false, channel };
+  }
+
+  // A version the user installed by hand is not ours to track.
+  if (channel === 'npm' && state.appliedVersion && state.appliedVersion !== currentVersion && state.prevVersion !== currentVersion) {
+    state = writeState(dataDir, { ...state, phase: 'idle', appliedVersion: null, prevVersion: null, attempts: 0, pendingVersion: null });
+  }
+
+  let lockBusy = false;
+  async function mutate(fn) {
+    let release;
+    try {
+      release = acquireLock(dataDir, 'update');
+    } catch (error) {
+      lockBusy = true;
+      log(`[Harness Mix] 跳过更新：${error.message}`);
+      return { skipped: true };
+    }
+    try { return { value: await fn() }; } finally { release(); }
+  }
+
+  // 1) Repair an apply that was interrupted by a crash or a hard kill.
+  if (state.phase === 'applying') {
+    log('[Harness Mix] 检测到上次更新中断，正在修复…');
+    const repaired = await mutate(async () => {
+      if (state.channel === 'npm') {
+        if (state.pendingVersion && state.pendingVersion === currentVersion) {
+          // The install actually completed before the crash: keep it, fix bookkeeping.
+          writeState(dataDir, { ...readState(dataDir), phase: 'idle', pendingVersion: null, appliedVersion: state.pendingVersion, prevVersion: state.appliedVersion, appliedAt: Date.now() });
+          return true;
+        }
+        await halt();
+        const target = state.appliedVersion || state.prevVersion;
+        if (target) await npmInstallGlobal(target, { run, log, delay });
+      } else if (state.channel === 'git' && state.preUpdateHead) {
+        await halt();
+        makeGit(root, gitExec)(['reset', '--hard', state.preUpdateHead]);
+      }
+      writeState(dataDir, { ...readState(dataDir), phase: 'idle', pendingVersion: null });
+      return true;
+    });
+    if (repaired.value) return { updated: false, repaired: true, restartRequired: true };
+    if (repaired.skipped) return { updated: false, failed: true, reason: 'lock' };
+    return { updated: false, failed: true };
+  }
+
+  // 2) Boot bookkeeping and crash-loop rollback.
+  if (state.appliedVersion && state.lastBootOkAt < state.appliedAt) {
+    state = writeState(dataDir, { ...state, attempts: state.attempts + 1 });
+    if (state.attempts >= 2 && state.prevVersion) {
+      log(`[Harness Mix] ${state.appliedVersion} 连续两次启动未成功，自动回滚到 ${state.prevVersion}…`);
+      const rolledBack = await mutate(async () => {
+        await halt();
+        if (state.channel === 'npm') {
+          const result = await npmInstallGlobal(state.prevVersion, { run, log, delay });
+          if (!result.ok) return false;
+        } else if (state.channel === 'git' && state.preUpdateHead) {
+          makeGit(root, gitExec)(['reset', '--hard', state.preUpdateHead]);
+          defaultHooks(root).build();
+        }
+        writeState(dataDir, { ...readState(dataDir), phase: 'idle', appliedVersion: null, prevVersion: null, attempts: 0, pendingVersion: null, rolledBackAt: Date.now() });
+        return true;
+      });
+      if (rolledBack.value) {
+        log(`[Harness Mix] 已回滚到 ${state.prevVersion}；如问题持续请运行 npm run diagnostics 反馈。`);
+        return { updated: false, rolledBack: true, restartRequired: true };
+      }
+      return { updated: false, failed: true, reason: 'lock' };
+    }
+  }
+
+  // 3a) git channel.
+  if (channel === 'git') {
+    let remote;
+    try {
+      remote = remoteState(root, makeGit(root, gitExec));
+    } catch (error) {
+      log(`[Harness Mix] 自动更新检查失败（不影响启动）：${error.message}`);
+      return { updated: false, failed: true };
+    }
+    if (remote.state !== 'available') {
+      const messages = {
+        current: '[Harness Mix] 已是最新版本',
+        ahead: '[Harness Mix] 本地提交领先远端，跳过自动更新',
+        diverged: '[Harness Mix] 本地与远端已分叉，请手动处理后重启，跳过自动更新',
+        dirty: '[Harness Mix] 工作区存在未提交改动，跳过自动更新',
+      };
+      if (messages[remote.state]) log(messages[remote.state]);
+      return { updated: false, state: remote.state };
+    }
+    if (mode === 'check') return { updated: false, available: true, to: remote.remote.slice(0, 8) };
+    log(`[Harness Mix] 发现新版本 ${remote.head.slice(0, 8)} → ${remote.remote.slice(0, 8)}，正在更新…`);
+    const applied = await mutate(async () => {
+      await halt();
+      writeState(dataDir, { ...readState(dataDir), channel: 'git', phase: 'applying', preUpdateHead: remote.head });
+      let outcome = null;
+      let failure = null;
+      try {
+        outcome = applyUpdate(root, remote, makeGit(root, gitExec), defaultHooks(root));
+      } catch (error) {
+        failure = error;
+      } finally {
+        writeState(dataDir, { ...readState(dataDir), phase: 'idle' });
+      }
+      if (failure) {
+        log(`[Harness Mix] 更新失败并已回退（不影响启动）：${failure.message}`);
+        return null;
+      }
+      writeState(dataDir, { ...readState(dataDir), channel: 'git', appliedVersion: remote.remote.slice(0, 8), prevVersion: remote.head.slice(0, 8), appliedAt: Date.now(), pendingVersion: null });
+      log(`[Harness Mix] 更新完成：${outcome.changed} 个文件` +
+        `${outcome.installed ? '，依赖已重装' : ''}${outcome.rebuilt ? '，原生组件已重建' : ''}`);
+      return outcome;
+    });
+    if (applied.skipped) return { updated: false, failed: true, reason: 'lock' };
+    if (applied.value) return { ...applied.value, restartRequired: true };
+    return { updated: false, failed: true };
+  }
+
+  // 3b) npm channel.
+  if (!isGlobalInstall(root, { run })) {
+    log('[Harness Mix] 当前不是 npm 全局安装，跳过自动更新；可手动运行 npm install -g harness-mix@latest');
+    return { updated: false, reason: 'not-global' };
+  }
+  let latest = null;
+  try {
+    latest = await fetchLatestVersion({ registry: resolveRegistry({ env, run }), dataDir, fetchImpl });
+  } catch (error) {
+    log(`[Harness Mix] 自动更新检查失败（不影响启动）：${error.message}`);
+    return { updated: false, failed: true };
+  }
+  if (!latest) return { updated: false, state: 'current' };
+  if (!env.HARNESS_MIX_UPDATE_PRERELEASE && String(latest).includes('-') && !currentVersion.includes('-')) {
+    log('[Harness Mix] 远端仅有预发布版本，已跳过（设置 HARNESS_MIX_UPDATE_PRERELEASE=1 可启用）');
+    return { updated: false, state: 'current' };
+  }
+  const target = state.pendingVersion || latest;
+  if (compareVersions(target, currentVersion) <= 0 && !state.pendingVersion) {
+    log('[Harness Mix] 已是最新版本');
+    return { updated: false, state: 'current' };
+  }
+  if (mode === 'check') return { updated: false, available: true, to: target };
+  log(`[Harness Mix] 发现新版本 ${currentVersion} → ${target}，正在更新…`);
+  const applied = await mutate(async () => {
+    await halt();
+    writeState(dataDir, { ...readState(dataDir), channel: 'npm', phase: 'applying', pendingVersion: target });
+    const result = await npmInstallGlobal(target, { run, log, delay });
+    if (!result.ok) {
+      writeState(dataDir, { ...readState(dataDir), phase: 'idle', pendingVersion: target });
+      log(`[Harness Mix] 更新失败，已安排下次启动重试（${target}）`);
+      return false;
+    }
+    writeState(dataDir, { ...readState(dataDir), phase: 'idle', pendingVersion: null, appliedVersion: target, prevVersion: currentVersion, appliedAt: Date.now(), lastCheckAt: Date.now() });
+    return true;
+  });
+  if (applied.skipped) return { updated: false, failed: true, reason: 'lock' };
+  if (applied.value) {
+    log(`[Harness Mix] 更新完成 ${currentVersion} → ${target}，正在重新启动…`);
+    return { updated: true, from: currentVersion, to: target, restartRequired: true };
+  }
+  return { updated: false, failed: true, pending: target };
+}
+
+module.exports = {
+  autoUpdate, remoteState, applyUpdate, makeGit, defaultHooks,
+  runUpdateFlow, reexecLauncher, fetchLatestVersion, npmInstallGlobal,
+  resolveRegistry, isGlobalInstall, npmGlobalRoot, readJson,
+};

package/src/main/native/usage.js

@@ -0,0 +1,105 @@
+const integer = n => Number.isSafeInteger(n) && n >= 0;
+const number = n => typeof n === 'number' && Number.isFinite(n) && n >= 0;
+const percent = n => typeof n === 'number' && Number.isFinite(n) && n >= 0 && n <= 100;
+
+function projectUsage(source = {}) {
+  if (!source || typeof source !== 'object') return null;
+  const result = {};
+  const fields = {
+    inputTokens: ['inputTokens', 'input'],
+    outputTokens: ['outputTokens', 'output'],
+    cachedInputTokens: ['cachedInputTokens', 'cacheRead'],
+    cacheWriteInputTokens: ['cacheWriteInputTokens', 'cacheWrite'],
+    reasoningOutputTokens: ['reasoningOutputTokens', 'thinkingTokens'],
+    totalTokens: ['totalTokens'],
+    outputTokensPerSecond: ['outputTokensPerSecond'],
+    totalCostUsd: ['totalCostUsd', 'cost'],
+    totalCredits: ['totalCredits'],
+    contextUsagePercent: ['contextUsagePercent', 'contextPercent'],
+    cacheHitRatePercent: ['cacheHitRatePercent', 'cacheHitPercent'],
+    planFiveHourUsedPercent: ['planFiveHourUsedPercent'],
+    planFiveHourResetsAtUnix: ['planFiveHourResetsAtUnix'],
+    planSevenDayUsedPercent: ['planSevenDayUsedPercent'],
+    planSevenDayResetsAtUnix: ['planSevenDayResetsAtUnix'],
+  };
+  for (const [target, keys] of Object.entries(fields)) {
+    const value = keys.map(key => source[key]).find(number);
+    if (value === undefined) continue;
+    if (target.endsWith('Tokens') && !integer(value)) continue;
+    if (target.endsWith('Unix') && !integer(value)) continue;
+    if ((target === 'cacheHitRatePercent' || target.endsWith('UsedPercent')) && value > 100) continue;
+    result[target] = value;
+  }
+  const used = source.contextUsedTokens ?? source.tokens;
+  const window = source.contextWindowTokens ?? source.contextWindow;
+  if (integer(used) && integer(window) && window > 0) {
+    result.contextUsedTokens = used;
+    result.contextWindowTokens = window;
+    if (result.contextUsagePercent === undefined) {
+      result.contextUsagePercent = Math.round((100 * used / window) * 100) / 100;
+    }
+  }
+  if ((result.contextUsedTokens !== undefined) !== (result.contextWindowTokens !== undefined)) {
+    delete result.contextUsedTokens;
+    delete result.contextWindowTokens;
+  }
+  if (result.planFiveHourResetsAtUnix !== undefined && result.planFiveHourUsedPercent === undefined) {
+    delete result.planFiveHourResetsAtUnix;
+  }
+  if (result.planSevenDayResetsAtUnix !== undefined && result.planSevenDayUsedPercent === undefined) {
+    delete result.planSevenDayResetsAtUnix;
+  }
+  return Object.keys(result).length ? result : null;
+}
+
+const VALID_PERIODS = new Set(['weekly', 'monthly', 'five_hour', 'seven_day', 'unknown']);
+
+function projectAccountCredits(source) {
+  if (!source || typeof source !== 'object') return null;
+  const rawUsed = source.usedPercent ?? source.usagePercent;
+  if (!percent(rawUsed)) return null;
+  const usedPercent = Math.round(rawUsed * 100) / 100;
+  const periodType = typeof source.periodType === 'string' && VALID_PERIODS.has(source.periodType.toLowerCase())
+    ? source.periodType.toLowerCase()
+    : 'unknown';
+  const out = { usedPercent, periodType };
+  if (typeof source.label === 'string' && source.label.trim()) {
+    out.label = source.label.trim();
+  }
+  if (typeof source.resetsAt === 'string' && source.resetsAt.trim()) {
+    out.resetsAt = source.resetsAt.trim();
+  }
+  if (Array.isArray(source.productUsage) && source.productUsage.length > 0) {
+    const products = [];
+    for (const item of source.productUsage) {
+      if (!item || typeof item !== 'object') continue;
+      const product = typeof item.product === 'string' ? item.product.trim() : '';
+      const pUsed = item.usagePercent ?? item.usedPercent;
+      if (!product || !percent(pUsed)) continue;
+      const entry = { product, usagePercent: Math.round(pUsed * 100) / 100 };
+      if (typeof item.resetsAt === 'string' && item.resetsAt.trim()) {
+        entry.resetsAt = item.resetsAt.trim();
+      }
+      products.push(entry);
+    }
+    if (products.length > 0) out.productUsage = products;
+  }
+  if (source.resetCredits && typeof source.resetCredits === 'object') {
+    const count = source.resetCredits.availableCount;
+    if (integer(count) && count > 0) {
+      const reset = { availableCount: count };
+      if (typeof source.resetCredits.nextExpiresAt === 'string' && source.resetCredits.nextExpiresAt.trim()) {
+        reset.nextExpiresAt = source.resetCredits.nextExpiresAt.trim();
+      }
+      if (Array.isArray(source.resetCredits.expiresAt) && source.resetCredits.expiresAt.length > 0) {
+        const exp = source.resetCredits.expiresAt.filter(e => typeof e === 'string' && e.trim());
+        if (exp.length > 0) reset.expiresAt = exp.slice(0, 32);
+      }
+      out.resetCredits = reset;
+    }
+  }
+  return out;
+}
+
+module.exports = { projectUsage, projectAccountCredits };
+

package/src/main/protocol-core/capability-manager.js

@@ -0,0 +1,16 @@
+const { createCapabilities, validateCapabilities } = require('../shared-contracts');
+
+class CapabilityManager {
+  constructor() { this.adapters = new Map(); }
+  register(id, capabilities) {
+    const errors = validateCapabilities(capabilities);
+    if (errors.length) throw new Error(errors.join('; '));
+    this.adapters.set(id, createCapabilities(capabilities));
+  }
+  get(id) { return structuredClone(this.adapters.get(id) ?? createCapabilities()); }
+  require(id, group, name) {
+    if (this.get(id)[group]?.[name] !== true) throw new Error(`原生接口不支持 ${group}.${name}`);
+  }
+}
+
+module.exports = { CapabilityManager };

package/src/main/protocol-core/event-router.js

@@ -0,0 +1,32 @@
+// Event Router：CoreEvent 入口。顺序校验（去重/回退警告）→ Projector → 订阅者。
+class EventRouter {
+  constructor({ projector, validator }) {
+    this.projector = projector;
+    this.validator = validator;
+    this.listeners = new Set();
+    this.warnings = [];
+  }
+
+  /**
+   * @returns {{ accepted: boolean, ignored: boolean, warnings: string[], projected: object }}
+   */
+  route(event) {
+    const verdict = this.validator.check(event);
+    if (verdict.warnings.length) this.warnings.push(...verdict.warnings);
+    if (verdict.action === 'ignore') return { accepted: false, ignored: true, warnings: verdict.warnings, projected: {} };
+    const projected = this.projector.apply(event);
+    for (const listener of this.listeners) listener({ type: 'core/event', event, projected });
+    return { accepted: true, ignored: false, warnings: verdict.warnings, projected };
+  }
+
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  clear() {
+    this.warnings = [];
+  }
+}
+
+module.exports = { EventRouter };

package/src/main/protocol-core/file-change-projector.js

@@ -0,0 +1,45 @@
+const { createItem } = require('../shared-contracts');
+const priority = { git: 1, snapshot: 2, native: 3 };
+
+function projectFileChanges(projector, event) {
+  const turn = projector.turns.get(event.turnId);
+  if (!turn || turn.threadId !== event.threadId) throw new Error('file changes require a matching turn');
+  const { changes = [], source = 'snapshot', replace = false } = event.payload;
+  if (!Object.hasOwn(priority, source)) throw new Error('unknown file change source');
+  const paths = new Set(changes.map(change => change.path));
+  if (replace) {
+    for (const id of [...turn.itemIds]) {
+      const item = projector.items.get(id);
+      if (item?.type === 'file_change' && item.source === source && !paths.has(item.path)) {
+        projector.items.delete(id); turn.itemIds = turn.itemIds.filter(value => value !== id);
+      }
+    }
+  }
+  for (const change of changes) {
+    if (typeof change.path !== 'string' || !change.path) throw new Error('file path required');
+    const id = `file_${turn.id}_${change.path}`;
+    const old = projector.items.get(id);
+    if (change.complete === true && typeof change.before === 'string' && change.before === change.after && !change.undone
+      && (change.changeType === 'modified' || old?.changeType === 'added' && change.changeType === 'deleted')) {
+      projector.items.delete(id); turn.itemIds = turn.itemIds.filter(value => value !== id);
+      continue;
+    }
+    // Only a complete native patch supersedes a workspace snapshot.
+    const snapshotDisagrees = source === 'snapshot' && change.complete === true && change.undone !== true
+      && typeof old?.before === 'string' && typeof old?.after === 'string'
+      && (old.before !== change.before || old.after !== change.after);
+    if (old && old.complete !== false && priority[old.source] > priority[source] && !snapshotDisagrees) {
+      if (source === 'snapshot' && change.undone === true) { old.undone = true; old.updatedAt = event.timestamp; }
+      continue;
+    }
+    if (old && source === 'native' && change.complete === false) continue;
+    const item = createItem({ ...change, id, threadId: event.threadId, turnId: turn.id,
+      type: 'file_change', source, status: 'completed', nativeRef: { ...old?.nativeRef, ...event.nativeRef, ...change.nativeRef },
+      createdAt: old?.createdAt ?? event.timestamp, updatedAt: event.timestamp }, event.timestamp);
+    projector.items.set(id, item);
+    if (!turn.itemIds.includes(id)) turn.itemIds.push(id);
+  }
+  return { turn, items: projector.itemsForTurn(turn.id).filter(item => item.type === 'file_change') };
+}
+
+module.exports = { projectFileChanges };

package/src/main/protocol-core/index.js

@@ -0,0 +1,8 @@
+module.exports = {
+  ...require('./protocol-core'),
+  ...require('./thread-manager'),
+  ...require('./turn-manager'),
+  ...require('./projector'),
+  ...require('./event-router'),
+  ...require('./sequence-validator'),
+};

package/src/main/protocol-core/interaction-router.js

@@ -0,0 +1,30 @@
+// A request is owned by one Core Turn. The native protocol alone accepts answers.
+class InteractionRouter {
+  constructor(core) { this.core = core; this.inFlight = new Set(); }
+
+  pending(threadId) {
+    const thread = this.core.getThread(threadId);
+    if (!thread?.activeTurnId) return [];
+    return this.core.getItemsForTurn(thread.activeTurnId).filter(item =>
+      ['approval', 'question'].includes(item.type) && item.interactionStatus === 'pending'
+      && !['completed', 'cancelled', 'error'].includes(item.status));
+  }
+
+  async respond(threadId, requestId, response, sendNative) {
+    const item = this.pending(threadId).find(item => item.requestId === requestId);
+    if (!item) throw new Error('该请求已处理或已过期');
+    if (this.inFlight.has(item.id)) throw new Error('该回答正在提交');
+    this.inFlight.add(item.id);
+    try {
+      await sendNative(item, response);
+      // Native callbacks may complete/cancel the turn while respond is in flight.
+      if (!this.pending(threadId).some(current => current.id === item.id)) return;
+      const event = { threadId, turnId: item.turnId, itemId: item.id };
+      this.core.dispatch({ ...event, type: 'item.updated', payload: { interactionStatus: 'responded' } });
+      this.core.dispatch({ ...event, type: 'item.completed' });
+      if (!this.pending(threadId).length) this.core.dispatch({ ...event, type: 'turn.resumed' });
+    } finally { this.inFlight.delete(item.id); }
+  }
+}
+
+module.exports = { InteractionRouter };