@sema-agent/client-core 0.3.0 → 0.5.0

package/README.md

@@ -23,8 +23,8 @@ Renamed from **`@sema-agent/wire-cc-adapter`** (0.1.x, deprecated — see *Migra
 
 ## Scope
 
-- **Today (0.2.0)** — the adapter seam plus the first half of the `adapt()` pipeline (detail
-  below), migrated as-is from `wire-cc-adapter` 0.1.x.
+- **Today (0.5.0)** — the adapter seam, the `adapt()` pipeline, the notification/caps/model
+  families, and the adapter kernel (stream driver + downstream projectors).
 - **Planned** — the shell's remaining shared session logic lands here in batches: the
   five-layer frame dispatch, the compensation arms, the notification/dedup ledgers, the
   fleet/panel projections. The TUI then keeps only its Ink rendering and keyboard interaction;
@@ -84,16 +84,69 @@ keys).
 0.2.0 is the repo/name migration: **no behaviour change**, both guard suites carried over and
 green (22 + 203 checks).
 
+0.3.0 moved in the **dependency-free pure functions and side-channel ledgers** (subagent content,
+engine agent-panel, fleet panel projection, live question store, inline task stats, print
+tool-result frame, caps cache, tool-label store, task-description projection) with 140 new
+behaviour checks.
+
+0.4.0 moved in the **request-shaping gate family and the notification family**:
+
+- `notifications.ts` absorbed the whole background-completion subsystem — the process-lifetime
+  dedup ledgers (model-notification vs completion-card are **separate key spaces**), the idle
+  completion watcher for workflow + background-agent runs, the outstanding-run counter with its
+  subscription, the own-run ledger used for frame ownership, the delivery-failure supplement, and
+  the `hook_notice` classifier half (ownership fail-closed mirrored from the server).
+- 17 `*WireCaps` projections (attachments, client context, cloud config, fork, images, mcp, model,
+  permission, prompt profile, retain-background, rewind, self-orchestration, skills, ultracode,
+  web search, agents, plus the wire client factory), the SSE idle triage, the classifier-verdict
+  recogniser, the control router, and the model-budget/catalog/latch/effort rules.
+- New `hostEnv.ts`: the single host-environment read port. The moved projections used to default
+  their `env` parameter to `process.env`, which throws in a browser; they now default to
+  `hostEnv()` (the very same object under Node, `{}` where there is no `process`).
+- 🔴 One host assembly duty: `installNotificationQueuePort()`. Without it, task-notification
+  delivery is dropped — `notificationQueuePortMisses()` must stay 0.
+
+0.5.0 moved in the **adapter kernel** — the stream driver and the downstream projectors — and
+grew the host context to carry what a non-Node host must supply:
+
+- `AdapterContext` gained five optional ports (**minor, not breaking**): `log`, `probe`, `signal`,
+  `setTimer`/`clearTimer`, `coalesceIntervalMs`. Every one is native in a browser
+  (`console`, omit, `AbortController.signal`, `setTimeout`, a number) — no polyfill. Absent means
+  *that capability is off*, never a fallback: the kernel does not reach for `console`, `setTimeout`
+  or a filesystem probe on its own.
+- `adapter/runStream.ts` + `adapter/downstream/*` + the runtime half of `adapter/types.ts` moved in.
+  The driver used to drag **1,571 files / 26 Node builtins / 412 react files** into its transitive
+  closure through two dynamic imports back into the shell; both are now `ChromeEvent` arms
+  (`last_turn_usage`, `plan_review_park`) with their host duty written on the arm. Measured closure
+  after the cut: **6 files, zero Node builtins, zero react**.
+- Six stream-driver behaviours landed with it: the turn-open triple-clear (the third clear —
+  stale prompt suggestions — plus the fifth sub-flow cut-out), the 1.5 s IDLE-FLUSH race that
+  surfaces already-generated content while the model is emitting a long tool argument, manual
+  iterator cleanup, the abort branch, and the no-`result` tail leg.
+- The coalescing **cadence** is now a host knob. CC itself runs two values in two hosts (its
+  desktop host coalesces single-frame deltas at 16 ms; the 2.1.207 CLI line we track uses 100 ms),
+  so the cadence is host render policy while the merge *semantics* stay here, in one place.
+
 Known intentional deltas from the CLI are enumerated in `ADAPTER_DIVERGENCES`.
 
 ## Guards
 
 ```bash
 npm install
-node scripts/run-client-core-pure-test.mjs   # 22 consumer-view checks; no CLI tree needed
-node scripts/run-client-core-diff-test.mjs   # 203 checks: differential + replay-id + ledger
+node scripts/run-client-core-pure-test.mjs          # 429 consumer-view checks (22 + 140 + 208 + 59); no CLI tree needed
+node scripts/run-client-core-portability-test.mjs  # 14 checks: kernel closure + browser bundle
+node scripts/run-client-core-diff-test.mjs         # 284 checks: differential + replay-id + ledger
 ```
 
