@xrkseek/harness 0.6.21 → 0.7.0-rc.1

package/node_modules/@xrkseek/xrk-settings/lib/invariant.js

@@ -1,67 +1 @@
-import { Service } from "@xrkseek/cordis";
-//#endregion
-//#region lib/types/index.js
-/**
-* Service Definition for the user-settings capability seam (`ctx.settings`). Providers store one raw document of
-* per-namespace sections; plugins register a namespace schema and read the
-* resolved value, which layers schema defaults, the registrant's composition
-* `base`, and the user document section, in that order.
-* @module @xrkseek/xrk-settings
-*/
-/**
-* Deep equality over JSON-compatible data (objects, arrays, primitives) — the
-* Service Definition's single change-detection predicate, exported so the invariant
-* companion checks exactly the implementation's relation.
-* @param a - one JSON-compatible value.
-* @param b - the other JSON-compatible value.
-* @returns whether the two values are structurally equal.
-*/
-function deepEqualJson(a, b) {
-	if (a === b) return true;
-	if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
-	if (Array.isArray(a) || Array.isArray(b)) {
-		if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
-		return a.every((entry, index) => deepEqualJson(entry, b[index]));
-	}
-	const left = a;
-	const right = b;
-	const keys = Object.keys(left);
-	if (keys.length !== Object.keys(right).length) return false;
-	return keys.every((key) => key in right && deepEqualJson(left[key], right[key]));
-}
-Service.init;
-//#endregion
-//#region lib/types/invariant.js
-/**
-* Package-owned invariant companion for `@xrkseek/xrk-settings`.
-* @module @xrkseek/xrk-settings/invariant
-*/
-const PACKAGE_NAME = "@xrkseek/xrk-settings";
-/** Cordis companion plugin name. */
-const name = "settings-invariant";
-/** Service required before the companion can reserve package ownership. */
-const inject = ["invariants"];
-/**
-* Install the commit-event contract: `settings/updated` fires only for a
-* currently registered namespace, only when the resolved value changed, and
-* only with the service's authoritative resolved value — all judged with the
-* seam's own equality predicate.
-*/
-const install = (ctx, fail) => {
-	ctx.on("settings/updated", (ns, next, prev) => {
-		const settings = ctx.get("settings");
-		if (settings === void 0) fail(`settings/updated for "${ns}" emitted without a live settings service`);
-		const current = settings.get(ns);
-		if (current === void 0) fail(`settings/updated for "${ns}" emitted while the namespace is unregistered`);
-		if (!deepEqualJson(current, next)) fail(`settings/updated for "${ns}" does not match the authoritative resolved value`);
-		if (deepEqualJson(next, prev)) fail(`settings/updated for "${ns}" emitted without a resolved-value change`);
-	});
-};
-/**
-* Register this package's invariant companion.
-* @param ctx - Cordis context carrying the invariant service.
-* @returns the installed registration's disposer after setup succeeds.
-*/
-const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
-//#endregion
-export { apply, inject, name };
+export * from "./types/invariant.js";

package/node_modules/@xrkseek/xrk-system-prompt/package.json

@@ -1,15 +1,15 @@
-{
-    "version":  "0.0.0-stub",
-    "name":  "@xrkseek/xrk-system-prompt",
-    "description":  "XRK stub - system-prompt registry service (ctx.systemPrompt)",
-    "exports":  {
-                    ".":  "./index.js",
-                    "./src/*":  "./src/*",
-                    "./package.json":  "./package.json"
-                },
-    "type":  "module",
-    "private":  true,
-    "devDependencies":  {
-                             "@xrkseek/cordis":  "workspace:^"
-                         }
-}
+{
+    "version":  "0.0.0-stub",
+    "name":  "@xrkseek/xrk-system-prompt",
+    "description":  "XRK stub - system-prompt registry service (ctx.systemPrompt)",
+    "exports":  {
+                    ".":  "./index.js",
+                    "./src/*":  "./src/*",
+                    "./package.json":  "./package.json"
+                },
+    "type":  "module",
+    "private":  true,
+    "devDependencies":  {
+                             "@xrkseek/cordis":  "workspace:^"
+                         }
+}

