harness-mix 0.1.0

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 };

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

@@ -0,0 +1,238 @@
+const { projectFileChanges } = require('./file-change-projector');
+const { createItem, validateItem, TERMINAL_ITEM_STATUS, TERMINAL_TURN_STATUS } = require('../shared-contracts');
+
+// Projector：CurrentState + CoreEvent → State（§7）。
+// 必须是确定性逻辑：同样的 CoreEvent 序列永远投影出同样的 State。
+// Projector 不判断任何 Harness 名称；语义全部由事件 payload 携带。
+class Projector {
+  constructor({ threads, turns }) {
+    this.threads = threads; // ThreadManager
+    this.turns = turns;     // TurnManager
+    this.items = new Map(); // itemId -> Item
+  }
+
+  /** 应用一个 CoreEvent，返回 { thread?, turn?, item? }（被改动的实体） */
+  apply(event) {
+    const existingTurn = event.turnId ? this.turns.get(event.turnId) : null;
+    if (existingTurn && existingTurn.threadId !== event.threadId) throw new Error('event belongs to another thread');
+    if (existingTurn && TERMINAL_TURN_STATUS.includes(existingTurn.status) && event.type.startsWith('item.')) return {};
+    if (existingTurn && typeof event.sequence === 'number') existingTurn.lastSequence = Math.max(existingTurn.lastSequence, event.sequence);
+    switch (event.type) {
+      case 'thread.rolledBack': {
+        const turns = this.turns.turnsForThread(event.threadId);
+        const count = event.payload.numTurns;
+        if (!Number.isSafeInteger(count) || count < 1 || count > turns.length || turns.some(t => !TERMINAL_TURN_STATUS.includes(t.status))) throw new Error('Invalid rollback boundary');
+        const removed = new Set(turns.slice(-count).map(t => t.id));
+        for (const id of removed) this.turns.turns.delete(id);
+        for (const [id, item] of this.items) if (removed.has(item.turnId)) this.items.delete(id);
+        const thread = this.threads.get(event.threadId);
+        thread.usage = {};
+        for (const turn of turns.slice(0, -count)) {
+          turn.nativeTurnRef = { ...turn.nativeTurnRef, sessionId: event.payload.sessionId };
+          const map = event.payload.checkpointMap;
+          if (map && turn.nativeTurnRef.checkpointId) turn.nativeTurnRef.checkpointId = map[turn.nativeTurnRef.checkpointId];
+        }
+        return { thread: this.threads.update(event.threadId, { status: 'idle', activeTurnId: null, nativeSessionRef: { sessionId: event.payload.sessionId } }, event.timestamp) };
+      }
+      case 'thread.created': {
+        const thread = this.threads.create({ id: event.threadId, ...event.payload }, event.timestamp);
+        return { thread };
+      }
+      case 'thread.updated': {
+        const thread = this.threads.update(event.threadId, event.payload, event.timestamp);
+        return { thread };
+      }
+      case 'turn.started': {
+        const turn = this.#ensureTurn(event);
+        this.turns.start(turn.id, event.timestamp);
+        if (typeof event.sequence === 'number') turn.lastSequence = event.sequence;
+        const thread = this.threads.update(turn.threadId, { status: 'running', activeTurnId: turn.id }, event.timestamp);
+        return { turn, thread };
+      }
+      case 'turn.waiting': {
+        const turn = this.#ensureTurn(event);
+        this.turns.wait(turn.id, event.timestamp);
+        const thread = this.threads.update(turn.threadId, { status: 'waiting' }, event.timestamp);
+        return { turn, thread };
+      }
+      case 'turn.resumed': {
+        const turn = this.#ensureTurn(event);
+        this.turns.resume(turn.id, event.timestamp);
+        return { turn, thread: this.threads.update(turn.threadId, { status: 'running' }, event.timestamp) };
+      }
+      case 'turn.completed':
+        return this.#settleTurn(event, 'completed');
+      case 'turn.cancelled':
+        return this.#settleTurn(event, 'cancelled');
+      case 'turn.failed':
+        return this.#settleTurn(event, 'failed');
+      case 'item.started':
+        return { item: this.#startItem(event) };
+      case 'item.delta':
+        return { item: this.#deltaItem(event) };
+      case 'item.updated':
+        return { item: this.#updateItem(event) };
+      case 'item.completed':
+        return { item: this.#completeItem(event) };
+      case 'files.updated': return projectFileChanges(this, event);
+      case 'plan.updated': {
+        if (!existingTurn || TERMINAL_TURN_STATUS.includes(existingTurn.status)) return {};
+        const itemId = `plan_${event.turnId}`;
+        const item = this.items.get(itemId) ?? this.#startItem({ ...event, itemId, payload: { type: 'plan' } });
+        item.entries = structuredClone(event.payload.entries ?? []);
+        item.updatedAt = event.timestamp;
+        return { item };
+      }
+      case 'usage.updated': {
+        const item = this.#upsertUsageItem(event);
+        const thread = this.threads.update(event.threadId, { usage: event.payload }, event.timestamp);
+        return { item, thread };
+      }
+      default:
+        return {};
+    }
+  }
+
+  /* ---------------- 内部 ---------------- */
+
+  #ensureTurn(event) {
+    const existing = event.turnId ? this.turns.get(event.turnId) : null;
+    if (existing) return existing;
+    // 容错：turn 事件先于显式 createTurn 到达时自动建立，不让状态损坏
+    return this.turns.create({ id: event.turnId ?? `turn_${event.eventId}`, threadId: event.threadId, nativeTurnRef: event.nativeRef }, event.timestamp);
+  }
+
+  #settleTurn(event, kind) {
+    const turn = this.#ensureTurn(event);
+    if (event.nativeRef) turn.nativeTurnRef = { ...turn.nativeTurnRef, ...event.nativeRef };
+    if (typeof event.sequence === 'number') turn.lastSequence = event.sequence;
+    // 首次结算生效：Turn 已进入终态后，迟到的重复结算事件为幂等噪声（如 cancel 后
+    // 原生流仍送达 agent_settled / result），不改变 Turn 生命周期。
+    if (TERMINAL_TURN_STATUS.includes(turn.status)) return { turn };
+    const stopReason = event.payload?.stopReason;
+    if (kind === 'completed') {
+      if (stopReason === 'cancelled') this.turns.cancel(turn.id, {}, event.timestamp);
+      else this.turns.complete(turn.id, {}, event.timestamp);
+    } else if (kind === 'cancelled') {
+      this.turns.cancel(turn.id, {}, event.timestamp);
+    } else {
+      this.turns.fail(turn.id, event.payload?.message ?? event.payload?.error, {}, event.timestamp);
+    }
+    // Turn 结算：所有未终态 Item 一并收尾（语义等同 legacy finishMessage）
+    this.#finalizeOpenItems(turn, event.timestamp);
+    const threadStatus = turn.status === 'error' ? 'error' : 'idle';
+    const thread = this.threads.update(turn.threadId, { status: threadStatus, activeTurnId: null }, event.timestamp);
+    return { turn, thread };
+  }
+
+  #finalizeOpenItems(turn, now) {
+    for (const itemId of turn.itemIds) {
+      const item = this.items.get(itemId);
+      if (!item || TERMINAL_ITEM_STATUS.includes(item.status)) continue;
+      if (item.type === 'tool_call') {
+        // 与 legacy 一致：已结算的 Turn 不代表工具成功
+        item.state = item.state && item.state !== 'running' ? item.state : 'interrupted';
+        item.status = item.state === 'error' ? 'error' : 'cancelled';
+      } else if (item.type === 'approval' || item.type === 'question') {
+        item.status = turn.status === 'completed' ? 'completed' : 'cancelled';
+      } else {
+        item.status = 'completed';
+      }
+      item.updatedAt = now;
+    }
+  }
+
+  #startItem(event) {
+    const existing = event.itemId ? this.items.get(event.itemId) : null;
+    if (existing) return existing; // 幂等
+    const { type, ...rest } = event.payload ?? {};
+    const streaming = type === 'agent_message' || type === 'reasoning';
+    const item = createItem({
+      id: event.itemId ?? `item_${event.eventId}`,
+      threadId: event.threadId,
+      turnId: event.turnId,
+      type,
+      status: streaming ? 'streaming' : 'started',
+      nativeRef: event.nativeRef,
+      ...(streaming ? { content: '' } : {}),
+      ...rest,
+    }, event.timestamp);
+    const errors = validateItem(item);
+    if (errors.length) throw new Error(`invalid item: ${errors.join('; ')}`);
+    this.items.set(item.id, item);
+    const turn = item.turnId ? this.turns.get(item.turnId) : null;
+    if (turn && !turn.itemIds.includes(item.id)) turn.itemIds.push(item.id);
+    return item;
+  }
+
+  #deltaItem(event) {
+    const item = this.items.get(event.itemId);
+    if (!item || TERMINAL_ITEM_STATUS.includes(item.status)) return item ?? null;
+    const text = typeof event.payload?.text === 'string' ? event.payload.text : '';
+    item.content = (item.content ?? '') + text;
+    item.status = 'streaming';
+    item.updatedAt = event.timestamp;
+    return item;
+  }
+
+  #updateItem(event) {
+    const item = this.items.get(event.itemId);
+    if (!item) return null;
+    for (const [key, value] of Object.entries(event.payload ?? {})) {
+      if (['id', 'threadId', 'turnId', 'type', 'createdAt'].includes(key)) continue;
+      if (key === 'artifacts' && Array.isArray(value)) item.artifacts = [...(item.artifacts ?? []), ...value];
+      else item[key] = value;
+    }
+    if (event.payload?.state && event.payload.state !== 'running' && item.type === 'tool_call') {
+      item.status = event.payload.state === 'error' ? 'error' : 'completed';
+    }
+    item.updatedAt = event.timestamp;
+    return item;
+  }
+
+  #completeItem(event) {
+    const item = this.items.get(event.itemId);
+    if (!item || TERMINAL_ITEM_STATUS.includes(item.status)) return item ?? null;
+    const state = event.payload?.state;
+    item.status = state === 'error' ? 'error' : 'completed';
+    if (state && item.type === 'tool_call') item.state = state;
+    item.updatedAt = event.timestamp;
+    return item;
+  }
+
+  #upsertUsageItem(event) {
+    const turn = event.turnId ? this.turns.get(event.turnId) : null;
+    const existing = turn
+      ? turn.itemIds.map((id) => this.items.get(id)).find((i) => i?.type === 'usage')
+      : null;
+    if (existing) {
+      existing.usage = { ...(existing.usage ?? {}), ...event.payload };
+      existing.updatedAt = event.timestamp;
+      return existing;
+    }
+    const item = createItem({
+      threadId: event.threadId,
+      turnId: event.turnId,
+      id: event.itemId ?? `usage_${event.turnId ?? event.threadId}`,
+      type: 'usage',
+      status: 'completed',
+      nativeRef: event.nativeRef,
+      usage: { ...event.payload },
+    }, event.timestamp);
+    this.items.set(item.id, item);
+    if (turn) turn.itemIds.push(item.id);
+    return item;
+  }
+
+  itemsForTurn(turnId) {
+    const turn = this.turns.get(turnId);
+    if (turn) return turn.itemIds.map((id) => this.items.get(id)).filter(Boolean);
+    return [...this.items.values()].filter((i) => i.turnId === turnId);
+  }
+
+  clear() {
+    this.items.clear();
+  }
+}
+
+module.exports = { Projector };

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

