dsh-any-agent 0.4.0 → 0.5.1

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.
Files changed (46) hide show
  1. package/CHANGELOG.md +80 -0
  2. package/DESIGN.md +9 -0
  3. package/README.md +49 -676
  4. package/README.zh.md +45 -690
  5. package/USAGE-NOTES.en.md +4 -3
  6. package/USAGE-NOTES.md +4 -3
  7. package/bin/dsh-any-agent.mjs +66 -2
  8. package/demo/mcp-client.mjs +130 -0
  9. package/demo/run.mjs +326 -0
  10. package/demo/transcript.json +47 -0
  11. package/docs/brand/README.md +58 -0
  12. package/docs/brand/header.jpg +0 -0
  13. package/docs/en/architecture.md +43 -0
  14. package/docs/en/compatibility.md +51 -0
  15. package/docs/en/demo.md +90 -0
  16. package/docs/en/install.md +257 -0
  17. package/docs/en/limits.md +27 -0
  18. package/docs/en/locking.md +24 -0
  19. package/docs/en/reference.md +42 -0
  20. package/docs/en/release.md +33 -0
  21. package/docs/en/security.md +66 -0
  22. package/docs/en/team.md +74 -0
  23. package/docs/en/tests.md +97 -0
  24. package/docs/en/usage.md +78 -0
  25. package/docs/zh/architecture.md +43 -0
  26. package/docs/zh/compatibility.md +49 -0
  27. package/docs/zh/demo.md +90 -0
  28. package/docs/zh/install.md +274 -0
  29. package/docs/zh/limits.md +30 -0
  30. package/docs/zh/locking.md +24 -0
  31. package/docs/zh/reference.md +42 -0
  32. package/docs/zh/release.md +38 -0
  33. package/docs/zh/security.md +66 -0
  34. package/docs/zh/team.md +71 -0
  35. package/docs/zh/tests.md +96 -0
  36. package/docs/zh/usage.md +76 -0
  37. package/package.json +5 -1
  38. package/scripts/check-release.mjs +73 -0
  39. package/src/config.mjs +90 -23
  40. package/src/host.mjs +1 -1
  41. package/src/hub.mjs +423 -69
  42. package/src/ids.mjs +21 -0
  43. package/src/mcp.mjs +15 -7
  44. package/src/redact.mjs +34 -0
  45. package/src/review.mjs +199 -0
  46. package/src/tools.mjs +184 -12
