@winmatrix/supervisor 1.0.5

package/src/deliverable-tracker.mjs

@@ -0,0 +1,119 @@
+/**
+ * D11.4: Deliverable 提取
+ *
+ * EngineFinalResult.output（text 字段）不应是全量事件文本的累加，
+ * 而应是最后一次工具调用之后的文本输出。
+ *
+ * 参考 Multica 的 acpDeliverableTracker 设计：
+ * - 每次 tool_call 事件后重置 buffer
+ * - 最后的 text 累积作为 deliverable
+ * - 无 tool_call 时全部 text 作为 deliverable
+ */
+
+/**
+ * Deliverable tracker 状态
+ * @typedef {Object} DeliverableState
+ * @property {string} currentBuffer - 当前累积的文本
+ * @property {boolean} hasToolCall - 是否遇到过工具调用
+ * @property {string} lastDeliverable - 上一个完整的 deliverable（最后一次 tool_call 后的文本）
+ */
+
+/**
+ * 创建新的 deliverable tracker 状态
+ * @returns {DeliverableState}
+ */
+export function createDeliverableState() {
+  return {
+    currentBuffer: '',
+    hasToolCall: false,
+    lastDeliverable: '',
+  };
+}
+
+/**
+ * 处理一个 Engine 进度事件，更新 deliverable 状态
+ *
+ * @param {DeliverableState} state - 当前状态
+ * @param {Object} event - EngineProgressEvent
+ * @returns {DeliverableState} 更新后的状态
+ */
+export function updateDeliverable(state, event) {
+  if (!event || !event.type) return state;
+
+  switch (event.type) {
+    case 'content_delta':
+      // 文本增量 → 追加到 buffer
+      return {
+        ...state,
+        currentBuffer: state.currentBuffer + (event.text || ''),
+      };
+
+    case 'tool_call':
+      // 工具调用 → 当前 buffer 成为 lastDeliverable，重置 buffer
+      return {
+        ...state,
+        hasToolCall: true,
+        lastDeliverable: state.currentBuffer,
+        currentBuffer: '',
+      };
+
+    case 'thinking_delta':
+    case 'stderr_delta':
+    case 'artifact':
+    case 'usage':
+    case 'status':
+    case 'interaction_requested':
+    case 'interaction_resolved':
+      // 这些事件不影响 deliverable
+      return state;
+
+    case 'tool_result_delta':
+      // 工具结果不影响 deliverable（只关注 Agent 的文本输出）
+      return state;
+
+    case 'result':
+      // 终态事件，不影响 deliverable buffer
+      return state;
+
+    case 'error':
+      // 错误不影响 deliverable
+      return state;
+
+    default:
+      return state;
+  }
+}
+
+/**
+ * 从 deliverable 状态提取最终 deliverable 文本
+ *
+ * 规则：
+ * 1. 如果有 tool_call，deliverable = currentBuffer（最后一次 tool_call 后的文本）
+ * 2. 如果没有 tool_call，deliverable = currentBuffer（全部文本）
+ * 3. 如果 currentBuffer 为空（如最后一次事件是 tool_call 后无文本），返回空字符串
+ *
+ * @param {DeliverableState} state
+ * @returns {string}
+ */
+export function extractDeliverable(state) {
+  // 无论是否有 tool_call，deliverable 始终是 currentBuffer
+  // 有 tool_call 时，currentBuffer 是最后一次 tool_call 后的文本
+  // 无 tool_call 时，currentBuffer 是全部文本
+  return state.currentBuffer;
+}
+
+/**
+ * 从事件数组中直接计算 deliverable（不依赖 tracker 状态）
+ * 用于从持久化的 events.jsonl 回溯计算
+ *
+ * @param {Object[]} events - EngineProgressEvent 数组
+ * @returns {string}
+ */
+export function computeDeliverableFromEvents(events) {
+  let state = createDeliverableState();
+  for (const envelope of events) {
+    const event = envelope.event || envelope;
+    state = updateDeliverable(state, event);
+  }
+  return extractDeliverable(state);
+}

package/src/engine-driver-config.mjs

