better-dsh 0.0.0 → 0.2.3

package/docs/plans/kernel-refactoring/actinoable-surface-to-llm-in-agent-runtime_prime.md

@@ -0,0 +1,113 @@
+# 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/docs/plans/recallable-compaction.md

@@ -0,0 +1,147 @@
+# 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/docs/plans/spike-tag-repro.mjs

@@ -0,0 +1,102 @@
+
+// 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/docs/plans/upstream-analysis.md

@@ -0,0 +1,128 @@
+# 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/docs/repositioning-and-rebranding.md

@@ -0,0 +1,102 @@
+# DASHR: Repositioning & Rebranding
+
+Status: proposal / agreed direction (2026-08-24)
+Audience: maintainers, contributors, future packaging & marketing work.
+
+---
+
+## 1. Pronunciation
+
+**DASHR** is read as **"Dasher"** — plain English natural reading. Anyone seeing the word
+should be able to pronounce it without a guide (which is the point of the vowelized
+spelling, see §3).
+
+## 2. Name origin (literal reading)
+
+- **DASH** = upstream `DSH` (DeepSeek Harness) with a vowel inserted, so the acronym
+  becomes a naturally pronounceable word.
+- **DASHR** = **"better form of dash"** — literally *dasher* with one vowel (`e`)
+  removed. The name itself encodes "a leaner-but-more dash".
+
+## 3. Repositioning
+
+### Before (current repo reality)
+
+DASHR was positioned as a **plugin**: the RLM mode for `dsh` (npm `dsh-rlm-mode`).
+One capability, installed into an existing dsh setup.
+
+### Now
+
+DASHR is repositioned as **"Better Dash"** — a complete, ready-to-run App built on the
+upstream DeepSeek Agent runtime ("Everything is plugin" / Cordis framework).
+
+The phrase "Better Dash" is deliberately down-to-earth. We do not want to appear
+grandiose: everything is built on open-source work. What the phrase conveys:
+
+- **完整体** — a whole product, not a component.
+- **开箱即用** — one install, works immediately.
+- **接地气** — honest about being open-source-derived; no inflated claims.
+
+### Product shape (the "Linux distro" model)
+
+| Layer | Analogy | DASHR reality |
+|---|---|---|
+| Kernel / core | Linux kernel | Upstream official DeepSeek Agent runtime (`dsh`), tracked at latest official release |
+| Distro | Ubuntu / RHEL | DASHR: curated plugin composition + compatibility guarantee |
+| Default enabled flagship | — | RLM mode (the former standalone plugin) |
+| Enterprise services | Canonical custom engagements | Fast custom-agent builds on top of the distro |
+
+Commercial positioning:
+
+- We do **not** sell the agent core. We sell a **composition of plugins** (a recipe),
+  the compatibility matrix behind it, and support.
+- The core stays anchored to the official latest release; we dynamically smoke-test
+  every bundled plugin against new core versions.
+- Distribution form: semi-precompiled binary — shaped like a complete App, one-click
+  install.
+- Full compatibility with the DASH community ecosystem: after installing the DASHR
+  App, users can still use the official plugin marketplace seamlessly.
+
+## 4. Self-owned vs community plugins
+
+- **(a) Own plugins**: e.g. improvements where the current PTC code mode falls short
+  (RLM mode is the flagship).
+- **(b) Curated community plugins**: selected useful plugins from the ecosystem
+  (source: `awesome-dsh-plugin`), each held to the compatibility matrix.
+- **(c) Packaged whole**: the App bundles (a)+(b) into one agent runtime with
+  one-click install.
+
+## 5. Known risks (ranked)
+
+1. **The compatibility matrix is the moat.** Upstream is at `0.1.0-rc` (no semver
+   guarantees); every rc requires plugin × core smoke tests. The product promise
+   does not exist until this CI matrix exists. Build it first.
+2. **Semi-precompiled binary ships three runtimes.** Node ≥22 + Python 3.11 kernel
+   (uv venv) + plugin deps. Realistic v1 form: structured directory + launcher +
+   installer (Electron-style), not a true single-file binary.
+3. **Naming / trademark boundary.** DASHR's name derives from DSH and currently
+   carries DeepSeek branding/badges. As a distro we must state clearly in docs that
+   this is an **unofficial distribution**, mirroring how Canonical/Debian and
+   Fedora/RHEL handle the relationship.
+4. **"Seamless official marketplace" is conditional.** Our `cordis.patch.yml` bundle
+   patch must stay minimal and be pushed upstream wherever possible; any behavior
+   divergence breaks the seamlessness promise.
+
+## 6. Repository implications
+
+- Three-layer layout going forward: `core/` (the npm plugin, stays independently
+  publishable — free acquisition funnel, keeps us honest against vendor lock),
+  `distro/` (lockfile + compatibility matrix + packaging), `app/` (launcher /
+  installer).
+- `install.sh` evolves from single-plugin installer to distro installer.
+- README narrative shifts from "RLM plugin for dsh" to "a DASH distribution —
+  RLM mode enabled by default".
+- The standalone plugin remains published and usable on plain dsh.
+
+## 7. Sequence
+
+1. Build the minimal viable compatibility matrix (target: upstream rc stream).
+2. Distill the plugin composition (own + curated) into a lockfile.
+3. Package as directory+launcher App; one-click install.
+4. Rebrand surfaces (README, docs, badges) to the "Better Dash" positioning with
+   the unofficial-distribution disclaimer.