dsh-root-planner-preset 1.1.5 → 1.1.6

package/README.md

@@ -122,9 +122,27 @@ Then **start a new session** and pick **Root Planner** in the preset selector. F
 
 **Verified**: the patch parses as loader YAML; the parsed persona is **byte-identical** to `persona.txt`; both delegation masks exclude every mutation entry point and name only tools the runtime reports as global; a clean checkout passes verification (`.gitattributes` pins LF, without which a Windows clone breaks the byte-identity check); the depth override reached the composed profile.
 
-**Fixed after a real failure**: a subagent spawn on a live `root-planner` session failed with `tools.restrict() names unknown global tool "subagent"`. The cause was a design error in this bundle, not a misconfiguration — `subagent` is registered inside each composed Agent's own scope, and a `toolFilter` takes global names only, so the mask was naming something it could never contain. The mask no longer names it, `verify-patch.mjs` asserts its absence by intent, and the mask is defined once in `child-tools.mjs` so the generator and the verifier cannot drift apart.
+**Verified end to end on a real task** — a 24-descendant run over a large reverse-engineering directory tree. Every line below was read from the session logs' own persisted tool schemas, which are the registry's output rather than a model's recollection:
 
-**Still not verified**: **no subagent has been spawned successfully under this preset yet.** Recursion is expected to work for the reason given above — the child inherits the preset and therefore its own scoped `subagent`, and a restriction does not hide scoped registrations — but that reasoning is exactly the kind that this bundle has already been wrong about once. Treat it as unconfirmed until someone reports a two-level delegation working.
+| Property | Evidence |
+|---|---|
+| The mask reaches every child | The root is offered **31** tools; depth-1 and depth-2 agents are offered **25**. The difference is exactly the six the mask omits: `workflow`, `present`, `job_output`, `job_list`, `job_kill`, `exit_plan_mode`. |
+| Subagents really are workers | `write`, `edit`, `ops_replace` and `pwsh` are present at every depth and were used: 10 `write` and 60 `edit` from the root, 14 `write` from one depth-1 agent, 20 `write` from a depth-2 agent. |
+| No subagent can leave a process running | `run_in_background` is absent from the `pwsh` schema at all three depths. (A naive log search says otherwise — the phrase also occurs in `ops_bash`'s own description, which is why `tools/check-pwsh-background.mjs` inspects the schema window instead.) |
+| Recursion works | 12 direct children, 4 of which delegated onward to 12 grandchildren; the root itself made 14 `subagent` calls. |
+| The depth cap holds | The tree stops at depth 2; no depth-3 session exists anywhere in the log directory. |
+| The live-child cap is soft, not fatal | One `subagent limit reached (active child limit: 8)` during an 8-wide fan-out. Settlements returned slots as children finished, and every later delegation succeeded. |
+
+**Corrected after the fact**: an earlier version of this file claimed the mask made
+children leaf agents. It does not. `subagent` is registered per composed agent rather
+than globally, so the mask can never name it — and because a restriction filters
+globals only, a child keeps it. Recursion is bounded by `maxDepth`, not by the mask.
+
+**How to check it yourself**: `tools/verify-session.mjs` proves which preset each
+session ran and at what depth, but it does not read tool schemas. Use
+`tools/extract-offered-tools.mjs` for the per-level tool list,
+`tools/check-pwsh-background.mjs` for the process bound, and
+`tools/count-tool-calls.mjs` for what a level actually called.
 
 ## Contributing
 

package/README.zh.md

@@ -102,9 +102,20 @@ dsh plugin --profile web add github:XiaoOu2024/dsh-root-planner-preset
 
 **已验证**：补丁可被 loader 解析；解析出的人设与 `persona.txt` **逐字节相同**；两个委派工具的白名单排除了所有写入入口、且只包含**运行时报告的全局工具**；干净检出后校验通过（`.gitattributes` 已钉死 LF，否则 Windows 克隆会破坏逐字节校验）；深度覆盖已落到合成配置。
 
-**因一次真实故障而修复**：在跑着 `root-planner` 的会话里创建子代理失败，报 `tools.restrict() names unknown global tool "subagent"`。根因是本包**设计上的错误**，不是配置错误——`subagent` 注册在每个被组合 Agent 自身的作用域里，而 `toolFilter` 只接受全局工具名，白名单写了一个它永远不可能合法包含的名字。现在白名单不再写它，`verify-patch.mjs` 会**按意图断言它必须缺席**，白名单也收敛到 `child-tools.mjs` 单一真源，生成器与校验脚本不可能再各说各话。
+**已在真实任务上端到端验证**——那次运行在一个大型逆向工程目录树上产生了 **24 个后代会话**。下面每一条都读自**会话日志自己持久化的工具 schema**，那是注册表的输出，不是模型的回忆：
 
-**仍未验证**：**还没有一次成功的子代理派出。** 递归按上面的理由**应当**可用——子代理继承预设、因此拥有自己的作用域 `subagent`，而限制不会隐藏作用域注册——但这个推理恰好就是本包已经错过一次的那类推理。在有人报告"两层委派成功"之前，请当作未确认。
+| 性质 | 证据 |
+|---|---|
+| 白名单覆盖每一层 | 根被提供 **31** 个工具；深度 1 与深度 2 的 agent 都是 **25** 个。差额正好是白名单排除的那 6 个：`workflow`、`present`、`job_output`、`job_list`、`job_kill`、`exit_plan_mode`。 |
+| 子代理确实是工人 | `write`、`edit`、`ops_replace`、`pwsh` 在每一层都在，而且真的被用了：根 10 次 `write` + 60 次 `edit`，某个深度 1 的子代理 14 次 `write`，某个深度 2 的孙代理 20 次 `write`。 |
+| 子代理留不下运行中的进程 | `run_in_background` 在三个层级的 `pwsh` schema 里**都不存在**。（朴素的全日志搜索会给出相反答案——`ops_bash` 自己的描述里也有这个词，所以要用 `tools/check-pwsh-background.mjs` 看 schema 窗口。） |
+| 递归成立 | 12 个直接子代理，其中 4 个继续派出了 12 个孙代理；根自己做了 14 次 `subagent` 调用。 |
+| 深度上限有效 | 树停在深度 2；整个日志目录里不存在任何深度 3 的会话。 |
+| 在世上限是软拒绝而非致命 | 8 路扇出时出现一次 `subagent limit reached (active child limit: 8)`；子代理完结时结算通知归还了槽位，此后每次委派都成功。 |
+
+**一处事后更正**：本文件早期版本称"白名单让子代理成为叶子"。**并非如此。** `subagent` 是按每个被组合 Agent 注册、而非全局注册，所以白名单**永远无法写下它的名字**；而限制只过滤全局工具，因此子代理**保有此工具**。递归的边界是 `maxDepth`，不是白名单。
+
+**想自己核**：`tools/verify-session.mjs` 能证明每个会话跑的是哪个预设、深度多少，但它不读工具 schema。逐层工具清单用 `tools/extract-offered-tools.mjs`，进程边界用 `tools/check-pwsh-background.mjs`，实际调用用 `tools/count-tool-calls.mjs`。
 
 ## 参与维护
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-root-planner-preset",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "type": "module",
   "description": "DSH agent preset that outsources file reading to strictly read-only subagents, while the root agent keeps the plan and owns every file mutation.",
   "license": "MIT",

package/tools/check-pwsh-background.mjs

@@ -0,0 +1,91 @@
+// Checks whether `run_in_background` still exists inside a session's `pwsh` tool
+// schema — the one property this preset enforces structurally rather than by asking
+// the model nicely.
+//
+// A whole-log substring search cannot answer it: the phrase also appears in
+// `ops_bash`'s own description on this machine, so the naive check reports "present"
+// for a session where the parameter has genuinely been removed.
+//
+// Usage: node tools/check-pwsh-background.mjs <session-dir> [...]
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createZstdDecompress } from 'node:zlib';
+
+/** Locate the end of the first zstd frame, where the next one begins. */
+function frameEnd(buf) {
+  for (let i = 4; i + 4 <= buf.length; i += 1) {
+    if (buf[i] === 0x28 && buf[i + 1] === 0xb5 && buf[i + 2] === 0x2f && buf[i + 3] === 0xfd) return i;
+  }
+  return buf.length;
+}
+
+/** Decompress a concatenated-zstd log frame by frame. */
+async function decompressAll(buf) {
+  let rest = buf;
+  let text = '';
+  while (rest.length > 0) {
+    const slice = rest.subarray(0, frameEnd(rest));
+    try {
+      text += await new Promise((resolve, reject) => {
+        const chunks = [];
+        const dec = createZstdDecompress();
+        dec.on('data', (chunk) => chunks.push(chunk));
+        dec.on('error', reject);
+        dec.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        dec.end(slice);
+      });
+    } catch {
+      break;
+    }
+    if (slice.length >= rest.length) break;
+    rest = rest.subarray(slice.length);
+  }
+  return text;
+}
+
+/**
+ * Find every `"name":"<tool>"` occurrence and return the window of text that follows
+ * it — close enough to hold that tool's own parameters object.
+ * @param text - whole decompressed log.
+ * @param tool - tool name to locate.
+ * @returns the following windows, longest first.
+ */
+function windowsAfter(text, tool) {
+  const needle = `\\"name\\":\\"${tool}\\"`;
+  const plain = `"name":"${tool}"`;
+  const out = [];
+  for (const pattern of [needle, plain]) {
+    let from = 0;
+    for (;;) {
+      const at = text.indexOf(pattern, from);
+      if (at === -1) break;
+      out.push(text.slice(at, at + 4000));
+      from = at + pattern.length;
+    }
+  }
+  return out.sort((a, b) => b.length - a.length);
+}
+
+for (const dir of process.argv.slice(2)) {
+  const text = await decompressAll(readFileSync(join(dir, 'session.v4.jsonl.zstd')));
+  const header = JSON.parse(text.split('\n')[0]);
+
+  const pwshWindows = windowsAfter(text, 'pwsh');
+  // The parameters object is the one that mentions the tool's own argument names.
+  const schemaWindow = pwshWindows.find((w) => w.includes('workdir') || w.includes('command')) ?? pwshWindows[0] ?? '';
+  const backgroundInSchema = /run_in_background/.test(schemaWindow);
+  const backgroundAnywhere = text.includes('run_in_background');
+
+  process.stdout.write(
+    `\n${dir.split(/[\\/]/).pop().slice(0, 20)}  depth=${header?.delegationDepth}\n` +
+      `  "run_in_background" anywhere in the log : ${backgroundAnywhere}\n` +
+      `  inside the pwsh schema window          : ${backgroundInSchema}` +
+      `${backgroundInSchema ? '  <-- the parameter is still offered' : '  <-- removed, as intended'}\n` +
+      `  pwsh schema window size                 : ${schemaWindow.length} chars\n`,
+  );
+  if (backgroundAnywhere && !backgroundInSchema) {
+    const at = text.indexOf('run_in_background');
+    process.stdout.write(`  first mention context: …${text.slice(Math.max(0, at - 120), at + 60)}…\n`);
+  }
+}

