carlos-flow 2.6.2 → 2.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/index.js CHANGED
@@ -2,13 +2,14 @@
2
2
  // Carlos 工作流的机械门禁工具集(留痕 / 派发 / 裁定 / 审计 / 快照还原计划)。
3
3
  // 重要:stdout 是 MCP 传输通道,所有日志一律走 stderr。
4
4
  import { spawnSync } from "node:child_process";
5
+ import path from "node:path";
5
6
  import { createServer, connect } from "node:net";
6
7
  import { Server } from "@modelcontextprotocol/sdk/server/index.js";
7
8
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
8
9
  import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
9
10
  import { PROTOCOL } from "./protocol.js";
10
11
  import { parseCard, validateCard, riskTier, isSensitive } from "./card.js";
11
- import { loadState, saveState, defaultState, audit, readAudit, getUserMessages, writeUserMessage, pathExists, gitHead, isStale, isBypassed, verifyAuditChain, withStateLock } from "./state.js";
12
+ import { loadState, saveState, defaultState, audit, readAudit, getUserMessages, writeUserMessage, pathExists, gitHead, isStale, isBypassed, verifyAuditChain, withStateLock, auditHashMode } from "./state.js";
12
13
  import { buildContractPrompt, snapshotFiles, readManifest, readManifestAll, writeDispatchPrompt, saveAgentResult, runVerifyCommand, enforceScope, MAX_DISPATCH } from "./dispatch.js";
13
14
 
