@winmatrix/supervisor 1.0.5

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@winmatrix/supervisor",
+  "version": "1.0.5",
+  "type": "module",
+  "main": "src/run-agent-engine.mjs",
+  "bin": {
+    "run-agent-engine": "./src/run-agent-engine.mjs",
+    "run-engine": "./src/run-engine.mjs"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "build": "node -e \"console.log('no build step')\"",
+    "test": "node --test tests/**/*.test.mjs"
+  },
+  "dependencies": {
+    "@winmatrix/agent-sdk": "^1.0.5",
+    "@winmatrix/protocol": "^1.0.5"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/blocked-args-filter.mjs

@@ -0,0 +1,95 @@
+/**
+ * D11.3: Blocked Args 过滤
+ *
+ * 用户或业务方可能通过 customArgs 传入 CLI 参数。
+ * 每种 PodEngineDriver 声明受协议保护的 blockedArgs，
+ * 在 launch 阶段从用户 customArgs 中移除匹配项并记入审计日志。
+ *
+ * 参考 Multica 的 filterCustomArgs() 设计，但增强为：
+ * - 被过滤参数不进入 fingerprint
+ * - 记入操作审计日志
+ */
+
+import { getEngineDriverConfig } from './engine-driver-config.mjs';
+
+/**
+ * 从用户 customArgs 中过滤 Engine 协议保护的参数
+ *
+ * @param {string} engineId - Engine 标识
+ * @param {string[]} customArgs - 用户传入的自定义参数
+ * @returns {{ filtered: string[], removed: string[] }}
+ *   filtered: 过滤后的安全参数列表
+ *   removed: 被移除的参数列表（用于审计）
+ */
+export function filterBlockedArgs(engineId, customArgs) {
+  if (!customArgs || !Array.isArray(customArgs) || customArgs.length === 0) {
+    return { filtered: [], removed: [] };
+  }
+
+  const config = getEngineDriverConfig(engineId);
+  const blockedArgs = config.blockedArgs;
+
+  if (blockedArgs.length === 0) {
+    return { filtered: [...customArgs], removed: [] };
+  }
+
+  const filtered = [];
+  const removed = [];
+
+  for (let i = 0; i < customArgs.length; i++) {
+    const arg = customArgs[i];
+
+    // 检查是否匹配 blocked arg
+    const matched = blockedArgs.some(blocked => {
+      // 精确匹配（如 --output-format）
+      if (arg === blocked) return true;
+      // --output-format=value 形式
+      if (arg.startsWith(blocked + '=')) return true;
+      return false;
+    });
+
+    if (matched) {
+      removed.push(arg);
+      // 检查这个参数是否需要下一个参数作为值
+      // 例如 --output-format stream-json，下一个 arg 是值
+      if (!arg.includes('=') && isValueArg(arg) && i + 1 < customArgs.length) {
+        i++;
+        removed.push(customArgs[i]);
+      }
+    } else {
+      filtered.push(arg);
+    }
+  }
+
+  return { filtered, removed };
+}
+
+/**
+ * 判断一个 CLI flag 是否需要后续值参数
+ * 大多数 --xxx 形式的 flag 都需要值
+ * @param {string} arg
+ * @returns {boolean}
+ */
+function isValueArg(arg) {
+  // 布尔 flag 不需要值
+  const booleanFlags = new Set([
+    '--verbose',
+    '--print',
+    '-p',
+    '--strict-mcp-config',
+    '--include-partial-messages',
+  ]);
+
+  return !booleanFlags.has(arg);
+}
+
+/**
+ * 格式化被过滤参数为审计日志消息
+ * @param {string[]} removed - 被移除的参数
+ * @param {string} engineId
+ * @returns {string}
+ */
+export function formatBlockedArgsAudit(removed, engineId) {
+  if (removed.length === 0) return '';
+  return `[blocked-args] engine=${engineId} filtered ${removed.length} args: ${removed.map(a => JSON.stringify(a)).join(', ')}`;
+}

package/src/claude-session-lib.mjs

@@ -0,0 +1,487 @@
+/**
+ * Claude Session 查询公共库（task 7.15）。
+ *
+ * 从 query-claude-sessions.mjs / query-claude-session-detail.mjs 抽出的纯函数，
+ * 供 run-agent-engine.mjs 的 session-* 子命令与（迁移过渡期）旧脚本共用。
+ *
+ * 设计约束：
+ * - 全部为纯函数（除 loadSdk / resolveDirViaGlobalListSessions 读 SDK / FS）；
+ * - 不输出 stdout、不读 process.argv——由调用方负责 argv 解析与输出；
+ * - 脱敏：所有 raw/preview 输出经 redactPreviewText / jsonReplacer 过滤敏感值。
+ */
+
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+
+export const TRUNCATE_LEN = 4096;
+export const REDACTED = '[REDACTED]';
+export const SENSITIVE_KEY_PATTERN =
+  /(authorization|password|passwd|pwd|secret|token|api[_-]?key|apikey|access[_-]?key|private[_-]?key|credential|session[_-]?key|jwt)/i;
+
+/** SDK 加载路径：优先 CLAUDE_AGENT_SDK_PATH，回退默认全局路径。 */
+export function resolveSdkPath(env = process.env) {
+  return (
+    env.CLAUDE_AGENT_SDK_PATH ||
+    '/home/node/.local/lib/node_modules/@anthropic-ai/claude-agent-sdk'
+  );
+}
+
+/**
+ * 加载 @anthropic-ai/claude-agent-sdk。失败返回 null（由调用方决定输出 error 形态）。
+ * @returns {{ sdk: object | null; error?: string }}
+ */
+export function loadSdk() {
+  const sdkPath = resolveSdkPath();
+  try {
+    return { sdk: require(sdkPath) };
+  } catch (e) {
+    return { sdk: null, error: `SDK 加载失败: ${e.message}` };
+  }
+}
+
+/* ── argv 解析（与旧脚本等价） ── */
+
+/** @param {string[]} argv @param {string} key */
+export function getOptValue(argv, key) {
+  const eqPrefix = key + '=';
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === key && argv[i + 1] != null) return argv[i + 1];
+    if (a.startsWith(eqPrefix)) return a.slice(eqPrefix.length);
+  }
+  return undefined;
+}
+
+/** @param {string[]} argv @param {string} flag */
+export function hasFlag(argv, flag) {
+  return argv.includes(flag);
+}
+
+/** @param {string} v @param {number} def @param {number} min @param {number} max */
+export function clampInt(v, def, min, max) {
+  const n = Number(v);
+  if (!Number.isFinite(n)) return def;
+  return Math.min(max, Math.max(min, Math.trunc(n)));
+}
+
+/** @param {string[]} argv @param {number} defaultVal @param {number} maxVal */
+export function parseLimit(argv, defaultVal, maxVal) {
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--limit=')) {
+      const n = Number(a.slice('--limit='.length));
+      return Math.min(maxVal, Math.max(1, Number.isFinite(n) ? n : defaultVal));
+    }
+    if (a === '--limit' && argv[i + 1] != null) {
+      const n = Number(argv[i + 1]);
+      return Math.min(maxVal, Math.max(1, Number.isFinite(n) ? n : defaultVal));
+    }
+  }
+  return Math.min(maxVal, defaultVal);
+}
+
+/* ── cursor 编解码（offset → 不透明 cursor，base64） ── */
+
+/**
+ * 将 offset 编码为不透明 cursor（base64(JSON)）。offset 默认 0 不产生 cursor。
+ * @param {number} offset
+ * @returns {string | undefined}
+ */
+export function encodeOffsetCursor(offset) {
+  if (!Number.isInteger(offset) || offset <= 0) return undefined;
+  return Buffer.from(JSON.stringify({ offset }), 'utf8').toString('base64');
+}
+
+/**
+ * 解码不透明 cursor 为 offset。非法/空 cursor 返回 0。
+ * @param {string | undefined} cursor
+ * @returns {number}
+ */
+export function decodeOffsetCursor(cursor) {
+  if (!cursor || typeof cursor !== 'string') return 0;
+  try {
+    const parsed = JSON.parse(Buffer.from(cursor, 'base64').toString('utf8'));
+    if (parsed && typeof parsed.offset === 'number' && Number.isFinite(parsed.offset)) {
+      return Math.max(0, Math.trunc(parsed.offset));
+    }
+  } catch {
+    // 非法 cursor 静默回退到 0
+  }
+  return 0;
+}
+
+/* ── 时间 / session 元数据 ── */
+
+/** @param {unknown} v */
+export function toIsoString(v) {
+  if (v == null) return undefined;
+  if (typeof v === 'number' && Number.isFinite(v)) {
+    const d = new Date(v);
+    return Number.isNaN(d.getTime()) ? undefined : d.toISOString();
+  }
+  if (typeof v === 'string') {
+    const d = new Date(v);
+    return Number.isNaN(d.getTime()) ? v : d.toISOString();
+  }
+  return undefined;
+}
+
+/** @param {Record<string, unknown>} session */
+export function lastActivityMs(session) {
+  const keys = [
+    'lastModified',
+    'last_modified',
+    'lastActivityAt',
+    'last_activity_at',
+    'updatedAt',
+    'updated_at',
+    'createdAt',
+    'created_at',
+  ];
+  for (const k of keys) {
+    const c = session[k];
+    if (typeof c === 'number' && Number.isFinite(c)) return c;
+    if (typeof c === 'string') {
+      const t = Date.parse(c);
+      if (!Number.isNaN(t)) return t;
+    }
+  }
+  return 0;
+}
+
+/**
+ * 从宽松 SDK session 记录构建结构化 SessionMeta（id/cwd/projectPath/...）。
+ * list 与 detail 共用；detail 额外带 fileSize。
+ * @param {Record<string, unknown>} session
+ */
+export function buildSessionMeta(session) {
+  const rawPath = session.projectPath ?? session.cwd;
+  const pathStr = rawPath != null ? String(rawPath).replace(/\/+$/, '') : undefined;
+  const cwdStr = session.cwd != null ? String(session.cwd).replace(/\/+$/, '') : pathStr;
+
+  const lastActivityAt =
+    toIsoString(session.lastActivityAt ?? session.last_activity_at) ??
+    toIsoString(session.updatedAt ?? session.updated_at) ??
+    toIsoString(session.lastModified ?? session.last_modified) ??
+    toIsoString(session.createdAt ?? session.created_at);
+
+  const createdAt = toIsoString(session.createdAt ?? session.created_at);
+
+  return {
+    id: session.id ?? session.sessionId,
+    cwd: cwdStr,
+    projectPath: pathStr,
+    projectName:
+      session.projectName != null
+        ? String(session.projectName)
+        : pathStr
+          ? pathStr.split('/').filter(Boolean).pop()
+          : undefined,
+    summary: session.summary != null ? String(session.summary) : undefined,
+    customTitle:
+      session.customTitle != null
+        ? String(session.customTitle)
+        : session.custom_title != null
+          ? String(session.custom_title)
+          : undefined,
+    firstPrompt:
+      session.firstPrompt != null
+        ? String(session.firstPrompt)
+        : session.first_prompt != null
+          ? String(session.first_prompt)
+          : undefined,
+    createdAt,
+    lastActivityAt,
+    messageCount:
+      typeof session.messageCount === 'number'
+        ? session.messageCount
+        : typeof session.numMessages === 'number'
+          ? session.numMessages
+          : undefined,
+    status: session.status != null ? String(session.status) : undefined,
+    gitBranch:
+      session.gitBranch != null
+        ? String(session.gitBranch)
+        : session.git_branch != null
+          ? String(session.git_branch)
+          : undefined,
+    tag: session.tag != null ? String(session.tag) : undefined,
+    fileSize:
+      typeof session.fileSize === 'number'
+        ? session.fileSize
+        : typeof session.file_size === 'number'
+          ? session.file_size
+          : undefined,
+  };
+}
+
+/* ── 消息抽取 / 脱敏 / diagnostics ── */
+
+/** 从 Claude API message.content 抽取纯文本块拼接。兼容字符串/数组两种形态。 */
+export function extractText(message) {
+  if (message == null) return '';
+  /** @type {unknown} */
+  let content = message;
+  if (typeof message === 'object' && message !== null && 'content' in message) {
+    content = /** @type {Record<string, unknown>} */ (message).content;
+  }
+
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+
+  const parts = [];
+  for (const block of content) {
+    if (block == null) continue;
+    if (typeof block === 'string') {
+      parts.push(block);
+      continue;
+    }
+    if (typeof block !== 'object') continue;
+    const b = /** @type {Record<string, unknown>} */ (block);
+    if (b.type === 'text' && typeof b.text === 'string') {
+      parts.push(b.text);
+    }
+  }
+  return parts.join('');
+}
+
+/** @param {unknown} message @returns {unknown[]} */
+export function extractContentBlocks(message) {
+  if (message == null) return [];
+  let content = message;
+  if (typeof message === 'object' && message !== null && 'content' in message) {
+    content = /** @type {Record<string, unknown>} */ (message).content;
+  }
+  if (typeof content === 'string') return [{ type: 'text', text: content }];
+  if (!Array.isArray(content)) return [];
+  return content;
+}
+
+/** JSON replacer：bigint 转字符串，敏感 key redact。 */
+export function jsonReplacer(_k, v) {
+  if (typeof v === 'bigint') return v.toString();
+  if (SENSITIVE_KEY_PATTERN.test(String(_k))) return REDACTED;
+  return v;
+}
+
+/** @param {unknown} messages @returns {{ list: unknown[]; ok: boolean }} */
+export function cloneMessagesForJson(messages) {
+  try {
+    return { list: JSON.parse(JSON.stringify(messages, jsonReplacer)), ok: true };
+  } catch {
+    return { list: [], ok: false };
+  }
+}
+
+/** @param {ReturnType<typeof buildSessionMeta>} sessionMeta @param {string} sessionIdArg */
+export function buildCliReplayGuide(sessionMeta, sessionIdArg, env = process.env) {
+  const agentHome = env.HOME?.trim() || '';
+  const projectPath =
+    (sessionMeta.projectPath && String(sessionMeta.projectPath)) ||
+    (sessionMeta.cwd && String(sessionMeta.cwd)) ||
+    '';
+  const sessionId = sessionMeta.id != null ? String(sessionMeta.id) : sessionIdArg;
+  const kubectlHome = agentHome || '<agentHome>';
+  const stepsZh = [
+    '使用与运行 agent 相同的 Linux 用户进入 Pod。',
+    agentHome
+      ? `export HOME="${agentHome}"`
+      : '在容器内执行 printenv HOME，再 export HOME=该值（须与查询此会话时一致）。',
+    `cd "${projectPath || '（见 projectPath）'}"`,
+    '运行 claude，应能看到该工程下的会话记录。',
+  ];
+  return {
+    agentHome: agentHome || undefined,
+    projectPath: projectPath || undefined,
+    sessionId,
+    stepsZh,
+    kubectlTemplate: `kubectl exec -it <pod> -n <ns> -- env HOME=${kubectlHome} bash -l`,
+    noteZh:
+      'Claude 会话数据位于 $HOME/.claude；数字人隔离时 HOME 常非 /home/node。HOME 或工程路径不一致则 CLI 看不到本会话。',
+  };
+}
+
+/** @param {string} s @param {boolean} noTruncate */
+export function maybeTruncate(s, noTruncate) {
+  if (noTruncate || s.length <= TRUNCATE_LEN) return { text: s, truncated: false };
+  return {
+    text: s.slice(0, TRUNCATE_LEN) + `\n…[truncated ${s.length - TRUNCATE_LEN} chars]`,
+    truncated: true,
+  };
+}
+
+/** @param {unknown} value @param {number} max */
+export function previewValue(value, max = 1000) {
+  let text = '';
+  if (typeof value === 'string') text = value;
+  else {
+    try {
+      text = JSON.stringify(value, jsonReplacer);
+    } catch {
+      text = String(value);
+    }
+  }
+  text = redactPreviewText(text);
+  return text.length > max ? text.slice(0, max) + `…[${text.length - max} chars]` : text;
+}
+
+/** @param {string} text */
+export function redactPreviewText(text) {
+  return text
+    .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]{20,}/gi, 'Bearer [REDACTED]')
+    .replace(/\b(?:eyJ[A-Za-z0-9_-]{10,})\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, REDACTED)
+    .replace(/\bsk-[A-Za-z0-9_-]{16,}\b/g, REDACTED)
+    .replace(/\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g, REDACTED)
+    .replace(
+      /((?:authorization|password|passwd|pwd|secret|token|api[_-]?key|apikey|access[_-]?key|private[_-]?key|credential|session[_-]?key|jwt)\s*[:=]\s*)(["']?)[^\s"',}\]]+/gi,
+      `$1$2${REDACTED}`,
+    )
+    .replace(
+      /((?:postgres|postgresql|mysql|redis|mongodb):\/\/[^:\s/@]+:)([^@\s]+)(@)/gi,
+      `$1${REDACTED}$3`,
+    );
+}
+
+/** @param {string} text */
+export function extractFileReferences(text) {
+  const matches = text.match(/(?:\/[^\s"'`<>|]+(?:\/[^\s"'`<>|]+)+|[A-Za-z]:\\[^\s"'`<>|]+)/g) ?? [];
+  return matches
+    .map((v) => v.replace(/[),.;，。；]+$/g, ''))
+    .filter((v) => v.length >= 4);
+}
+
+/**
+ * 构建 diagnostics 富字段（messageStats / latestAssistantText / assistantTail /
+ * toolCalls / toolResults / fileReferences / timeline）。供 detail metadata 透传。
+ * @param {unknown[]} messages
+ * @param {boolean} noTruncate
+ */
+export function buildDiagnostics(messages, noTruncate) {
+  const stats = {
+    total: messages.length,
+    user: 0,
+    assistant: 0,
+    system: 0,
+    toolUse: 0,
+    toolResult: 0,
+    errorToolResult: 0,
+  };
+  const toolCalls = [];
+  const toolResults = [];
+  const timeline = [];
+  const assistantTail = [];
+  const fileRefs = new Set();
+  let latestAssistantText = '';
+
+  for (let i = 0; i < messages.length; i += 1) {
+    const m = messages[i];
+    if (m == null || typeof m !== 'object') continue;
+    const rec = /** @type {Record<string, unknown>} */ (m);
+    const message = rec.message;
+    const messageRole =
+      message && typeof message === 'object' && 'role' in message
+        ? String(/** @type {Record<string, unknown>} */ (message).role ?? '')
+        : '';
+    const role = String(rec.type ?? messageRole ?? 'unknown');
+    if (role === 'user') stats.user += 1;
+    else if (role === 'assistant') stats.assistant += 1;
+    else if (role === 'system') stats.system += 1;
+
+    const text = extractText(message);
+    if (text) {
+      for (const p of extractFileReferences(text)) fileRefs.add(p);
+      if (role === 'assistant') {
+        latestAssistantText = text;
+        assistantTail.push(previewValue(text, 1200));
+        if (assistantTail.length > 5) assistantTail.shift();
+      }
+    }
+
+    let messageToolUse = 0;
+    let messageToolResult = 0;
+    for (const block of extractContentBlocks(message)) {
+      if (block == null || typeof block !== 'object') continue;
+      const b = /** @type {Record<string, unknown>} */ (block);
+      if (b.type === 'tool_use') {
+        stats.toolUse += 1;
+        messageToolUse += 1;
+        if (toolCalls.length < 80) {
+          toolCalls.push({
+            index: i,
+            id: b.id != null ? String(b.id) : undefined,
+            name: b.name != null ? String(b.name) : undefined,
+            inputPreview: previewValue(b.input, 1200),
+          });
+        }
+        for (const p of extractFileReferences(previewValue(b.input, 2000))) fileRefs.add(p);
+      } else if (b.type === 'tool_result') {
+        stats.toolResult += 1;
+        messageToolResult += 1;
+        const isError = b.is_error === true || b.isError === true;
+        if (isError) stats.errorToolResult += 1;
+        const preview = previewValue(b.content, 1400);
+        if (toolResults.length < 80 && (isError || toolResults.length < 20)) {
+          toolResults.push({
+            index: i,
+            toolUseId: b.tool_use_id != null ? String(b.tool_use_id) : undefined,
+            isError,
+            preview,
+          });
+        }
+        for (const p of extractFileReferences(preview)) fileRefs.add(p);
+      }
+    }
+
+    if (timeline.length < 120) {
+      timeline.push({
+        index: i,
+        role,
+        textPreview: text ? previewValue(text, noTruncate ? 2000 : 500) : undefined,
+        toolUseCount: messageToolUse || undefined,
+        toolResultCount: messageToolResult || undefined,
+      });
+    }
+  }
+
+  return {
+    messageStats: stats,
+    latestAssistantText: previewValue(
+      maybeTruncate(latestAssistantText, noTruncate).text,
+      noTruncate ? 8000 : TRUNCATE_LEN,
+    ),
+    assistantTail,
+    toolCalls,
+    toolResults,
+    fileReferences: Array.from(fileRefs).slice(0, 80),
+    timeline,
+  };
+}
+
+/**
+ * SDK：listSessions() 不传 dir 时会列举所有项目。可在 session 元数据路径「差一点」时
+ * 用其全局列表里的 cwd 重试加载消息。
+ * @param {object} sdkMod
+ * @param {string} sid
+ * @returns {Promise<string | undefined>}
+ */
+export async function resolveDirViaGlobalListSessions(sdkMod, sid) {
+  if (typeof sdkMod.listSessions !== 'function') return undefined;
+  try {
+    const list = await sdkMod.listSessions({ limit: 800 });
+    if (!Array.isArray(list)) return undefined;
+    for (const entry of list) {
+      if (entry == null || typeof entry !== 'object') continue;
+      const rec = /** @type {Record<string, unknown>} */ (entry);
+      const eid = rec.sessionId ?? rec.id;
+      if (eid == null || String(eid) !== String(sid)) continue;
+      const cwd = rec.cwd;
+      if (cwd != null && String(cwd).trim() !== '') {
+        return String(cwd).replace(/\/+$/, '');
+      }
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}