super-dsh 0.3.0-c → 0.3.0-e

package/node_modules/better-dsh/docs/10_plans/kernel-refactoring/actinoable-surface-to-llm-in-agent-runtime_prime.md

@@ -1,113 +0,0 @@
-# Self Survey of `dsh` (DeepSeek Harness Agent) and Prime Agent - Actionable Surface to LLM in Agent runtime
-
-
-- Actionables: tools, toolset(s), skills, bash, executable code scripts (e.g. python ...)
-- Surface to LLM: the text/prompts exposed to LLM during agent runtime
-
-
-
-
-## Prime Agent(第一人称:Prime Agent 运行时自述)
-
-### 地基 — 我"调用工具"的 wire 形态(function calling)
-
-- 和 dsh 是同一个 function-calling JSON:`Function: { name, arguments }` —— 只有两个 element,`name` 平级、无 `tools.` 之类前缀命名空间。
-- **但我的平级工具枚举清单里只有一个名字:`ipython`。** 所以 wire 层固定是:`name` 只有 `"ipython"` 一种取值;`arguments` 只有一个必填键 `code`(字符串)。没有别的字段。
-
-- 我发出的真实 wire 原文(从我自己这个 session 的日志里抄的,一字未改):
-
-```json
-{"type": "toolCall", "id": "call_00_wf7zeFy6KRIXEaeC5zZS3896",
- "name": "ipython",
- "arguments": {"code": "%%bash\nls -la /home/u1/workspaces/dashr/dev/kernel-refactoring/"}}
-```
-
-- 客户端拿 `name: "ipython"` 定位唯一执行器,把 `arguments.code` 整段交给**常驻 IPython kernel** 执行,把我 print / 显示出来的 stdout 文本塞回 toolResult(原文照抄,stderr 与 kernel 状态另列):
-
-```json
-{"role": "toolResult", "toolCallId": "call_00_wf7zeFy6KRIXEaeC5zZS3896",
- "toolName": "ipython",
- "content": [{"type": "text", "text": "<cell 的 stdout>"}],
- "details": {"durationMs": 472, "status": "ok", "stdout": "...", "stderr": "", "kernelRestarted": false},
- "isError": false}
-```
-
-- **`await` 不在 wire 层,在 `code` 层**——`await` 是 Python 语法,发生在我写进 `arguments.code` 的那段程序里面。完整的语法链就四步:
-
-  1. 我要做一个动作 → 想好一段 **Python 程序**(一句话也是一个程序);
-  2. 把它写进 `arguments.code`(可以是 `await 技能函数(...)`、`%%bash` cell、`rlm(...)`、或任意 Python);
-  3. 发出唯一形态的 JSON:`Function: { name: "ipython", arguments: { code: "<那个程序>" } }`;
-  4. kernel 跑完,stdout 原样作为 toolResult 回到我的上下文,我再决定下一轮。
-
-- wire 示例(全部是同一个工具名,差别只在 `code` 里):
-
-```json
-// 例子1:调用联网技能 —— await 发生在 code 里
-Function: { name: "ipython", arguments: {"code": "await websearch('prime agent')"} }
-
-// 例子2:shell —— %%bash 必须是 code 的第一行
-Function: { name: "ipython", arguments: {"code": "%%bash\nls -la"} }
-
-// 例子3:子代理 admission —— 返回的是句柄,不是答案
-Function: { name: "ipython", arguments: {"code": "h = await rlm('sub-task', name='worker')"} }
-```
-
-### Actionables — 全部经 `ipython` 的 `code` 触达(没有第二层工具枚举)
-
-wire 层是平的、只有一个名字;dsh 那 29 个平级工具对应到我这边的全部"动作清单",都是我写进 `code` 里的 Python 对象:
-
-- **内核全局预导入的 9 个 python skill 模块**,调用形态统一是 `await <模块>.<函数>(...)`,返回值可绑定变量、可组合:
-  `agent_message`(send / list_agents)、`agent_observe`、`attach_image`、`compact`、`edit`、`goal`、`refine`(run)、`rlm_heartbeat`、`websearch`
-- **内核全局 `rlm`**:`await rlm('sub-task')`(非阻塞 admission,返回 rlm_child_id/name/session_dir/model,永不返回答案)、`rlm.list_subagents()`、`rlm.delete_subagent()`、`rlm.find_models()`、`rlm.get_harness_state()`、`rlm.harness.*`(memory / prompt_note / skill / subagent-spec 四类 CRUD,默认 session 本地,`global_=True` 才跨会话)
-- **`%%bash` cell**(必须是 `code` 的第一行)——shell、项目命令、CLI 全走这里;**没有独立的 bash 工具名**
-- **任意 Python**:stdlib 读/写/搜索文件、编排进程、`uv pip install` 装包、`%cd` / `os.environ` 管内核状态
-- **每个 skill 的 shell CLI**:`<skill> ...`(在 %%bash 里跑)
-- **markdown skills**(项目 `.agents/skills` 向上收集 + 用户级 + 捆绑 dist):不是 callable 绑定,用 ipython 读它们的 SKILL.md 学 API
-- **没有的东西**:read / write / glob / grep / todo_write / subagent / send_message……这些名字在我的 wire 枚举里**不存在**;对应能力 = code 里的 Python 或 skill 函数。这条不是靠运行时报错兜底,是 schema 面根本不暴露。
-
-### Surface to LLM — 我暴露给模型的文本
-
-- 系统提示正文(每次请求动态组装,顺序固定):code-first 人设开篇 → IPYTHON_CONTROL_PROMPT(长驻 notebook、%%bash 纪律、状态持久、await 调用、"do not invent non-native wrappers" 等反模式明令)→ RLM-native call contract → delegation doctrine(子代理 admission/消息/观察拓扑)→ continual harness 状态菜单(prompt/memory/skill/subagent 计数)→ 项目 AGENTS.md 链(Project Context)→ 会话变量:cwd、conversation log 路径、recursive agent depth、预装 Python 包清单
-- 工具 schema:只有 `ipython` 一个(`name` + `parameters:{code: string}`,description 写在 schema 里,正文不重复列工具目录)
-- skills catalog:`<available_skills>` XML 块拼在正文里(当前 session 26 条:name / type / python_import / description / location,措辞是 kernel 形态)
-- SKILL.md 本体:不注入;我用 ipython 读文件学 API
-- 对话历史 + 压缩(compact skill;单条 cell 输出截断上限默认 2000 行 / 50KB)
-- kernel 事件通知:`<ipython_kernel_reset>` 标记、interrupted cell 的 wait/kill 选择提示
-
-
-### 组合性 — 预绑定的名字是「Python 类型化的内置工具」,可当一等对象组合(本 session 已实测)
-
-- 术语(建议 Dash prompt 也采用):**Python 类型化的内置工具(typed Python built-in tools)**。它们不是 wire 层的 function call,而是 kernel 全局命名空间里的 typed Python 对象:
-  - `edit` = 可调用模块,成员 `run(path, old_str, new_str) -> str` 是 async 函数,抛 `FileNotFoundError` / `ValueError`
-  - `rlm` = 可调用模块(`rlm(...)` 即 spawn),成员 run / find_models / list_subagents / delete_subagent / harness / get_harness_state
-  - 实现层:`edit` 是进程内 async Python 函数(`Path.read_text/write_text` 直接 syscall),零 shell 零 subprocess
-- 实测组合模式(全部真实执行):
-
-| 组合模式 | 写法 | 结果 |
-|---|---|---|
-| 条件 | `if "x" in Path(p).read_text(): await edit(...)` | ✅ |
-| 异常 | `except ValueError` / `except FileNotFoundError` | ✅ 类型化异常 |
-| 重试 | for + try/except,失败换更宽 old_str | ✅ |
-| 批量 / 并行 | for 收集返回值 / `asyncio.gather(*[edit(...)])` | ✅ |
-| 对象化 | 存 dict、当参数传、自写 `safe_edit()` wrapper(加重试/降级策略) | ✅ |
-
-- 对照:平级 function call(DSH/Hermes)里组合只能发生在模型脑内、跨多轮往返、非确定;这里组合发生在确定性 Python 代码里,一个 cell 一轮往返。
-- **反面证据(诚实记录)**:本 session 的 system prompt 关于组合只有一句 "composed into program logic just like any other call",无例子、未说明是 typed 对象 → 本 session 模型未自发组合过一次(写文件全用裸 Python)。结论:**不写清楚,模型就不会。**(此为 prompt 缺口,补丁见下节)
-
-### 状态管理 — cell 化之后的「可回查状态机」(本 session 已实测)
-
-三种后台句柄,全部跨 cell 存活于 kernel 命名空间、可回查、可控制:
-
-| 句柄 | 创建 | 回查状态 | 控制 |
-|---|---|---|---|
-| asyncio Task | `t = asyncio.create_task(coro())` | `t.done()` / `t.result()` | `t.cancel()` |
-| 子进程(Hermes job/PID 等价物) | `p = subprocess.Popen(...)` | `p.poll()` / `p.pid` | `p.kill()` / `p.wait()` |
-| rlm 子代理 | `h = await rlm('sub-task')` | `rlm.list_subagents()` → `status` 字段 | `rlm.delete_subagent(h)` |
-
-- `await` 是"等"的语法;`asyncio.create_task` / Popen 是"不等"的句柄 —— 本 session 的 prompt 只教了 await,没教 async 句柄,这是第二个 prompt 缺口。
-- rlm 实测闭环:admission 立即返回 `RLMSpawnHandle(rlm_child_id, session_dir, model)` → `list_subagents()` 查 `status='completed'` → `delete_subagent` 回收 → 子代理回复经 agent_message **事件驱动送达**(实测:delete 之后消息仍到达,投递队列与句柄注册表解耦)。
-- 长命令(`%%bash` curl 等):包进 create_task/Popen,句柄落 kernel 命名空间,下一 cell 回查;kernel 死则句柄丢(进程还活,句柄没了)。
-
-### 建议 prompt 补丁(Prime upstream `IPYTHON_CONTROL_PROMPT` 与 Dash preset 共用)
-
-> Pre-imported skill modules and the global `rlm` are typed Python objects, not wire-level tools: each exposes documented async functions and raises typed exceptions (e.g. `edit` raises `FileNotFoundError`/`ValueError`). Treat them as first-class values: compose them with conditionals, `try/except` on their typed errors, loops, `asyncio.gather` for parallelism, custom wrapper functions for retry/degradation policies, or storage in data structures. For background work, keep pollable handles in the kernel namespace: `asyncio.create_task` → `done()/result()/cancel()`; `subprocess.Popen` → `pid/poll()/kill()`; `rlm()` admission → `rlm.list_subagents()/delete_subagent()`, with results arriving asynchronously via `agent_message`. Prefer composing multiple tool calls inside one cell over issuing them one call per cell.