@@ -0,0 +1,132 @@
+const { InteractionRouter } = require('./interaction-router');
+const contracts = require('../shared-contracts');
+const { ThreadManager } = require('./thread-manager');
+const { TurnManager } = require('./turn-manager');
+const { Projector } = require('./projector');
+const { EventRouter } = require('./event-router');
+const { SequenceValidator } = require('./sequence-validator');
+
+/**
+ * ProtocolCore：Harness Mix 新内核 facade（§6）。
+ * 第一阶段仅内存状态。API 保持简单：
+ *   createThread / getThread / createTurn / getTurn / dispatch
+ *   getItem / getItemsForTurn / snapshot / reset / subscribe
+ */
+class ProtocolCore {
+  constructor({ strictSequence = true } = {}) {
+    this.interactions = new InteractionRouter(this);
+    this.threads = new ThreadManager();
+    this.turns = new TurnManager();
+    this.projector = new Projector({ threads: this.threads, turns: this.turns });
+    this.validator = new SequenceValidator({ strict: strictSequence });
+    this.router = new EventRouter({ projector: this.projector, validator: this.validator });
+    this.sequenceByThread = new Map(); // threadId -> 自动分配的下一个 sequence
+  }
+
+  /** 建立 Core Thread（走事件投影，保证一切状态都来自 CoreEvent） */
+  createThread({ id, workspaceId, harnessId, nativeSessionRef, metadata } = {}) {
+    const existing = id ? this.threads.get(id) : null;
+    if (existing) return existing;
+    const thread = contracts.createThread({ id, workspaceId, harnessId, nativeSessionRef, metadata });
+    this.dispatch({
+      threadId: thread.id,
+      type: 'thread.created',
+      payload: {
+        workspaceId: thread.workspaceId,
+        harnessId: thread.harnessId,
+        nativeSessionRef: thread.nativeSessionRef,
+        metadata: thread.metadata,
+      },
+    });
+    return this.threads.get(thread.id);
+  }
+
+  getThread(threadId) {
+    return this.threads.get(threadId);
+  }
+
+  // Validate the entire checkpoint before mutating state. Hydration executes no effects.
+  restore({ version, thread, turns, items }) {
+    if (version !== 1) throw new Error('unsupported Core checkpoint');
+    const errors = contracts.validateThread(thread);
+    const ids = new Set(items.map(i => i.id));
+    if (ids.size !== items.length || new Set(turns.map(t => t.id)).size !== turns.length) errors.push('duplicate checkpoint IDs');
+    for (const turn of turns) {
+      errors.push(...contracts.validateTurn(turn));
+      if (turn.threadId !== thread.id || turn.itemIds.some(id => !ids.has(id))) errors.push('invalid checkpoint turn ownership');
+      if (this.getTurn(turn.id) && this.getTurn(turn.id).threadId !== thread.id) errors.push('checkpoint turn ID collision');
+    }
+    for (const item of items) {
+      errors.push(...contracts.validateItem(item));
+      if (item.threadId !== thread.id || (item.turnId && !turns.some(t => t.id === item.turnId && t.itemIds.includes(item.id)))) errors.push('invalid checkpoint item ownership');
+      if (this.getItem(item.id) && this.getItem(item.id).threadId !== thread.id) errors.push('checkpoint item ID collision');
+    }
+    if (errors.length) throw new Error(errors.join('; '));
+    this.threads.threads.set(thread.id, structuredClone(thread));
+    for (const turn of turns) this.turns.turns.set(turn.id, structuredClone(turn));
+    for (const item of items) this.projector.items.set(item.id, structuredClone(item));
+    this.sequenceByThread.set(thread.id, Math.max(this.sequenceByThread.get(thread.id) ?? 0, ...turns.map(t => t.lastSequence)));
+    this.validator.lastSequenceByThread.set(thread.id, this.sequenceByThread.get(thread.id));
+  }
+
+  /** 先创建 Core Turn，再调用 Harness（§26 的目标形态；Shadow 阶段由 Runtime 触发） */
+  createTurn({ threadId, nativeTurnRef } = {}) {
+    return this.turns.create({ threadId, nativeTurnRef });
+  }
+
+  getTurn(turnId) {
+    return this.turns.get(turnId);
+  }
+
+  /** 统一事件入口：补全 eventId / timestamp / sequence 后经 Router → Projector */
+  dispatch(event) {
+    const full = contracts.createCoreEvent(event);
+    if (full.sequence == null) {
+      const next = (this.sequenceByThread.get(full.threadId) ?? 0) + 1;
+      this.sequenceByThread.set(full.threadId, next);
+      full.sequence = next;
+    } else {
+      const known = this.sequenceByThread.get(full.threadId) ?? 0;
+      if (full.sequence > known) this.sequenceByThread.set(full.threadId, full.sequence);
+    }
+    const errors = contracts.validateCoreEvent(full);
+    if (errors.length) throw new Error(`invalid core event: ${errors.join('; ')}`);
+    return this.router.route(full);
+  }
+
+  getItem(itemId) {
+    return this.projector.items.get(itemId) ?? null;
+  }
+
+  getItemsForTurn(turnId) {
+    return this.projector.itemsForTurn(turnId);
+  }
+
+  subscribe(listener) {
+    return this.router.subscribe(listener);
+  }
+
+  get warnings() {
+    return this.router.warnings;
+  }
+
+  snapshot() {
+    return {
+      threads: this.threads.all(),
+      turns: [...this.turns.turns.values()],
+      items: [...this.projector.items.values()],
+      warnings: [...this.router.warnings],
+    };
+  }
+
+  reset() {
+    this.threads.clear();
+    this.turns.clear();
+    this.projector.clear();
+    this.validator.reset();
+    this.router.clear();
+    this.sequenceByThread.clear();
+  }
+}
+
+module.exports = { ProtocolCore };

