Skip to content

refactor: delegate session-handoff rendering to acp-kernel - #434

Closed
ranxianglei wants to merge 2 commits into
masterfrom
2026-09-01_handoff-delegate
Closed

ranxianglei wants to merge 2 commits into
masterfrom
2026-09-01_handoff-delegate

Conversation

@ranxianglei

@ranxianglei ranxianglei commented Sep 1, 2026 •

Copy link
Copy Markdown
Owner

Closes #601 — tracking issue for this PR.

What

Removes the duplicated session-handoff markdown logic from the proxy by delegating to the kernel's shared renderer (acp-kernel PR #183), so the proxy and billion-context-pi no longer each carry a copy of renderHandoff / renderMessage / matchSession (requested in ranxianglei/billion-context-pi#271).

Changes (src/export.ts)

  • The v3-snapshot path (s.lastMessages) now delegates the whole doc — metadata header + folded (prune) / full conversation — to kernel renderHandoff({coreMessages, state, full, meta}), with protocol / upstream / requests injected via meta.extraBullets.
  • The v2 fallback (per-block summaries + blockContents originals) is unchanged and stays byte-identical.
  • matchSession now comes from the kernel (label accessor = s.meta.label).
  • Bumps acp-kernel 0.0.47 → 0.0.49 (the release that ships the handoff exports). package-lock.json is refreshed once 0.0.49 is on npm.

Verification (local pre-validation against acp-kernel#183's build)

  • npm run typecheck — clean
  • npm test — 892 pass, 0 fail (incl. tests/cli-export.test.ts, which asserts the v2-fallback output is byte-identical)
  • npm run build — success

Dependency / merge order

Blocked on acp-kernel#183 merging + acp-kernel 0.0.49 publishing. Until then CI is red at npm ci (cannot resolve 0.0.49). After 0.0.49 is live, run npm install to refresh the lockfile and the PR goes green.

Replaces the local renderHandoff/renderMessage/matchSession in src/export.ts
with the kernel's shared implementations (acp-kernel PR #183), so the proxy
and the Pi adapter no longer duplicate the handoff markdown logic.

- The v3-snapshot path (s.lastMessages) now delegates the whole doc
  (metadata + folded/full conversation) to kernel renderHandoff.
- The v2 fallback (block summaries + blockContents) is unchanged and stays
  byte-identical; matchSession now comes from the kernel.
- Bumps acp-kernel 0.0.47 -> 0.0.49 (the release that ships the handoff
  exports). package-lock.json is refreshed once 0.0.49 is published on npm.

Local pre-validation against acp-kernel#183's build: typecheck clean,
892/892 tests pass, build success.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 ework agent · qwen3.8-27b

[bot] 🏷 PR opened: #435 (branch 2026-09-01_kernel-handoff-export)

Implemented exactly as described in the issue:

  • src/export.ts — the v3-snapshot path (s.lastMessages) now delegates the whole doc (metadata header + folded/full conversation) to kernel renderHandoff({coreMessages, state, full, meta}), with protocol / upstream / requests injected via meta.extraBullets. The v2 fallback is untouched. Local renderMessage and matchSession are deleted; matchSession now comes from the kernel with label accessor s.meta.label.
  • package.json — acp-kernel bumped 0.0.47 → 0.0.49. package-lock.json intentionally left at 0.0.47 until 0.0.49 is on npm.

Verification (local, against acp-kernel#183's build 0.0.48-pr.183.36):

  • npm run typecheck — clean
  • npm test — 892 pass, 0 fail (incl. tests/cli-export.test.ts v2 byte-identity and tests/export-uncompressed.test.ts v3 path)
  • npm run build — success
  • Extra check: rendered the same representative session (all four content types, empty message, role grouping, one active compression block) through master's old code vs. the new delegated code — output is byte-identical for both full=false and full=true.

Status: blocked on acp-kernel#183 merging + acp-kernel 0.0.49 publishing (currently open/unmerged; latest stable on npm is 0.0.48). CI will be red at npm ci until then. Once 0.0.49 is live I'll run npm install to refresh the lockfile, push, and the PR goes green.

@github-actions

github-actions Bot commented Sep 2, 2026

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-09-01_handoff-delegate (56361d2)

Option A — Install from npm PR tag (recommended)

npm install -g billion-context@pr-434

Each push to this PR publishes a new version under the pr-434 npm tag.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr434.tgz
npm install -g package

This comment is automatically updated on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

Review vs master 3cd85b6: ❌ needs rework before merge — superseded in part by #587 (PR#587), which rewrote renderHandoff semantics after this PR was authored.

What still holds:

  • Kernel 0.0.56 renderHandoff(input) signature matches the PR's call shape ({coreMessages, state, full, meta{title,label,sessionId,contextTokens,extraBullets}}) ✓
  • Kernel matchSession(sessions, selector, labelFn) 3-arg form is exported ✓
  • Delegation removes ~100 lines of duplicated rendering ✓

What breaks vs #587:

  1. Folded-snapshot trap. Master src/export.ts:73-74: const folded = s.lastMessagesFolded === true; const view = full || folded ? messages : prune(...). Persisted snapshots are now bounded pre-pruned views whose ids no longer align with state ranges — master deliberately does NOT re-prune them (comment at export.ts:71: prune() would resurrect dropped summaries at index 0). Kernel renderHandoff unconditionally does view = full ? coreMessages : prune(coreMessages, state) — feeding it a folded snapshot re-triggers exactly the resurrection bug fix #401: persist bounded folded-view snapshot instead of full raw history #587 documented.
  2. Lost --full block originals. fix #401: persist bounded folded-view snapshot instead of full raw history #587's --full on a folded session appends per-block original messages from blockContents (dead-session recovery). Kernel renderHandoff has no blockContents parameter — that capability silently disappears.
  3. merge-tree shows src/export.ts auto-merging (different textual regions) — this is a silent semantic clobber, worse than a conflict: the kernel early-return and fix #401: persist bounded folded-view snapshot instead of full raw history #587's folded branch would coexist incoherently.

Rework direction (see #601): keep the host renderer for the folded and --full+blockContents cases; delegate only the plain unfolded case — or extend kernel renderHandoff with a prePruned: true mode + optional block-append input, then fully delegate.

(tracking: #601)

@ranxianglei

Copy link
Copy Markdown
Owner Author

Superseded by PR#631 — rework of this delegation onto post-#587 export.ts, now that kernel v0.0.57 ships folded/blocksFull (acp-kernel#216/#217). Rendering verified byte-identical on all existing export suites. Closing in favor of #631.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

delegate session-handoff rendering to acp-kernel renderHandoff

1 participant