@@ -0,0 +1,131 @@
+/**
+ * Engine Driver 配置（design D11.2 / D11.3 / D11.4）
+ *
+ * 每种 Engine 声明：
+ * - resumeRejectedPatterns: resume 被拒绝时 Engine 输出的特征短语
+ * - blockedArgs: 受协议保护的 CLI 参数，用户 customArgs 中的匹配项将被过滤
+ * - gracefulShutdownTimeoutMs: 两阶段关闭 Phase 1 超时（stdin.Close() 后等待 Engine 自行退出）
+ *
+ * 参考 Multica 开源项目的 18 种 agent CLI 生产适配经验。
+ */
+
+/**
+ * @typedef {Object} EngineDriverConfig
+ * @property {string[]} resumeRejectedPatterns
+ * @property {string[]} blockedArgs
+ * @property {number} gracefulShutdownTimeoutMs
+ * @property {string} [phase2TimeoutMs]
+ */
+
+/** @type {Record<string, EngineDriverConfig>} */
+export const ENGINE_DRIVER_CONFIGS = {
+  'claude-code': {
+    /**
+     * D11.2: Claude Code resume 拒绝检测模式
+     * 来源: Claude Code CLI 输出的中英文错误消息
+     */
+    resumeRejectedPatterns: [
+      'no conversation found',
+      'no saved session found',
+      '已绑定另外',
+      'bound to another account',
+      'bound to a different account',
+      'session not found',
+      'cannot resume session',
+    ],
+
+    /**
+     * D11.3: Claude Code 受协议保护的 CLI 参数
+     * Supervisor 自身设置这些参数，不允许用户 customArgs 覆盖
+     */
+    blockedArgs: [
+      '-p', '--print',
+      '--output-format',
+      '--input-format',
+      '--permission-mode',
+      '--mcp-config',
+      '--settings',
+      '--strict-mcp-config',
+      '--effort',
+      '--verbose',
+      '--include-partial-messages',
+    ],
+
+    /**
+     * D11.2: Claude Code 对 stdin.Close() 会写状态文件再退出
+     * 给 10s grace period
+     */
+    gracefulShutdownTimeoutMs: 10000,
+    phase2TimeoutMs: 5000,
+  },
+
+  'codex': {
+    resumeRejectedPatterns: [
+      'thread not found',
+      'cannot resume thread',
+      'session expired',
+      'invalid thread id',
+    ],
+
+    blockedArgs: [
+      'app-server',
+      '--listen',
+    ],
+
+    /**
+     * Codex app-server 需要较长 drain 时间
+     */
+    gracefulShutdownTimeoutMs: 10000,
+    phase2TimeoutMs: 5000,
+  },
+
+  'hermes': {
+    resumeRejectedPatterns: [
+      'session not found',
+      'cannot resume session',
+      'invalid session',
+      'session expired',
+    ],
+
+    blockedArgs: [
+      'acp',
+    ],
+
+    /**
+     * Hermes 通常退出较快
+     */
+    gracefulShutdownTimeoutMs: 5000,
+    phase2TimeoutMs: 5000,
+  },
+
+  'openclaw': {
+    resumeRejectedPatterns: [
+      'session not found',
+      'cannot resume session',
+      'invalid session',
+      'session expired',
+    ],
+
+    blockedArgs: [
+      'agent-server',
+      '--listen',
+    ],
+
+    gracefulShutdownTimeoutMs: 5000,
+    phase2TimeoutMs: 5000,
+  },
+};
+
+/**
+ * 获取 Engine 的 driver 配置，未知 engine 使用默认配置
+ * @param {string} engineId
+ * @returns {EngineDriverConfig}
+ */
+export function getEngineDriverConfig(engineId) {
+  return ENGINE_DRIVER_CONFIGS[engineId] ?? {
+    resumeRejectedPatterns: [],
+    blockedArgs: [],
+    gracefulShutdownTimeoutMs: 5000,
+    phase2TimeoutMs: 5000,
+  };
+}

package/src/env-sanitizer.mjs