package/node_modules/better-dsh/docs/10_plans/recallable-compaction.md

@@ -1,147 +0,0 @@
-# Recallable Compaction（可回溯压缩）— 设计备忘
-
-> 状态：设计备忘（**未实现**）· 2026-08-20 · 用户方向 + API 面 spike 验证通过
-> 归属：`dashr/dev/`（gitignored 本地 scratch，不进公开仓库）
-> 上游文档：`dev/dashr-compaction-window-and-archive.md`（Feature 2 压缩损失补偿的总纲；本文档是其「回溯通道」的落地设计，并回收其 §3 开放问题中已解决项）
-
-## 0. 背景：Context as variable 的四方向与本 gap
-
-dashr 参考 Prime Agent 的三个核心特点（RLM 模式 / IPython REPL tool calling / Context as variable）中，前两个已完全实现；第三个目前只实现一半。完全体的四个方向：
-
-| 方向 | 状态 |
-|---|---|
-| 1. 事件流过滤 | ✅ 已实现（`recencyWindowTokens`，Feature 1，v0.1.1+） |
-| 2. 运行时变量存取 | ✅ 已实现（kernel 变量自由存取） |
-| 3. **上下文压缩与回溯** | ❌ **未实现 ← 本文档** |
-| 4. 广义上下文组件化 | ✅ 已实现（Continual Harness / `refine()`） |
-
-方向 3 的缺口：压缩后旧上下文被摘要 shadow，运行时模型无法直接读取原文（原文虽在 session 持久化文件中，但模型经资源工具查询繁琐且难定位）。Feature 2 原设计（强制归档 + 摘要尾部标记）解决「可恢复」，本文档补上「模型可寻址的回溯通道」与全部 API 面验证。
-
-## 1. Spike 结论（2026-08-20，Dash agent 实证 + 本机复验）
-
-> 委托方式：Dash HTTP API（session `session-a2a61011`，`cwd=/home/u1/workspaces/dashr`，rlm-mode preset）。证据脚本 `dev/spike-tag-repro.mjs` 已随文档保存，本机复跑 exit 0、输出吻合。
-
-| # | 事实 | 对设计的影响 |
-|---|---|---|
-| 1 | surface 是 **append-only + 深冻结** 的不可变投影；唯一写入口 `Session.append`；**不存在原地 patch 节点文本的 API** | 不能 mutate，只能 replace |
-| 2 | 「改写单个节点」的官方正解 = 再 append 一个 `replace`，`start === end === 目标 seq`，新节点 shadow 旧节点 —— 这正是上游 compaction 改写历史所用的同一机制 | 挂 tag 的通道 ✓ |
-| 3 | 新摘要节点 seq = **`result.summarySeq + 1`**（contractual adjacency；`commitCompactionBody` 源码确认：`compaction/summary` 事件后紧邻 `user/message` 替换节点，`= endSeq - 1`） | 摘要节点可精确定位 ✓ |
-| 4 | 被 shadow 的原文**事后仍可读**：`session.events[shadowedSeqs]` 完整保留（append-only log 不删除，shadow 只是从 surface 投影隐去） | **归档不必在压缩前捕获** —— 顺序约束消失 |
-| 5 | `user/message` 重写无限制（`assertToolResultRewrite` 只约束 `tool/result`） | 摘要文本可自由追加 tag 块 |
-| 6 | 替换节点保留原 `source`（含 `compactionId`）时，下游 checkpoint 识别（`isCompactCheckpointSource`）不破 | tag 挂载无损 ✓ |
-
-**关键修正**：原方案「归档先于压缩」（压缩前取到将被 shadow 的区间 → 归档 → 才允许压缩）不再需要。事实 #3+#4 意味着顺序可以是**先压缩、后归档、再挂 tag**——每一步只依赖已提交的事实，**tag 永不悬挂，无需任何补偿逻辑**。
-
-## 2. 设计：三步流程
-
-在 `compactIfNeeded`（与 `compactNow` 共用）的 `compactRegion` 返回之后：
-
-1. **读原文**（事后，从 append-only log）：`result.shadowedSeqs` → `session.deriveEventMessage(session.events[seq])` → 分类 → 序列化。
-2. **写归档存储**：介质二选一（§2.2，待用户拍板）。
-3. **挂 tag**：单节点 `replace`（`start === end === result.summarySeq + 1`），把 tag 文本块追加到摘要内容尾部。
-
-归档失败时降级为现状行为（照常压缩、仅无 tag），**不阻塞压缩**（沿用旧 doc 原则）。
-
-### 2.1 分类（沿用旧 doc §2.2，纯机械非语义）
-
-| bucket | 来源 | 说明 |
-|---|---|---|
-| `user_requests` | user 消息 | 用户指令原文 |
-| `assistant_responses` | assistant 消息 | 正文 verbatim；thinking 块剥除与否见开放项 |
-| `tool_results` | toolResult 消息 | 含 cell stdout |
-| `file_ops` | 机械提取 | read/modified 列表 |
-
-### 2.2 归档介质（开放决策，二选一）
-
-**方案 K — kernel 变量 + dill snapshot**（旧 doc 原方案）：
-- 复用 State Storage，实现量最小。
-- 代价：(a) trunk 与用户工作变量抢同一个 `capBytes` 预算，超限时**整个 snapshot 被 skip**（连用户变量一起丢）；(b) dill 跨 Python 版本脆弱；(c) 原文常驻 kernel 进程 RAM，随压缩次数线性涨。
-
-**方案 F — 独立 trunk 文件 + kernel 索引 + `recall()` 读文件**（推荐）：
-- trunk 本体 = 纯文本 JSON（带 role/seq），落 `kernel-snapshots/<sessionId>/trunks/<compactionId>.json`；kernel 里只放索引 dict（tag → 路径）；`recall(tag)` helper 直接读文件。
-- 好处：独立预算天然成立（不吃 snapshot cap）；写入即时持久（无 snapshot 的 1500ms debounce 窗口）；恢复 = 回填索引或重扫目录；绕开 dill 版本问题。
-- 代价：recall 读文件比读内存慢几毫秒，对 LLM 无感。
-- State Storage 职责因此更清晰：snapshot 管用户工作变量，trunk store 管压缩原文。
-
-### 2.3 tag 与 recall 协议
-
-- tag id：`ctx-<compactionId>`（或自增计数）。
-- tag 文本块（挂摘要尾部，格式示例）：
-
-```
-[原文回溯: ctx-12]
-本轮压缩的原始上下文已归档，需要细节时用 recall('ctx-12') 读取。
-```
-
-- `recall(tag)` helper（py-sdk 注入）：保留命名空间藏 trunk 数据（**不暴露裸全局**，防模型 cell 误覆盖/`del`）；只读访问；超长输出截断提示；缺失报明确错误。
-- Control Prompt 增加约定段：摘要条目带 `ctx-N` 标签时，需要全文就 `recall('ctx-N')`。
-- token 经济学：摘要照常在上下文（tag 一行文本 ≈ 0 成本）；模型只在需要时付出一次读取成本；归档不查询则不进上下文。
-
-### 2.4 预算与淘汰（开放数字）
-
-归档随压缩次数线性增长，必须设上限，否则省下的上下文 token 从 RAM/磁盘侧门还回去。候选：最近 N 档 / 总 token 预算 / LRU。淘汰是安全的——session log 里原文永远在（§2.5）。
-
-### 2.5 自愈（compactionId 稳定性）
-
-tag 携带 `compactionId + shadowedSeqs`；revive 时发现归档缺失，可从 session log 重放重建。本质：**session log 就是原文的持久层，归档只是模型可寻址的快路径缓存**。
-
-### 2.6 两条触发路径（共用挂点）
-
-- auto pressure：`RecencyAwareCompactionEngine.compactIfNeeded`
-- manual：`/compact` → `compactNow`
-- 挂点都在 `compactRegion` 返回后，路径无关。
-
-## 3. 代码骨架（compactRegion 返回后）
-
-```ts
-const result = await this.compactRegion(range.start, range.end, agent, signal)
-if (result === null) return null
-
-const session = agent.session
-const summaryNodeSeq = result.summarySeq + 1        // contractual adjacency
-
-// 1) 事后读原文（append-only log 完整保留）
-const original = result.shadowedSeqs
-  .map(seq => session.deriveEventMessage(session.events[seq]))
-  .filter((m): m is Message => m !== null)
-// 2) 归档（介质见 §2.2，失败则跳过第 3 步、不阻塞压缩）
-const tagId = `ctx-${result.compactionId}`
-// await archiveRecall(tagId, classify(original))   // 分类见 §2.1
-// 3) 单节点 replace 挂 tag
-const summaryMsg = session.deriveEventMessage(session.events[summaryNodeSeq])!
-session.append('user/message', createUserMessage({
-  content: [...summaryMsg.content, { type: 'text', text: `\n[原文回溯: ${tagId}] 全文可通过 recall('${tagId}') 读取。` }],
-  source: summaryMsg.source,                        // 保留 compactionId，checkpoint 识别不破
-}), {
-  surfaceOp: { op: 'replace', start: summaryNodeSeq, end: summaryNodeSeq },
-  sourceEventSeqs: [summaryNodeSeq],
-})
-```
-
-## 4. 与旧 doc §3 开放问题对照
-
-| # | 问题 | 状态 |
-|---|---|---|
-| 1 | 实现路径 A/B/C | 已裁定方案 B（子类化），Feature 1 已落地 v0.1.1+ |
-| 3 | 摘要后编辑口 | **已解决**（本文档 §1）：落盘前无插入口，落盘后单节点 replace 等效；且原文可事后读取，归档无需压缩前捕获 |
-| 8 | compactionId 稳定性 | **已解决**（§2.5 自愈：log 重放重建） |
-| 4 | 归档增长上限 | 仍开放（§2.4 候选方案） |
-| 5 | thinking 块剥不剥 | 仍开放（剥=省空间丢推理过程；留=完整但体积翻倍） |
-| 6 | 标记措辞与 token 预算 | 仍开放（§2.3 给出了候选格式） |
-| 7 | 与 pruner 的交互 | 仍开放，但假设已变：recency 路径在 compactRegion 前调 `pruneSession`；若 prune 也是 surface-replace 机制，则 log 原文应仍在（append-only），需实现时验证 |
-| 9 | recency 低于 system prompt 体积 | Feature 1 已带 no-op 守卫，软警告低优先 |
-
-## 5. 验证计划（实现时执行）
-
-- **单测**：分类落桶（每条消息恰落一桶）、tag 格式、单节点 replace（`dev/spike-tag-repro.mjs` 已是该场景的可运行骨架）。
-- **e2e**：灌满上下文 → 触发压缩（auto + manual 各一次）→ 断言：(1) 归档存储含被压缩区间原文；(2) 摘要尾部含 tag；(3) 模型执行 `recall(tag)` 能复述原文某细节。
-- **pruner 交互**（开放项 #7）：`pruneSession` 之后 log 里的原文事件是否完整。
-- **回归**：未配归档时行为与现状一致（默认全关）；测试只增不减（现有 140/140 不动）。
-
-## 6. 参考
-
-- `dev/dashr-compaction-window-and-archive.md`（Feature 2 总纲 + Feature 1 已实现记录）
-- `dev/spike-tag-repro.mjs`（API 面复现脚本，`node dev/spike-tag-repro.mjs` 可复跑，exit 0）
-- `dashr/src/compaction/recency-engine.ts`（挂点）、`dashr/src/py-sdk.ts`（recall helper 注入点）
-- 上游源码：`@deepseek-ai/dsh-session`（append/surface）、`@deepseek-ai/dsh-compaction-basic/lib/index.js` `commitCompactionBody`（替换节点 append 顺序）、`@deepseek-ai/dsh-compaction`（CompactionResult）
-- 委托 spike 报告：`/tmp/a2a/dashr-tag-spike.md`（Dash agent 产出，2026-08-20；关键结论已全部吸收进本文档 §1）

