Feature parity: port the upstream `export` command (session handoff export)

[tjp72]

The upstream billion-context ships a session export command (bili export) built on acp-kernel's prune() renderer. The Pi adapter (billion-context-pi) does not port this capability — sessions compressed inside Pi cannot be exported as a readable handoff document. This issue tracks restoring feature parity.

What upstream has

src/export.ts (~175 lines) plus a CLI command:

bili export                              # list persisted sessions (id/title/label/tokens/blocks)
bili export <session-id|label>           # render handoff markdown
bili export <id> --output handoff.md     # write to file
bili export <id> --full                  # full original messages instead of folded view

Key behaviors worth preserving:

1. Folded view by default — uses acp-kernel's prune(messages, state) to render the conversation exactly as the model saw it: compressed ranges are replaced by their block summaries ([Compressed conversation section] placeholders), never the raw messages.
2. --full mode — renders every original message: from the v3 conversation snapshot when available, otherwise falls back to the blockContents cache (v2 sessions).
3. v2 fallback — sessions without a persisted snapshot still export block summaries (with originals only under --full), plus an explicit note when nothing is recoverable.
4. Handoff semantics — the rendered document ends with guidance to paste the block summaries into a new session to continue without the proxy.

Why this matters for the Pi adapter

• Sessions managed by the adapter are currently opaque after the fact — there is no way to produce a human-readable, fold-aware snapshot of a compressed conversation.
• The handoff document is the only mechanism to migrate context between different hosts or to a fresh session without the proxy.
• prune() already lives in acp-kernel (which Pi pins and bundles); only the consumer code (export.ts + CLI wiring) is missing.

Proposed scope

1. Port export.ts (listSessions / exportSession / renderHandoff) to the Pi source tree.
2. Wire the export command into the Pi CLI (or expose it as a tool/command if Pi has no CLI surface — adapter-appropriate integration).
3. Keep both output modes (--output to file and stdout return) and the --full flag.
4. Preserve the v2 fallback path so older persisted sessions remain exportable.

Acceptance criteria

• export with no selector lists persisted sessions with title/label/tokens/blocks.
• export <id> renders the folded view (block summaries in place of compressed ranges, in conversation order).
• export <id> --full renders original messages from the snapshot/blockContents cache.
• --output writes the markdown file; without it the document is returned to stdout.
• Empty store / no-match / ambiguous-selector error messages match upstream behavior.
• Export output contains no secrets or environment-specific paths (upstream parity).

References

• Upstream: src/export.ts, src/cli.ts (export command parsing)
• Kernel dependency: acp-kernel src/prune.ts (prune, stripOrphaned*, summaryMessageId)

[ranxianglei]

ework接单

[ranxianglei]

🤖 ework agent · qwen3.8-27b

Done — the upstream export command is ported. PR: #272

What it does