package/src/hub.mjs CHANGED
@@ -17,7 +17,9 @@ import {
17
17
  copyFileSync,
18
18
  cpSync,
19
19
  mkdirSync,
20
+ mkdtempSync,
20
21
  readFileSync,
22
+ realpathSync,
21
23
  writeFileSync,
22
24
  existsSync,
23
25
  renameSync,
@@ -25,13 +27,15 @@ import {
25
27
  rmSync,
26
28
  readdirSync,
27
29
  } from 'node:fs';
28
- import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
30
+ import { dirname, isAbsolute, join, parse, resolve, sep } from 'node:path';
29
31
  import { homedir, tmpdir } from 'node:os';
30
32
  import { spawnSync } from 'node:child_process';
31
33
  import {
34
+ ALLOW_FULL_ACCESS,
32
35
  APPROVAL_POLICIES,
33
36
  DEFAULT_PERMISSION,
34
37
  DEFAULT_REASONING_EFFORT,
38
+ DEFAULT_REVIEW,
35
39
  IDLE_TTL_MS,
36
40
  LIST_PROBE_TTL_MS,
37
41
  MAX_LIVE,
@@ -40,6 +44,8 @@ import {
40
44
  PROMPT_TIMEOUT_MS,
41
45
  REAP_INTERVAL_MS,
42
46
  REASONING_EFFORTS,
47
+ REVIEWS_DIR,
48
+ REVIEW_MODES,
43
49
  RUNS_DIR,
44
50
  SENTINEL_INCLUDE_REASONING,
45
51
  SENTINEL_TTL_MS,
@@ -51,6 +57,16 @@ import {
51
57
  assertWritableDir,
52
58
  defaultApprovalPolicy,
53
59
  } from './config.mjs';
60
+ import {
61
+ REVIEW_VERDICTS,
62
+ buildReviewTicket,
63
+ normalizeReviewMode,
64
+ readReviewRecord,
65
+ reviewIdForRun,
66
+ writeReviewRecord,
67
+ } from './review.mjs';
68
+ import { sanitizeApprovalContext } from './redact.mjs';
69
+ import { assertSafeId } from './ids.mjs';
54
70
  import { AcpProcess } from './acp.mjs';
55
71
  import { SessionHost } from './host.mjs';
56
72
  import { rssMb } from './procstat.mjs';
@@ -175,6 +191,46 @@ const MAX_RUNS = 20;
175
191
  /** 回合记录里 prompt 预览的长度。 */
176
192
  const MAX_RUN_PREVIEW = 200;
177
193
 
194
+ /**
195
+ * 清掉 `dir` 下超过 TTL 的文件与空会话目录;`.tmp` 残留不论年龄都按同一 cutoff 清。
196
+ * 只遍历一层会话目录,绝不递归进别处 —— 调用方(哨兵/审核目录)都是本服务自己的。
197
+ */
198
+ function pruneDirTree(dir, ttlMs) {
199
+ if (!ttlMs || !existsSync(dir)) return { pruned: 0, dirs_removed: 0 };
200
+ let pruned = 0;
201
+ let dirsRemoved = 0;
202
+ const cutoff = Date.now() - ttlMs;
203
+ try {
204
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
205
+ if (!entry.isDirectory()) continue;
206
+ const sub = join(dir, entry.name);
207
+ for (const f of readdirSync(sub, { withFileTypes: true })) {
208
+ if (!f.isFile()) continue;
209
+ const fp = join(sub, f.name);
210
+ try {
211
+ if (statSync(fp).mtimeMs < cutoff) {
212
+ rmSync(fp, { force: true });
213
+ pruned++;
214
+ }
215
+ } catch {
216
+ /* 单个文件失败就跳过 */
217
+ }
218
+ }
219
+ try {
220
+ if (readdirSync(sub).length === 0) {
221
+ rmSync(sub, { recursive: true, force: true });
222
+ dirsRemoved++;
223
+ }
224
+ } catch {
225
+ /* 目录清理失败无所谓 */
226
+ }
227
+ }
228
+ } catch {
229
+ /* 目录读不了就跳过 */
230
+ }
231
+ return { pruned, dirs_removed: dirsRemoved };
232
+ }
233
+
178
234
  /** 按 ACP 权限应答的规范形状挑选项。 */
179
235
  function pickOption(options, want) {
180
236
  const list = Array.isArray(options) ? options : [];
@@ -182,26 +238,6 @@ function pickOption(options, want) {
182
238
  return match?.optionId;
183
239
  }
184
240
 
185
- /** Only expose review context in memory; redact common credential fields and literals. */
186
- function sanitizeApprovalContext(value, key = '') {
187
- if (/^(?:api[_-]?key|authorization|proxy[_-]?authorization|cookie|set[_-]?cookie|password|passwd|secret|token|access[_-]?token|refresh[_-]?token|credentials?|headers|env|environment)$/i.test(key)) {
188
- return '[REDACTED]';
189
- }
190
- if (typeof value === 'string') {
191
- return value
192
- .replace(/\b(?:sk|ak)-[A-Za-z0-9_-]{8,}/g, '[REDACTED]')
193
- .replace(/\bBearer\s+[^\s'";]+/gi, 'Bearer [REDACTED]')
194
- .replace(/((?:api[_-]?key|password|passwd|secret|(?:access[_-]?)?token)\s*(?:=|:)\s*)(?:"[^"\r\n]*"|'[^'\r\n]*'|[^\s;]+)/gi, '$1[REDACTED]')
195
- .replace(/(--(?:api[_-]?key|password|passwd|secret|token)\s+)(?:"[^"\r\n]*"|'[^'\r\n]*'|[^\s;]+)/gi, '$1[REDACTED]')
196
- .replace(/(https?:\/\/)[^\s/@]+:[^\s/@]+@/gi, '$1[REDACTED]@');
197
- }
198
- if (Array.isArray(value)) return value.map((item) => sanitizeApprovalContext(item));
199
- if (value && typeof value === 'object') {
200
- return Object.fromEntries(Object.entries(value).map(([name, item]) => [name, sanitizeApprovalContext(item, name)]));
201
- }
202
- return value ?? null;
203
- }
204
-
205
241
  function approvalContext(params, toolCall, desc, options) {
206
242
  const input = toolCall.rawInput ?? toolCall.input ?? null;
207
243
  return sanitizeApprovalContext({
@@ -274,6 +310,17 @@ export function sanitizeResultForSentinel(result) {
274
310
  return input === undefined ? safeMeta : { ...safeMeta, input: sanitizeApprovalContext(input) };
275
311
  });
276
312
  }
313
+ // 审核单里可能有原任务预览、审核理由与证据摘要;哨兵会保留 7 天,同样要脱敏。
314
+ if (rest.review && typeof rest.review === 'object') {
315
+ const rv = { ...rest.review };
316
+ for (const key of ['prompt_preview', 'notes']) {
317
+ if (typeof rv[key] === 'string') rv[key] = sanitizeApprovalContext(rv[key], key);
318
+ }
319
+ if (Array.isArray(rv.checklist)) rv.checklist = rv.checklist.map((x) => sanitizeApprovalContext(x));
320
+ if (Array.isArray(rv.findings)) rv.findings = rv.findings.map((x) => sanitizeApprovalContext(x));
321
+ if (rv.evidence) rv.evidence = sanitizeApprovalContext(rv.evidence);
322
+ rest.review = rv;
323
+ }
277
324
  // 始终给出布尔值:调用方才能区分“思考被剥离”与“本来没有思考”。
278
325
  const out = { ...rest, thinking_omitted: Boolean(thinking) && !SENTINEL_INCLUDE_REASONING };
279
326
  if (SENTINEL_INCLUDE_REASONING && thinking !== undefined) out.thinking = thinking;
@@ -299,6 +346,8 @@ export class Conversation {
299
346
  provider: state.provider ?? null,
300
347
  model: state.model ?? null,
301
348
  };
349
+ /** 调用方审核策略(off / advisory)。可在 dsh_send 单次覆盖。 */
350
+ this.review = REVIEW_MODES.includes(state.review) ? state.review : DEFAULT_REVIEW;
302
351
  this.lastConfigApplied = null;
303
352
  /** 是否已回读并确认会话记录的权限档(null=尚未核对,true/false=结果)。 */
304
353
  this.permissionVerified = null;
@@ -365,6 +414,7 @@ export class Conversation {
365
414
  reasoningEffort: this.cfg.reasoningEffort,
366
415
  provider: this.cfg.provider,
367
416
  model: this.cfg.model,
417
+ review: this.review,
368
418
  workspace: this.workspace,
369
419
  };
370
420
  }
@@ -396,6 +446,8 @@ export class Conversation {
396
446
  title_hint: this.titleHint ?? null,
397
447
  cwd: this.cwd,
398
448
  permission: this.permission,
449
+ /** 会话默认审核策略;单次 dsh_send 可以覆盖。 */
450
+ review: this.review,
399
451
  /** true=已回读会话记录且一致;false/null=缓存暂时没有记录(read-only 仍由审批层兜底)。 */
400
452
  permission_verified: this.permissionVerified,
401
453
  on_approval: this.onApproval,
@@ -641,7 +693,23 @@ export class Conversation {
641
693
  return report;
642
694
  }
643
695
 
644
- // 3) 杀 + 重试(内核在持有者进程退出时释放信号量)
696
+ // 3) 共享进程:杀它会连坐同组会话,先把代价说清楚,别让对方在不知情下按下去。
697
+ // 共享进程池(0.5.0 默认开启)让一个 PID 载着多个会话,takeover 只看"谁握着锁"
698
+ // 会做出一个很贵的决定 —— 杀掉持有者 = 同组所有会话的进行中回合一起断。
699
+ const sharedVictims = this.#hub.hostVictimsOf(killTarget, this.id);
700
+ if (sharedVictims.length > 0) {
701
+ report.shared_sessions = sharedVictims;
702
+ if (!force) {
703
+ report.message =
704
+ `抢占被拒绝:PID ${killTarget} 是共享进程,上面还挂着 ${sharedVictims.length} 个其它会话` +
705
+ `(${sharedVictims.map((id) => id.slice(0, 8)).join(', ')})。\n` +
706
+ '杀掉它会连坐这些会话:各自进行中的回合会中断(会话本体无损,之后照常 resume)。\n' +
707
+ '确认可以接受就带 force=true 重试;不想连坐就先 dsh_release 那些会话,或等它们空闲。';
708
+ return report;
709
+ }
710
+ }
711
+
712
+ // 4) 杀 + 重试(内核在持有者进程退出时释放信号量)
645
713
  const kill = killHolderChild(killTarget, { expectedSpawnedAt: holder.marker?.spawned_at });
646
714
  report.killed_pid = killTarget;
647
715
  report.kill = kill;
@@ -661,7 +729,10 @@ export class Conversation {
661
729
  report.ok = true;
662
730
  report.message =
663
731
  `已抢占:杀掉持有者 PID ${killTarget}(${holder.reason}),并成功接管会话。` +
664
- `\n⚠️ 如果那个进程当时正在跑回合,那一轮的工作会中断(会话日志会记为 interrupted)。`;
732
+ `\n⚠️ 如果那个进程当时正在跑回合,那一轮的工作会中断(会话日志会记为 interrupted)。` +
733
+ (sharedVictims.length > 0
734
+ ? `\n⚠️ 它是共享进程,另外 ${sharedVictims.length} 个会话也被一起断掉了(各自 resume 即可)。`
735
+ : '');
665
736
  } catch (e) {
666
737
  report.message = `杀掉 PID ${killTarget} 之后仍无法接管:${e.message}`;
667
738
  }
@@ -833,6 +904,17 @@ export class Conversation {
833
904
  workspace_changed: false,
834
905
  elapsed_ms: 0,
835
906
  };
907
+ const reviewMode = runRecord.review_mode ?? this.review;
908
+ if (reviewMode !== 'off') {
909
+ runRecord.result.review = buildReviewTicket({
910
+ conversationId: this.id,
911
+ runId: runRecord.run_id,
912
+ promptPreview: runRecord.prompt_preview,
913
+ result: runRecord.result,
914
+ mode: reviewMode,
915
+ permission: this.permission,
916
+ });
917
+ }
836
918
  try {
837
919
  if (typeof this.#hub.writeRunSentinel === 'function') {
838
920
  const file = this.#hub.writeRunSentinel(this.id, runRecord);
@@ -881,13 +963,15 @@ export class Conversation {
881
963
  *
882
964
  * @returns 等到回合结束 → 完整 result;没等到(wait=false 或等超时)→ 收据对象
883
965
  */
884
- async prompt(text, { reasoning = 'hide', timeoutMs = PROMPT_TIMEOUT_MS, run, wait = true } = {}) {
966
+ async prompt(text, { reasoning = 'hide', timeoutMs = PROMPT_TIMEOUT_MS, run, wait = true, review } = {}) {
885
967
  if (this.busy) {
886
968
  throw new Error(
887
969
  `会话 ${this.id} 正在跑另一个回合。可以:dsh_interject 插话(打断并改口 / 排队),或 dsh_interrupt 打断。`,
888
970
  );
889
971
  }
890
- const runRecord = run ?? this.createRun(text);
972
+ const runRecord = run ?? this.createRun(text, { review });
973
+ const reviewMode = runRecord.review_mode ?? normalizeReviewMode(review ?? this.review);
974
+ runRecord.review_mode = reviewMode;
891
975
  runRecord.status = 'running';
892
976
  runRecord.started_at = now();
893
977
  this.currentRun = runRecord;
@@ -934,6 +1018,26 @@ export class Conversation {
934
1018
  const t0 = now();
935
1019
  let settled = false;
936
1020
 
1021
+ /**
1022
+ * 把"调用方审核单"挂到回合结果上。
1023
+ *
1024
+ * 审核单必须随结果一起返回(正文、structuredContent、哨兵都是同一份 result),
1025
+ * 否则调用方在异步收活时只会看到一段自述,很容易直接把它当成完成事实。
1026
+ */
1027
+ const attachReview = (result) => {
1028
+ if (reviewMode !== 'off') {
1029
+ result.review = buildReviewTicket({
1030
+ conversationId: this.id,
1031
+ runId: runRecord.run_id,
1032
+ promptPreview: runRecord.prompt_preview,
1033
+ result,
1034
+ mode: reviewMode,
1035
+ permission: this.permission,
1036
+ });
1037
+ }
1038
+ return result;
1039
+ };
1040
+
937
1041
  /** 回合真正结束时收尾。无论有没有人在等,都**只执行一次**。 */
938
1042
  const finalize = (stopReason, failure) => {
939
1043
  if (settled) return runRecord.result;
@@ -987,6 +1091,7 @@ export class Conversation {
987
1091
  diff_stat: after,
988
1092
  elapsed_ms: now() - t0,
989
1093
  };
1094
+ attachReview(result);
990
1095
  runRecord.ended_at = now();
991
1096
  runRecord.elapsed_ms = result.elapsed_ms;
992
1097
  runRecord.status = failure ? 'error' : stopReason === 'cancelled' ? 'cancelled' : 'done';
@@ -1019,6 +1124,7 @@ export class Conversation {
1019
1124
  workspace_changed: false,
1020
1125
  elapsed_ms: now() - t0,
1021
1126
  };
1127
+ attachReview(fallback);
1022
1128
  runRecord.ended_at = now();
1023
1129
  runRecord.status = 'error';
1024
1130
  runRecord.error = fallback.error;
@@ -1131,13 +1237,15 @@ export class Conversation {
1131
1237
  }
1132
1238
 
1133
1239
  /** 建一条回合记录。派活时先建,好让调用方立刻拿到 run_id(异步模式的关键)。 */
1134
- createRun(text, { clientRunId = null } = {}) {
1240
+ createRun(text, { clientRunId = null, review = this.review } = {}) {
1135
1241
  const run = {
1136
1242
  run_id: `run-${Date.now().toString(36)}-${++this.runSeq}`,
1137
1243
  conversation_id: this.id,
1138
1244
  client_run_id: clientRunId ?? null,
1139
1245
  prompt_preview: text.length > MAX_RUN_PREVIEW ? `${text.slice(0, MAX_RUN_PREVIEW)}…` : text,
1140
1246
  status: 'queued',
1247
+ /** 本回合的审核策略(off / advisory);由 dsh_send / dsh_interject 或会话默认决定。 */
1248
+ review_mode: normalizeReviewMode(review, this.review),
1141
1249
  started_at: null,
1142
1250
  ended_at: null,
1143
1251
  elapsed_ms: null,
@@ -1168,7 +1276,7 @@ export class Conversation {
1168
1276
  // ── 会话级队列(忙时非阻塞入队)────────────────────────────────
1169
1277
 
1170
1278
  /** 入队;返回 run 记录与 1-based 位置。队列只在内存,重启丢失。 */
1171
- enqueue(text, { reasoning = 'hide', clientRunId = null, preview = null } = {}) {
1279
+ enqueue(text, { reasoning = 'hide', clientRunId = null, preview = null, review = this.review } = {}) {
1172
1280
  const MAX_QUEUE = 8;
1173
1281
  if (clientRunId) {
1174
1282
  const existing = this.getRunByClientId(clientRunId);
@@ -1178,7 +1286,7 @@ export class Conversation {
1178
1286
  throw new Error(`队列已满(最多 ${MAX_QUEUE} 条);先用 dsh_queue list 清理,或等当前回合结束`);
1179
1287
  }
1180
1288
  // 预览用调用方原文,执行用可能已注入团队前缀的 text。
1181
- const run = this.createRun(preview ?? text, { clientRunId });
1289
+ const run = this.createRun(preview ?? text, { clientRunId, review });
1182
1290
  run.status = 'queued';
1183
1291
  this.queue.push({ run, text, reasoning, clientRunId, enqueued_at: now() });
1184
1292
  return { run, position: this.queue.length, deduped: false };
@@ -1215,6 +1323,16 @@ export class Conversation {
1215
1323
  workspace_changed: false,
1216
1324
  elapsed_ms: 0,
1217
1325
  };
1326
+ if (run.review_mode !== 'off') {
1327
+ run.result.review = buildReviewTicket({
1328
+ conversationId: this.id,
1329
+ runId: run.run_id,
1330
+ promptPreview: run.prompt_preview,
1331
+ result: run.result,
1332
+ mode: run.review_mode,
1333
+ permission: this.permission,
1334
+ });
1335
+ }
1218
1336
  // 取消也是终态 → 写哨兵,避免等待方永远空等。
1219
1337
  const file = this.#hub.writeRunSentinel(this.id, run);
1220
1338
  run.result.sentinel_file = file ?? this.#hub.runSentinelPath(this.id, run.run_id);
@@ -1268,6 +1386,142 @@ export class Conversation {
1268
1386
  return this.runs.length ? this.runs[this.runs.length - 1] : null;
1269
1387
  }
1270
1388
 
1389
+ /**
1390
+ * 异步收据里的"待审核"审核单:回合还没结束,只有清单和 run_id,
1391
+ * 告诉调用方"拿到哨兵结果后先审核,再当完成"。
1392
+ */
1393
+ pendingReviewTicket(runId) {
1394
+ const run = this.runs.find((x) => x.run_id === runId) ?? null;
1395
+ const mode = run?.review_mode ?? this.review;
1396
+ if (mode === 'off') return null;
1397
+ return buildReviewTicket({
1398
+ conversationId: this.id,
1399
+ runId,
1400
+ promptPreview: run?.prompt_preview ?? null,
1401
+ result: null,
1402
+ mode,
1403
+ permission: this.permission,
1404
+ pending: true,
1405
+ });
1406
+ }
1407
+
1408
+ /**
1409
+ * 记录调用方对某个已完成回合的审核裁决。
1410
+ *
1411
+ * 三种来源按优先级取事实:
1412
+ * 1) 内存里的 run(含完整 result);
1413
+ * 2) 哨兵文件(服务重启 / run 记录被挤出内存后仍然可审核);
1414
+ * 3) 已有的审核记录(允许修订裁决)。
1415
+ *
1416
+ * 注意:**不阻塞后续派活,也不自动回灌给 DSH**。审核只是把"调用方已经看过并给出结论"
1417
+ * 这件事落成可审计的事实;要修就由调用方再 dsh_send。
1418
+ */
1419
+ submitReview(runId, { verdict, notes, findings } = {}) {
1420
+ if (typeof runId !== 'string' || runId.trim() === '') {
1421
+ throw new Error('run_id 不能为空');
1422
+ }
1423
+ assertSafeId(runId, 'run_id');
1424
+ if (!REVIEW_VERDICTS.includes(verdict)) {
1425
+ throw new Error(`verdict 必须是 ${REVIEW_VERDICTS.join(' | ')} 之一`);
1426
+ }
1427
+ const cleanNotes = typeof notes === 'string' ? notes.trim() : '';
1428
+ const cleanFindings = Array.isArray(findings)
1429
+ ? findings.filter((f) => typeof f === 'string' && f.trim() !== '').map((f) => f.trim())
1430
+ : [];
1431
+ if (verdict !== 'pass' && !cleanNotes && !cleanFindings.length) {
1432
+ throw new Error('verdict=fail/partial 时必须提供 notes(或 findings)说明理由');
1433
+ }
1434
+
1435
+ const run = this.runs.find((x) => x.run_id === runId) ?? null;
1436
+ let result = run?.result ?? null;
1437
+ let promptPreview = run?.prompt_preview ?? null;
1438
+ let mode = run?.review_mode ?? this.review;
1439
+
1440
+ if (run) {
1441
+ if (run.status === 'running' || run.status === 'queued') {
1442
+ throw new Error(`回合 ${runId} 还没结束,不能审核(等哨兵文件出现或 dsh_get 显示完成后重试)`);
1443
+ }
1444
+ if (!result) throw new Error(`回合 ${runId} 没有可用结果,无法审核`);
1445
+ } else {
1446
+ // 内存里没有这条 run:以哨兵为准。它只在回合终止时写入,所以天然是"已完成"。
1447
+ let sentinel = null;
1448
+ try {
1449
+ sentinel = JSON.parse(readFileSync(this.#hub.runSentinelPath(this.id, runId), 'utf8'));
1450
+ } catch {
1451
+ /* 下面的审核记录回退会给出更准确的错误 */
1452
+ }
1453
+ if (sentinel) {
1454
+ result = sentinel.result ?? null;
1455
+ if (result?.review && typeof result.review === 'object') {
1456
+ promptPreview = result.review.prompt_preview ?? promptPreview;
1457
+ mode = result.review.mode ?? mode;
1458
+ }
1459
+ }
1460
+ }
1461
+
1462
+ const existing = readReviewRecord(this.id, runId);
1463
+ if (!result && !existing) {
1464
+ throw new Error(
1465
+ `未知 run_id: ${runId}(内存里没有、也没有哨兵/审核记录;请确认 run_id 是否正确,` +
1466
+ `或先用 dsh_get / 哨兵文件取回结果)`,
1467
+ );
1468
+ }
1469
+
1470
+ const ticket =
1471
+ result?.review && typeof result.review === 'object'
1472
+ ? { ...result.review }
1473
+ : existing
1474
+ ? { ...existing }
1475
+ : buildReviewTicket({
1476
+ conversationId: this.id,
1477
+ runId,
1478
+ promptPreview,
1479
+ result: result ?? {},
1480
+ mode,
1481
+ permission: this.permission,
1482
+ });
1483
+ if (!ticket.review_id) ticket.review_id = reviewIdForRun(runId);
1484
+ ticket.conversation_id = ticket.conversation_id ?? this.id;
1485
+ ticket.run_id = ticket.run_id ?? runId;
1486
+ ticket.mode = ticket.mode ?? mode;
1487
+
1488
+ const reviewedAt = new Date().toISOString();
1489
+ const { file, payload } = writeReviewRecord({
1490
+ ticket,
1491
+ verdict,
1492
+ notes: cleanNotes,
1493
+ findings: cleanFindings,
1494
+ reviewedAt,
1495
+ });
1496
+ const review = {
1497
+ ...ticket,
1498
+ status: verdict,
1499
+ verdict,
1500
+ notes: payload.notes,
1501
+ findings: payload.findings,
1502
+ reviewed_at: reviewedAt,
1503
+ review_file: file,
1504
+ };
1505
+ if (run) {
1506
+ run.review = review;
1507
+ if (run.result && typeof run.result === 'object') run.result.review = review;
1508
+ }
1509
+ // 哨兵是调用方异步收活的来源;把裁决回写进去,避免它一直显示 pending。
1510
+ this.#hub.updateRunSentinelReview(this.id, runId, {
1511
+ status: review.status,
1512
+ verdict: review.verdict,
1513
+ notes: review.notes,
1514
+ findings: review.findings,
1515
+ reviewed_at: reviewedAt,
1516
+ review_file: file,
1517
+ });
1518
+ return {
1519
+ ...review,
1520
+ review_file: file,
1521
+ sentinel_file: this.#hub.runSentinelPath(this.id, runId),
1522
+ };
1523
+ }
1524
+
1271
1525
  /** 等到当前回合结束(不忙则立即返回 true;`timeoutMs <= 0` 一直等;超时返回 false)。 */
1272
1526
  async waitIdle(timeoutMs = 30 * 60 * 1000) {
1273
1527
  if (!this.busy) return true;
@@ -1306,9 +1560,9 @@ export class Conversation {
1306
1560
  * 之所以无竞态:dsh-acp 在让 prompt 请求返回**之前**就清空了 inflight 槽位,
1307
1561
  * 且只在 agent 完全 idle 后才 settle(lib/index.js:1003-1011)。
1308
1562
  */
1309
- async interject(message, { mode = 'interject', reasoning = 'hide', timeoutMs = PROMPT_TIMEOUT_MS, clientRunId = null } = {}) {
1563
+ async interject(message, { mode = 'interject', reasoning = 'hide', timeoutMs = PROMPT_TIMEOUT_MS, clientRunId = null, review } = {}) {
1310
1564
  // 先建 run:幂等键要在"等待上一轮"之前就登记,否则重试会造出第二个 run。
1311
- const run = this.createRun(message, { clientRunId });
1565
+ const run = this.createRun(message, { clientRunId, review });
1312
1566
  if (!this.busy) {
1313
1567
  const r = await this.prompt(message, { reasoning, timeoutMs, run });
1314
1568
  return { ...r, interjected: 'idle', waited_ms: 0 };
@@ -1317,7 +1571,7 @@ export class Conversation {
1317
1571
  if (mode === 'interject') {
1318
1572
  this.proc?.notify('session/cancel', { sessionId: this.id });
1319
1573
  }
1320
- // 排队等待的时长跟随调用方的 timeout_ms(0 = 一直等),不再固定 30 分钟。
1574
+ // 排队等待的时长跟随调用方的 timeoutMs(0 = 一直等),不再固定 30 分钟。
1321
1575
  const idle = await this.waitIdle(timeoutMs);
1322
1576
  const waited = now() - t0;
1323
1577
  if (!idle) {
@@ -1337,6 +1591,17 @@ export class Conversation {
1337
1591
  workspace_changed: false,
1338
1592
  elapsed_ms: 0,
1339
1593
  };
1594
+ // 取消同样是一次终态结果:审核单照挂,调用方仍可记录"这次没跑成"。
1595
+ if (run.review_mode !== 'off') {
1596
+ run.result.review = buildReviewTicket({
1597
+ conversationId: this.id,
1598
+ runId: run.run_id,
1599
+ promptPreview: run.prompt_preview,
1600
+ result: run.result,
1601
+ mode: run.review_mode,
1602
+ permission: this.permission,
1603
+ });
1604
+ }
1340
1605
  const file = this.#hub.writeRunSentinel?.(this.id, run);
1341
1606
  run.result.sentinel_file = file ?? this.#hub.runSentinelPath?.(this.id, run.run_id) ?? null;
1342
1607
  throw err;
@@ -1460,14 +1725,56 @@ export function formatReasoning(c, mode) {
1460
1725
  *
1461
1726
  * @returns {string|null} null 表示没问题,否则返回一段可直接抛出的说明。
1462
1727
  */
1728
+ /**
1729
+ * 当前文件系统是否大小写不敏感(缓存一次)。
1730
+ *
1731
+ * 不能按平台猜:GitHub 的 `macos-latest` 是**大小写敏感的 APFS**,而普通 macOS
1732
+ * 默认又不敏感;Windows 一定不敏感;Linux 一定敏感。用临时文件探针最稳。
1733
+ */
1734
+ let caseInsensitiveCache = null;
1735
+ export function fsCaseInsensitive() {
1736
+ if (caseInsensitiveCache !== null) return caseInsensitiveCache;
1737
+ if (process.platform === 'win32') {
1738
+ caseInsensitiveCache = true;
1739
+ return true;
1740
+ }
1741
+ try {
1742
+ const dir = mkdtempSync(join(tmpdir(), 'dsh-any-agent-case-'));
1743
+ writeFileSync(join(dir, 'probe'), '');
1744
+ caseInsensitiveCache = existsSync(join(dir, 'PROBE'));
1745
+ rmSync(dir, { recursive: true, force: true });
1746
+ } catch {
1747
+ caseInsensitiveCache = false;
1748
+ }
1749
+ return caseInsensitiveCache;
1750
+ }
1751
+
1463
1752
  export function homeWorkspaceProblem(cwd, permission) {
1464
1753
  if (permission === 'read-only') return null;
1465
1754
  const home = homedir();
1466
1755
  if (!home) return null;
1756
+ const caseInsensitive = process.platform === 'win32' || fsCaseInsensitive();
1467
1757
  const norm = (p) => {
1468
- const r = resolve(p);
1469
- return process.platform === 'win32' ? r.toLowerCase() : r;
1758
+ // 解析 symlink:一个指向家目录/根目录的软链不能绕过这两个边界。
1759
+ // 路径不存在时(测试里的 "some-project")回落到 resolve。
1760
+ let r;
1761
+ try {
1762
+ r = realpathSync(p);
1763
+ } catch {
1764
+ r = resolve(p);
1765
+ }
1766
+ return caseInsensitive ? r.toLowerCase() : r;
1470
1767
  };
1768
+ // 根目录 = 整个磁盘。workspace-write 的沙箱根会跟着 cwd 走,
1769
+ // 于是“只写工作区”退化成“可写全盘”,必须显式要求 danger-full-access。
1770
+ const fsRoot = resolve(parse(cwd).root);
1771
+ if (norm(cwd) === norm(fsRoot)) {
1772
+ return [
1773
+ 'cwd 不能是文件系统根目录: ' + cwd,
1774
+ ' workspace-write 的沙箱根会变成整个磁盘,等于绕过“只写工作区”的权限档。',
1775
+ ' 请传一个具体的项目目录;确实要全盘访问请显式用 permission=danger-full-access。',
1776
+ ].join('\n');
1777
+ }
1471
1778
  if (norm(cwd) !== norm(home)) return null;
1472
1779
 
1473
1780
  const temp = tmpdir();
@@ -1488,7 +1795,7 @@ export function homeWorkspaceProblem(cwd, permission) {
1488
1795
  export class Hub {
1489
1796
  constructor({ log } = {}) {
1490
1797
  this.conversations = new Map();
1491
- /** 共享 ACP 进程池:key = `${cwd}\0${permission}`(实验性,DSH_MCP_SHARED_PROCESS=1)。 */
1798
+ /** 共享 ACP 进程池:key = `${cwd}\0${permission}`(0.5.0 起默认启用,`DSH_MCP_SHARED_PROCESS=0` 关闭)。 */
1492
1799
  this.hosts = new Map();
1493
1800
  this.log = log ?? NOOP_LOG;
1494
1801
  /** 最近一次 dsh_list 磁盘探测的结果:{ok, error, cached, at}。 */
@@ -1511,6 +1818,7 @@ export class Hub {
1511
1818
  // 看起来正常,但注册表/哨兵/锁登记全部丢失,异步等待永远醒不过来。
1512
1819
  assertWritableDir(dirname(STATE_FILE), '状态目录');
1513
1820
  assertWritableDir(RUNS_DIR, '哨兵目录');
1821
+ assertWritableDir(REVIEWS_DIR, '审核记录目录');
1514
1822
  assertWritableDir(LOCKS_DIR, '锁登记目录');
1515
1823
 
1516
1824
  // 旧版本的默认状态文件在包安装目录里;一次性迁移到新的用户可写目录。
@@ -1585,6 +1893,8 @@ export class Hub {
1585
1893
 
1586
1894
  /** 某个 run 的完成哨兵文件路径。 */
1587
1895
  runSentinelPath(conversationId, runId) {
1896
+ assertSafeId(conversationId, 'conversation_id');
1897
+ assertSafeId(runId, 'run_id');
1588
1898
  return join(RUNS_DIR, conversationId, `${runId}.json`);
1589
1899
  }
1590
1900
 
@@ -1620,6 +1930,34 @@ export class Hub {
1620
1930
  }
1621
1931
  }
1622
1932
 
1933
+ /**
1934
+ * 把调用方的审核裁决回写进该 run 的哨兵文件(best-effort)。
1935
+ *
1936
+ * 为什么回写:异步调用方收活主要靠读哨兵。若审核后哨兵仍写着 `review.status=pending`,
1937
+ * 下一次读文件会得到一个与事实相反的状态。原子重写不破坏闩锁语义:文件始终存在,
1938
+ * 内容要么是旧的完整版本,要么是新的完整版本。
1939
+ */
1940
+ updateRunSentinelReview(conversationId, runId, review) {
1941
+ const file = this.runSentinelPath(conversationId, runId);
1942
+ try {
1943
+ const payload = JSON.parse(readFileSync(file, 'utf8'));
1944
+ const result = payload.result && typeof payload.result === 'object' ? payload.result : {};
1945
+ result.review = {
1946
+ ...(result.review && typeof result.review === 'object' ? result.review : {}),
1947
+ ...review,
1948
+ };
1949
+ payload.result = result;
1950
+ payload.reviewed_at = review.reviewed_at ?? null;
1951
+ const tmp = `${file}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
1952
+ writeFileSync(tmp, JSON.stringify(payload, null, 2), 'utf8');
1953
+ renameSync(tmp, file);
1954
+ return true;
1955
+ } catch (e) {
1956
+ this.log.info(`[hub] 回写哨兵审核状态失败(${file}): ${e.message}`);
1957
+ return false;
1958
+ }
1959
+ }
1960
+
1623
1961
  /**
1624
1962
  * 启动时清理过期哨兵(默认 7 天前)与崩溃残留的 .tmp 文件。
1625
1963
  *
@@ -1627,39 +1965,16 @@ export class Hub {
1627
1965
  * 只在服务启动时做一次,因此绝不会删掉"当前正在等待的"哨兵(那时它还不需要存在)。
1628
1966
  */
1629
1967
  pruneSentinels({ ttlMs = SENTINEL_TTL_MS } = {}) {
1630
- if (!ttlMs || !existsSync(RUNS_DIR)) return { pruned: 0, dirs_removed: 0 };
1631
- let pruned = 0;
1632
- let dirsRemoved = 0;
1633
- const cutoff = Date.now() - ttlMs;
1634
- try {
1635
- for (const entry of readdirSync(RUNS_DIR, { withFileTypes: true })) {
1636
- if (!entry.isDirectory()) continue;
1637
- const dir = join(RUNS_DIR, entry.name);
1638
- for (const f of readdirSync(dir, { withFileTypes: true })) {
1639
- if (!f.isFile()) continue;
1640
- const fp = join(dir, f.name);
1641
- try {
1642
- if (statSync(fp).mtimeMs < cutoff) {
1643
- rmSync(fp, { force: true });
1644
- pruned++;
1645
- }
1646
- } catch {
1647
- /* 单个文件失败就跳过 */
1648
- }
1649
- }
1650
- try {
1651
- if (readdirSync(dir).length === 0) {
1652
- rmSync(dir, { recursive: true, force: true });
1653
- dirsRemoved++;
1654
- }
1655
- } catch {
1656
- /* 目录清理失败无所谓 */
1657
- }
1658
- }
1659
- } catch (e) {
1660
- this.log.info(`[hub] 清理哨兵失败: ${e.message}`);
1661
- }
1662
- return { pruned, dirs_removed: dirsRemoved };
1968
+ const runs = pruneDirTree(RUNS_DIR, ttlMs);
1969
+ // 审核记录同样含正文/理由,按同一 TTL 清理;目录分开是为了语义清晰,
1970
+ // 也避免一次清理把"刚提交的裁决"和"已完成的哨兵"混为一谈。
1971
+ const reviews = pruneDirTree(REVIEWS_DIR, ttlMs);
1972
+ return {
1973
+ pruned: runs.pruned,
1974
+ dirs_removed: runs.dirs_removed,
1975
+ reviews_pruned: reviews.pruned,
1976
+ review_dirs_removed: reviews.dirs_removed,
1977
+ };
1663
1978
  }
1664
1979
 
1665
1980
  /** 删除某个 run 的哨兵(起跑前防御性清残留;调用方消费后也可自行删)。 */
@@ -1672,6 +1987,8 @@ export class Hub {
1672
1987
  }
1673
1988
 
1674
1989
  async get(id) {
1990
+ // 会话 id 会参与 meta/tombstone/会话存储的路径拼接;先挡住路径分隔符与 `..`。
1991
+ assertSafeId(id, 'conversation_id');
1675
1992
  // ★ forget 是终态:墓碑存在时,任何按 id 的查询都必须明确失败,
1676
1993
  // 否则 DSH 会话存储里的记录会让它悄悄复活("forget 不持久")。
1677
1994
  if (isForgotten(id)) {
@@ -1747,6 +2064,7 @@ export class Hub {
1747
2064
  createdAt: persisted?.createdAt,
1748
2065
  lastUsedAt: persisted?.lastUsedAt,
1749
2066
  turnCount: persisted?.turnCount,
2067
+ review: REVIEW_MODES.includes(persisted?.review) ? persisted.review : DEFAULT_REVIEW,
1750
2068
  workspace: persisted?.workspace ?? null,
1751
2069
  },
1752
2070
  this,
@@ -1816,8 +2134,25 @@ export class Hub {
1816
2134
  }
1817
2135
  }
1818
2136
 
2137
+ /**
2138
+ * 共享进程下,某个子进程 PID 上还挂着哪些**别的**会话。
2139
+ *
2140
+ * 用途只有一个:`takeover` 要杀这个 PID 之前,先看看会不会连坐 ——
2141
+ * 杀一个还载着三个会话的宿主,代价是那三个会话的进行中回合一起断。
2142
+ * 只有本服务自己的宿主池查得清这件事;别的实例的宿主编号外部,查不到就只能让调用方
2143
+ * 自己用 `force` 承担。
2144
+ */
2145
+ hostVictimsOf(pid, exceptId) {
2146
+ if (!pid) return [];
2147
+ for (const host of this.hosts.values()) {
2148
+ if (host.pid !== pid) continue;
2149
+ return [...host.conversations.keys()].filter((id) => id !== exceptId);
2150
+ }
2151
+ return [];
2152
+ }
2153
+
1819
2154
  /** 新建一个会话:拉起进程 + ACP 初始化 + session/new。 */
1820
- async create({ cwd, permission = DEFAULT_PERMISSION, onApproval, titleHint, reasoningEffort, provider, model, keepAlive = false } = {}) {
2155
+ async create({ cwd, permission = DEFAULT_PERMISSION, onApproval, titleHint, reasoningEffort, provider, model, keepAlive = false, review } = {}) {
1821
2156
  if (!cwd) {
1822
2157
  throw new Error(
1823
2158
  '没有可用的工作目录。你既没传 cwd,客户端也没有提供当前打开的项目(MCP roots)。\n' +
@@ -1835,6 +2170,20 @@ export class Hub {
1835
2170
  if (!PERMISSION_TIERS.includes(permission)) {
1836
2171
  throw new Error(`permission 必须是 ${PERMISSION_TIERS.join(' | ')} 之一`);
1837
2172
  }
2173
+ // title_hint 会写进注册表与侧车,每一轮 save() 都会重复落盘;不设上限就是一个
2174
+ // 稳定的磁盘/内存放大点(调用方可以传任意长度)。可读标签 200 字足够。
2175
+ if (titleHint !== undefined && titleHint !== null) {
2176
+ if (typeof titleHint !== 'string') throw new Error('title_hint 必须是字符串');
2177
+ if (titleHint.length > 200) throw new Error('title_hint 最长 200 字符');
2178
+ }
2179
+ // ★ 0.5.0:danger-full-access 不再默认可用。它把整机写权限交给调用方,
2180
+ // 而本服务可能被任何 MCP 客户端拉起;必须由机器所有者显式放行。
2181
+ if (permission === 'danger-full-access' && !ALLOW_FULL_ACCESS) {
2182
+ throw new Error(
2183
+ 'permission=danger-full-access 需要机器侧显式允许:设置 DSH_MCP_ALLOW_FULL_ACCESS=1 后重试。' +
2184
+ ' 默认请用 workspace-write(写入限制在工作区内)或 read-only。',
2185
+ );
2186
+ }
1838
2187
  const policy = onApproval ?? defaultApprovalPolicy(permission);
1839
2188
  if (!APPROVAL_POLICIES.includes(policy)) {
1840
2189
  throw new Error(`on_approval 必须是 ${APPROVAL_POLICIES.join(' | ')} 之一`);
@@ -1851,6 +2200,10 @@ export class Hub {
1851
2200
  if (!REASONING_EFFORTS.includes(effort)) {
1852
2201
  throw new Error(`reasoning_effort 必须是 ${REASONING_EFFORTS.join(' | ')} 之一`);
1853
2202
  }
2203
+ const reviewMode = normalizeReviewMode(review ?? DEFAULT_REVIEW);
2204
+ if (!REVIEW_MODES.includes(reviewMode)) {
2205
+ throw new Error(`review 必须是 ${REVIEW_MODES.join(' | ')} 之一`);
2206
+ }
1854
2207
  if (model && !provider) {
1855
2208
  throw new Error('指定 model 时必须同时给 provider(ACP 的模型标识是 [provider, model] 二元组)');
1856
2209
  }
@@ -1886,6 +2239,7 @@ export class Hub {
1886
2239
  reasoningEffort: effort,
1887
2240
  provider: provider ?? null,
1888
2241
  model: model ?? null,
2242
+ review: reviewMode,
1889
2243
  },
1890
2244
  this,
1891
2245
  );
@@ -2016,7 +2370,7 @@ export class Hub {
2016
2370
 
2017
2371
  /** 空闲回收:停掉闲置进程,会话本身保留(可 resume 复活)。
2018
2372
  *
2019
- * ★ `DSH_MCP_IDLE_TTL_MS=0`(**默认**)= **永不回收**。
2373
+ * ★ `DSH_MCP_IDLE_TTL_MS=0` = **永不回收**(0.4.0 起默认是 10 分钟,不再是默认值)。
2020
2374
  * 理由(实测,见 USAGE-NOTES §3.10~3.12):空闲回收是写锁**唯一**会变空的时刻,
2021
2375
  * 而只要锁一空,你在 web 里点开那条会话,`dsh web` 就会**永久**持有它
2022
2376
  * (切走 ✗ 等待 ✗ 归档 ✗ 都不释放),本服务之后每一次 resume 都失败 ——