宿主多会话支持(二):回合边界判定统一 + 子会话状态继承(#317 遗留)

[ranxianglei]

背景

#317(Prime Agent 集成报告)中的记账隔离已由 #327 修复:nudgeShownTurns、压缩失败追踪等账本已按 sessionId 键化,会话启动/退出只清理本会话。本 issue 跟踪剩余的两个结构性缺口(即 #317 的接缝 1 与接缝 2),修复后同一 pi 进程内的多会话宿主(Prime 等内联子/兄弟会话)才能真正跑顺。

问题 1:回合边界判定不统一

现状:什么消息算"新回合起点"在三个地方各自独立判定,且互不一致:

• src/tokens.ts:98 — hostTokens 估算
• src/index.ts:739 — turnKey 计算
• src/messages.ts:29 — 上下文条目划分

影响:宿主通过 agent_message(custom_message)注入的消息进入上下文,但不算回合起点 → 多个真实回合塌缩进同一个 turnKey:

• nudge 记账格子错位(账本已隔离但格子本身错了)
• 退化熔断、节流阀的周期统计失真
• 回合证据闭合(reasoning-drop)对齐不到正确的回合

方案:

• 导出单一谓词 isTurnBoundary(entry),三处收敛到同一实现
• 提供宿主策略入口(是否把 custom_message/agent_message 计为回合起点),默认保持 pi 原生行为不变(不改变存量单会话用户的 nudge 节奏)
• 在宿主适配文档中写明该契约(连带补 docs/host-adapter.md)

问题 2:子会话状态继承(deriveChildState)

现状:runtime.stateFor(childSid) 一律返回全新状态。

影响:

• pi 原生 delegate(独立进程跑子会话)→ 全新状态是正确语义,保持不变
• 内联子会话(同进程,如 Prime RLM)→ 需要继承父会话的压缩块(否则 decompress/search_context 找不到块),但节奏基线(nudge 记账、节流阀、失败计数、预算水位)应重新起算

方案:设计 deriveChildState(parentState) → childState 契约:

• 继承:压缩块、消息引用、原始消息索引(保证块可解压、可搜索)
• 重置:所有节奏账本(nudge shown、compress 失败追踪、节流阀、溢出计数)
• 一次性迁移标记(子会话首次派生时写入,避免重复派生)
• 持久化沿用 ~/.pi/agent/sessions/<childSid>.acp.json,与父文件独立

验收

• 三处回界判定收敛为单一谓词,单元测试断言一致性
• 宿主策略默认关闭时,存量行为逐字节不变(回归测试)
• deriveChildState 继承/重置语义有单元测试;pi 原生 delegate 路径零变化
• docs/host-adapter.md 覆盖回界策略与子会话派生契约

关联

• 上游: Prime Agent integration: session-scoped ACP state and isolated inline RLM runners #317(本 issue 为其遗留项)、feat(acp): scope nudge + compress-outcome bookkeeping per session (#317) #327(已合并,记账层)
• 自动压缩兜底(Prime Agent integration: session-scoped ACP state and isolated inline RLM runners #317 接缝 5)归 Title: Context never auto-compresses when the model ignores the nudge — climbs 75%→95%+ on long agentic tasks (no enforcement path) #269 轨道,不在本 issue 范围

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 进展同步(环境受阻,代码勘察已完成):

阻塞:沙箱磁盘 100% 占满(/dev/sda1,avail 0),npm ci 报 ENOSPC。已清 npm cache(~887M)但空间秒级被并行任务重新占满;期间连回帖工具都因会话持久化失败写不进去。现在刚恢复一个小窗口,先补上这条。

已完成勘察(不需要安装依赖):

• 三处回界判定不一致属实:src/tokens.ts:97 lastUserMessageId、src/index.ts:692 turnStartIndex(都只认 message.role === "user"),而 src/messages.ts:25 entriesToCoreMessages 把 custom_message 投影为 user-role core message —— 宿主注入的 agent_message 进了 LLM 上下文却不构成回合起点,与 issue 描述一致。
• 已摸清 turnKey 的全部消费点(src/index.ts:419/431 nudge 与熔断统计、src/compress-tool.ts:342 重试上限)和 runtime 账本结构(nudgeShownTurns/compressFailTurnKey/按 sid 键化的 throttle/overflow/tokenScale/deadCompress)。
• 子会话继承的挂点确认在 src/state.ts(readParentSessionPath + tryLoadParentState:目前整份照抄父状态,无节奏账本重置、无一次性派生标记)。

下一步:需要 ~1–2GB 磁盘窗口装依赖并跑测试。沙箱里有一批陈旧的同仓 workdir(每个 ~250M node_modules),我会在确认非活跃后清理它们继续实现(isTurnBoundary 收敛 + deriveChildState + 测试 + docs/host-adapter.md),完成即开 PR。若磁盘持续被占满请运维介入。

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 已完成，PR: #366

问题 1 — 回合边界判定统一

• 新增 src/turn-boundary.ts：单一谓词 isTurnBoundary(entry, policy) + lastTurnBoundaryId / lastTurnBoundaryIndex。三处旧实现全部收敛：tokens.ts 的 lastUserMessageId（已删除）、index.ts 的 turnStartIndex（已删除）与 turnKey 计算、messages.ts 的上下文条目投影条件。
• 宿主策略入口：新配置键 hostSession（boolean 简写或 { countCustomMessages }），默认关闭 = pi 原生行为。关闭时谓词与旧的 user-role-only 扫描逐条等价——单测以 legacy 扫描为 oracle 对拍混合条目序列，证明存量单会话用户的 nudge 节奏逐字节不变；开启后宿主注入的非 UI custom_message 成为所有按回合账本的起点（nudge 格子、compress 重试上限、节流/溢出周期统计），LLM 上下文投影不受影响（那本就是 pi 原生行为）。

问题 2 — deriveChildState 子会话状态继承

• 纯函数 deriveChildState(parentState)（src/state.ts）+ 编排入口 runtime.deriveChildState(childRef, parentRef)（SessionRef {sessionId, sessionFile?}，宿主无需持有完整 context）。
• 继承：blocks（深拷贝）、messageRefs、tokenSnapshot（原始消息索引）、nextBlockId/nextRunId（沿用，防止新块 id 与继承块冲突）→ 继承块可 decompress、可 search_context（单测用 kernel activeBlocks/blockById 验证派生状态可查）。
• 重置：nudge 节奏基线、stats、absorbed——子会话重新起算。
• 一次性迁移标记：derivedFrom: {parentSessionId, derivedAt} 持久化进子 sidecar <child>.jsonl.acp.json，与父文件独立；重复派生拒绝。
• 护栏：子会话已有自有非派生块 / 父无块 / 子无 sessionFile → 拒绝且不改任何状态；显式派生优先于隐式 parentSession 头继承（恰好升级一次，不二次覆盖）。
• pi 原生 delegate（独立进程）路径零变化：verbatim 头继承逻辑与其既有测试原样通过。

验收对照

• 三处回界判定收敛为单一谓词，tests/turn-boundary.test.ts 断言 id/index 双视图一致性 + 谓词矩阵
• 宿主策略默认关闭时存量行为不变——legacy-scan oracle 回归测试 + 全量套件
• tests/derive-child-state.test.ts 覆盖继承/重置矩阵、深拷贝隔离、marker 往返、各护栏拒绝、内联子代理 header 场景；delegate 路径零变化
• 新增 docs/host-adapter.md（回界策略 + 子会话派生契约，含宿主使用片段与启用指引）；CONFIGURATION.md(+zh-CN) 增 hostSession 节；CHANGELOG 条目

验证：typecheck 干净；test 671 pass / 0 fail / 3 skip（基线 648/0/3，净增 23）；build 干净（dist 741.7 KB）。未动 version 字段（内容提交不 bump）。

中文摘要：修复了 #317 遗留的两个多会话结构性缺口——回合边界收敛为单一谓词（默认关闭时存量行为逐字节不变，有回归测试），新增内联子会话 deriveChildState 派生契约（继承块/引用/索引、重置节奏账本、一次性迁移标记、delegate 路径零变化）并补齐 host-adapter 文档；三项检查全绿，可以合并。

[qiangu2020]

补充一组 Prime Agent 0.9.4 + 官方 npm billion-context-pi 0.1.67 的实测结果，作为 #317 → #364 / #366 的接入验收信息。

目标是移除本地 vendor fork，直接消费官方发布包。感谢 #327 的会话记账隔离修复；但“该部分已合并”目前还不等于 Prime 可以直接加载官方包。

1. 实际加载首先失败：CONFIG_DIR_NAME 未导出

通过已安装 Prime 的真实 dist/core/extensions/loader.js 的 loadExtensions() 加载未经修改的 npm 0.1.67，返回：

Failed to load extension: The "path" argument must be of type string. Received undefined

Prime loader 将 @earendil-works/pi-coding-agent alias 到 Prime 自身的 dist/index.js。该公共入口并未导出 CONFIG_DIR_NAME；官方扩展的配置目录代码把这个 undefined 传给 path.join()。同一个 loader 下，现有 0.1.58 本地适配版本加载成功（包含目录名 fallback）。

关键验证方式（路径为占位符，不是必须照抄的安装路径）：

import { loadExtensions } from '<PRIME_INSTALL>/dist/core/extensions/loader.js';
import * as prime from '<PRIME_INSTALL>/dist/index.js';
console.log(typeof prime.CONFIG_DIR_NAME); // undefined
const result = await loadExtensions(['<OFFICIAL_PACKAGE>/dist/index.js'], process.cwd());
console.log(result.errors); // error above

建议明确配置目录的宿主契约/注入方式或 feature-detection fallback；不能仅凭 Pi scope 名推断所有公共导出一致。具体 Prime 导出修复也可能应在宿主侧完成，希望文档说明责任边界。

2. 修复加载后还有宿主判定阻断（源码/API 核查）

实际 Prime SessionManager.inMemory()：

typeof sm.getBranch === "function"
typeof sm.buildContextEntries === "undefined"

0.1.67 readContextEntries() 有 getBranch fallback，但 isPiHost() 仍只检查 buildContextEntries，isOmpHost() 是其反值；session_start 因此会把 Prime 也归为 unsupported OMP 并禁用 ACP。

这是源码路径与真实 API 的核对，不是声称官方 session_start 已实跑：上面的加载错误发生得更早。现有 wrapper 加入 getBranch→buildContextEntries alias 才避开该门禁；但 raw branch 不一定等价于所有宿主的有效上下文，不建议仅删除 OMP guard 或加空 stub。请在 host-adapter 契约中明确 supported-host detection 与 entry-source 语义，并添加 Prime-shaped host fixture。

3. #366 的进展及后续验收

看到 #366 已提供 hostSession policy、deriveChildState 和公开 API，方向正好覆盖剩余需求。但截至本次检查 PR 尚未合并，GitHub mergeable=false；需要基于 #327 后的当前 master 解决冲突，并验证 sid 参数没有退回旧签名。上述 1/2 的启动阻断也需要纳入验收，否则仅有 helper 单测无法证明 Prime 可直接接入。

建议追加验收：

• Prime 实际 loader 加载 pristine 官方 dist，零 diagnostics；
• 正确识别 Prime，仍保持不受支持 OMP 的保护；
• 非空 agent_message 开启新回合，UI/control/synthetic 消息策略明确；
• 父/子压缩块与引用可恢复/可检索，子会话节奏独立，resume 不重复派生；
• 使用 Prime 原生 RLM 时可以通过官方配置关闭 Pi CLI delegation；
• 当前意图、完整工具回合、已有压缩会话的实际 outgoing context 不丢失/不重复。

Prime 0.9.4 的 daemon/runtime-host child 路径和 direct inline fallback 不完全相同，runner 隔离仍属于宿主责任，不能把所有 child 路径概括为一种。这里不要求本仓库修 Prime core。

自动压缩兜底仍留在 #269 轨道，不把本地 fork 的该行为混入本 issue 的最小修复范围。当前没有替换真实安装或重启活动会话；已验证的是上述加载对照，不是完整端到端迁移通过。

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 两个启动阻断都已修复并推上 PR #366（已 rebase 到 post-#327 的 master，即 v0.1.66，acp-kernel 0.0.63）。先说结论与层次判断，再给验证证据。

阻断 1：CONFIG_DIR_NAME 未导出 —— 是"适配器假设了 alias 模块的完整导出面"这一层的问题，不是单纯缺个 fallback

• 我本地用 CJS shim 复现了关键事实：缺失命名导出在不同 resolver 下死法不同——Prime loader 下运行时表现为 undefined（你们观测到的 path.join TypeError），而纯 Node ESM→CJS interop 下是链接期 SyntaxError: Named export 'CONFIG_DIR_NAME' not found。所以只对静态命名导入做 typeof fallback 只覆盖一半失败模式。
• 修复：新增 src/config-dir.ts，对 pi 包做 namespace import（两种 resolver 下都安全）+ feature-detect，缺失/非法时回退 Pi 规范值 .pi；五个路径使用点（log/index/user-config/setup-subagent-tools/update）全部收敛到该常量。审计确认它是 src/ 里唯一的 pi 包 value import（其余全是 import type，构建时擦除），dist 产物中 pi 包的 import 语句恰好一条、即那条 namespace import。
• 责任边界写入 docs/host-adapter.md §4：alias pi 包的宿主应当re-export CONFIG_DIR_NAME（只有宿主知道自己的目录名）；适配器侧保证不因缺失命名导出现在加载崩溃。你们在 Prime 侧补导出仍是首选做法，两边不再互相依赖。

阻断 2：宿主判定 —— 根因是把"非 pi 形状"当作了 OMP 的正向指纹

• isOmpHost = !isPiHost 把一切无 buildContextEntries() 的宿主判成 OMP。但 OMP（0.1.52 on OMP host: nudge example emits refs that do not exist in session (compress never succeeds in one-shot runs) #234 里明确写着 "Pi fork"）和 Prime 同为 Pi fork、同为 getBranch-only 形状——形状本身无法区分两者，所以正确修法不是删 guard 或加空 stub（空 stub 还会关掉补偿 getBranch 落后一条消息的 live-merge，你们的判断是对的）。
• 修复：isPiHost 保持严格（仅 buildContextEntries），继续管 delegate-tool 的 pi-only CLI flag（fork 宿主不该用 --mode json/--session 拉起子进程）；新 src/host.ts：entrySourceOf（buildContextEntries > getBranch > null）、isDeclaredForkHost（PI_ACP_FORK_HOST=1/true，调用时读取）、isUnsupportedHost = !isPiHost && !declared。默认行为不变：未声明的非 pi 宿主（含真 OMP）照旧拒绝；声明的 fork 放行并自动走既有 !isPiHost live-merge。拒绝文案 OMP_UNSUPPORTED_MESSAGE → UNSUPPORTED_HOST_MESSAGE，不再断言"这是 OMP"，同时指向两条出路（fork opt-in / OMP 走 billion-context proxy）。
• 契约文档化：docs/host-adapter.md §3 写明 supported-host detection 三步序、为何不能用形状判定、entry-source 语义表（哪个源、live-merge 是否生效、delegate flag 语义）、以及"不要 stub 空 buildContextEntries"的警告；Prime-shaped fixture 测试矩阵在 tests/host-detection.test.ts + tests/omp-refuse.test.ts opt-in 用例。

验收项 c 也收紧了：空内容 custom_message（纯控制信号）现在不开启新回合——谓词与投影共用同一 extractText 判据（条目要么进上下文要么不进，只有进上下文的条目才能划回合）；acp-status 面板恒排除；策略在 host-adapter §1 逐条写明。

对照你们列的六条追加验收：
a) Prime 真实 loader 加载 pristine dist——本环境跑不了 Prime，无法替你们实跑；能给出的是上面的结构性保证（dist 唯一 pi import = 容忍缺失导出的 namespace import，零其他 value import）。请重跑你们的 loadExtensions 对照，预期零 diagnostics。
b) 正确识别 Prime 且保住 OMP 保护——默认拒绝不变（有测试），opt-in 经 env 显式声明（有 fixture 测试）。
c) 非空 agent_message 开新回合、UI/control/synthetic 策略明确——已实现+测试+文档（见上）。
d) 父/子块可恢复可检索、子会话节奏独立、resume 不重复派生——round 1 测试覆盖（深拷贝隔离、derived state 上 activeBlocks/blockById 可达、一次性 marker、重复派生拒绝、child sidecar 独立持久化）；另外分支上原有一个 #367 提交（包入口导出 createRuntime/SessionRef/deriveChildState，正是让这条契约对外部宿主可达的修复），我 rebase+force-push 前发现它已在远程分支头上，已 cherry-pick 保留而非覆盖——现在派生契约可从 import { createRuntime } from "billion-context-pi" 端到端调用（其 tests/host-api.test.ts 经包名 self-reference 实测）。
e) Prime 原生 RLM 关闭 Pi CLI delegation——acp.json "delegate": false，host-adapter §3 已写明；delegate 路径本身零变化。
f) outgoing context 不丢不重——默认策略 ≡ legacy 扫描的回归 oracle + 投影/边界一致性测试；master 上的 degeneration/reasoning-drop/thinking-tokens 改动 rebase 后共存，全量套件通过。

验证数字：typecheck clean；738 tests / 735 pass / 0 fail / 3 skipped（rebase 后、修复前基线为 719/716）；build clean（dist 755.19 KB）；sid 签名已核对未回退（SessionRef {sessionId, sessionFile?}、deriveChildState(child, parent)、lastTurnBoundaryId(entries, turnPolicy) 各调用点 rebase 后完好）。分支历史现为 v0.1.66 ← feat(host)#364 ← fix(host) Prime 加载/识别 ← fix(host)#367 入口导出。

自动压缩兜底仍留在 #269 轨道，本次未触碰。剩下需要你们在真实 Prime 环境确认的只剩 a) 的 loader 实跑与 RLM e2e。

中文摘要：修复了 Prime 接入的两个启动阻断——配置目录改为 namespace import + feature-detect（兼容链接期报错与运行时 undefined 两种失败模式），宿主判定从"非 pi 即 OMP"改为显式 PI_ACP_FORK_HOST 声明门（OMP 默认保护不变，且保住 fork 的 live-merge 补偿）；另按验收项 c 收紧了空消息不开回合；PR #366 已 rebase 到 v0.1.66 并保留了 #367 的入口导出提交，可以合并。