package/node_modules/@xrkseek/xrk-system-prompt/src/index.ts

@@ -1,144 +1,144 @@
-/**
- * System-prompt registry: the `ctx.systemPrompt` service packages contribute
- * model guidance to.
- *
- * A contributor registers a named section from the apply of its own fiber;
- * `assemble()` resolves the sections in `order`, drops the ones that say
- * nothing for this turn, and joins the rest. A section whose body is a
- * provider is resolved at assembly time, so it can follow per-turn state.
- *
- * This is the workspace stand-in for the published
- * `@xrkseek/xrk-system-prompt`: it carries the contract the workspace's
- * consumers and specs are written against, so their behavior is specified
- * against a service rather than a deployment. Replace it with the real package
- * (or remap it) once that lands.
- */
-
-import { Context, Service } from '@xrkseek/cordis'
-
-/** One section as a package registers it. */
-export interface PromptSectionInput {
-  /** Stable identifier, namespaced by the contributing package. */
-  readonly name: string
-  /** Assembly position; lower runs first. Defaults to `0`. */
-  readonly order?: number
-  /**
-   * Section body, or a provider resolved at assembly time. A body that
-   * resolves empty (or whitespace-only) leaves no section behind.
-   */
-  readonly text: string | (() => string | Promise<string>)
-}
-
-/** One section as it stands inside an assembled prompt. */
-export interface PromptSection {
-  readonly name: string
-  readonly order: number
-  readonly text: string
-}
-
-/** An assembled prompt. */
-export interface AssembledPrompt {
-  /** Sections in assembly order. */
-  readonly sections: readonly PromptSection[]
-  /** `sections` joined with a blank line — the text handed to the model. */
-  readonly text: string
-  /** Optional route variables filled by model-selection. */
-  readonly variables?: Record<string, string>
-}
-
-/** Context passed through `system-prompt/assemble`. */
-export interface AssembleContext {
-  readonly signal?: AbortSignal
-}
-
-declare module '@xrkseek/cordis' {
-  interface Context {
-    systemPrompt: SystemPromptService
-  }
-  interface Events {
-    'system-prompt/assemble'(
-      assembly: unknown,
-      context: AssembleContext,
-      next: () => Promise<AssembledPrompt>,
-    ): Promise<AssembledPrompt>
-  }
-}
-
-/** Plugin config. */
-export interface Config {
-  /** Base persona; an empty persona contributes nothing. */
-  readonly persona?: string
-}
-
-/** Section name carrying the configured persona. */
-const PERSONA_SECTION = 'persona'
-
-/**
- * Render an assembled prompt as text.
- * @param prompt - an assembled prompt, or text passed through unchanged.
- * @returns the prompt text.
- */
-export function renderPrompt(prompt: AssembledPrompt | string): string {
-  return typeof prompt === 'string' ? prompt : prompt.text
-}
-
-/** The `ctx.systemPrompt` registry. */
-export class SystemPromptService extends Service {
-  private readonly sections = new Map<string, PromptSectionInput>()
-  private readonly persona: string
-
-  /**
-   * @param ctx - the context this service registers in.
-   * @param config - plugin config; `persona` is the base prompt body.
-   */
-  constructor(ctx: Context, config: Config = {}) {
-    super(ctx, 'systemPrompt')
-    this.persona = typeof config.persona === 'string' ? config.persona : ''
-  }
-
-  /**
-   * Contribute one prompt section for as long as this service's fiber lives.
-   * @param input - the section to register.
-   * @returns a disposer removing the section again.
-   * @throws when the name is already registered.
-   */
-  section(input: PromptSectionInput): () => void {
-    const { name } = input
-    if (this.sections.has(name)) {
-      throw new Error(`prompt section already registered: ${name}`)
-    }
-    const sections = this.sections
-    // Service method tracing binds `this.ctx` to the caller, so the section
-    // unloads together with the fiber that contributed it.
-    void this.ctx.effect(() => {
-      sections.set(name, input)
-      return () => {
-        sections.delete(name)
-      }
-    }, `systemPrompt.section(${JSON.stringify(name)})`)
-    return () => {
-      sections.delete(name)
-    }
-  }
-
-  /**
-   * Resolve every registered section, in `order`.
-   * @returns the assembled prompt: its sections and their joined text.
-   */
-  async assemble(): Promise<AssembledPrompt> {
-    const sections: PromptSection[] = []
-    if (this.persona.trim()) {
-      sections.push({ name: PERSONA_SECTION, order: -1, text: this.persona })
-    }
-    const registered = [...this.sections.values()]
-      .sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
-    for (const input of registered) {
-      const text = typeof input.text === 'function' ? await input.text() : input.text
-      if (!text.trim()) continue
-      sections.push({ name: input.name, order: input.order ?? 0, text })
-    }
-    return { sections, text: sections.map(entry => entry.text).join('\n\n') }
-  }
-}
-
-export default SystemPromptService
+/**
+ * System-prompt registry: the `ctx.systemPrompt` service packages contribute
+ * model guidance to.
+ *
+ * A contributor registers a named section from the apply of its own fiber;
+ * `assemble()` resolves the sections in `order`, drops the ones that say
+ * nothing for this turn, and joins the rest. A section whose body is a
+ * provider is resolved at assembly time, so it can follow per-turn state.
+ *
+ * This is the workspace stand-in for the published
+ * `@xrkseek/xrk-system-prompt`: it carries the contract the workspace's
+ * consumers and specs are written against, so their behavior is specified
+ * against a service rather than a deployment. Replace it with the real package
+ * (or remap it) once that lands.
+ */
+
+import { Context, Service } from '@xrkseek/cordis'
+
+/** One section as a package registers it. */
+export interface PromptSectionInput {
+  /** Stable identifier, namespaced by the contributing package. */
+  readonly name: string
+  /** Assembly position; lower runs first. Defaults to `0`. */
+  readonly order?: number
+  /**
+   * Section body, or a provider resolved at assembly time. A body that
+   * resolves empty (or whitespace-only) leaves no section behind.
+   */
+  readonly text: string | (() => string | Promise<string>)
+}
+
+/** One section as it stands inside an assembled prompt. */
+export interface PromptSection {
+  readonly name: string
+  readonly order: number
+  readonly text: string
+}
+
+/** An assembled prompt. */
+export interface AssembledPrompt {
+  /** Sections in assembly order. */
+  readonly sections: readonly PromptSection[]
+  /** `sections` joined with a blank line — the text handed to the model. */
+  readonly text: string
+  /** Optional route variables filled by model-selection. */
+  readonly variables?: Record<string, string>
+}
+
+/** Context passed through `system-prompt/assemble`. */
+export interface AssembleContext {
+  readonly signal?: AbortSignal
+}
+
+declare module '@xrkseek/cordis' {
+  interface Context {
+    systemPrompt: SystemPromptService
+  }
+  interface Events {
+    'system-prompt/assemble'(
+      assembly: unknown,
+      context: AssembleContext,
+      next: () => Promise<AssembledPrompt>,
+    ): Promise<AssembledPrompt>
+  }
+}
+
+/** Plugin config. */
+export interface Config {
+  /** Base persona; an empty persona contributes nothing. */
+  readonly persona?: string
+}
+
+/** Section name carrying the configured persona. */
+const PERSONA_SECTION = 'persona'
+
+/**
+ * Render an assembled prompt as text.
+ * @param prompt - an assembled prompt, or text passed through unchanged.
+ * @returns the prompt text.
+ */
+export function renderPrompt(prompt: AssembledPrompt | string): string {
+  return typeof prompt === 'string' ? prompt : prompt.text
+}
+
+/** The `ctx.systemPrompt` registry. */
+export class SystemPromptService extends Service {
+  private readonly sections = new Map<string, PromptSectionInput>()
+  private readonly persona: string
+
+  /**
+   * @param ctx - the context this service registers in.
+   * @param config - plugin config; `persona` is the base prompt body.
+   */
+  constructor(ctx: Context, config: Config = {}) {
+    super(ctx, 'systemPrompt')
+    this.persona = typeof config.persona === 'string' ? config.persona : ''
+  }
+
+  /**
+   * Contribute one prompt section for as long as this service's fiber lives.
+   * @param input - the section to register.
+   * @returns a disposer removing the section again.
+   * @throws when the name is already registered.
+   */
+  section(input: PromptSectionInput): () => void {
+    const { name } = input
+    if (this.sections.has(name)) {
+      throw new Error(`prompt section already registered: ${name}`)
+    }
+    const sections = this.sections
+    // Service method tracing binds `this.ctx` to the caller, so the section
+    // unloads together with the fiber that contributed it.
+    void this.ctx.effect(() => {
+      sections.set(name, input)
+      return () => {
+        sections.delete(name)
+      }
+    }, `systemPrompt.section(${JSON.stringify(name)})`)
+    return () => {
+      sections.delete(name)
+    }
+  }
+
+  /**
+   * Resolve every registered section, in `order`.
+   * @returns the assembled prompt: its sections and their joined text.
+   */
+  async assemble(): Promise<AssembledPrompt> {
+    const sections: PromptSection[] = []
+    if (this.persona.trim()) {
+      sections.push({ name: PERSONA_SECTION, order: -1, text: this.persona })
+    }
+    const registered = [...this.sections.values()]
+      .sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
+    for (const input of registered) {
+      const text = typeof input.text === 'function' ? await input.text() : input.text
+      if (!text.trim()) continue
+      sections.push({ name: input.name, order: input.order ?? 0, text })
+    }
+    return { sections, text: sections.map(entry => entry.text).join('\n\n') }
+  }
+}
+
+export default SystemPromptService