package/node_modules/better-dsh/docs/10_plans/spike-tag-repro.mjs

@@ -1,102 +0,0 @@
-
-// Minimal reproduction: verify that a session surface node's text can be
-// "rewritten" (summary + recall tag) via the append-only replace surfaceOp,
-// and that the new compaction summary node's seq is determinable.
-// Read-only spike — no dashr repo files touched.
-
-import { Session } from '/home/u1/workspaces/dashr/dashr/node_modules/@deepseek-ai/dsh-session/lib/index.js'
-import { createUserMessage, createAssistantMessage } from '/home/u1/workspaces/dashr/dashr/node_modules/@deepseek-ai/dsh-llm/lib/index.js'
-
-const s = Session.create('spike-tag-demo')
-
-const userMsg = (text) => createUserMessage({
-  content: [{ type: 'text', text }],
-  source: { kind: 'user' },
-})
-
-const asstMsg = (text, step) => createAssistantMessage({
-  content: [{ type: 'text', text }],
-  source: { provider: 'p', model: 'm' },
-})
-
-const summarize = (m) => m.map(x => `${x.role}: ${x.content.map(b => b.text ?? '<non-text>').join('')}`).join('\n  ')
-
-console.log('=== stage 0: four surface appends ===')
-s.append('user/message', userMsg('user-0: hello'), { surfaceOp: 'append' })
-s.append('assistant/message', { turn: 1, step: 1, message: asstMsg('asst-1: world', 1) }, { surfaceOp: 'append' })
-s.append('user/message', userMsg('user-2: question'), { surfaceOp: 'append' })
-s.append('assistant/message', { turn: 1, step: 2, message: asstMsg('asst-3: answer', 2) }, { surfaceOp: 'append' })
-console.log('surface.nodes =', JSON.stringify(s.surface.nodes))
-console.log('deriveMessages:\n  ' + summarize(s.deriveMessages()))
-
-console.log('\n=== stage 1: simulate compactRegion writing a summary over nodes [1,2] ===')
-// Mirror commitCompactionBody exactly: log-only compaction/summary, then the
-// surface replacement user/message immediately after (summarySeq + 1).
-const summaryEvent = s.append('compaction/summary', {
-  compactionId: 'c-1',
-  summary: [{ type: 'text', text: 'CONDENSED: user-2 and asst-3 happened.' }],
-  shadowedRange: { start: 1, end: 2 },
-  shadowedSeqs: [1, 2],
-  shadowedTokenCount: 1234,
-  provider: 'p', model: 'm',
-})
-const replacement = s.append('user/message',
-  createUserMessage({
-    content: [
-      { type: 'text', text: 'This is an automatically generated checkpoint...\n\n<compacted-summary>' },
-      { type: 'text', text: 'CONDENSED: user-2 and asst-3 happened.' },
-      { type: 'text', text: '</compacted-summary>' },
-    ],
-    source: { kind: 'plugin', plugin: 'compact', compactionId: 'c-1' },
-  }),
-  {
-    surfaceOp: { op: 'replace', start: 1, end: 2 },
-    sourceEventSeqs: [summaryEvent.seq, 1, 2],
-  },
-)
-console.log('summaryEvent.seq (compaction/summary) =', summaryEvent.seq)
-console.log('replacement.seq (surface summary node) =', replacement.seq, ' === summarySeq+1 ?', replacement.seq === summaryEvent.seq + 1)
-console.log('surface.nodes =', JSON.stringify(s.surface.nodes))
-console.log('deriveMessages:\n  ' + summarize(s.deriveMessages()))
-
-console.log('\n=== stage 2: PATCH the summary node text (append recall tag) ===')
-// The summary surface node seq is determinable as summarySeq + 1 (== replacement.seq).
-const summaryNodeSeq = replacement.seq
-const tagged = s.append('user/message',
-  createUserMessage({
-    content: [
-      { type: 'text', text: 'This is an automatically generated checkpoint...\n\n<compacted-summary>' },
-      { type: 'text', text: 'CONDENSED: user-2 and asst-3 happened.' },
-      { type: 'text', text: '</compacted-summary>' },
-      { type: 'text', text: '\n[原文回溯: ctx-12] 全文可通过 recall(\'ctx-12\') 读取。' },
-    ],
-    source: { kind: 'plugin', plugin: 'compact', compactionId: 'c-1' },
-  }),
-  {
-    surfaceOp: { op: 'replace', start: summaryNodeSeq, end: summaryNodeSeq },
-    sourceEventSeqs: [summaryNodeSeq],
-  },
-)
-console.log('patched node seq =', tagged.seq)
-console.log('surface.nodes =', JSON.stringify(s.surface.nodes))
-console.log('deriveMessages:\n  ' + summarize(s.deriveMessages()))
-
-console.log('\n=== stage 3: shadowed originals remain recoverable from the append-only log ===')
-console.log('shadowedSeqs [1,2] still in session.events:')
-for (const seq of [1, 2]) {
-  const e = s.events[seq]
-  const m = s.deriveEventMessage(e)
-  console.log(`  seq ${seq}: type=${e.type} role=${m?.role} text="${m?.content.map(b => b.text ?? '').join('')}"`)
-}
-
-console.log('\n=== stage 4: confirm in-place mutation is rejected (deep-frozen) ===')
-const frozenMsg = s.deriveMessages().find(m => m.content.some(b => b.text?.includes('[原文回溯')))
-let mutateOk = false
-try {
-  frozenMsg.content.push({ type: 'text', text: 'sneaky' })
-  mutateOk = true
-} catch (err) {
-  console.log('mutation threw:', err.constructor.name, '-', err.message)
-}
-console.log('in-place push succeeded?', mutateOk)
-console.log('total events:', s.events.length, '| seq (next):', s.seq)