@@ -0,0 +1,112 @@
+/**
+ * D11.3: 环境变量隔离
+ *
+ * Supervisor 启动 Engine 子进程前，过滤可能干扰 Engine 行为的环境变量。
+ * 参考 Multica 的 isFilteredChildEnvKey() 设计。
+ */
+
+/**
+ * 需要过滤的环境变量前缀/名称模式
+ * 这些是 Supervisor 自身的运行时标记，不应泄漏到 Engine 子进程
+ */
+const FILTERED_ENV_PATTERNS = [
+  // Supervisor 自身的 Claude 运行时标记
+  /^CLAUDECODE_/i,
+  /^CLAUDE_CODE_/i,
+
+  // Supervisor/WinMatrix 内部标记（但保留白名单中的）
+  /^WINMATRIX_SUPERVISOR_/i,
+
+  // Multica 兼容（如果 daemon 环境泄漏）
+  /^MULTICA_/i,
+
+  // Agent Engine Gateway 内部标记（Supervisor 自身使用的，不传递给 Engine）
+  /^WM_AGENT_ENGINE_INTERNAL_/i,
+];
+
+/**
+ * 必须保留的环境变量前缀（即使匹配了过滤模式）
+ */
+const ENV_PASSTHROUGH_PATTERNS = [
+  // Engine 需要的 API 密钥和端点
+  /_API_KEY$/i,
+  /_BASE_URL$/i,
+  /_API_BASE$/i,
+
+  // 系统基础环境变量
+  /^PATH$/i,
+  /^HOME$/i,
+  /^USER$/i,
+  /^SHELL$/i,
+  /^LANG$/i,
+  /^LC_/i,
+  /^TERM$/i,
+  /^TZ$/i,
+
+  // Node.js 运行时
+  /^NODE_/i,
+  /^NPM_/i,
+
+  // Engine 需要的配置（白名单）
+  /^WIN_AGENT_ENGINE_/i, // Gateway Run 标记等
+  /^CLAUDE_/i,           // Claude 配置（但 CLAUDECODE_ 和 CLAUDE_CODE_ 被过滤）
+];
+
+/**
+ * 过滤 Supervisor 内部使用的临时标记，不传递给 Engine
+ */
+const FILTERED_EXACT_KEYS = new Set([
+  'WIN_AGENT_ENGINE_GATEWAY_RUN', // Supervisor 设置，但 Engine 不需要
+  'WM_INTERNAL_SUPERVISOR',
+]);
+
+/**
+ * 判断一个环境变量 key 是否应该被过滤
+ * @param {string} key
+ * @returns {boolean}
+ */
+export function isFilteredEnvKey(key) {
+  // 精确匹配的过滤项（优先级最高）
+  if (FILTERED_EXACT_KEYS.has(key)) return true;
+
+  // 先检查是否匹配过滤模式（过滤优先于白名单）
+  // 这样 CLAUDE_CODE_ENTRYPOINT 被过滤，即使 CLAUDE_ 在白名单中
+  for (const pattern of FILTERED_ENV_PATTERNS) {
+    if (pattern.test(key)) return true;
+  }
+
+  // 再检查白名单（未被过滤的保留）
+  for (const pattern of ENV_PASSTHROUGH_PATTERNS) {
+    if (pattern.test(key)) return false;
+  }
+
+  return false;
+}
+
+/**
+ * 从 process.env 构建传递给 Engine 子进程的清洁环境变量
+ * @param {Record<string, string>} [overrides] - 需要额外设置的环境变量
+ * @returns {Record<string, string>}
+ */
+export function sanitizeEnv(overrides = {}) {
+  const clean = {};
+
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value !== undefined && !isFilteredEnvKey(key)) {
+      clean[key] = value;
+    }
+  }
+
+  // 应用 overrides
+  Object.assign(clean, overrides);
+
+  return clean;
+}
+
+/**
+ * 获取被过滤的环境变量 key 列表（用于审计日志）
+ * @returns {string[]}
+ */
+export function getFilteredEnvKeys() {
+  return Object.keys(process.env).filter(isFilteredEnvKey);
+}

package/src/resume-degradation.mjs