package/tools/child-status.mjs

@@ -0,0 +1,102 @@
+// Reports whether each child session in a run is finished or still active, from its
+// own log — the question behind "subagent limit reached": are slots being held by
+// children that already stopped, or by children that are genuinely still working?
+//
+// Usage: node tools/child-status.mjs <root-session-dir>
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { createZstdDecompress } from 'node:zlib';
+
+/** Locate the end of the first zstd frame, where the next one begins. */
+function frameEnd(buf) {
+  for (let i = 4; i + 4 <= buf.length; i += 1) {
+    if (buf[i] === 0x28 && buf[i + 1] === 0xb5 && buf[i + 2] === 0x2f && buf[i + 3] === 0xfd) return i;
+  }
+  return buf.length;
+}
+
+/** Decompress a concatenated-zstd log frame by frame. */
+async function decompressAll(buf) {
+  let rest = buf;
+  let text = '';
+  while (rest.length > 0) {
+    const slice = rest.subarray(0, frameEnd(rest));
+    try {
+      text += await new Promise((resolve, reject) => {
+        const chunks = [];
+        const dec = createZstdDecompress();
+        dec.on('data', (chunk) => chunks.push(chunk));
+        dec.on('error', reject);
+        dec.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        dec.end(slice);
+      });
+    } catch {
+      break;
+    }
+    if (slice.length >= rest.length) break;
+    rest = rest.subarray(slice.length);
+  }
+  return text;
+}
+
+const rootDir = process.argv[2];
+if (rootDir === undefined) {
+  process.stderr.write('usage: node tools/child-status.mjs <root-session-dir>\n');
+  process.exit(2);
+}
+
+const base = join(rootDir, '..');
+const rootId = rootDir.split(/[\\/]/).pop();
+const rows = [];
+
+for (const name of readdirSync(base)) {
+  const file = join(base, name, 'session.v4.jsonl.zstd');
+  try {
+    if (!statSync(file).isFile()) continue;
+  } catch {
+    continue;
+  }
+  const text = await decompressAll(readFileSync(file));
+  const events = text
+    .split('\n')
+    .filter((line) => line.trim().length > 0)
+    .flatMap((line) => {
+      try {
+        return [JSON.parse(line)];
+      } catch {
+        return [];
+      }
+    });
+  const header = events[0];
+  if (name !== rootId && header?.origin !== 'subagent') continue;
+
+  const types = new Map();
+  for (const event of events) types.set(event.type, (types.get(event.type) ?? 0) + 1);
+
+  const last = events[events.length - 1];
+  rows.push({
+    id: name,
+    depth: header?.delegationDepth,
+    mtime: statSync(file).mtime,
+    events: events.length,
+    lastType: last?.type,
+    lastTime: last?.time,
+    // A turn that ended and left nothing pending is the shape of a settled child.
+    turnEnds: types.get('turn/end') ?? 0,
+    hasInboxPending: types.has('agent/inbox/spliced') && !types.has('agent/inbox/claimed'),
+    cancels: types.get('agent/cancel') ?? 0,
+  });
+}
+
+rows.sort((a, b) => (a.lastTime ?? 0) - (b.lastTime ?? 0));
+const fmt = (ms) => (ms === undefined ? '?' : new Date(ms).toISOString().slice(11, 19));
+
+process.stdout.write(`${rows.length} agent session(s) under ${base}\n\n`);
+process.stdout.write('depth  turnEnds  events  last event type           last event time  session\n');
+for (const row of rows) {
+  process.stdout.write(
+    `${String(row.depth ?? '-').padEnd(6)} ${String(row.turnEnds).padEnd(9)} ${String(row.events).padEnd(7)} ` +
+      `${String(row.lastType ?? '-').padEnd(25)} ${fmt(row.lastTime).padEnd(16)} ${row.id.slice(0, 20)}\n`,
+  );
+}