package/node_modules/better-dsh/docs/10_plans/upstream-analysis.md

@@ -1,128 +0,0 @@
-# DASHR 上游源码分析（dsh × prime-agent）
-
-> 日期：2026-08-16 · 工具：Graphify (graphify-http-mcp :4749, AST 模式)
-> 用途：DASHR 自研运行时选型底图。两部分来源 + 结合方式蓝图见后续文档。
-
-## 0. 前置事实
-
-| 项 | deepseek-harness (dsh) | prime-agent (PI) |
-|---|---|---|
-| Clone | `dashr/deepseek-harness` @ `47f9438` (2026-08-13, npm-public PR #2519) | `dashr/prime-agent` @ `97b994c` (2026-08-14, daemon spawn ledger #1387) |
-| 语言主体 | TypeScript (ESM), Node ≥22.19 / ≥24 | TS host + Python runtime（模型面 Python，调度面 TS） |
-| 规模 | ~85MB 源码, 2319 ts + 19 py | ~30MB, 925 ts + 23 py（+runtime） |
-| pnpm workspaces | `packages/<group>/<pkg>` 两级, 50 组 ~230 包 | `packages/{agent,ai,coding-agent,tui}` 4 包 + `prime-agent-runtime/` (py) |
-| 许可 | MIT（预发布期承诺） | MIT |
-
-## 1. Graphify 图谱（AST，无 LLM 语义增强）
-
-| 指标 | dsh | prime-agent |
-|---|---|---|
-| nodes | 54,318 | 13,676 |
-| edges | 72,496 | 29,765 |
-| communities | 4,110 | 775 |
-| code 节点 | 33,026 | 10,784 |
-| graph.json | 44.9 MB | 15.4 MB |
-
-产物：各库 `graphify-out/{graph.json, GRAPH_REPORT.md, manifest.json}`。
-graph.html 因 >5000 节点未生成（GRAPHIFY_VIZ_NODE_LIMIT），交互视图需切子图或提限。
-增量更新：`update_graph(project_path)`；Graphify 缓存于 `graphify-out/cache/`。
-
-`.graphifyignore` 已写入两库（排除 node_modules/.git/dist/test fixtures/snapshots）。
-
-## 2. deepseek-harness 结构
-
-### 2.1 布局（依据 AGENTS.md + 实测目录）
-
-```
-vendor/      vendored Cordis 内核（manifest+sync procedure）
-packages/    @deepseek-ai/dsh-<name>，50 组 ~230 包
-  core/        agent, agent-loop, session, system-prompt, tools, scope
-  llm/         llm, llm-deepseek, llm-pi-ai, llm-retry, token-meter
-  subagent/    subagent + acp/claude-code/codex/dsh-sdk/fork-in-process/... 11 包
-  其他能力组:  fs, shell, subprocess, terminal, lsp, skill, web, mcp, acp,
-               compaction, context, workflow, todo, plan, preset, guard,
-               self-modification, hooks, session, identity, settings,
-               credentials, interaction, boot, sdk, typert, api, sandbox, ...
-apps/       cli + web
-python/     Python SDK + bundled runtime
-native/     node-addon-landlock-run（Landlock 沙箱 addon）
-.agents/    notes/（设计笔记，一手取证源）
-docs/       architecture, cordis-api, postmortem, subsystems
-```
-
-### 2.2 图谱枢纽（god_nodes, by degree）
-
-- `Context` (790) — Cordis 上下文，全库交汇点
-- `InvariantInstaller` (216), `Service` (138) — 插件注册骨架
-- `createSnapshotStore()` (97), `SnapshotStore` (79), `bindSnapshotSelector()` (88) — 会话快照存储链
-- `launchWebScaffold()` / `WebScaffold` / `watchConsole()` — web 测试脚手架
-- tsconfig `paths` (139) + package `scripts` (124) — workspace 胶水节点多，体现 monorepo 复杂度
-
-### 2.3 关键机制（docs/cordis-api 图谱查询 + AGENTS.md）
-
-- 插件注册原语：`ctx.plugin()` / `ctx.inject()` / `Registry`（docs/cordis-api/registry.md）
-- Registrations are effects：所有贡献走 `ctx.effect()` / `ctx.on()`，`register()` 返回 disposer（时空可组合性的实现基础；即 Cordis 论文「可逆效应」机制，论文仓库 `github.com/cordiverse/paper`，解读见 deepseek-dsh.md §1.4）
-- 能力三层拆分：Service Definition（接口）/ provider（实现）/ Consumer（消费者）→ 换实现不动消费者
-- per-session preset：`preset/` 包，agent.cordis.yml 组装，会话锁 `agent-preset-locked`
-
-## 3. prime-agent 结构
-
-### 3.1 布局
-
-```
-packages/
-  agent/         5 文件：agent-loop.ts, agent.ts, proxy.ts, types.ts（薄）
-  ai/            provider 层：api-registry, bedrock, stream, oauth,
-                 models.generated, openrouter-reasoning, mcp
-  coding-agent/  主体：src/core/{kernel, tools, session-manager, ...}
-                 skills/（Python 技能：rlm, refine, compact, goal, edit,
-                 websearch, agent-message, rlm-heartbeat, ...）
-  tui/           终端 UI
-prime-agent-runtime/   Python 侧 RLM runtime
-  src/rlm/{__init__, harness, skill, mcp_base}.py
-  test/           subagent_registry, mcp_base, agent_message_skill, harness
-```
-
-### 3.2 图谱枢纽（god_nodes）
-
-- `AgentSession` (430) — 核心会话对象
-- `InteractiveMode` (388), `TUI` (139), `Component` (134) — 交互层重
-- `AgentDaemon` (184), `DaemonSupervisor` (134), `DaemonAgentConnection` (122) — daemon 体系（最新 commit 正是 supervisor-owned rlm spawn ledger）
-- `SettingsManager` (172), `SessionManager` (108)
-
-### 3.3 关键链路（query_graph 取证）
-
-**子 agent spawn（rlm()）**：
-`rlm/__init__.py` → `run()` → `host_request()`（comm 通道发 TS host）→ `_spawn_handle_from_payload()` → `RLMSpawnHandle`；Python 侧 `HarnessState/HarnessScope/HarnessEntry/RefinementEvent`（harness.py, community 70/90）构成 Continual Harness 状态。TS 侧 `fork-server.ts SpawnParams`（community 157）承接。
-
-**IPython kernel（Context as Variable）**：
-- `core/tools/ipython.ts`：`IpythonKernelProvisioner` → `.startKernel()` / `.ensure()`
-- `core/kernel/index.ts` `KernelManager`：`.doStart()`, `.enqueueExecute()`, `.runIopubPump()`, `.handleExecutionMessage()`, `.shutdown()`
-- 状态持久化：`state-snapshot.ts` `.snapshotState()` / `.restoreState()` / `RestoreResult`（community 217）→ 变量级 checkpoint
-- fork：`fork-server.ts` `forkKernel()`（community 157，与 SpawnParams 同社区 → fork 复用 kernel 状态）
-
-## 4. 结合面初步观察（待蓝图输入）
-
-| 维度 | 取 dsh | 取 prime-agent |
-|---|---|---|
-| 内核/装配 | Cordis 插件体系, preset, 能力三层 | — |
-| 模型面 | — | 持久 IPython kernel + state-snapshot |
-| 子 agent | subagent 11 包矩阵 | `rlm()` 函数式 + fork-server |
-| 记忆 | — | Continual Harness (ρ,G,K,M) |
-| 沙箱 | bwrap+Landlock (native addon) | — |
-| LLM 接入 | llm-deepseek/pi-ai/retry/token-meter | ai/ 包多 provider |
-
-风险点：两库语言运行时不同（dsh 纯 TS vs PA 模型面 Python）；结合方式决定桥接层（PA 式 comm channel 或 dsh 式 in-process SDK）。
-
-## 5. 图谱查询备忘
-
-MCP endpoint `http://127.0.0.1:4749/mcp`（Streamable HTTP, 需 `Accept: application/json, text/event-stream`）。
-`graph_path` 参数 = `graphify-out/` 目录（含尾 graph.json 解析）。常用：
-`graph_stats / god_nodes / query_graph / get_neighbors / shortest_path / graph_affected(影响面) / graph_tree / surprising_connections`。
-
-增量：代码改动后 `update_graph`；LLM 语义增强需 API key（可选 gemini）。
-
-## 6. 相关档案
-
-- 调研/实测：`agent-harness/21_CLI-Agent/03_deepseek-dsh/deepseek-dsh.md`
-- `agent-harness/21_CLI-Agent/04_prime-agent/prime-agent-{research,deployment-experiment,rlm-analysis,paradigm-discussion,continual-harness}.md`

package/node_modules/better-dsh/docs/20_specs/agent/spec.md

@@ -1,54 +0,0 @@
-# agent Specification
-
-## Purpose
-
-Let the model address the agent roster, output artifacts, and full transcripts via `agent://` URLs — the single home for what upstream split across roster tools and a separate `history://` scheme.
-
-## Requirements
-
-### Requirement: Agent roster addressing
-The system SHALL let bare `agent://` return the roster of every live session, oldest first, as a five-column table: `id`, `status`, `kind`, `parent`, `last activity`. `status` comes from the live agent registry (`idle`/`running`; `-` when the session has no live agent); `kind` is the session header's `origin` (default `main`); `parent` is the delegating parent session id (`-` at top level); `last activity` is the last session event's time in ISO 8601 (`-` when the session has no events).
-
-#### Scenario: Listing all agents
-- **WHEN** the model reads bare `agent://`
-- **THEN** the system returns one row per live session with all five columns, e.g. `id  status  kind  parent  last activity`
-
-#### Scenario: Session without a live agent
-- **WHEN** a roster row's session has no entry in the live agent registry
-- **THEN** its `status` column renders `-`
-
-### Requirement: Agent output addressing
-The system SHALL let `agent://<id>` return that agent's output artifact: the rendered content of its last non-empty assistant message (matching `SubagentResult.output` semantics), or empty text when the agent produced no non-empty assistant output. Addressing is scoped to the caller's own family (the caller itself and its descendant children) — ids outside the family return `AGENT_UNKNOWN_ID`.
-
-#### Scenario: Reading a completed agent's output
-- **WHEN** the model reads `agent://<finished agent id>` from within its family
-- **THEN** the system returns the rendered text of that agent's last non-empty assistant message
-
-#### Scenario: Reading an unknown agent
-- **WHEN** the model reads `agent://<unknown id>` (or an id outside the caller's family)
-- **THEN** the system returns the structured `AGENT_UNKNOWN_ID` error
-
-### Requirement: Agent transcript addressing
-The system SHALL let `agent://<id>/transcript` return the agent's full derived message history in order, each message headed by its role (`assistant`, `user`, `tool result`, `system`), with tool calls rendered as `[tool: name] arguments` and errors as `[tool error] …`. Addressing follows the same family scoping as output addressing.
-
-#### Scenario: Reading an agent's session history
-- **WHEN** the model reads `agent://<id>/transcript` for an agent in the caller's family
-- **THEN** the system returns every message of that session in order, role-headed
-
-### Requirement: Nested output addressing
-The system SHALL let `agent://<id>/<child>` return a direct child's output artifact, resolving the child only through the parent's enumerated children. Unknown children, or children not live in the session store, return `AGENT_UNKNOWN_ID`. Paths with more than two segments return `AGENT_BAD_PATH`.
-
-#### Scenario: Reading a nested child output
-- **WHEN** the model reads `agent://<parent id>/<child id>` and the child is a direct child of that parent
-- **THEN** the system returns the child's output artifact
-
-#### Scenario: Child not enumerable from the parent
-- **WHEN** the model reads `agent://<id>/<non-child id>`
-- **THEN** the system returns the structured `AGENT_UNKNOWN_ID` error
-
-### Requirement: history has no scheme of its own
-The system SHALL provide transcript history only under `agent://<id>/transcript`. There is no `history://` handler and no special-case error for it: `history://` produces the generic `URL_UNREGISTERED_SCHEME` error like any other unregistered scheme.
-
-#### Scenario: history scheme is unregistered
-- **WHEN** the model reads `history://<id>`
-- **THEN** the system returns the structured `URL_UNREGISTERED_SCHEME` error listing the registered schemes (history not among them)

package/node_modules/better-dsh/docs/20_specs/ast/spec.md

@@ -1,57 +0,0 @@
-# ast Specification
-
-## Purpose
-`ast` 是**纯 tool 设施**：无进程、无状态、无协议——文本进 → tree-sitter 语法树 → 结构匹配/改写 → 结果出。以 `dvc://ast` 设备面挂载（`ast_grep` 结构搜索 + `ast_edit` 结构改写，natives 懒加载），由 agent 在工具循环里主动调用；不设任何运行时拦截点、不订阅文件事件、不参与文本同步。与 hash-edit/LSP 的分工：结构问题归 ast，语义问题（类型/跨文件引用/诊断）归 LSP，锚点编辑归 hash-edit。
-
-## Requirements
-
-### Requirement: Pure tool semantics
-The ast device SHALL behave as a stateless function: every call carries its inputs (pattern, paths, content) and returns its result; no server process, no document mirror, no cross-call state SHALL exist.
-
-#### Scenario: Stateless call
-- **WHEN** the agent invokes `ast_grep` twice with identical inputs
-- **THEN** both calls parse independently and return identical results, with no cached tree or warm process in between
-
-### Requirement: Lazy in-package engine, zero startup cost
-The ast device's WASM engine SHALL load lazily on first use; host start and agent session start SHALL NOT parse anything or load grammar binaries. The engine and its grammars SHALL ship inside the package (`lib/ast-assets/`) and SHALL require no network access, no npm resolution, and no `.vendor` provisioning at call time.
-
-#### Scenario: Cold session
-- **WHEN** a session ends without ever invoking the ast device
-- **THEN** no WASM engine was instantiated and no grammar binary was loaded
-
-#### Scenario: Offline first use
-- **WHEN** the device is first invoked with no network access and no `.vendor` directory
-- **THEN** the search still completes from the in-package engine
-
-### Requirement: dvc scheme surface only
-The ast capability SHALL expose exclusively through the `dvc://ast` write/read contract (bare `dvc://` roster lists it; `dvc://ast` read returns its doc; `dvc://ast` write dispatches). No dedicated tool name, no scheme branches in read/grep/glob, and no hook into read/write/edit flows SHALL be added.
-
-#### Scenario: Surface inventory
-- **WHEN** the model-facing tool surface is enumerated
-- **THEN** ast appears only as the `dvc://ast` device — its invocation is an ordinary `write` the agent decides to make
-
-### Requirement: Structural semantics boundary
-The ast device SHALL provide structural matching/rewriting only. It makes no claim about types, cross-file references, or diagnostics; a deployment wanting semantics SHALL use the lsp capability instead.
-
-#### Scenario: No semantic answers
-- **WHEN** the agent asks the ast device for type information or project diagnostics
-- **THEN** no such capability exists on the device surface (the call is not offered)
-
-### Requirement: Diagnostic fields (deliberate divergence from the native predecessor)
-The ast devices SHALL surface failure modes that the native predecessor swallowed silently (0.2.6 contract addition). `ast_grep` results SHALL carry `patternErrors?: string[]` — present (non-empty) iff at least one supplied pattern failed to compile as a single-root AST node, one entry per failing pattern formatted `pattern <index> ("<pattern text>"): <underlying message>`; multi-root patterns land here and matches from the remaining patterns still return — and `pathNotFound?: boolean` — `true` only when the resolved target path does not exist on disk, absent otherwise. `ast_edit` results SHALL carry the same `patternErrors` semantics over `ops[].pat` (a failing op contributes no edits), `overlapping?: number` — the count of edits dropped by the overlap guard, present only when greater than zero — and the same `pathNotFound` semantics (true when at least one resolved target root does not exist on disk). Patterns that fail with a hard syntax compile error SHALL still throw through as `DVC_DEVICE_ERROR`. The devices perform no workspace boundary check — the boundary is the approval/policy layer — and `ast_edit` writes whatever paths it is given. All pre-existing fields keep their names and semantics.
-
-#### Scenario: Multi-root pattern is reported, not swallowed
-- **WHEN** `ast_grep` runs a multi-root pattern (e.g. `"alpha": $V`) that fails to compile as a single-root AST node
-- **THEN** the result carries `patternErrors` with one entry naming the pattern index, the pattern text, and the underlying message, and zero matches from that pattern — instead of an indistinguishable empty result
-
-#### Scenario: Missing path is distinguishable from zero matches
-- **WHEN** the resolved target path does not exist on disk
-- **THEN** the result carries `pathNotFound: true` with `filesSearched: 0`, so "nothing there" is no longer confused with "pattern matched nothing"
-
-#### Scenario: Overlap-guard drops are counted
-- **WHEN** `ast_edit` ops produce edits that overlap an already accepted edit
-- **THEN** the first-registered op wins, the shadowed edit is dropped, and the result reports the dropped-edit count in `overlapping` instead of dropping it silently
-
-#### Scenario: Hard syntax errors still throw
-- **WHEN** a pattern fails with a hard syntax compile error (e.g. `$$$`)
-- **THEN** the device throws and the caller receives the structured `DVC_DEVICE_ERROR`, exactly as before