@@ -0,0 +1,117 @@
+/**
+ * D11.2: Resume 降级链
+ *
+ * 当 EngineSessionBinding.mode='resume' 时，Supervisor 必须处理
+ * resume 被 Engine 拒绝的情况。降级流程：
+ *
+ * 1. 检测到 resume rejected（短语匹配 / 结构化错误）
+ * 2. 标记 run 为 resume_degraded
+ * 3. 清除 resume sessionRef，改为 ephemeral mode
+ * 4. 在 prompt 尾部注入 continuity notice
+ * 5. 上报 resume_degraded 事件
+ *
+ * 降级只发生一次，不允许链式降级。
+ *
+ * 参考 Multica 的 resumeRejectedPhrases + fresh session 重试设计。
+ */
+
+import { getEngineDriverConfig } from './engine-driver-config.mjs';
+
+/**
+ * Continuity notice 模板 — 注入到降级后 prompt 尾部
+ */
+const CONTINUITY_NOTICE = [
+  '',
+  '---',
+  '[System: 上一次会话上下文不可恢复，已从新会话开始。请基于当前信息继续工作。如果之前的上下文对当前任务重要，请明确说明。]',
+].join('\n');
+
+/**
+ * 检测 Engine 输出是否表明 resume 被拒绝
+ *
+ * @param {string} engineId
+ * @param {string} output - Engine 的 stdout/stderr 累积输出
+ * @returns {boolean}
+ */
+export function isResumeRejected(engineId, output) {
+  const config = getEngineDriverConfig(engineId);
+  const patterns = config.resumeRejectedPatterns;
+
+  if (!patterns || patterns.length === 0) return false;
+  if (!output) return false;
+
+  const lowerOutput = output.toLowerCase();
+  return patterns.some(pattern => lowerOutput.includes(pattern.toLowerCase()));
+}
+
+/**
+ * 检测 Engine stderr 是否表明 resume 被拒绝
+ * （某些 Engine 把错误信息写到 stderr）
+ *
+ * @param {string} engineId
+ * @param {string} stderr - Engine 的 stderr 累积输出
+ * @returns {boolean}
+ */
+export function isResumeRejectedInStderr(engineId, stderr) {
+  return isResumeRejected(engineId, stderr);
+}
+
+/**
+ * 生成降级后的 continuity notice
+ * 追加到 prompt 尾部
+ *
+ * @param {Object} [options]
+ * @param {string} [options.originalSessionId] - 被拒绝的原 session ID
+ * @param {string} [options.reason] - 拒绝原因
+ * @returns {string}
+ */
+export function buildContinuityNotice(options = {}) {
+  let notice = CONTINUITY_NOTICE;
+
+  if (options.originalSessionId) {
+    notice += `\n[原会话 ID: ${options.originalSessionId}，无法恢复]`;
+  }
+
+  if (options.reason) {
+    notice += `\n[原因: ${options.reason}]`;
+  }
+
+  return notice;
+}
+
+/**
+ * 构建 resume 降级事件
+ * 用于上报到 events.jsonl
+ *
+ * @param {Object} options
+ * @param {string} options.originalSessionId
+ * @param {string} [options.reason]
+ * @param {string} [options.detectedPattern] - 匹配到的拒绝模式
+ * @returns {Object} EngineProgressEvent
+ */
+export function buildResumeDegradedEvent(options) {
+  return {
+    type: 'status',
+    text: `resume_degraded: session ${options.originalSessionId} rejected, falling back to new session`,
+    metadata: {
+      resumeDegraded: true,
+      originalSessionId: options.originalSessionId,
+      reason: options.reason || 'resume_rejected',
+      detectedPattern: options.detectedPattern || null,
+    },
+  };
+}
+
+/**
+ * 检测 Engine 退出是否因为 resume 失败
+ * （exit code 非零 + stderr 包含拒绝模式）
+ *
+ * @param {string} engineId
+ * @param {number|null} exitCode
+ * @param {string} stderr
+ * @returns {boolean}
+ */
+export function isResumeFailureOnExit(engineId, exitCode, stderr) {
+  if (exitCode === 0) return false;
+  return isResumeRejectedInStderr(engineId, stderr);
+}