package/node_modules/@xrkseek/xrk-token-meter/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/llm/token-meter/README.md
+README.md: a2deab11a31285ba598b8864d3a734ecf7c56620
+README.zh.md: e0c3a8aa123ca0acc374277cd92b415e0b0b3cb5

package/node_modules/@xrkseek/xrk-token-meter/README.md

@@ -0,0 +1,68 @@
+# @xrkseek/xrk-token-meter
+
+English | [中文](README.zh.md)
+
+Replay-aware token measurement through the singleton `ctx.tokenMeter` service. It advances one isolated fold per session from the durable log, so compaction and other pressure-sensitive plugins can share accounting without depending on `CompactionEngine`.
+
+## Configuration
+
+The estimator has no settings. It intentionally uses one fixed heuristic: four characters per token plus structural overhead for roles, blocks, and request-envelope fields. Any key is rejected; model capacity belongs to the adapter that owns an exact provider/model route and is available through `ctx.llm.resolveModelInfo().context`.
+
+## Measurement contract
+
+`ctx.tokenMeter` directly exposes two operations:
+
+- `measure(session, requestHeader?)` returns request pressure and the current priced surface at one consumed-log revision.
+- `estimateMessage(message)` prices one message with the fixed heuristic.
+
+`measure()` synchronizes once and returns one detached, deeply immutable snapshot. `totalTokens` is request-and-response pressure, while `surfaceTokens` is the surface-only heuristic total and equals the sum of `nodes[].tokens`. A `requestHeader` override affects pressure fields only; the surface fields still describe the current session. Every call clones the positional nodes, so measurement is O(surface).
+
+The fold tracks full request-header snapshots, step boundaries, surface appends and replacements, successful assistant messages, provider usage, and the chunk seqs cited by each assistant message. Provider usage is reused only when the latest successful call's canonical request envelope matches the measured envelope and its total is no lower than that call's full heuristic anchor; a later success replaces the earlier anchor. Otherwise the complete current envelope and surface are estimated. Surface changes remain signed relative to a matching anchor, including negative deltas after shrinking replacements.
+
+Usage accounting sums disjoint input, cache-read, cache-write, and output buckets; reasoning is not added again. Every successful call records an assistant anchor, including content-less calls. An explicit empty `sourceEventSeqs` list means a known empty provider stream, while an absent legacy list conservatively treats the durable assistant output as provider output.
+
+## Session projections
+
+When the composition provides `ctx.sessionProjections`, token-meter registers three units through an optional child fiber.
+
+`tokenUsage` carries the complete durable log's `uncachedInputTokens`, `outputTokens`, `cacheReadTokens`, and `cacheWriteTokens`. Usage chunks are counted even when a request later fails; a final assistant-message usage for the same `(turn, step)` replaces that sample instead of double-counting it. Reasoning remains an output subdivision. The single last-sample slot relies on a session-log ordering property: once a later step reports usage, a legal log never reports usage for an earlier step again.
+
+`contextPressure` carries optional `pressureTokens` — the newest provider-reported prompt size, summing uncached input plus cache reads and writes — optional `projectedTokens`, and optional `contextWindow` from the newest `request/context` record. Both figures stay absent until a provider reports usage; capacity stays absent for a route whose adapter advertises none. Output is excluded, so `pressureTokens` holds still while a turn streams and steps forward when the next request reports its usage.
+
+`projectedTokens` is what the NEXT request's prompt would cost: the sample plus the heuristic repricing of everything the surface gained or lost since it was taken, clamped at zero and folded through the same `surface-fold.ts` the measurement service replays. Only the delta is estimated, so the figure stays anchored to the provider while reacting the moment content lands — or a compaction shadows a span. That last case is why the field exists: compaction summarizes through a direct `ctx.llm.stream()` call and appends no usage of its own, so `pressureTokens` alone reports the pre-compaction prompt until an entire further turn completes. Occupancy displays read `projectedTokens`.
+
+`contextBreakdown` carries heuristic `systemTokens`, `toolsTokens`, and `messageTokens` — the context's composition rather than its provider-billed size. The envelope figures reprice last-wins on every `request/header`; the message figure replays `surface-fold.ts` — the same positional fold `measure()` runs — so it equals `measure().surfaceTokens` at every event boundary and compaction shrinks it the way it shrinks the next request. All three figures use the measurement service's fixed heuristic and are estimates: they will not sum to `projectedTokens`, whose provider anchor carries exactly the error — CJK text and JSON schemas underprice badly at four characters per token — that the composition rows still contain. Present them as an approximate composition, never as a total.
+
+All three units use the standard projection baseline, live frame, higher-seq-wins store, and JSON checkpoint paths. Unloading token-meter removes all three keys. A composition without the projection seam keeps the measurement service's existing behavior.
+
+### Context occupancy is an approximation, by design
+
+The occupancy fields are independent last-wins records and are **not** one atomic observation of a single request. Switching models pairs the fresh capacity with the previous route's sample until the next request reports usage, and `pressureTokens` describes the last request rather than the surface as it stands right now — `projectedTokens` carries that sample forward over the surface's movement, but its anchor is still the older request.
+
+This is deliberate. An occupancy percentage is a user-facing reference figure, not a billing record or a gating input — nothing in the harness makes decisions from it, and compaction reads `measure()` instead. A UI computes occupancy by dividing measured pressure by the separately resolved capacity for the selected model.
+
+The [Agent Note](../../../.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md) records the rejected atomic-pair comparison. Consumers that need an exact same-boundary figure should call `measure()` at their own request boundary rather than read this projection.
+
+## Composition
+
+```yaml
+- name: '@xrkseek/xrk-token-meter'
+- name: '@xrkseek/xrk-compaction-basic'
+```
+
+Both plugins have usable defaults. The meter remains independent of model routing and optional compaction. A deployment configures capacity on its LLM adapter and compaction policy on `dsh-compaction-basic`.
+
+## Model Experience
+
+Indirectly, through consumers such as `dsh-compaction-basic`; the service itself adds no prompt, message, schema, tool, or model call.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **The fixed heuristic is approximate** — content without reusable provider usage is priced by character count plus structural overhead, not an exact provider tokenizer or request serializer.
+- **Every measurement clones the current surface** — coherent immutable snapshots make reads O(surface), including below-threshold pressure checks.
+- **Provider usage is only reusable for an identical canonical envelope** — prompt, prefix, tools, provider, model, or call-config changes deliberately fall back to full heuristic estimation.
+- **Missing legacy source seqs are handled conservatively** — assistant messages without `sourceEventSeqs` cannot distinguish provider output from listener rewrites, so the fold avoids claiming a known empty or exact chunk stream.