package/src/main/protocol-core/sequence-validator.js

@@ -0,0 +1,44 @@
+// Sequence Validator：去重与顺序基础。
+// 规则（§9）：
+//   - eventId 已存在 → ignore（重复事件不得二次投影）
+//   - sequence 回退 → 开发环境 warn，但不得直接破坏状态（仍接受）
+//   - sequence 正常递增 → accept
+class SequenceValidator {
+  constructor({ strict = false } = {}) {
+    this.strict = strict;
+    this.seenEventIds = new Set();
+    this.lastSequenceByThread = new Map(); // threadId -> number
+  }
+
+  /**
+   * @returns {{ action: 'accept' | 'ignore', warnings: string[] }}
+   */
+  check(event) {
+    const warnings = [];
+    if (!event || typeof event !== 'object') return { action: 'ignore', warnings: ['malformed event'] };
+    if (event.eventId && this.seenEventIds.has(event.eventId)) {
+      return { action: 'ignore', warnings: [`duplicate eventId ${event.eventId}`] };
+    }
+    const threadId = event.threadId ?? '__global__';
+    if (typeof event.sequence === 'number') {
+      const last = this.lastSequenceByThread.get(threadId);
+      if (last != null && event.sequence <= last) {
+        const message = `sequence regression on thread ${threadId}: last=${last} event=${event.sequence}`;
+        warnings.push(message);
+        if (this.strict) return { action: 'ignore', warnings };
+        // 非严格模式：记录警告但接受，状态不被顺序问题破坏。
+      } else {
+        this.lastSequenceByThread.set(threadId, event.sequence);
+      }
+    }
+    if (event.eventId) this.seenEventIds.add(event.eventId);
+    return { action: 'accept', warnings };
+  }
+
+  reset(threadId) {
+    if (threadId == null) { this.seenEventIds.clear(); this.lastSequenceByThread.clear(); return; }
+    this.lastSequenceByThread.delete(threadId);
+  }
+}
+
+module.exports = { SequenceValidator };

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

