better-dsh 0.2.2-a → 0.2.2-c

package/docs/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/docs/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/docs/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/docs/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/docs/v0.1.8-improved-/345/256/236/346/265/213/346/212/245/345/221/212.md

@@ -1,142 +0,0 @@
-# DASHR v0.1.8 改进版复测报告（第一人称实测）
-
-> 复测方式：仍以 DASHR 运行时自身为被测对象（本会话，dsh Web GUI）。运行时已按上版报告调整并重启，本次对**上版全部问题逐条复测**，并重跑测试套件。
-> 复测日期：2026-08-24（同日晚，更新 commit `7ec46ac`）
-
----
-
-## 0. 结论摘要
-
-| 结论 | 结果 |
-|---|---|
-| 上版 **P0（snapshot 失效）** | ✅ **已修复** |
-| 上版 **P1（docstring 回归）** | ✅ **已修复** |
-| 上版 P2/P3（命名漂移、masking 张力、fgm→pgmi） | ✅ **全部修复/重新设计** |
-| 测试套件 | ✅ **156/156 全绿**（上版 155/163） |
-| 遗留问题 | 🟡 README 中后段 + 根 README 仍残留旧架构文档；`compact` 引擎本部署仍未挂载 |
-
-**一句话结论**：改进版把上版报告里的**功能性问题全部清零**——内核环境自管（Python 3.11 + dill）让 snapshot 复活，delegation 工具从「桥接包装」改为「直接暴露」消除了 masking 与 dual-exposure 的张力；但**文档层还有两处 README 残留旧架构描述**需要清理。
-
----
-
-## 1. 本次变更（commit `7ec46ac`）
-
-```
-dashr: runtime-owned kernel environment + native delegation exposure
-```
-
-1. **内核环境自管**（新增 `src/kernel-env.ts`，210 行）：运行时自己 provision 一个托管 CPython 3.11 venv（`ipykernel` + `dill`），落在**包内 `.venv-kernel`**（不再 `/tmp` 悬空 symlink）。显式解释器被校验：缺 `dill` = 响亮告警（禁用快照），缺 `ipykernel` = 硬错误。
-2. **原生 delegation 直接暴露**：masking 从 8 名收敛到**仅 2 名**（`send_message` + `report`）；`subagent`/`subagent_fork`/`list_agents`/`interrupt_agent`/`workflow`/`ralph` 直接暴露为 `tool.*` 成员；**`rlm`/`agent_list`/`rlm_workflow`/`rlm_ralph` 桥接全部删除**。
-3. **Rebrand**：`@fgm-builds/dashr` → `@pgmi-builds/dashr`；RLM 术语在 CONTEXT/ADR 去强调。
-
----
-
-## 2. 上版问题逐条复测
-
-| 上版问题 | 严重度 | 本次实测证据 | 状态 |
-|---|---|---|---|
-| snapshot 失效（dill 缺 + Python 3.14） | 🔴 P0 | 实测内核 `Python 3.11.15` + `dill 0.4.1` + `ipykernel 7.3.0`；`.venv-kernel` 指向 uv 托管 3.11；快照测试全绿 | ✅ 修复 |
-| docstring 回归 | 🟠 P1 | 实测 `helper.__doc__ == 'First summary line.\n    Details follow.'`；`runtime.spec.ts` 绿 | ✅ 修复 |
-| `agent_message` vs `send_message` | 🟡 P2 | 实测 `tool.agent_message` → `unknown binding`；`tool.send_message` 为双向桥接；CONTEXT/ADR 已改 | ✅ 修复 |
-| flat-global vs `tool.*` | 🟡 P2 | CONTEXT.md「Binding」已改「`tool.*` member」 | ✅ 修复 |
-| `fgm` vs `pgmi` | 🟡 P2 | `package.json` name / `cordis.patch.yml` 均 `@pgmi-builds/dashr` | ✅ 修复 |
-| masking 7 vs 8 | 🟡 P2 | 重新设计为 2 名，ADR-0002 已同步 | ✅ 修复 |
-| masking 对直接面无效（结构性张力） | 🟡 P3 | 决策落地：delegation 直接暴露、`rlm` 删除，张力消除 | ✅ 修复 |
-| 桥接错误风格不一致 | 🟡 P3 | `rlm_workflow` 等已删，仅剩 `send_message`（结构化 error 值） | ✅ 消除 |
-
----
-
-## 3. 新功能面实测（第一人称逐项）
-
-### ✅ 3.1 内核环境自管 —— 通过
-
-```
-kernel python: 3.11.15
-dill: 0.4.1
-ipykernel: 7.3.0
-```
-
-`.venv-kernel/bin/python` 现指向 `/home/u1/.local/share/uv/python/cpython-3.11-linux-x86_64-gnu/bin/python3.11`（真实存在，非悬空）。
-
-### ✅ 3.2 原生 delegation 直接暴露 —— 通过
-
-`tool.subagent` / `tool.subagent_fork` / `tool.list_agents` / `tool.interrupt_agent` / `tool.workflow` / `tool.ralph` 现在**全部直接绑定**（call-through 返回的是真实工具的参数校验错误，而非 `unknown binding`）：
-
-```
-tool.subagent        -> REJECTED (invalid arguments: missing required property "description")
-tool.list_agents     -> bound+callable（返回子代理列表）
-tool.workflow        -> REJECTED (missing required property "script")
-tool.ralph           -> REJECTED (missing required property "objective")
-```
-
-### ✅ 3.3 桥接收敛（仅 send_message + refine + compact）—— 通过
-
-```
-tool.send_message    -> bound+callable   （双向桥接）
-tool.refine          -> bound+callable
-tool.compact         -> bound+callable
-tool.rlm             -> REJECTED (unknown binding "tool.rlm")
-tool.agent_list      -> REJECTED (unknown binding)
-tool.rlm_workflow    -> REJECTED (unknown binding)
-tool.rlm_ralph       -> REJECTED (unknown binding)
-tool.agent_message   -> REJECTED (unknown binding)
-```
-
-`rlm` 家族彻底移除，递归改走 `tool.subagent` / `tool.subagent_fork` 直连。
-
-### ✅ 3.4 递归 + A2A 全链路（新形态）—— 通过
-
-```
-tool.subagent spawn → {'kind':'continuable','subagentId':'3e8f3609-...'}   （8*9）
-child 完成上报
-tool.send_message(receiver='child') 下行追问 9*9 → 上报 "81"
-tool.send_message(receiver='parent') from root → 结构化 UNAUTHORIZED（guard 仍在）
-```
-
-### ✅ 3.5 无回归项 —— 通过
-
-`tool.*` 绑定、跨 cell 持久化、`ToolCallError(.toolName)`、`asyncio.gather`、顶层 `return` → SyntaxError 均与上版一致，无回归。
-
-### ✅ 3.6 测试套件 —— 全绿
-
-```
-Test Files  18 passed (18)
-     Tests  156 passed (156)
-```
-
-上版失败的 `snapshot-revive` / `snapshot-restore` / `lifecycle` / `session-keys` / `runtime`(docstring) 全部转绿；新增 `bindings.spec.ts`（7）、`parallel.spec.ts`（2）。
-
----
-
-## 4. 遗留问题（新发现）
-
-### 🟡 4.1 包内 `dashr/README.md` 中后段仍描述旧架构
-
-header 段已更新（`dsh-rlm-mode`→`dashr`、`RLMRuntime`→`ReplRuntime`、`ipython`→`eval`、kernel 自管），但**中后段未同步**，仍残留：
-
-- 「**`ipython`** — the only tool the model may call directly」（应为 `eval`）
-- 「FLAT top-level callables — `await name({...})`」（应为 `tool.*` member）
-- 「bridge callables `rlm`, `send_message`, `agent_list`, `rlm_workflow`, `rlm_ralph`」（已删）
-- 「Delegation and messaging (rlm, send_message, agent_list, rlm_workflow, rlm_ralph)」整段 `rlm()` API 文档（已删）
-- install 段仍指 `dsh-rlm-mode` + `rlm-mode` preset（preset 已删）
-- `dashr-kernel` group `isolate: { rlmRuntime: true }`（旧 realm 架构，现为 host-plane `dashr-repl`）
-
-### 🟡 4.2 根 `README.md` 完全未 rebrand
-
-根 `README.md` 仍是「# Dashr: RLM Plugin for `dsh`」+ `dsh-rlm-mode` npm badge + 完整 RLM 定位 + `rlm()` API 示例——本次 commit **未触碰根 README**。
-
-### 🟡 4.3 `compact` 引擎本部署未挂载
-
-`tool.compact` 返回 `{'context_tokens': 137635, 'error': 'compact() is unavailable: no ctx.compaction engine is mounted in this composition'}`——桥接存在，但本 composition 无宿主压缩引擎（与上版一致，非本 commit 引入）。
-
-### ⚪ 4.4 观察项：会话续接时工具目录未随插件升级刷新
-
-本会话（`session-5037d6a6`）跨过了插件更新 + 运行时重启，但**本会话的 system prompt（Tool Catalog）仍是旧版**——仍在声明 `rlm`/`agent_list`/`rlm_workflow`/`rlm_ralph` 可用，而实测运行时已 `unknown binding`。新开会话应得到正确目录，但「持久会话热升级插件后目录不刷新」值得留意。
-
----
-
-## 5. 建议
-
-1. **清理 README 残留**：把 `dashr/README.md` 中后段（ipython/flat/rlm 家族/install/preset/isolate realm）+ 根 `README.md`（RLM 定位、`dsh-rlm-mode` badge、`rlm()` API）对齐 v0.1.8 实际形态（`eval`、`tool.*`、直接 delegation、`@pgmi-builds/dashr`）。
-2. **验证 compact 部署**：在目标部署形态下挂载宿主压缩引擎，复验 `compact` 与 Global Context Recency Window。
-3. **会话续接目录刷新**（可选）：考虑在插件升级/重启后让持久会话的 Tool Catalog 失效或重算，避免模型看到过期工具面。