package/node_modules/@xrkseek/xrk-token-meter/README.zh.md

@@ -0,0 +1,68 @@
+# @xrkseek/xrk-token-meter
+
+[English](README.md) | 中文
+
+通过单例 `ctx.tokenMeter` 服务进行具备回放感知能力的 token 测量。它从持久日志为每个会话推进一个隔离 fold，因此压缩（compaction）与其他压力敏感插件可以共享计量，无需依赖 `CompactionEngine`。
+
+## 配置
+
+估算器没有配置项。它有意使用一项固定启发式规则：每个 token 按四个字符估算，再加上角色、块与请求 envelope 字段的结构开销。任何配置键都会被拒绝；模型容量属于拥有精确提供方／模型路由的适配器，可通过 `ctx.llm.resolveModelInfo().context` 获取。
+
+## 测量约定
+
+`ctx.tokenMeter` 直接公开两个操作：
+
+- `measure(session, requestHeader?)` 在同一个已消费日志 revision 上返回请求压力与当前已计价表层。
+- `estimateMessage(message)` 使用固定启发式规则为一条消息计价。
+
+`measure()` 会同步一次，并返回一个独立且深度不可变的快照。`totalTokens` 是请求与响应压力，`surfaceTokens` 是仅表层启发式总量，等于 `nodes[].tokens` 之和。`requestHeader` 覆盖只影响压力字段；表层字段仍描述当前会话。每次调用都会克隆带位置的节点，因此测量是 O(surface)。
+
+fold 跟踪完整请求标头快照、步骤边界、表层追加与替换、成功 assistant 消息、提供方用量，以及每条 assistant 消息引用的分片 seq。只有当最新成功调用的规范请求 envelope 与已测量 envelope 匹配，且其总量不低于该调用的完整启发式锚点时，才会复用提供方用量；后续成功会替换较早锚点。否则会对当前 envelope 与表层进行完整估算。表层变更保持相对于匹配锚点的带符号值，包括缩减替换后的负 delta。
+
+用量计量会求和不重叠的输入、cache-read、cache-write 与输出 bucket；不会再次添加推理（reasoning）。每次成功调用都会记录一个 assistant 锚点，包括无内容调用。显式的空 `sourceEventSeqs` 列表表示已知空提供方流；遗留记录缺少该列表时，fold 会保守地将持久 assistant 输出视为提供方输出。
+
+## 会话投影
+
+当组合提供 `ctx.sessionProjections` 时，token-meter 会通过一个可选子 fiber 注册三个单元。
+
+`tokenUsage` 携带完整持久日志中的 `uncachedInputTokens`、`outputTokens`、`cacheReadTokens` 和 `cacheWriteTokens`。即使请求随后失败，用量分片仍会计入；同一 `(turn, step)` 的最终 assistant 消息用量会替换该样本，而不是重复计数。推理仍是输出的一个细分项。只保留单个最新样本，依赖的是会话日志的一条顺序性质：一旦某个更晚的步骤报告了用量，合法日志就绝不会再为更早的步骤报告用量。
+
+`contextPressure` 携带可选的 `pressureTokens`（提供方报告的最新提示词规模，为未缓存输入加缓存读取与写入之和）、可选的 `projectedTokens`，以及来自最新一条 `request/context` 记录的可选 `contextWindow`。提供方报告用量前两个数字都保持缺失；路由适配器未公布容量时容量也保持缺失。输出不计入其中，因此轮次流式输出期间 `pressureTokens` 保持不动，等到下一个请求报告用量时才前进。
+
+`projectedTokens` 是「下一个请求的提示词要花多少」：在该样本之上，加上自取样以来表层增减部分的启发式重新计价，下界钳制为零，折叠走的是测量服务重放的同一份 `surface-fold.ts`。只有增量部分是估算的，因此这个数字既锚定在提供方读数上，又能在内容落地——或压缩遮蔽一段区间——的瞬间做出反应。最后这种情况正是该字段存在的理由：压缩通过直连的 `ctx.llm.stream()` 调用生成摘要，自身不追加任何用量，所以仅凭 `pressureTokens` 会一直报告压缩前的提示词规模，直到再完成一整个轮次为止。占用率展示读取 `projectedTokens`。
+
+`contextBreakdown` 携带启发式的 `systemTokens`、`toolsTokens` 与 `messageTokens`，描述上下文的组成而非提供方计费规模。envelope 数字在每条 `request/header` 上按后者胜重新计价；消息数字重放 `surface-fold.ts`——也就是 `measure()` 运行的同一个带位置 fold——因此它在每个事件边界上都等于 `measure().surfaceTokens`，压缩会像缩小下一个请求那样缩小它。三个数字都使用测量服务的固定启发式规则，属于估算值：它们加起来不等于 `projectedTokens`——后者的提供方锚点所体现的恰好是这些明细行仍然带着的误差（按「4 字符 ≈ 1 token」计价，CJK 文本与 JSON schema 会被严重低估）。请把它们当作近似的**组成**呈现，而不是总量。
+
+三个单元都使用标准的投影基线、实时帧、seq 高者胜值仓和 JSON 检查点路径。卸载 token-meter 会移除这三个键。不带投影 seam 的组合会保留测量服务的既有行为。
+
+### 上下文占用率是刻意为之的近似值
+
+这些占用率字段各自后者胜、彼此独立，**不是**对单个请求的一次原子观测。切换模型时，新容量会与上一路由的样本配对，直到下一个请求报告用量为止；而 `pressureTokens` 描述的是最后一个请求，不是此刻的表层——`projectedTokens` 把该样本沿表层的增减推进到当下，但它的锚点仍然是那个较早的请求。
+
+这是刻意的选择。占用率百分比是面向用户的参考数字，既不是计费记录，也不是门控输入：harness 中没有任何环节依据它做决策，压缩改为直接读取 `measure()`。UI 用测得的压力除以为所选模型单独解析出的容量来计算占用率。
+
+[Agent Note](../../../.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md) 记录了否决「让这对值保持原子」方案的那次对比。需要同一边界精确数字的消费方应在自己的请求边界调用 `measure()`，而不是读取该投影。
+
+## 组合
+
+```yaml
+- name: '@xrkseek/xrk-token-meter'
+- name: '@xrkseek/xrk-compaction-basic'
+```
+
+两个插件都有可用默认值。meter 保持与模型路由和可选压缩无关。部署会在 LLM（大语言模型）适配器上配置容量，并在 `dsh-compaction-basic` 上配置压缩策略。
+
+## 模型体验
+
+通过 `dsh-compaction-basic` 等消费方间接影响；该服务自身不添加提示词、消息、schema、工具或模型调用。
+
+#### KV Cache 影响
+
+不会直接失效；请求前缀变更由上述消费方负责。
+
+## 已知限制与暂缓事项
+
+- **固定启发式规则是近似值**：没有可复用提供方用量的内容按字符数加结构开销计价，而不是使用精确提供方 tokenizer 或请求 serializer。
+- **每次测量都会克隆当前表层**：一致且不可变的快照使读取成为 O(surface)，包括低于阈值的压力检查。
+- **提供方用量只能为完全相同的规范 envelope 复用**：提示词、前缀、工具、提供方、模型或调用配置变更都会有意回退到完整启发式估算。
+- **保守处理缺少源事件 seq 的遗留记录**：没有 `sourceEventSeqs` 的 assistant 消息无法区分提供方输出与 listener 改写，因此 fold 不会声称已知空流或精确分片流。