New /acp-export command (named acp-export rather than export to avoid colliding with Pi's built-in /export HTML/JSONL export, and to match the existing acp / acp-status / acp-decompress / acp-search / acp-subagents family):

• No selector — lists ACP-managed sessions with title / label / tokens / blocks.
• <id> — renders the folded view: block summaries in place of compressed ranges, in conversation order, via the kernel's prune().
• <id> --full — renders the original messages from the session.
• --output <file> — writes the markdown file; without it the document is sent to the transcript (filtered from LLM context) or notified.

Design notes (Pi adapter vs. the proxy)

The Pi adapter keeps the full conversation in each session's .jsonl and ACP state in an adjacent <sessionFile>.acp.json (written every turn), so both the folded and full views are always available — no snapshot cache or v2 fallback needed, which is simpler than the proxy. Sessions are enumerated by scanning the session directory for *.acp.json files (any ACP-active session has one). Export documents are tagged acp-export and excluded from LLM-context projection, the same way acp-status panels are.

Parity checks (per the acceptance list)

• ✅ export with no selector lists persisted sessions with title/label/tokens/blocks.
• ✅ export <id> renders the folded view (block summaries in place of compressed ranges, in conversation order).
• ✅ export <id> --full renders the original messages.
• ✅ --output writes the markdown file; without it the document is returned.
• ✅ Empty store / no-match / ambiguous-selector error messages match upstream behavior.
• ✅ Export output contains no secrets or environment-specific paths.

Verification

• npm run typecheck — clean
• npm test — 472 pass, 0 fail, 3 skipped
• npm run build — success (acp-kernel inlined)

New: src/export.ts + tests/export-cmd.test.ts (10 tests: arg parsing, list, folded, full, output, no-match, empty store, ambiguous selector, command wiring). Updated src/commands.ts, src/messages.ts, and the command-count assertion in tests/integration.test.ts.

[ranxianglei]

这个export是否有对齐billion-context ,另外,是在内核实现的吗?还是重复实现了两次

[ranxianglei]

🤖 ework agent · qwen3.8-27b

两个问题分开答:

1. 是否对齐 billion-context(proxy)

核心渲染逻辑对齐,我逐行比对了 proxy 的 src/export.ts 和这边的 src/export.ts:

• renderHandoff 结构一致:# billion-context session handoff 头 + title/label/session id/tokens/blocks 元数据 + ## Full conversation / ## Conversation (folded view as the model saw it, N client messages) + 按 role 分组(### <role>)
• renderMessage(text / tool-call / tool-result / reasoning 四种 contentType)逐行一致
• matchSession(exact id → label → prefix)一致
• exportSession 流程 + 错误信息一致:no session matches "..." (run ... to list sessions)、selector "..." matches N sessions (...); use the full session id

差异都是 Pi 数据模型导致的,有意为之:

• 无 v2 fallback:proxy 有一段"无 snapshot 时只渲染 block 摘要 + blockContents"的 v2 分支。Pi 的 .jsonl 永远有完整对话(等价于 proxy 的 v3 snapshot),所以那段在 Pi 是死代码,删掉了。
• 会话来源:Pi 读 .jsonl + 相邻 .acp.json;proxy 读 envelope JSON。
• 元数据:Pi 没有 protocol/upstreamOrigin/requests,改用 messages 数。
• 命令面:/acp-export vs bili export(Pi 内置已有 /export,会撞名)。

2. 是否在内核实现 / 是否重复实现

没有在内核,确实重复实现了。 这是我做得不够好的地方。

我核对过 acp-kernel 的完整导出面:没有 renderHandoff / exportSession / SessionSummary / matchSession。内核里那个 renderMessage(index.js:1590)是另一个函数——给 LLM context 注入 <acp> tag 用的,和 handoff 无关,只是重名。

所以渲染核心现在有两份:proxy 的 src/export.ts 和 billion-context-pi 的 src/export.ts 各有一份 renderHandoff / renderMessage / matchSession。proxy 那边也是自包含的(只从内核 import 了 prune),没有走内核。

建议修复(抽到内核,消除重复)

把数据无关的渲染核心抽到 acp-kernel,两个 adapter 委托:

• 内核新增:renderHandoff({ coreMessages, state, full, meta }) + renderMessage(m) + matchSession(sessions, selector) —— 都只依赖 CoreMessage / CompressionState,与 adapter 无关
• adapter 各自保留:会话枚举(listSessions / loadSession)、输出路由(sendMessage / notify / file)、arg 解析
• 和现有模式一致:内核提供 buildStatusReport / searchBlocks,adapter 接线

落地顺序(受发布顺序约束,acp-kernel 必须先 ship):

1. acp-kernel 新增这 3 个导出 → 发版
2. billion-context(proxy)改成委托内核
3. billion-context-pi 改成委托内核(本次 PR 一并改)

要我现在按这个方向做吗?涉及 acp-kernel 发版 + 两个 repo 更新,你确认后我就开工。

[ranxianglei]

抽到内核吧 然后俩仓库都改了 做回归测试

[ranxianglei]

🤖 ework agent · qwen3.8-27b

已按「抽到内核 + 两个仓库都改 + 回归测试」完成，共 3 个 PR：

1. 内核（把重复的 handoff 渲染收敛进去） — acp-kernel#183

• 新增 renderHandoff / renderMessage / matchSession（+ HandoffInput / HandoffMeta 类型）。
• 宿主差异通过 meta.extraBullets 注入（proxy 传 protocol / upstream / requests；Pi 传 messages）；proxy 的 v2 fallback（block summaries + blockContents）保持不变。
• 回归：typecheck 干净，572 测试全过（含新增 6 个 handoff 测试），build 成功。未 bump 版本（release 分支专属）。

2. Pi adapter — billion-context-pi#272（在原 export 命令 PR 上追加一个 commit）

• src/export.ts 改为调用内核 renderHandoff({coreMessages, state, full, meta}) 和 matchSession(all, selector, labelOf)，删掉本地三份重复实现（净 −52 行）。
• acp-kernel 依赖 0.0.48 → 0.0.49。
• 回归：typecheck 干净，472 过 / 3 skip，build 成功。

3. Proxy — billion-context#434

• src/export.ts 的 v3 快照分支（s.lastMessages）整体委托内核；v2 fallback 字节级不变；matchSession 用内核版。
• acp-kernel 依赖 0.0.47 → 0.0.49（顺带吃到 0.0.48 的变更，已验证无破坏）。
• 回归：typecheck 干净，892 测试全过（含断言 v2 fallback 字节一致的 cli-export 测试），build 成功。

⚠️ 合并 / 发布顺序（关键）

1. 先合并 acp-kernel#183；
2. 发 acp-kernel 0.0.49（release 分支 → CI 自动 publish），确认 npm view acp-kernel version = 0.0.49；
3. 两个 adapter PR 的 lockfile 此时 npm install 刷新后即可转绿。现在它们在 CI 的 npm ci 阶段是红的（0.0.49 还没上 npm，无法解析）。

一个小的行为变化：折叠视图标题里的计数现在用「原始 client 消息数」（与 proxy 对齐）；之前 Pi 侧用的是 prune 之后的数量。已确认没有测试受影响。

三个仓库本地都用 acp-kernel#183 的构建做了 overlay 预验证（AGENTS.md 的 local pre-validation 流程），所以 0.0.49 一发布，两个 adapter PR 应直接转绿。

[ranxianglei]

内核合并了,发内核版本pr

[ranxianglei]

🤖 ework agent · qwen3.8-27b

内核版本 PR 已发：acp-kernel#184（release v0.0.49）

• 分支 2026-09-01_release-v0.0.49，基于最新 master（已含合并的 fix(setup): subagent ACP tool injection becomes an explicit /acp-subagents command (#179) #183）。
• 只改 package.json 一行：0.0.48 → 0.0.49（release commit 约定，不夹带其它变更）。
• v0.0.48 以来的唯一变更就是 handoff 渲染器（fix(setup): subagent ACP tool injection becomes an explicit /acp-subagents command (#179) #183）：renderHandoff / renderMessage / matchSession。
• 本地预检全绿：typecheck 干净、572 测试全过、build 成功。

接下来（需要你来）：

1. 合并 acp-kernel#184 → CI 自动打 tag v0.0.49 并 npm publish；
2. 确认 npm view acp-kernel version = 0.0.49；
3. 两个 adapter PR 各自 npm install 刷新 lockfile 后即转绿：
   • billion-context-pi#272
   • billion-context#434

（现在这两个 PR 在 CI 的 npm ci 阶段是红的，因为 0.0.49 还没上 npm；发布后我可以在两个仓库跑 npm install 提交 lockfile 刷新。）

[ranxianglei]

合并了 继续

[ranxianglei]

🤖 ework agent · qwen3.8-27b

继续完成 ✅

0.0.49 已确认上 npm（npm view acp-kernel version = 0.0.49）。

两个 adapter 的 lockfile 已刷新到 0.0.49 并推送，本地都用真实发布的 0.0.49（非 overlay）跑过全量回归：

PR	lockfile commit	回归
billion-context-pi#272	398d6c8	typecheck 干净、472 过 / 3 skip、build ✓
billion-context#434	56361d2	typecheck 干净、892 全过、build ✓

现在 0.0.49 已发布 + 两个 lockfile 都已指向 0.0.49，所以 CI 的 npm ci 阶段应该转绿了。

剩下就是你来合并这两个 adapter PR（human-only）：

• billion-context-pi#272
• billion-context#434

需要的话我可以盯一下两个 PR 的 CI 状态确认全绿。

[ranxianglei]

🤖 ework agent · qwen3.8-27b

CI 已确认全绿 ✅（都是 lockfile 刷新 commit 的 run，不是旧的）

• billion-context-pi#272（398d6c89）：9 项全 success — e2e (ubuntu/windows)、test (ubuntu/windows × 22/24)、pr-validation、docker、build-artifact。
• billion-context#434（56361d22）：6 项全 success — test (ubuntu/windows × 22/24)、version-guard、build-artifact。

两个 adapter PR 现在都可以合并了（human-only，我不合并）：

• feat: add /acp-export command (session handoff export) #272
• refactor: delegate session-handoff rendering to acp-kernel billion-context#434

合并后，/acp-export（Pi）和 bili export（proxy）就共用内核的 handoff 渲染逻辑了，#271 的 feature parity 完成。

[ranxianglei]

看看内核合并了吗

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

查过了，内核都合并了 ✅

• acp-kernel#183（handoff 渲染器）：已合并（2026-09-02 01:00Z）
• acp-kernel#184（release v0.0.49）：已合并（01:05Z），0.0.49 已发布

但有个情况要注意：npm 上 acp-kernel 现在已经到 0.0.56 了 —— 我们从 0.0.49 之后，内核又连续发了 7 个版本（0.0.50–0.0.56，共 32 个 commit）。我扫了一下这些改动，全是压缩引擎的 bugfix/improvement（sync 去活块、panel 计数标签、nudge 阈值门控、persist ENOENT 重试、report tool 归因、quote-fidelity 提示词等），没有一个动到 handoff 渲染器，所以 handoff 逻辑在 0.0.49→0.0.56 全程稳定存在。

两个 adapter PR 现在还开着，pin 的是 0.0.49（比最新落后 7 个版本的引擎修复）：

• billion-context-pi#272（open）
• billion-context#434（open）

我的建议：把两个 adapter PR 的 acp-kernel 依赖从 0.0.49 bump 到 0.0.56 再合并，这样它们直接带上这 7 个版本的引擎修复，不用之后再来一轮。bump 完我在两个仓库各重跑一遍 typecheck+test+build 确认全绿再推。

要我现在就做这个 bump 吗？（如果你更想先按 0.0.49 落地 export、之后单独追版本也行，说一声即可。）

[ranxianglei]

可以 你先提一个pr