14
15
  const log = (msg) => {
@@ -21,7 +22,19 @@ const log = (msg) => {
21
22
 
22
23
  // ---- 通用工具函数 ----------------------------------------------------------
23
24
 
24
- const ok = (obj) => ({ content: [{ type: "text", text: JSON.stringify(obj, null, 2) }] });
25
+ // 成功响应:统一注入 ok:true。
26
+ //
27
+ // 之前各工具的 payload 有的显式写 \`ok: true\`、有的没写(如 flow_audit),
28
+ // 于是调用方拿到手的心智模型不一致 —— 想判断成败只能逐个工具记「这个有没有 ok」。
29
+ // 现在由 ok() 统一注入:
30
+ // · payload 里没有 ok 字段 → 补上 ok:true
31
+ // · payload 里已有 ok 字段 → 保留原值(不改 ok:false 的语义)
32
+ // 这是**增量兼容**:现有调用方读取 total / events / by_type 等字段不受影响。
33
+ const ok = (obj) => {
34
+ const payload = obj && typeof obj === "object" && !Array.isArray(obj) ? obj : { value: obj };
35
+ const withOk = "ok" in payload ? payload : { ok: true, ...payload };
36
+ return { content: [{ type: "text", text: JSON.stringify(withOk, null, 2) }] };
37
+ };
25
38
  const fail = (message) => ({ content: [{ type: "text", text: "ERROR: " + String(message) }], isError: true });
26
39
 
27
40
  const asStringArray = (v) => (Array.isArray(v) ? v.map((x) => String(x)) : []);
@@ -301,7 +314,6 @@ const TOOLS = [
301
314
  properties: {
302
315
  sessionId: { type: "string", description: "会话 ID,默认 unknown" },
303
316
  role: { type: "string", enum: ["executor", "auditor"], description: "领取角色" },
304
- cwd: { type: "string", description: "工作目录,默认 process.cwd()" },
305
317
  },
306
318
  },
307
319
  handler: async (args) => {
@@ -419,6 +431,25 @@ const TOOLS = [
419
431
  const entries = snapshotFiles(sessionId, scope, cwd);
420
432
  audit("run", sessionId, { kind: "snapshot", role, files: scope.length, ok: true });
421
433
 
434
+ // Phase 1-1: 记录「派发前基线」。
435
+ //
436
+ // 为什么是记录而不是当场阻断:
437
+ // 派发这一刻,子 Agent **还没动手** —— 它之后会改哪些文件根本无从得知。
438
+ // 此时跑 git diff 得到的是「用户自己已有的未提交改动」,
439
+ // 拿它当越界拦下来会**误伤正常用法**(用户本来就在改这些文件)。
440
+ //
441
+ // 正确的时机是**裁定前**:用「当前改动 - 派发基线」算出**本次执行引入的**
442
+ // 改动,再与卡片 scope 比对 —— 这才是「越界直接阻断」的真实落点,
443
+ // 阻断的是「越界之后仍然拿到 PASS」这个闭环。
444
+ const baseline = enforceScope(scope, cwd);
445
+ state.dispatch_baseline = Array.isArray(baseline.checked) ? baseline.checked : [];
446
+ saveState(sessionId, state);
447
+ audit("run", sessionId, {
448
+ kind: "dispatch_baseline",
449
+ role,
450
+ files: state.dispatch_baseline.length,
451
+ });
452
+
422
453
  if (a.run === true) {
423
454
  // 写入 prompt 文件,供主 Agent 读取后通过 subagent 工具派发
424
455
  const { file } = writeDispatchPrompt(sessionId, role, prompt, cwd);
@@ -545,6 +576,36 @@ const TOOLS = [
545
576
  return fail("已有的验证结果对应的命令与当前卡片的 verify.cmd 不一致,不能记录 PASS 裁定。" +
546
577
  "请对当前卡片重新执行 flow_run_verify,再记录裁定。");
547
578
  }
579
+
580
+ // 防假闭环之四:越界改动必须被拦住。
581
+ //
582
+ // 「越界直接阻断」的**真实落点**在这里:判定「本次执行有没有改到
583
+ // scope 之外的文件」,而不是「派发前工作区干不干净」。
584
+ //
585
+ // 做法:拿「当前 git 改动清单」减去「派发时记录的基线」,
586
+ // 剩下的就是**本次执行引入的**改动 —— 用户自己原有的未提交改动
587
+ // 不会被误判为越界。
588
+ //
589
+ // 无基线(未走过 flow_dispatch)时退化为「全量改动」判定:
590
+ // 此时没有参照点,用全量更保守(fail-closed)。
591
+ const scopeNow = Array.isArray(state.card.scope) ? state.card.scope : [];
592
+ const current = enforceScope(scopeNow, a.cwd || process.cwd());
593
+ const baseline = Array.isArray(state.dispatch_baseline) ? state.dispatch_baseline : [];
594
+ const baselineSet = new Set(baseline.map((f) => path.normalize(f)));
595
+ const introduced = (current.checked || []).filter((f) => !baselineSet.has(path.normalize(f)));
596
+ const scopeCheck = enforceScope(scopeNow, a.cwd || process.cwd(), introduced);
597
+ if (!scopeCheck.ok) {
598
+ audit("decision", sessionId, {
599
+ kind: "scope_violation",
600
+ reason: "越界改动",
601
+ violations: scopeCheck.violations,
602
+ introduced: introduced.length,
603
+ });
604
+ return fail("检测到越界改动,不能记录 PASS 裁定:" +
605
+ (scopeCheck.violations || []).join(", ") +
606
+ "。这些文件不在卡片 scope 白名单内。" +
607
+ "请把越界文件加入 scope(重新提交任务卡)后重试,或先撤销这些改动。");
608
+ }
548
609
  }
549
610
 
550
611
  const findings = [];
@@ -654,7 +715,7 @@ const TOOLS = [
654
715
  chainResult = verifyAuditChain(opts);
655
716
  }
656
717
 
657
- return ok({ total: rows.length, by_type, by_kind, events: rows, chain: chainResult });
718
+ return ok({ total: rows.length, by_type, by_kind, events: rows, chain: chainResult, mode: auditHashMode() });
658
719
  } catch (e) {
659
720
  return fail(e && e.message ? e.message : String(e));
660
721
  }
@@ -847,7 +908,6 @@ const TOOLS = [
847
908
  type: "object",
848
909
  properties: {
849
910
  sessionId: { type: "string", description: "会话 ID,默认 unknown" },
850
- cwd: { type: "string", description: "工作目录,默认 process.cwd()" },
851
911
  },
852
912
  },
853
913
  handler: async (args) => {
@@ -946,9 +1006,13 @@ const TOOLS = [
946
1006
 
947
1007
  const scope = Array.isArray(state.card.scope) ? state.card.scope : [];
948
1008
  const paths = Array.isArray(a.paths) ? a.paths : [];
949
- const result = enforceScope(scope, a.paths, a.cwd);
1009
+ // 不传 paths → 自动跑 `git diff --name-only` 取当前实际改动清单。
1010
+ // 传了 paths → 用调用方给的清单(自查场景)。
1011
+ const result = paths.length
1012
+ ? enforceScope(scope, a.cwd, paths)
1013
+ : enforceScope(scope, a.cwd);
950
1014
 
951
- return ok({ ok: result.ok, scope, checked: a.paths, ...result });
1015
+ return ok({ ok: result.ok, scope, checked: paths.length ? paths : result.checked || [], ...result });
952
1016
  } catch (e) {
953
1017
  return fail(e && e.message ? e.message : String(e));
954
1018
  }
@@ -1073,7 +1137,6 @@ const TOOLS = [
1073
1137
  const tier = riskTier(card.scope);
1074
1138
  const withLock = withStateLock(sessionId, () => {
1075
1139
  const prev = loadState(sessionId);
1076
- const wasActivated = prev.activation_activated === true;
1077
1140
  const state = {
1078
1141
  ...defaultState(),
1079
1142
  ...prev,
@@ -1129,20 +1192,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
1129
1192
  tools: TOOLS.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
1130
1193
  }));
1131
1194
 
1132
- server.setRequestHandler(CallToolRequestSchema, async (request) => {
1133
- const t = TOOLS.find((x) => x.name === request.params.name);
1134
- if (!t) {
1135
- return { content: [{ type: "text", text: "Unknown tool: " + request.params.name }], isError: true };
1136
- }
1137
- try {
1138
- return await t.handler(request.params.arguments || {});
1139
- } catch (e) {
1140
- return {
1141
- content: [{ type: "text", text: "ERROR: " + (e && e.message ? e.message : String(e)) }],
1142
- isError: true,
1143
- };
1144
- }
1145
- });
1195
+ // ⚠️ 这里曾经**重复注册**过一次 CallToolRequestSchema(另一个不带参数校验的版本)。
1196
+ // MCP SDK 的 setRequestHandler 用 Map.set → 后注册的覆盖先注册的,
1197
+ // 于是先注册的那个(含约 17 行)**永远不会执行** —— 当前行为是对的,
1198
+ // 但它靠的是「注册顺序」这种隐式约定:任何一次重排或插入都会静默
1199
+ // 丢掉参数校验(required 字段 / 类型 / enum 全部失效)。
1200
+ // 现在只保留下面那一个带 validateToolArgs 的注册。
1201
+ //
1202
+ // check:no-dead-handler 门禁会统计同一 schema 的注册次数,>1 即红。
1146
1203
 
1147
1204
  // ---- Phase 1-1: 工具参数校验器(required 字段 / 类型 / enum)----
1148
1205
  function validateToolArgs(toolName, args) {
package/src/state.js CHANGED
@@ -3,7 +3,7 @@ import fs from "node:fs";
3
3
  import path from "node:path";
4
4
  import os from "node:os";
5
5
  import { spawnSync } from "node:child_process";
6
- import { createHash } from "node:crypto";
6
+ import { createHash, createHmac } from "node:crypto";
7
7
 
8
8
 
9
9
  // 展开路径里的 `~`(家目录)。
@@ -91,8 +91,47 @@ export function sanitizeId(s) {
91
91
  return v;
92
92
  }
93
93
 
94
+ // 当前状态文件结构版本号。
95
+ // 改动 defaultState() 的**字段结构**时,必须 +1 并在 migrate() 里加一条迁移。
96
+ export const CURRENT_SCHEMA_VERSION = 1;
97
+
98
+ /**
99
+ * 迁移旧版本的状态文件。
100
+ *
101
+ * 逐版本迁移,每一步都只处理「从 vN 到 vN+1」的差异,
102
+ * 保证任何历史版本都能一路迁到当前版本(不跳步)。
103
+ *
104
+ * v0 → v1:最早的版本没有 schemaVersion 字段(等于 v0)。
105
+ * · 补上 schemaVersion
106
+ * · dispatch_baseline 早期不存在 → 补空数组(无基线时裁定走全量判定,更保守)
107
+ */
108
+ export function migrate(parsed) {
109
+ if (!parsed || typeof parsed !== "object") return parsed;
110
+ let v = Number(parsed.schemaVersion);
111
+ if (!Number.isInteger(v) || v < 0) v = 0; // 无版本号 → 当作 v0
112
+ const out = { ...parsed };
113
+
114
+ if (v < 1) {
115
+ // v0 → v1
116
+ if (!Array.isArray(out.dispatch_baseline)) out.dispatch_baseline = [];
117
+ if (!Array.isArray(out.activation_pending)) out.activation_pending = [];
118
+ if (typeof out.activation_activated !== "boolean") out.activation_activated = false;
119
+ v = 1;
120
+ }
121
+
122
+ out.schemaVersion = CURRENT_SCHEMA_VERSION;
123
+ return out;
124
+ }
125
+
94
126
  export function defaultState() {
95
127
  return {
128
+ // 状态文件结构版本号。
129
+ // 为什么需要:早先靠 {...defaultState(), ...parsed} 做防御性合并,
130
+ // 但**没有版本号** —— 将来改字段名(如 bypass_ts → bypass_at)时,
131
+ // 老用户的 state.json 里那个旧字段会被当成「未知字段」静默丢弃,
132
+ // 表现为「免检没清零」「待补项丢失」这类**很难定位**的退化。
133
+ // 加了版本号 + migrate(),旧状态会被**显式迁移**而不是静默降级。
134
+ schemaVersion: CURRENT_SCHEMA_VERSION,
96
135
  card: null,
97
136
  card_ts: 0,
98
137
  tier: "read_only",
@@ -114,6 +153,11 @@ export function defaultState() {
114
153
  // 闸门状态由「卡片内容 + 此标记」幂等派生,不再依赖上一轮的 pending 传递,
115
154
  // 这样跨进程并发写入也不会出现「卡片为空却 pending=[]」的矛盾组合。
116
155
  activation_activated: false,
156
+ // 派发时记录的工作区改动基线(文件路径数组)。
157
+ // 用途:裁定前用「当前改动 - 基线」算出**本次执行引入的**改动,
158
+ // 再与卡片 scope 比对 —— 这样既能拦住越界,又不会把用户自己原有的
159
+ // 未提交改动误判为越界。没有基线时退化为全量判定(更保守,fail-closed)。
160
+ dispatch_baseline: [],
117
161
  };
118
162
  }
119
163
 
@@ -122,7 +166,7 @@ export function loadState(sid) {
122
166
  const file = path.join(RUNS_DIR, sanitizeId(sid), "state.json");
123
167
  const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
124
168
  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return defaultState();
125
- return { ...defaultState(), ...parsed };
169
+ return { ...defaultState(), ...migrate(parsed) };
126
170
  } catch {
127
171
  return defaultState();
128
172
  }
@@ -239,6 +283,37 @@ function auditPayload(rec) {
239
283
  return JSON.stringify(out);
240
284
  }
241
285
 
286
+ // ---- 审计链哈希模式 ----
287
+ //
288
+ // 裸 SHA-256 哈希链能防的是「**意外**损坏」(截断、位翻转、误删),
289
+ // **防不了有意篡改**:攻击者能读文件,就能重算整条链。
290
+ //
291
+ // 因此提供两种模式:
292
+ // · hmac —— 设置了 CARLOS_FLOW_AUDIT_KEY 时使用带密钥的 HMAC-SHA256。
293
+ // 攻击者没有密钥 → 重算不出正确 hash → 篡改必被发现。
294
+ // · plain —— 未设置密钥时的降级模式(裸 SHA-256),**在 verify 结果里
295
+ // 显式标注 mode**,让调用方知道自己拿到的是哪种保证。
296
+ //
297
+ // 不做「默认启用 HMAC」:没有密钥就签不了名,用户第一次用就会报错。
298
+ // 也不做「假装 HMAC」:plain 模式必须诚实地说自己只是弱保证。
299
+ const AUDIT_KEY = (() => {
300
+ const k = process.env.CARLOS_FLOW_AUDIT_KEY;
301
+ return typeof k === "string" && k.length >= 16 ? k : null;
302
+ })();
303
+
304
+ export function auditHashMode() {
305
+ return AUDIT_KEY ? "hmac" : "plain";
306
+ }
307
+
308
+ // 计算一条记录的 hash(写入与校验必须用同一套函数,否则永远对不上)
309
+ function computeAuditHash(rec, prev) {
310
+ const payload = rec.ts + rec.type + rec.sessionID + auditPayload(rec) + prev;
311
+ if (AUDIT_KEY) {
312
+ return createHmac("sha256", AUDIT_KEY).update(payload).digest("hex");
313
+ }
314
+ return createHash("sha256").update(payload).digest("hex");
315
+ }
316
+
242
317
  // 追加审计行;永不抛错,失败仅写 stderr;返回记录对象
243
318
  export function audit(type, sid, fields = {}) {
244
319
  const rec = {
@@ -253,9 +328,7 @@ export function audit(type, sid, fields = {}) {
253
328
  // 前驱 hash 取自目标文件尾部 → 与进程数无关,切换状态目录也不会断链
254
329
  const prev = lastHashOf(file);
255
330
  rec.prevHash = prev;
256
- rec.hash = createHash("sha256")
257
- .update(rec.ts + rec.type + rec.sessionID + auditPayload(rec) + prev)
258
- .digest("hex");
331
+ rec.hash = computeAuditHash(rec, prev);
259
332
  // 单次 appendFileSync:O_APPEND 语义,多进程并发写不会互相截断
260
333
  fs.appendFileSync(file, JSON.stringify(rec) + "\n", "utf8");
261
334
  } catch (e) {
@@ -269,12 +342,15 @@ export function audit(type, sid, fields = {}) {
269
342
  // 校验审计链完整性(可选:需完整文件,不能只看尾部)
270
343
  export function verifyAuditChain(opts = {}) {
271
344
  const rawDate = typeof opts.date === "string" && /^\d{4}-\d{2}-\d{2}$/.test(opts.date) ? opts.date : localDate();
272
- const file = path.join(AUDIT_DIR, `${localDate()}.jsonl`);
345
+ // ⚠️ 必须用 rawDate(而不是 localDate())—— 否则 opts.date 完全失效:
346
+ // 传 date='2020-01-01' 读的仍是**今天**的文件,调用方以为在查历史、
347
+ // 实际拿到今天的数据(错而不报,最难发现)。
348
+ const file = path.join(AUDIT_DIR, `${rawDate}.jsonl`);
273
349
  let raw = "";
274
350
  try {
275
351
  raw = fs.readFileSync(file, "utf8");
276
352
  } catch {
277
- return { ok: true, total: 0, broken: 0, legacy: 0, brokenAt: [], file };
353
+ return { ok: true, total: 0, broken: 0, legacy: 0, brokenAt: [], file, mode: auditHashMode() };
278
354
  }
279
355
  let prev = "0".repeat(64);
280
356
  let total = 0;
@@ -292,27 +368,35 @@ export function verifyAuditChain(opts = {}) {
292
368
  }
293
369
  total++;
294
370
  if (typeof r.hash !== "string") {
371
+ // 旧格式记录(无 hash)→ 计入 legacy 计数,但**不重置链起点**。
372
+ //
373
+ // 早先这里写的是 prev = "0".repeat(64),于是**一条**旧记录就会让
374
+ // 它之后所有记录的 prevHash 全部对不上 → 全判 broken。
375
+ // 后果:v2.5 升级上来的用户,审计链校验会长期报红,
376
+ // 而 README 把「可验证审计链」列为核心能力 —— 用户会以为自己的
377
+ // 审计记录被篡改了。**漏报比误报可接受,误报更伤信任。**
295
378
  legacy++;
296
- prev = "0".repeat(64);
297
379
  continue;
298
380
  }
299
- const expect = createHash("sha256")
300
- .update(r.ts + r.type + r.sessionID + auditPayload(r) + prev)
301
- .digest("hex");
381
+ const expect = computeAuditHash(r, prev);
302
382
  if (expect !== r.hash || r.prevHash !== prev) {
303
383
  broken++;
304
384
  if (brokenAt.length < 10) brokenAt.push({ ts: r.ts, type: r.type, kind: r.kind });
305
385
  }
306
386
  prev = r.hash;
307
387
  }
308
- return { ok: broken === 0, total, broken, legacy, brokenAt, file };
388
+ // mode 字段说明本次校验的**保证强度**:
389
+ // hmac → 带密钥(CARLOS_FLOW_AUDIT_KEY),能发现有意篡改
390
+ // plain → 裸 SHA-256,只能发现意外损坏(攻击者能重算整条链)
391
+ return { ok: broken === 0, total, broken, legacy, brokenAt, file, mode: auditHashMode() };
309
392
  }
310
393
 
311
394
  export function readAudit(opts = {}) {
312
395
  const { sessionId, type, limit } = opts;
313
396
  const rawDate = typeof opts.date === "string" && /^\d{4}-\d{2}-\d{2}$/.test(opts.date) ? opts.date : localDate();
314
397
  try {
315
- const file = path.join(AUDIT_DIR, `${localDate()}.jsonl`);
398
+ // ⚠️ 必须用 rawDate(而不是 localDate())—— 否则 opts.date 完全失效。
399
+ const file = path.join(AUDIT_DIR, `${rawDate}.jsonl`);
316
400
  const raw = fs.readFileSync(file, "utf8");
317
401
  const out = [];
318
402
  for (const line of raw.split("\n")) {