dsh-any-agent 0.6.0 → 0.6.2

package/src/live.mjs

@@ -0,0 +1,186 @@
+/**
+ * live 事件流：把"DSH 在做什么"写成按会话分的 JSONL，给用户旁路查看。
+ *
+ * 为什么是文件而不是端口：本服务是 MCP 客户端拉起的 stdio 子进程，可能同时有好几个实例
+ * （Claude Code / Codex / Cursor 各一个），彼此内存不通。文件天然跨实例、跨重启；同一会话
+ * 同一时刻只有一个写者（写锁保证），所以"一会话一文件、单写者追加"不需要再加锁。
+ * 查看端（`dsh-any-agent watch` / `dashboard`，见 live-view.mjs）只读这些文件。
+ *
+ * 纪律（与 audit.mjs 相同）：
+ *   - 同步追加一行；**所有异常吞掉**，写失败绝不影响派活。
+ *   - 思考内容在事件格式里**没有位置**：没有任何事件类型接收它，任何级别都不落盘。
+ *   - 字符串一律先过 sanitizeApprovalContext 脱敏，再截断。
+ *
+ * 布局：`<LIVE_DIR>/<conversation_id>/events.jsonl`（满了滚动成 `events.jsonl.1`，只留一份）。
+ * 按会话分目录是为了直接复用 pruneDirTree 做 TTL 清理。
+ * 数据契约见 docs/zh/live-view-design.md §6。
+ */
+
+import { appendFileSync, mkdirSync, renameSync, rmSync, statSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+import { LIVE_DIR, LIVE_LEVEL, LIVE_LEVELS } from './config.mjs';
+import { sanitizeApprovalContext } from './redact.mjs';
+import { pruneDirTree } from './sentinel.mjs';
+
+export const LIVE_SCHEMA = 1;
+export const LIVE_FILE = 'events.jsonl';
+/** 单文件上限；超过就滚动成 `.1`（只留一份旧档）。 */
+const MAX_FILE_BYTES = 5 * 1024 * 1024;
+/** 单行上限；超过先丢掉 detail 字段，仍超就不写。 */
+const MAX_LINE_BYTES = 4096;
+/** 会话 id 会拼进路径：只认安全字符（同 ids.mjs 的约束，宽松到能放下 DSH 的 uuid）。 */
+const SAFE_ID = /^[A-Za-z0-9._-]{1,128}$/;
+/** 这些事件带上客户端名，查看端用它把会话挂到"谁派的"下面。 */
+const CLIENT_TYPES = new Set(['conv.open', 'run.queued', 'run.start']);
+
+/** 写者标识：进程 pid + 本次启动的随机串。查看端用 pid 判断写者是否还活着。 */
+export const WRITER = `${process.pid}:${randomBytes(4).toString('hex')}`;
+
+const settings = { dir: LIVE_DIR, level: LIVE_LEVEL };
+let client = null;
+let seq = 0;
+/** 本进程已知的文件大小（首次写时 stat 一次，之后自己累加），用于滚动判断。 */
+const sizes = new Map();
+
+/** 测试 / 工具用：覆盖目录与级别。 */
+export function configureLive({ dir, level } = {}) {
+  if (typeof dir === 'string' && dir) settings.dir = dir;
+  if (LIVE_LEVELS.includes(level)) settings.level = level;
+  sizes.clear();
+  return { ...settings };
+}
+
+export function liveSettings() {
+  return { ...settings };
+}
+
+/** MCP initialize 里的 clientInfo（Claude Code / Codex / …）。 */
+export function setLiveClient(info) {
+  if (!info || typeof info !== 'object') return;
+  const name = typeof info.name === 'string' ? info.name.slice(0, 80) : null;
+  const version = typeof info.version === 'string' ? info.version.slice(0, 40) : null;
+  if (name) client = { name, version };
+}
+
+export function liveClient() {
+  return client ? { ...client } : null;
+}
+
+export function liveConvDir(convId, dir = settings.dir) {
+  return join(dir, convId);
+}
+
+export function liveFilePath(convId, dir = settings.dir) {
+  return join(dir, convId, LIVE_FILE);
+}
+
+/** 脱敏 + 截断成一行预览。对象先逐字段脱敏再序列化。 */
+export function livePreview(value, max = 300) {
+  if (value === undefined || value === null) return null;
+  let s;
+  try {
+    if (typeof value === 'string') s = sanitizeApprovalContext(value);
+    else s = JSON.stringify(sanitizeApprovalContext(value));
+  } catch {
+    return null;
+  }
+  if (typeof s !== 'string' || !s) return null;
+  s = s.replace(/\s+/g, ' ').trim();
+  return s.length > max ? `${s.slice(0, max)}…` : s;
+}
+
+/**
+ * 工具输入摘要：优先取最能说明"做了什么"的字段（命令、路径、搜索词），否则整体序列化。
+ * 返回值已脱敏、已截断。
+ */
+export function summarizeToolInput(input, max = 300) {
+  if (input === undefined || input === null) return null;
+  if (typeof input !== 'object') return livePreview(String(input), max);
+  const pick = (...keys) => {
+    for (const k of keys) {
+      const v = input[k];
+      if (typeof v === 'string' && v.trim()) return v;
+      if (Array.isArray(v) && v.length && v.every((x) => typeof x === 'string')) return v.join(' ');
+    }
+    return null;
+  };
+  const cmd = pick('command', 'cmd', 'script');
+  if (cmd) return livePreview(cmd, max);
+  const path = pick('path', 'file_path', 'filePath', 'file', 'paths', 'target');
+  const query = pick('pattern', 'query', 'glob', 'regex', 'url');
+  if (path || query) return livePreview([path, query].filter(Boolean).join(' · '), max);
+  return livePreview(input, max);
+}
+
+/**
+ * 写一条事件。永不抛错；返回是否真的写了。
+ *
+ * @param {string} convId 会话 id
+ * @param {string} type   事件类型（run.start / tool / approval / …）
+ * @param {object} fields meta 级字段（任何级别都写）
+ * @param {object} [detail] detail 级字段（仅 level=detail 时写；调用方负责先脱敏/截断）
+ */
+export function emitLive(convId, type, fields = {}, detail = null) {
+  if (settings.level === 'off') return false;
+  if (typeof convId !== 'string' || !SAFE_ID.test(convId)) return false;
+  try {
+    const ev = { v: LIVE_SCHEMA, ts: new Date().toISOString(), conv: convId, w: WRITER, n: ++seq, type };
+    if (CLIENT_TYPES.has(type) && client) ev.client = client.name;
+    for (const [k, v] of Object.entries(fields ?? {})) if (v !== undefined) ev[k] = v;
+    let line = JSON.stringify(ev);
+    if (settings.level === 'detail' && detail) {
+      const withDetail = { ...ev };
+      for (const [k, v] of Object.entries(detail)) if (v !== undefined && v !== null) withDetail[k] = v;
+      const full = JSON.stringify(withDetail);
+      if (Buffer.byteLength(full) <= MAX_LINE_BYTES) line = full;
+      else line = JSON.stringify({ ...ev, truncated: true });
+    }
+    line += '\n';
+    const bytes = Buffer.byteLength(line);
+    if (bytes > MAX_LINE_BYTES + 1) return false;
+
+    const dir = liveConvDir(convId);
+    const file = join(dir, LIVE_FILE);
+    mkdirSync(dir, { recursive: true });
+    let size = sizes.get(file);
+    if (size === undefined) {
+      try {
+        size = statSync(file).size;
+      } catch {
+        size = 0;
+      }
+    }
+    if (size + bytes > MAX_FILE_BYTES && size > 0) {
+      try {
+        renameSync(file, `${file}.1`);
+      } catch {
+        /* 被占用就继续往原文件写，下次再滚 */
+      }
+      size = 0;
+    }
+    appendFileSync(file, line, 'utf8');
+    sizes.set(file, size + bytes);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** forget 时删掉该会话的事件目录。 */
+export function removeLive(convId) {
+  if (typeof convId !== 'string' || !SAFE_ID.test(convId)) return false;
+  try {
+    const dir = liveConvDir(convId);
+    for (const k of [...sizes.keys()]) if (k.startsWith(dir)) sizes.delete(k);
+    rmSync(dir, { recursive: true, force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 启动时按 TTL 清理过期事件文件（与哨兵同一 TTL）。 */
+export function pruneLive(ttlMs) {
+  return pruneDirTree(settings.dir, ttlMs);
+}

package/src/mcp.mjs

@@ -11,6 +11,7 @@ import { fileURLToPath } from 'node:url';
 import { createHandlers, TOOL_DEFS } from './tools.mjs';
 import { DEFAULT_PERMISSION } from './config.mjs';
 import { LineDecoder } from './line-decoder.mjs';
+import { setLiveClient } from './live.mjs';
 
 const SERVER_NAME = 'dsh-any-agent';
 /**
@@ -156,6 +157,8 @@ export function createMcpServer({ hub, toolDefs = TOOL_DEFS, handlers = createHa
         // 默认 cwd —— 用户在客户端里看到哪个项目，就在这里干活。
         const caps = params?.capabilities;
         clientCapabilities = caps && typeof caps === 'object' ? caps : {};
+        // live 事件流用客户端名把会话挂到"谁派的"下面（仅名字/版本，不含其它字段）。
+        setLiveClient(params?.clientInfo);
         ok(id, {
           protocolVersion: typeof requested === 'string' ? requested : FALLBACK_PROTOCOL,
           capabilities: { tools: { listChanged: false } },

package/src/residue.mjs

@@ -15,6 +15,7 @@
  *     - runs/<id>/                     完成哨兵
  *     - reviews/<id>/                  调用方审核记录
  *     - locks/<id>.json                写锁持有者登记
+ *     - live/<id>/                     live 事件流（watch / dashboard 的数据源）
  *
  * ★ 护栏（和 purgeTestSessions 同一条）：只清"能证明是测试会话"的。证据按可信度：
  *     会话头里的 cwd > 元数据侧车里的 cwd > 注册表条目里的 cwd。
@@ -28,7 +29,7 @@
 import { existsSync, readFileSync, readdirSync, renameSync, rmSync, rmdirSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { tmpdir } from 'node:os';
-import { REVIEWS_DIR, RUNS_DIR, STATE_FILE } from './config.mjs';
+import { LIVE_DIR, REVIEWS_DIR, RUNS_DIR, STATE_FILE } from './config.mjs';
 import { LOCKS_DIR } from './locks.mjs';
 import { isTestSessionCwd, pruneTestWorkspaces, purgeOrphanProjcache, purgeTestSessions } from './workspace.mjs';
 
@@ -49,12 +50,13 @@ function resolveState(spec) {
     runsDir: s.runsDir ?? join(dir, 'runs'),
     reviewsDir: s.reviewsDir ?? join(dir, 'reviews'),
     locksDir: s.locksDir ?? join(dir, 'locks'),
+    liveDir: s.liveDir ?? join(dir, 'live'),
   };
 }
 
 /** 当前进程配置的状态目录（= MCP 服务默认用的那份，通常是 `~/.dsh/.dsh-any-agent`）。 */
 export function defaultState() {
-  return { stateFile: STATE_FILE, runsDir: RUNS_DIR, reviewsDir: REVIEWS_DIR, locksDir: LOCKS_DIR };
+  return { stateFile: STATE_FILE, runsDir: RUNS_DIR, reviewsDir: REVIEWS_DIR, locksDir: LOCKS_DIR, liveDir: LIVE_DIR };
 }
 
 const readJson = (file) => {
@@ -105,7 +107,7 @@ export function purgeProjectState({ ids, states, headerCwds = new Map(), trusted
   const trustedSet = trusted === true ? null : new Set(Array.isArray(trusted) ? trusted : []);
   const isTrusted = (id) => trusted === true || (trustedSet?.has(id) ?? false);
   const specs = (states?.length ? states : [defaultState()]).map(resolveState);
-  const res = { removed: { registry: 0, meta: 0, runs: 0, reviews: 0, locks: 0 }, refused: [], errors: [] };
+  const res = { removed: { registry: 0, meta: 0, runs: 0, reviews: 0, locks: 0, live: 0 }, refused: [], errors: [] };
   const wanted = [...new Set((ids ?? []).filter((x) => typeof x === 'string' && SAFE_ID.test(x)))];
 
   for (const st of specs) {
@@ -133,6 +135,7 @@ export function purgeProjectState({ ids, states, headerCwds = new Map(), trusted
     for (const id of allowed) {
       if (removePath(join(st.runsDir, id), dryRun)) res.removed.runs++;
       if (removePath(join(st.reviewsDir, id), dryRun)) res.removed.reviews++;
+      if (removePath(join(st.liveDir, id), dryRun)) res.removed.live++;
       if (removePath(join(st.locksDir, `${id}.json`), dryRun)) res.removed.locks++;
       if (removePath(join(st.metaDir, `${id}.json`), dryRun)) res.removed.meta++;
       // 侧车写到一半崩溃会留 `<id>.json.tmp.<pid>.<rand>`
@@ -215,6 +218,7 @@ export function sweepStateDir({ state, dryRun = false, removeEmptyDirs = false }
   };
   collect(spec.runsDir, false);
   collect(spec.reviewsDir, false);
+  collect(spec.liveDir, false);
   collect(spec.locksDir, true);
   collect(spec.metaDir, true);
   try {