@@ -0,0 +1,50 @@
+const { createThread, validateThread } = require('../shared-contracts');
+
+// ThreadManager：Core 侧 Thread 的存储与字段级更新。
+// 第一阶段仅内存状态，不设计数据库（§6）。
+class ThreadManager {
+  constructor() {
+    this.threads = new Map(); // threadId -> Thread
+  }
+
+  create(input, now = Date.now()) {
+    const existing = input?.id ? this.threads.get(input.id) : null;
+    if (existing) return existing;
+    const thread = createThread(input, now);
+    const errors = validateThread(thread);
+    if (errors.length) throw new Error(`invalid thread: ${errors.join('; ')}`);
+    this.threads.set(thread.id, thread);
+    return thread;
+  }
+
+  get(threadId) {
+    return this.threads.get(threadId) ?? null;
+  }
+
+  /** 白名单字段更新；unknown 字段直接拒绝，防止协议外状态混入 */
+  update(threadId, patch = {}, now = Date.now()) {
+    const thread = this.threads.get(threadId);
+    if (!thread) return null;
+    const allowed = ['status', 'activeTurnId', 'metadata', 'nativeSessionRef', 'usage', 'workspaceId'];
+    for (const key of Object.keys(patch)) {
+      if (!allowed.includes(key)) continue;
+      if (key === 'metadata' || key === 'nativeSessionRef' || key === 'usage') {
+        thread[key] = { ...(thread[key] ?? {}), ...patch[key] };
+      } else {
+        thread[key] = patch[key];
+      }
+    }
+    thread.updatedAt = now;
+    return thread;
+  }
+
+  all() {
+    return [...this.threads.values()];
+  }
+
+  clear() {
+    this.threads.clear();
+  }
+}
+
+module.exports = { ThreadManager };

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