package/tools/count-tool-calls.mjs

@@ -0,0 +1,78 @@
+// Counts the tool calls actually made in one session, by name.
+//
+// Written to settle a question that string counting cannot: which delegation tool a
+// given level really called, and therefore which tools the child mask actually left
+// visible. A raw occurrence count of "subagent" matches "subagent_fork" too, and the
+// preset's own prose mentions both.
+//
+// Usage: node tools/count-tool-calls.mjs <session-dir> [...]
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createZstdDecompress } from 'node:zlib';
+
+/** Locate the end of the first zstd frame, where the next one begins. */
+function frameEnd(buf) {
+  for (let i = 4; i + 4 <= buf.length; i += 1) {
+    if (buf[i] === 0x28 && buf[i + 1] === 0xb5 && buf[i + 2] === 0x2f && buf[i + 3] === 0xfd) return i;
+  }
+  return buf.length;
+}
+
+/** Decompress a concatenated-zstd log frame by frame. */
+async function decompressAll(buf) {
+  let rest = buf;
+  let text = '';
+  while (rest.length > 0) {
+    const slice = rest.subarray(0, frameEnd(rest));
+    try {
+      text += await new Promise((resolve, reject) => {
+        const chunks = [];
+        const dec = createZstdDecompress();
+        dec.on('data', (chunk) => chunks.push(chunk));
+        dec.on('error', reject);
+        dec.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        dec.end(slice);
+      });
+    } catch {
+      break;
+    }
+    if (slice.length >= rest.length) break;
+    rest = rest.subarray(slice.length);
+  }
+  return text;
+}
+
+for (const dir of process.argv.slice(2)) {
+  const text = await decompressAll(readFileSync(join(dir, 'session.v4.jsonl.zstd')));
+  const events = text
+    .split('\n')
+    .filter((line) => line.trim().length > 0)
+    .flatMap((line) => {
+      try {
+        return [JSON.parse(line)];
+      } catch {
+        return [];
+      }
+    });
+
+  const header = events[0];
+  const calls = new Map();
+  for (const event of events) {
+    if (event.type !== 'tool/call') continue;
+    const name = event.data?.name ?? event.data?.message?.name;
+    if (typeof name !== 'string') continue;
+    calls.set(name, (calls.get(name) ?? 0) + 1);
+  }
+
+  const name = dir.split(/[\\/]/).pop().slice(0, 20);
+  process.stdout.write(
+    `\n${name}  depth=${header?.delegationDepth}  origin=${header?.origin}  ${events.length} events\n`,
+  );
+  const rows = [...calls.entries()].sort((a, b) => b[1] - a[1]);
+  process.stdout.write(`  ${rows.length} distinct tools called: ${rows.map(([t, n]) => `${t}×${n}`).join(', ') || '(none)'}\n`);
+  const delegation = rows.filter(([t]) => t.startsWith('subagent'));
+  process.stdout.write(
+    `  delegation calls: ${delegation.map(([t, n]) => `${t}×${n}`).join(', ') || '(none)'}\n`,
+  );
+}