+Each suite carries a floor that only moves up — a refactor that stops executing a group of
+assertions is a failure, not a quieter pass.
+
+The portability guard walks the value-level import closure of the stream driver (asserting zero
+Node builtins, zero react, zero shell debug edge, closure size under its ceiling) and then really
+bundles it with esbuild `--platform=browser`. It carries its own **positive control**: a
+deliberately poisoned file must be reported by the same scanner, otherwise the run exits 9
+(the tool is broken) rather than green.
+
 The differential half needs the CLI tree (the reference bridge lives there). It is located via
 `SEMA_CLI_ROOT`, else a sibling checkout of the sema CLI source tree (internal reference bridge; not part of the published package); a pinned `SEMA_CLI_ROOT` without
 `src/sema/upstreamBridge.ts` fails loudly instead of falling back to another tree. With no CLI

package/dist/adapt.d.ts

@@ -1,6 +1,31 @@
 import type { AdapterContext, AdapterOutput, WireToCcAdapter } from './seam.js';
-/** cli COALESCER 节流(207 口径;187 时代是 16ms)。宿主无关,时钟从 ctx.now() 取。 */
+/**
+ * 活体增量攒批节拍的**默认值**(时钟从 ctx.now() 取;宿主可用 `ctx.coalesceIntervalMs` 覆盖)。
+ *
+ * 取值依据(两个都是实测,别把其中一个当"唯一真相"):
+ *  · **100ms** = 我们对标的 CC 2.1.207 CLI 口径(187 时代是 16ms,207 提到 100ms 降重绘频率,
+ *    长回答滚动更稳)—— 壳是 207 fork,所以库的默认值取它,壳消费本包时行为零变化;
+ *  · **16ms** = CC **桌面端**宿主 `makeStreamDeltaCoalescer` 的单帧攒批节拍(设计稿 R1 实测)。
+ * ⇒ 结论:**节拍是宿主渲染策略,不是 wire 语义** —— CC 自己两个端就是两个值。web/桌面宿主
+ *   想要 16ms 就传 `coalesceIntervalMs: 16`,合并**语义**(思考先于文本、段边界重开块、
+ *   committed 恒随后)在库里,一份。
+ *
+ * 🔴 顺带钉一句反面事实(R1 证伪,别再写进任何注释/文档):**"UI 从不见裸 token" 是错的** ——
+ * CC 攒批后 flush 的载荷仍是 `stream_event` 增量 delta,CC 的 UI 照样消费增量;
+ * 完整 assistant 消息是 SDK 另发的一路。我们这里的 `stream_delta` chrome 臂同构。
+ */
 export declare const FLUSH_INTERVAL_MS = 100;
+/**
+ * T40 IDLE-FLUSH 竞速窗(cli upstreamBridge `IDLE_FLUSH_MS` 逐字同值)。
+ *
+ * 病:模型转入长工具参数生成(大 Write 的 input_json 不经本桥)时 SSE 增量停摆,而 thinking/
+ * answerSegment 里**已经生成**的内容还押着陪等(pty 确证:11s 整屏 hash 恒定)。
+ * 修:增量停 ≥1.5s 且缓冲非空 ⇒ 先 drainLive()(活体预览语义不变),再提交思考+文本段
+ * (段序铁律不破:本来就该在下一张工具卡前 flush,这里只是提前)。
+ * 🔴 这是**过渡修**,正解在 core [817](wire 侧给事件);且**需要宿主定时器**:
+ * `ctx.setTimer` 缺席 ⇒ 整条竞速不启用(纯等下一帧),与 0.4.0 逐字同行为。
+ */
+export declare const IDLE_FLUSH_MS = 1500;
 /** cli SUBAGENT_TOOL_NAMES / WORKFLOW_TOOL_NAMES 同源(判别资产,别各自重写)。 */
 export declare const SUBAGENT_TOOL_NAMES: ReadonlySet<string>;
 export declare const WORKFLOW_TOOL_NAMES: ReadonlySet<string>;