@@ -0,0 +1,63 @@
+const { createTurn, validateTurn, canTransition, TERMINAL_TURN_STATUS } = require('../shared-contracts');
+
+// TurnManager：唯一允许修改 Turn 生命周期状态的模块（§8）。
+// Renderer / Transcript / Adapter 都不得自行推进或推断 Turn 状态。
+class TurnManager {
+  constructor() {
+    this.turns = new Map(); // turnId -> Turn
+  }
+
+  create({ id, threadId, nativeTurnRef } = {}, now = Date.now()) {
+    const turn = createTurn({ id, threadId, nativeTurnRef }, now);
+    const errors = validateTurn(turn);
+    if (errors.length) throw new Error(`invalid turn: ${errors.join('; ')}`);
+    this.turns.set(turn.id, turn);
+    return turn;
+  }
+
+  get(turnId) {
+    return this.turns.get(turnId) ?? null;
+  }
+
+  start(turnId, now = Date.now()) { return this.#transition(turnId, 'running', { startedAt: now }, now); }
+  wait(turnId, now = Date.now()) { return this.#transition(turnId, 'waiting_interaction', {}, now); }
+  resume(turnId, now = Date.now()) { return this.#transition(turnId, 'running', {}, now); }
+
+  complete(turnId, info = {}, now = Date.now()) {
+    return this.#transition(turnId, 'completed', { completedAt: now, ...info }, now);
+  }
+
+  cancel(turnId, info = {}, now = Date.now()) {
+    return this.#transition(turnId, 'cancelled', { completedAt: now, ...info }, now);
+  }
+
+  fail(turnId, error, info = {}, now = Date.now()) {
+    return this.#transition(turnId, 'error', { completedAt: now, error: String(error ?? 'unknown error'), ...info }, now);
+  }
+
+  #transition(turnId, to, extra = {}, now = Date.now()) {
+    const turn = this.turns.get(turnId);
+    if (!turn) throw new Error(`turn ${turnId} does not exist`);
+    if (turn.status === to) return turn; // 幂等：重复完成/取消不报错
+    // start() 允许从 created 经 starting 直接进入 running
+    const from = turn.status === 'created' && to === 'running' ? 'starting' : turn.status;
+    if (!canTransition(from, to)) {
+      const terminal = TERMINAL_TURN_STATUS.includes(turn.status) ? ' (terminal status)' : '';
+      throw new Error(`illegal turn transition: ${turn.status} → ${to}${terminal}`);
+    }
+    turn.status = to;
+    turn.updatedAt = now;
+    Object.assign(turn, extra);
+    return turn;
+  }
+
+  turnsForThread(threadId) {
+    return [...this.turns.values()].filter((t) => t.threadId === threadId);
+  }
+
+  clear() {
+    this.turns.clear();
+  }
+}
+
+module.exports = { TurnManager };