host adapter: deriveChildState runtime is not reachable from the published package API

[qiangu2020]

Reproduction

At PR #366 head (5f435a730ef806e8baaab4916f02c76c9d677b78), docs/host-adapter.md tells an inline host to call:

await runtime.deriveChildState(childRef, parentRef);

However, the published package API only exports createAcpExtension from src/index.ts / dist/index.d.ts. createAcpExtension() creates const runtime = createRuntime(adapter) inside its extension-factory closure and does not return or expose it. createRuntime is exported from src/runtime.ts, but package.json exports only . -> dist/index.js; there is no dist/runtime.js subpath.

Therefore a Prime-style adapter importing billion-context-pi cannot obtain the "extension runtime" required by the documented host contract. This remains true even after #366 is built and published unless the entrypoint export/API changes.

Impact

Inline children cannot perform the required one-time explicit derivation before their first context event. With a parentSession header they instead take the legacy implicit inheritance path, which copies parent pacing/rhythm state verbatim rather than the inherit-blocks/reset-rhythm behavior #366 intends.

Suggested minimal fix

Expose a supported host-facing way to invoke derivation. For example, re-export createRuntime plus AcpRuntime/SessionRef from the package entrypoint, or add a callback/handle on createAcpExtension that exposes its runtime. Then add a package-entrypoint test which imports only from billion-context-pi and performs the documented call.

Related: #317, #364, #366.

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Verified — real gap. Checked at three layers before touching code:

1. Published package (v0.1.67 tarball): dist/index.d.ts exports only createAcpExtension + default; the built dist/index.js has a single export block and createRuntime appears in it only as an internal definition/call site, never in the export list. The exports map is "." only, so billion-context-pi/dist/runtime.js is unreachable even though the file ships in the tarball (Node would throw ERR_PACKAGE_PATH_NOT_EXPORTED).
2. PR feat(host): unified turn boundary + child-session state derivation (#364) #366 head (5f435a7): the diff adds deriveChildState to AcpRuntime, the SessionRef interface, the pure deriveChildState in src/state.ts, and docs/host-adapter.md — but adds no new entrypoint exports to src/index.ts. tsup bundles a single entry (src/index.ts), so the published module namespace can only grow through that file.
3. Impact chain confirmed: with no reachable runtime, inline children fall back to the parentSession header path, which inherits verbatim (blocks and rhythm) — exactly the wrong behavior feat(host): unified turn boundary + child-session state derivation (#364) #366 defines for inline children.

Root cause vs symptom: the root cause is a design gap introduced by #366's documentation — the contract names "the extension runtime", an object the package keeps inside the factory closure. The unreachable API is the cause; the wrong-inheritance fallback is its symptom. Your suggested fix hits the core, so I'm implementing it rather than discussing alternatives.

Plan (in progress):

• Re-export from the entrypoint: createRuntime (value), AcpRuntime + SessionRef (types), plus the pure deriveChildState (host-adapter.md §2 documents it as a host-facing surface too, so leaving it out would leave half the contract broken).
• docs/host-adapter.md: correct the "on the extension runtime" wording — hosts construct their own instance via createRuntime(adapter) from the package entrypoint. Derivation operates on on-disk sidecars through session refs, so any runtime instance works (that cross-instance property is already designed in; the doc just didn't say how to get a handle).
• New tests/host-api.test.ts that imports only from billion-context-pi (Node self-reference → built dist): asserts the names exist and runs the documented await runtime.deriveChildState(childRef, parentRef) round-trip end-to-end with temp-dir sidecars, including the one-time-marker guard. CI reordered to build before test so the self-reference resolves in CI.
• Changelog entry.

Since deriveChildState only exists on PR #366's branch (wt-364-ework-daemon), the fix commits there and lands with #366 — a separate PR against master couldn't compile today. FYI: #366 is currently behind master (based on v0.1.61, master is at v0.1.67) and shows as conflicted, so it needs a rebase before merge regardless of this fix.

中文摘要:核实属实——已发布包(0.1.67)入口只导出 createAcpExtension,exports map 封死子路径,#366 的 diff 也没添加入口导出,文档中的 runtime.deriveChildState 调用确实不可达;根因是 #366 文档契约引用了包内私有对象。正在按最小方案修复(入口重导出 createRuntime/AcpRuntime/SessionRef/deriveChildState + 仅从包名导入的入口测试 + 文档修正),提交落在 #366 分支上随其一起合并。

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

Verified, fixed. Commit 4a4e88a, pushed to wt-364-ework-daemon → updates PR #366 (#366), which now carries both changes.

Verification (before touching code)

• Issue confirmed real. Inspected the published v0.1.67 tarball: dist/index.d.ts exports only createAcpExtension (+ default); the built dist/index.js has a single export block with no createRuntime; package.json exports maps only "." → dist/index.js, so any billion-context-pi/runtime subpath fails. At PR feat(host): unified turn boundary + child-session state derivation (#364) #366 head (5f435a7) nothing in src/index.ts changes this. Not a duplicate (searched issue/PR history for derivation/host-adapter/Prime inline-child topics).
• Layering. The unreachable call is the symptom; the root cause is a design gap in feat(host): unified turn boundary + child-session state derivation (#364) #366: its doc contract names "the extension runtime" as the host-facing surface, but that instance is private to the createAcpExtension factory closure and was never exposed. Your suggested fix direction (entrypoint re-export) is the right level — it exposes a supported API rather than patching around the closure. And yes, until reachable, inline children silently take the implicit parentSession-header path, which copies pacing/rhythm verbatim — exactly what feat(host): unified turn boundary + child-session state derivation (#364) #366 exists to avoid.

Fix contents (4a4e88a)

File	Change
src/index.ts	Re-export createRuntime, types AcpRuntime / SessionRef, and pure deriveChildState from the package entrypoint. Derivation operates on on-disk sidecars via session refs, so it works across runtime instances — hosts build their own with createRuntime(adapter) (same AdapterConfig as createAcpExtension; {} suffices for derivation alone)
docs/host-adapter.md	"API surfaces" rewritten: both surfaces documented as package-entrypoint imports; usage snippet now starts with import { createRuntime } from "billion-context-pi"
tests/host-api.test.ts	New — imports only from "billion-context-pi" (Node self-reference → dist/index.js) plus acp-kernel for fixtures. Covers: entrypoint typeof checks; pure-function deep-copy + rhythm reset; the documented await runtime.deriveChildState(childRef, parentRef) end-to-end over temp-dir sidecars (inherited blocks, one-time derivedFrom marker, repeat-derivation refusal). Skips cleanly when dist/ is unbuilt
.github/workflows/ci.yml	Test job reordered: build now precedes test, so the self-reference resolves in CI
CHANGELOG.md	Entry added under Unreleased

Why it rides on PR #366 instead of a standalone PR

CI runs only for pull_request against master, and this fix cannot compile against master alone (deriveChildState doesn't exist there yet) — nor would it matter until #366 lands. It's therefore an additive commit on #366's head; the PR body now carries an addendum documenting this, and #366's merge will ship both.

Verification results

Local at the new head: typecheck ✅ · build ✅ · full suite 677 tests, 0 failures, 3 pre-existing skips (omp identity + live-context tests, unrelated — none from this change); the three new host-api tests pass standalone. CI will run on the updated PR.

中文摘要：修复了 #366 文档契约中 deriveChildState 对外部宿主不可达的问题（根因：契约指向工厂闭包内的私有 runtime，而发布包只导出 createAcpExtension）——包入口重新导出 createRuntime/SessionRef/deriveChildState，新增仅从包名导入的端到端测试、CI 改为先 build 后 test，作为追加提交并入 PR #366；本地 typecheck/build/全量测试全绿，等 CI 与人工合并。