package/node_modules/@xrkseek/xrk-token-meter/lib/index.js

@@ -0,0 +1 @@
+export * from "./types/index.js";

package/node_modules/@xrkseek/xrk-token-meter/lib/invariant.js

@@ -0,0 +1 @@
+export * from "./types/invariant.js";

package/node_modules/@xrkseek/xrk-token-meter/lib/types/breakdown-projection.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Pure fold for the heuristic context-composition projection: system prompt
+ * and tool schemas from the newest request envelope, conversation from the
+ * live surface. Prices with the same shared estimator as the meter service,
+ * so the three figures match `measure()`'s heuristic vocabulary exactly.
+ */
+import type { ProjectionDefinition } from '@xrkseek/xrk-session-projection';
+import type { ShadowPriceClaim } from './surface-projection.ts';
+interface ContextBreakdownState {
+    systemTokens: number;
+    toolsTokens: number;
+    messageTokens: number;
+    /** Shadow price armed by the immediately preceding metering event. */
+    claim?: ShadowPriceClaim;
+}
+/**
+ * Token-meter's context-composition projection unit.
+ *
+ * Envelope figures are last-wins per `request/header`; the message figure
+ * rides {@link foldSurfaceProjection} — the same O(1) fold the occupancy
+ * projection uses — so fully metered logs equal `measure().surfaceTokens` at
+ * every event boundary and compaction shrinks the figure by its logged shadow
+ * price. A replacement without a claim preserves the previous total. The
+ * state is a fixed handful of numbers, so the persisted checkpoint stays
+ * O(1) over the session's life.
+ */
+export declare const contextBreakdownProjectionDefinition: ProjectionDefinition<'contextBreakdown', ContextBreakdownState>;
+export {};
+//# sourceMappingURL=breakdown-projection.d.ts.map