package/tools/extract-offered-tools.mjs

@@ -0,0 +1,69 @@
+// Extracts the tool names a session was actually offered, from the tool schemas the
+// session log persists.
+//
+// Why this exists: a subagent's own account of its tools is a language-model
+// recollection, and it can be wrong in both directions (the first such report
+// omitted `write` from its list while claiming to discuss it). The persisted
+// schemas are the registry's own output, so they settle questions like "does the
+// child mask really apply?" and "is run_in_background gone?" without guessing.
+//
+// Usage: node tools/extract-offered-tools.mjs <session-dir> [...]
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createZstdDecompress } from 'node:zlib';
+
+/** Locate the end of the first zstd frame, where the next one begins. */
+function frameEnd(buf) {
+  for (let i = 4; i + 4 <= buf.length; i += 1) {
+    if (buf[i] === 0x28 && buf[i + 1] === 0xb5 && buf[i + 2] === 0x2f && buf[i + 3] === 0xfd) return i;
+  }
+  return buf.length;
+}
+
+/** Decompress a concatenated-zstd log frame by frame. */
+async function decompressAll(buf) {
+  let rest = buf;
+  let text = '';
+  while (rest.length > 0) {
+    const slice = rest.subarray(0, frameEnd(rest));
+    try {
+      text += await new Promise((resolve, reject) => {
+        const chunks = [];
+        const dec = createZstdDecompress();
+        dec.on('data', (chunk) => chunks.push(chunk));
+        dec.on('error', reject);
+        dec.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        dec.end(slice);
+      });
+    } catch {
+      break;
+    }
+    if (slice.length >= rest.length) break;
+    rest = rest.subarray(slice.length);
+  }
+  return text;
+}
+
+for (const dir of process.argv.slice(2)) {
+  const text = await decompressAll(readFileSync(join(dir, 'session.v4.jsonl.zstd')));
+
+  // A tool schema is an object carrying `name` plus `parameters` (and `description`).
+  // Collect every name that appears next to a parameters object anywhere in the log.
+  const names = new Set();
+  for (const match of text.matchAll(/\{\\?"name\\?":\\?"([a-zA-Z_][a-zA-Z0-9_]*)\\?":\{[^{}]*\\?"type\\?":\\?"object\\?"/g)) {
+    names.add(match[1]);
+  }
+  for (const match of text.matchAll(/\\?"name\\?":\\?"([a-zA-Z_][a-zA-Z0-9_]*)\\?",\\?"description\\?":/g)) {
+    names.add(match[1]);
+  }
+
+  const header = JSON.parse(text.split('\n')[0]);
+  const listed = [...names].sort();
+  process.stdout.write(
+    `\n${dir.split(/[\\/]/).pop().slice(0, 20)}  depth=${header?.delegationDepth}\n  ${listed.length} names: ${listed.join(', ')}\n`,
+  );
+  for (const probe of ['workflow', 'present', 'job_output', 'exit_plan_mode', 'subagent', 'subagent_fork', 'pwsh', 'write']) {
+    process.stdout.write(`    ${probe.padEnd(16)} ${names.has(probe) ? 'present' : 'ABSENT'}\n`);
+  }
+}