@@ -45,11 +70,13 @@ export declare const ADAPTER_COVERAGE: {
     readonly frames: readonly ["assistant", "user", "stream_event", "turn_usage", "result", "system", "task_notification", "workflow_complete", "diagnostics", "steering_injected", "workspace_changed", "retry_status", "tool_end_result(仅 response-id 复位 + 开卡台账出栈,不铸 tool_result)"];
     /** 已落码臂产出的 transcript 消息类目(差分守卫的比对域)。 */
     readonly transcriptKinds: readonly ["assistant_text", "assistant_thinking", "assistant_tool_use", "user_tool_result_decision", "user_task_notification", "system_passthrough"];
+    /** B3(0.5.0)新落码的臂/半场 —— 从 todo 移过来的,别再在 todo 里留同名条目。 */
+    readonly b3: readonly ["T38 三清第三清 + T57 第五处断闸:prompt_suggestions(turn 开场作废 + 子流断闸)", "T40 IDLE-FLUSH 1.5s 竞速(需 ctx.setTimer;缺席=不启用)", "T58 手动 iterator 的 finally cleanup(early break/throw 都要关上游生成器)", "T59 abort 半场(ctx.signal;中断后不产终答)", "T60 无 result 收尾腿(泄尾增量 → 清 liveness → 尾思考 → 尾文本段)"];
     /** 如实留白——写不动/依赖未搬运资产的臂,#52b 起分批接。 */
-    readonly todo: readonly ["tool_end_result → user tool_result 正常路径(需搬 wireOutputToBody/structuredToToolUseResult/mock 合成器 + TodoWrite/ReportFindings 富卡片,约 600 行;workflow 轮询信封的人话投影已在 workflow.ts 就位,等这条接线)", "tool_end_result 的两个侧产物:Remember → memory_saved 系统消息、task/task-list structured → 面板台账全量同步", "result/turn 末的开卡兜底关闭(同上,依赖合成器)", "task_progress → 面板行绑定(bindTaskCard FIFO/显式父、inline stats、alias、resident 台账、SubagentStart hook、workflow lane 三级门)", "settlePanelTasks 三处 sweep(依赖上面的行台账)", "#117a bg Bash 回执探测(detectEngineBgShellReceipt 文案锚定探测器)", "abort/Esc 半场(AdapterContext 无 signal 位——见 SEAM-GAP-4)", "IDLE_FLUSH 1.5s 竞速(件1 大 Write 静默窗;需 ctx 侧定时器能力)", "macrotask 让渡(cli 在提交前让出宏任务给 Ink;宿主渲染策略,不进库)"];
+    readonly todo: readonly ["tool_end_result → user tool_result 正常路径(需搬 wireOutputToBody/structuredToToolUseResult/mock 合成器 + TodoWrite/ReportFindings 富卡片,约 600 行;workflow 轮询信封的人话投影已在 workflow.ts 就位,等这条接线)", "tool_end_result 的两个侧产物:Remember → memory_saved 系统消息、task/task-list structured → 面板台账全量同步", "result/turn 末的开卡兜底关闭(同上,依赖合成器)", "task_progress → 面板行绑定(bindTaskCard FIFO/显式父、inline stats、alias、resident 台账、SubagentStart hook、workflow lane 三级门)", "settlePanelTasks 三处 sweep(依赖上面的行台账)", "#117a bg Bash 回执探测(detectEngineBgShellReceipt 文案锚定探测器)", "abort 半场里依赖行台账的两件:settlePanelTasks 兜底 sweep + 开卡合成器兜底关卡(见上面两条)", "macrotask 让渡(cli 在提交前让出宏任务给 Ink;宿主渲染策略,不进库)"];
 };
 /** 本批**已知的、有意的**行为分歧(差分守卫显式登记,绝不当等价) */
-export declare const ADAPTER_DIVERGENCES: readonly [string, string, string];
+export declare const ADAPTER_DIVERGENCES: readonly [string, string, string, string];
 /** 有台账序列化位的适配器(seam 的 WireToCcAdapter 只定了 exportLedger——见 SEAM-GAP-1)。 */
 export interface WireToCcAdapterWithLedger extends WireToCcAdapter {
     exportLedger(): AdapterLedgerState & Record<string, unknown>;