package/node_modules/@xrkseek/xrk-token-meter/lib/types/breakdown-projection.js

@@ -0,0 +1,56 @@
+/**
+ * Pure fold for the heuristic context-composition projection: system prompt
+ * and tool schemas from the newest request envelope, conversation from the
+ * live surface. Prices with the same shared estimator as the meter service,
+ * so the three figures match `measure()`'s heuristic vocabulary exactly.
+ */
+import { z } from 'zod';
+import { canonicalHeader } from '@xrkseek/xrk-session';
+import { estimateSystemTokens, estimateToolsTokens } from "./estimate.js";
+import { foldSurfaceProjection } from "./surface-projection.js";
+const breakdownSchema = z.object({
+    systemTokens: z.number().int().nonnegative(),
+    toolsTokens: z.number().int().nonnegative(),
+    messageTokens: z.number().int().nonnegative(),
+}).strict();
+/**
+ * Token-meter's context-composition projection unit.
+ *
+ * Envelope figures are last-wins per `request/header`; the message figure
+ * rides {@link foldSurfaceProjection} — the same O(1) fold the occupancy
+ * projection uses — so fully metered logs equal `measure().surfaceTokens` at
+ * every event boundary and compaction shrinks the figure by its logged shadow
+ * price. A replacement without a claim preserves the previous total. The
+ * state is a fixed handful of numbers, so the persisted checkpoint stays
+ * O(1) over the session's life.
+ */
+export const contextBreakdownProjectionDefinition = {
+    key: 'contextBreakdown',
+    schema: breakdownSchema,
+    init: () => ({ systemTokens: 0, toolsTokens: 0, messageTokens: 0 }),
+    apply: (state, event) => {
+        const fold = foldSurfaceProjection(state.claim, event);
+        let systemTokens = state.systemTokens;
+        let toolsTokens = state.toolsTokens;
+        if (event.type === 'request/header') {
+            const header = canonicalHeader(event.data.header);
+            systemTokens = estimateSystemTokens(header);
+            toolsTokens = estimateToolsTokens(header);
+        }
+        if (systemTokens === state.systemTokens
+            && toolsTokens === state.toolsTokens
+            && fold.deltaTokens === 0
+            && fold.claim === undefined
+            && state.claim === undefined)
+            return state;
+        return {
+            systemTokens,
+            toolsTokens,
+            messageTokens: state.messageTokens + fold.deltaTokens,
+            ...fold.claim === undefined ? {} : { claim: fold.claim },
+        };
+    },
+    view: ({ systemTokens, toolsTokens, messageTokens }) => ({ systemTokens, toolsTokens, messageTokens }),
+    stateVersion: 2,
+};
+//# sourceMappingURL=breakdown-projection.js.map

package/node_modules/@xrkseek/xrk-token-meter/lib/types/client.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Client-namespace projection of token-meter's browser-safe contracts and folds.
+ *
+ * @module @xrkseek/xrk-token-meter/client
+ */
+export type * from './projection.ts';
+export { deriveTurnTokenUsage } from './turn-usage.ts';
+export type { TurnTokenUsage, TurnTokenUsageRoute } from './turn-usage.ts';
+//# sourceMappingURL=client.d.ts.map