@dsh-cc/cache-health 0.6.2

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/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 check:readme --write
+README.md: 7f024789a8e72beb7f633b8952f0ba96cce13663
+README.zh.md: 46bd7294b1478a80a73b3f86914b5e8cd3cb7603

package/README.md

@@ -0,0 +1,32 @@
+# @dsh-cc/cache-health
+
+English | [中文](README.zh.md)
+
+Passive prompt-cache prefix-stability observer with the `/cache-health` slash command. A `llm/stream` waterfall listener tracks which part of each outbound model request's prefix (system → tools → messages, in order) is volatile across calls within a session; the command joins the observation ledger with provider-metered cache usage (`cacheReadTokens` / `cacheWriteTokens`) from session events. Detector-only: it reports, never rewrites — no request rewriting, no provider-call changes, no harness changes.
+
+## Command contract
+
+| Input | Result |
+|---|---|
+| `/cache-health` | Show the current stable prefix (segment count, estimated tokens, changed-since-last-call flag), the drift table (only rows whose prefix changed, with redacted excerpts), per-call and session-total cache read/write token ratios, front-loaded suspects (drift at segment ≤ 2: system / tools / first message — where cwd and `DSH_SESSION_*` volatility lives), and tail appends listed explicitly as NOT suspects. |
+
+Cache metering numbers are provider-metered; zero-metered upstreams produce zeros, not evidence of misses.
+
+## Ledger
+
+One JSONL row per model call at `<dshHome>/cache-health/<projectKey>/<sessionId>.jsonl`, where `projectKey` is a short hash of the session cwd (the context-crusher idiom). Rows carry `{ts, seq, provider, model, stableSegments, stablePrefixHash, stablePrefixTokensEst, prefixChanged, driftSegmentIndex?, driftExcerpt?, callPurpose?}` — `stablePrefixHash` is a fingerprint of the stable prefix (hash over its segment hashes), stable across calls sharing the prefix and comparable with the offline `cache-trajectory` analyzer. Appends are fire-and-forget — observation never adds latency to model calls. The file is capped at 2000 rows (oldest trimmed on overflow).
+
+Rows reflect the raw pre-middleware view of `llm/stream` options, not a wire-faithful rendering: a future middleware rewriting options in `llm/stream` would make this ledger under-report churn. Excerpts are whitespace-collapsed, redacted (`sk-…` keys, `Bearer` tokens, opaque runs ≥ 32 chars), and truncated to 80 characters. `stablePrefixTokensEst` (canonical length / 4) is an estimate, not a token count.
+
+## Configuration
+
+```yaml
+- id: cache-health
+  name: '@dsh-cc/cache-health'
+  config:
+    enabled: true   # default; set false to disable the listener and the command
+```
+
+## Composition
+
+The CC preset (`@dsh-cc/preset-cc`) mounts the plugin as a slash-command row (`cache-health` in its `agent.cordis.yml`). The plugin declares `inject = ['commands', 'sessions']` and reads `dshHomePath` defensively; a host without `dshHomePath` force-disables the observer.

package/README.zh.md

@@ -0,0 +1,32 @@
+# @dsh-cc/cache-health
+
+[English](README.md) | 中文
+
+被动的提示词缓存前缀稳定性观察器，附带 `/cache-health` 斜杠命令。一个 `llm/stream` 瀑布监听器跟踪每次出站模型请求的前缀（system → tools → messages，按序）在会话内哪些部分是易变的；该命令将观察账本与会话事件中的提供商计量缓存用量（`cacheReadTokens` / `cacheWriteTokens`）连接起来。仅探测：只报告，从不改写——不改写请求、不改提供商调用、不改 harness。
+
+## 命令契约
+
+| 输入 | 结果 |
+|---|---|
+| `/cache-health` | 显示当前稳定前缀（段数、估算 token 数、自上次调用是否变化）、漂移表（仅列出前缀变化的行，附脱敏摘录）、每次调用与会话总计的缓存读/写 token 比例、前置可疑项（漂移段 ≤ 2：system / tools / 首条消息——cwd 与 `DSH_SESSION_*` 易变性所在），并明确列出尾部追加不属于可疑项。 |
+
+缓存计量数字来自提供商计量；零计量的上游产生的是零，而不是未命中的证据。
+
+## 账本
+
+每次模型调用一行 JSONL，位于 `<dshHome>/cache-health/<projectKey>/<sessionId>.jsonl`，其中 `projectKey` 是会话 cwd 的短哈希（context-crusher 惯例）。行包含 `{ts, seq, provider, model, stableSegments, stablePrefixHash, stablePrefixTokensEst, prefixChanged, driftSegmentIndex?, driftExcerpt?, callPurpose?}`——`stablePrefixHash` 是稳定前缀的指纹（对其各段哈希再哈希），共享前缀的调用间保持稳定，可与离线 `cache-trajectory` 分析器对齐比对。追加是即发即忘的——观察绝不会给模型调用增加延迟。文件上限 2000 行（溢出时裁剪最旧的）。
+
+行反映的是 `llm/stream` options 的中间件之前原始视图，而非线上忠实呈现：未来若有中间件在 `llm/stream` 中改写 options，该账本将低估抖动。摘录会折叠空白、脱敏（`sk-…` 密钥、`Bearer` 令牌、≥ 32 字符的不透明串）并截断到 80 字符。`stablePrefixTokensEst`（规范化长度 / 4）是估算值，不是 token 计数。
+
+## 配置
+
+```yaml
+- id: cache-health
+  name: '@dsh-cc/cache-health'
+  config:
+    enabled: true   # 默认；设为 false 可同时禁用监听器与命令
+```
+
+## 组装
+
+CC 预设（`@dsh-cc/preset-cc`）将本插件作为斜杠命令行挂载（其 `agent.cordis.yml` 中的 `cache-health` 行）。插件声明 `inject = ['commands', 'sessions']` 并防御性读取 `dshHomePath`；没有 `dshHomePath` 的宿主会强制禁用观察器。

package/lib/index.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Passive prompt-cache health observer. A `llm/stream` waterfall listener
+ * tracks which part of each outbound request's prefix (system → tools →
+ * messages) is volatile across calls within a session, and a `/cache-health`
+ * slash command joins the observation ledger with provider-metered cache
+ * usage from session events.
+ *
+ * Detector-only by design: the observer never rewrites options, never calls
+ * providers, and never touches the harness. Every observation failure is
+ * logged and swallowed — a bug here must never break a model call.
+ *
+ * @module @dsh-cc/cache-health
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { GenerateOptions } from '@deepseek-ai/dsh-llm';
+import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session';
+import { CacheHealthLedger } from './ledger.ts';
+import { PrefixTracker } from './tracker.ts';
+export { CacheHealthLedger, LEDGER_MAX_ROWS, type LedgerRow } from './ledger.ts';
+export { buildReport, CACHE_METER_DISCLAIMER, foldUsage, renderReport, TAIL_APPEND_NOTE, type CacheHealthReport, type UsageFold, } from './report.ts';
+export { canonicalJson, excerpt, PrefixTracker, sha256Hex, type PrefixObservation } from './tracker.ts';
+export declare const name = "cache-health";
+export declare const inject: string[];
+/** `/cache-health` configuration: a single on/off switch (default on). */
+export interface Config {
+    /** Set to false to disable both the llm/stream listener and the command. */
+    readonly enabled: boolean;
+}
+export declare const Config: z<Schemastery.ObjectS<{
+    enabled: z<boolean, boolean>;
+}>, Schemastery.ObjectT<{
+    enabled: z<boolean, boolean>;
+}>>;
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Harness-home path resolver, provided by @deepseek-ai/dsh-app-boot at boot. Optional in tests. */
+        dshHomePath?: (...segments: string[]) => string;
+    }
+}
+/**
+ * The minimal session surface the observer needs (structural subset of the
+ * dsh-session Session, so tests can pass real sessions or stubs).
+ */
+interface ObservedSession {
+    readonly id: SessionId;
+    readonly header: {
+        readonly cwd?: string;
+    };
+    snapshotEvents(): readonly SessionEvent[];
+}
+/** Dependencies for the testable observe path. */
+export interface CacheHealthDeps {
+    /** Session store lookup; a miss skips the observation. */
+    readonly sessions?: {
+        get(id: SessionId): ObservedSession | undefined;
+    };
+    readonly ledger: CacheHealthLedger;
+    readonly tracker: PrefixTracker;
+    /** Warning sink for swallowed observer failures. */
+    readonly warn: (message: string) => void;
+}
+/**
+ * Observe one model request. Read-only on `options`; all failures — including
+ * throws from session lookup or hashing — are caught, warned, and swallowed.
+ * Skips: auxiliary calls (`compaction`, `session-title`), requests without a
+ * sessionId, and unknown sessions.
+ */
+export declare function observeRequest(deps: CacheHealthDeps, options: GenerateOptions): void;
+/**
+ * Register the cache-health observer: the `llm/stream` listener and the
+ * `/cache-health` command.
+ * @param ctx - context carrying the command registry and session store.
+ * @param config - plugin config (enabled flag).
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAExC,OAAO,KAAK,EAAE,eAAe,EAAe,MAAM,sBAAsB,CAAA;AACxE,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AAEvE,OAAO,EAAE,iBAAiB,EAAkB,MAAM,aAAa,CAAA;AAE/D,OAAO,EAAE,aAAa,EAAa,MAAM,cAAc,CAAA;AAEvD,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAA;AAChF,OAAO,EACL,WAAW,EACX,sBAAsB,EACtB,SAAS,EACT,YAAY,EACZ,gBAAgB,EAChB,KAAK,iBAAiB,EACtB,KAAK,SAAS,GACf,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAEvG,eAAO,MAAM,IAAI,iBAAiB,CAAA;AAClC,eAAO,MAAM,MAAM,UAA2B,CAAA;AAE9C,0EAA0E;AAC1E,MAAM,WAAW,MAAM;IACrB,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AAED,eAAO,MAAM,MAAM;;;;GAEjB,CAAA;AAKF,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,oGAAoG;QACpG,WAAW,CAAC,EAAE,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,KAAK,MAAM,CAAA;KAChD;CACF;AAUD;;;GAGG;AACH,UAAU,eAAe;IACvB,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC1C,cAAc,IAAI,SAAS,YAAY,EAAE,CAAA;CAC1C;AAED,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,EAAE,SAAS,GAAG,eAAe,GAAG,SAAS,CAAA;KAAE,CAAA;IACvE,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;IAClC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;IAC/B,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CACzC;AAOD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,CAgCpF;AAWD;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAwBxD"}

package/lib/index.js

@@ -0,0 +1,120 @@
+/**
+ * Passive prompt-cache health observer. A `llm/stream` waterfall listener
+ * tracks which part of each outbound request's prefix (system → tools →
+ * messages) is volatile across calls within a session, and a `/cache-health`
+ * slash command joins the observation ledger with provider-metered cache
+ * usage from session events.
+ *
+ * Detector-only by design: the observer never rewrites options, never calls
+ * providers, and never touches the harness. Every observation failure is
+ * logged and swallowed — a bug here must never break a model call.
+ *
+ * @module @dsh-cc/cache-health
+ */
+import z from '@deepseek-ai/schemastery';
+import { helpable } from '@dsh-cc/command-usage';
+import { CacheHealthLedger } from "./ledger.js";
+import { buildReport, renderReport } from "./report.js";
+import { PrefixTracker, shortHash } from "./tracker.js";
+export { CacheHealthLedger, LEDGER_MAX_ROWS } from "./ledger.js";
+export { buildReport, CACHE_METER_DISCLAIMER, foldUsage, renderReport, TAIL_APPEND_NOTE, } from "./report.js";
+export { canonicalJson, excerpt, PrefixTracker, sha256Hex } from "./tracker.js";
+export const name = 'cache-health';
+export const inject = ['commands', 'sessions'];
+export const Config = z.object({
+    enabled: z.boolean().default(true),
+});
+function dshHomeFn(ctx) {
+    try {
+        return ctx.dshHomePath;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** projectKey = shortHash of the session cwd (context-crusher idiom). */
+function projectKeyOf(session) {
+    return shortHash(session.header.cwd ?? process.cwd());
+}
+/**
+ * Observe one model request. Read-only on `options`; all failures — including
+ * throws from session lookup or hashing — are caught, warned, and swallowed.
+ * Skips: auxiliary calls (`compaction`, `session-title`), requests without a
+ * sessionId, and unknown sessions.
+ */
+export function observeRequest(deps, options) {
+    try {
+        if (options.purpose === 'compaction' || options.purpose === 'session-title')
+            return;
+        if (options.sessionId === undefined)
+            return;
+        const session = deps.sessions?.get(options.sessionId);
+        if (session === undefined)
+            return;
+        const observation = deps.tracker.observe(String(session.id), options);
+        const events = session.snapshotEvents();
+        const row = {
+            ts: new Date().toISOString(),
+            seq: events.length > 0 ? events[events.length - 1].seq : 0,
+            provider: options.provider,
+            model: options.model,
+            stableSegments: observation.stableSegments,
+            stablePrefixHash: observation.stablePrefixHash,
+            stablePrefixTokensEst: observation.stablePrefixTokensEst,
+            prefixChanged: observation.prefixChanged,
+            ...(observation.driftSegmentIndex !== undefined
+                ? { driftSegmentIndex: observation.driftSegmentIndex }
+                : {}),
+            ...(observation.driftExcerpt !== undefined
+                ? { driftExcerpt: observation.driftExcerpt }
+                : {}),
+        };
+        deps.ledger.append(projectKeyOf(session), String(session.id), row);
+    }
+    catch (error) {
+        try {
+            deps.warn(`cache-health: observation failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        catch {
+            // never propagate
+        }
+    }
+}
+/** Execute `/cache-health` against the invocation's own session ledger. */
+async function execute(invocation, ledger) {
+    const session = invocation.agent.session;
+    const projectKey = shortHash(session.header.cwd ?? process.cwd());
+    const rows = await ledger.read(projectKey, String(session.id));
+    const report = buildReport(rows, session.snapshotEvents());
+    return { kind: 'success', text: renderReport(report) };
+}
+/**
+ * Register the cache-health observer: the `llm/stream` listener and the
+ * `/cache-health` command.
+ * @param ctx - context carrying the command registry and session store.
+ * @param config - plugin config (enabled flag).
+ */
+export function apply(ctx, config) {
+    if (!config.enabled)
+        return;
+    const home = dshHomeFn(ctx);
+    if (home === undefined) {
+        ctx.logger.warn('cache-health: no dshHomePath on the host context; force-disabled');
+        return;
+    }
+    const ledger = new CacheHealthLedger(home('cache-health'), (error) => {
+        ctx.logger.warn(`cache-health: ledger write failed: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    const tracker = new PrefixTracker();
+    const sessions = ctx.sessions;
+    ctx.on('llm/stream', (options, next) => {
+        observeRequest({ sessions, ledger, tracker, warn: (message) => ctx.logger.warn(message) }, options);
+        return next();
+    }, { global: true, prepend: true });
+    ctx.commands.register(helpable({
+        name: 'cache-health',
+        description: 'show prompt-cache prefix stability and provider-metered cache usage for this session',
+        handler: invocation => execute(invocation, ledger),
+    }));
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/lib/ledger.d.ts

@@ -0,0 +1,53 @@
+/**
+ * JSONL ledger for prefix observations: one row per model call, appended to
+ * `<dshHome>/cache-health/<projectKey>/<sessionId>.jsonl`. All I/O is
+ * fire-and-forget — the llm/stream path must never await on it — and every
+ * error is reported through the injected sink, never thrown.
+ *
+ * @module @dsh-cc/cache-health/ledger
+ */
+/** Hard cap of rows per session file; older rows are trimmed on overflow. */
+export declare const LEDGER_MAX_ROWS = 2000;
+/** One ledger row (one JSON object per jsonl line). */
+export interface LedgerRow {
+    /** ISO timestamp of the observation. */
+    readonly ts: string;
+    /** Seq of the last session event at observe time (the log's throughSeq). */
+    readonly seq: number;
+    readonly provider: string;
+    readonly model: string;
+    readonly stableSegments: number;
+    /** Fingerprint of the stable prefix — hash over its segment hashes. */
+    readonly stablePrefixHash: string;
+    readonly stablePrefixTokensEst: number;
+    readonly prefixChanged: boolean;
+    readonly driftSegmentIndex?: number;
+    readonly driftExcerpt?: string;
+    /** When set, the call is an auxiliary one (compaction / session-title). */
+    readonly callPurpose?: string;
+}
+/** Error sink (the plugin passes a warn-logger); never throws. */
+export type LedgerErrorSink = (error: unknown) => void;
+/**
+ * Append-only ledger store. One instance per mounted plugin; `root` is
+ * `dshHomePath('cache-health')`. Row counts are tracked in memory from
+ * process start (an on-disk file longer than the cap is trimmed on the
+ * first post-start overflow check).
+ */
+export declare class CacheHealthLedger {
+    readonly root: string;
+    private readonly onError;
+    private readonly counts;
+    /** Per-file write chain: serializes appends so rows keep call order (still floating). */
+    private readonly pending;
+    constructor(root: string, onError?: LedgerErrorSink);
+    /** Ledger file path for one session within a project. */
+    pathFor(projectKey: string, sessionId: string): string;
+    /** Append one row as a FLOATING promise chained per file (call order preserved). Never await on the llm/stream path. */
+    append(projectKey: string, sessionId: string, row: LedgerRow): void;
+    /** Read all rows of one session ledger; missing/corrupt file → []. */
+    read(projectKey: string, sessionId: string): Promise<LedgerRow[]>;
+    /** Rewrite the file keeping only the newest LEDGER_MAX_ROWS rows. */
+    private trim;
+}
+//# sourceMappingURL=ledger.d.ts.map

package/lib/ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../src/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,6EAA6E;AAC7E,eAAO,MAAM,eAAe,OAAO,CAAA;AAEnC,uDAAuD;AACvD,MAAM,WAAW,SAAS;IACxB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAA;IACtC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;IAC/B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;IACnC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED,kEAAkE;AAClE,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;AAEtD;;;;;GAKG;AAGH,qBAAa,iBAAiB;IAM1B,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IACnD,yFAAyF;IACzF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;gBAGhD,IAAI,EAAE,MAAM,EACJ,OAAO,GAAE,eAA0B;IAGtD,yDAAyD;IACzD,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAItD,wHAAwH;IACxH,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,GAAG,IAAI;IAqBnE,sEAAsE;IAChE,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAmBvE,qEAAqE;YACvD,IAAI;CAOnB"}

package/lib/ledger.js

@@ -0,0 +1,89 @@
+/**
+ * JSONL ledger for prefix observations: one row per model call, appended to
+ * `<dshHome>/cache-health/<projectKey>/<sessionId>.jsonl`. All I/O is
+ * fire-and-forget — the llm/stream path must never await on it — and every
+ * error is reported through the injected sink, never thrown.
+ *
+ * @module @dsh-cc/cache-health/ledger
+ */
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+/** Hard cap of rows per session file; older rows are trimmed on overflow. */
+export const LEDGER_MAX_ROWS = 2000;
+/**
+ * Append-only ledger store. One instance per mounted plugin; `root` is
+ * `dshHomePath('cache-health')`. Row counts are tracked in memory from
+ * process start (an on-disk file longer than the cap is trimmed on the
+ * first post-start overflow check).
+ */
+// ponytail: in-memory row count ignores pre-existing file length until the
+// first overflow; initialize from disk on first append if that ever matters.
+export class CacheHealthLedger {
+    root;
+    onError;
+    counts = new Map();
+    /** Per-file write chain: serializes appends so rows keep call order (still floating). */
+    pending = new Map();
+    constructor(root, onError = () => { }) {
+        this.root = root;
+        this.onError = onError;
+    }
+    /** Ledger file path for one session within a project. */
+    pathFor(projectKey, sessionId) {
+        return join(this.root, projectKey, `${sessionId}.jsonl`);
+    }
+    /** Append one row as a FLOATING promise chained per file (call order preserved). Never await on the llm/stream path. */
+    append(projectKey, sessionId, row) {
+        const file = this.pathFor(projectKey, sessionId);
+        const write = async () => {
+            await mkdir(dirname(file), { recursive: true });
+            await appendFile(file, `${JSON.stringify(row)}\n`, 'utf8');
+            const count = (this.counts.get(file) ?? 0) + 1;
+            this.counts.set(file, count);
+            if (count > LEDGER_MAX_ROWS)
+                await this.trim(file);
+        };
+        const prev = this.pending.get(file) ?? Promise.resolve();
+        const next = prev.then(write, write);
+        this.pending.set(file, next);
+        next.catch((error) => {
+            try {
+                this.onError(error);
+            }
+            catch {
+                // sink failure must never propagate
+            }
+        });
+    }
+    /** Read all rows of one session ledger; missing/corrupt file → []. */
+    async read(projectKey, sessionId) {
+        const file = this.pathFor(projectKey, sessionId);
+        try {
+            const text = await readFile(file, 'utf8');
+            const rows = [];
+            for (const line of text.split('\n')) {
+                if (line.trim() === '')
+                    continue;
+                try {
+                    rows.push(JSON.parse(line));
+                }
+                catch {
+                    // skip corrupt line, keep the rest
+                }
+            }
+            return rows;
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Rewrite the file keeping only the newest LEDGER_MAX_ROWS rows. */
+    async trim(file) {
+        const text = await readFile(file, 'utf8');
+        const lines = text.split('\n').filter(line => line.trim() !== '');
+        const kept = lines.slice(-LEDGER_MAX_ROWS);
+        await writeFile(file, kept.length > 0 ? `${kept.join('\n')}\n` : '', 'utf8');
+        this.counts.set(file, kept.length);
+    }
+}
+//# sourceMappingURL=ledger.js.map

package/lib/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../src/ledger.ts"],"names":[],"mappings":"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"}

package/lib/report.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Pure /cache-health fold and render: joins ledger rows with session-event
+ * usage records and renders a plain-text report. No cordis or fs imports —
+ * unit-testable in isolation.
+ *
+ * @module @dsh-cc/cache-health/report
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { LedgerRow } from './ledger.ts';
+/** Usage folded onto one ledger row. */
+export interface UsageFold {
+    readonly cacheReadTokens: number;
+    readonly cacheWriteTokens: number;
+}
+/** The full /cache-health report before rendering. */
+export interface CacheHealthReport {
+    /** Latest row's stable-prefix state (undefined with no rows). */
+    readonly current?: {
+        readonly stableSegments: number;
+        readonly stablePrefixHash: string;
+        readonly stablePrefixTokensEst: number;
+        readonly changedSinceLastCall: boolean;
+    };
+    /** Rows whose prefix changed, in seq order. */
+    readonly driftRows: readonly LedgerRow[];
+    /** Drift rows at segment index <= 2 (system/tools/first message volatility). */
+    readonly frontLoadedSuspects: readonly LedgerRow[];
+    /** Drift rows at later indexes — tail appends, not prefix busters. */
+    readonly tailAppends: readonly LedgerRow[];
+    /** Per-row usage ratio plus session totals. */
+    readonly usage: {
+        readonly perRow: readonly (readonly [LedgerRow, UsageFold])[];
+        readonly totalCacheReadTokens: number;
+        readonly totalCacheWriteTokens: number;
+    };
+}
+/** Disclaimer for provider-metered cache counters (zero ≠ miss). */
+export declare const CACHE_METER_DISCLAIMER = "provider-metered; zero-metered upstreams (e.g. glm-5.2 via llmbox) produce zeros, not evidence of misses";
+/** Disclaimer for tail-appends (they extend, not bust, the prefix). */
+export declare const TAIL_APPEND_NOTE = "tail appends extend the prefix rather than busting it";
+/**
+ * Fold session-event usage onto ledger rows by the interval rule: with rows
+ * sorted by seq, a usage event at seq s accrues to row i when
+ * `rows[i].seq < s <= rows[i+1].seq` (the last row takes all remaining
+ * usage); events at or before the first row's seq are dropped. Rows sharing
+ * a seq (same throughSeq) therefore split the boundary: only the LAST row
+ * with that seq can receive events strictly after it.
+ * @param rows - ledger rows in append order (any order is tolerated).
+ * @param events - the session's durable event log, in sequence order.
+ */
+export declare function foldUsage(rows: readonly LedgerRow[], events: readonly SessionEvent[]): readonly (readonly [LedgerRow, UsageFold])[];
+/**
+ * Build the report: join rows with usage, split drift rows into
+ * front-loaded suspects (driftSegmentIndex <= 2: system/tools/first message
+ * carry cwd and DSH_SESSION_* volatility) and tail appends.
+ */
+export declare function buildReport(rows: readonly LedgerRow[], events: readonly SessionEvent[]): CacheHealthReport;
+/**
+ * Render the report as human shell text in the /cost style.
+ * @param report - the fold result.
+ * @returns the multi-line report text.
+ */
+export declare function renderReport(report: CacheHealthReport): string;
+//# sourceMappingURL=report.d.ts.map

package/lib/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAE5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE5C,wCAAwC;AACxC,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;CAClC;AAED,sDAAsD;AACtD,MAAM,WAAW,iBAAiB;IAChC,iEAAiE;IACjE,QAAQ,CAAC,OAAO,CAAC,EAAE;QACjB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;QAC/B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;QACjC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAA;QACtC,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAA;KACvC,CAAA;IACD,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,EAAE,SAAS,SAAS,EAAE,CAAA;IACxC,gFAAgF;IAChF,QAAQ,CAAC,mBAAmB,EAAE,SAAS,SAAS,EAAE,CAAA;IAClD,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,SAAS,SAAS,EAAE,CAAA;IAC1C,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,SAAS,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,EAAE,CAAA;QAC7D,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAA;QACrC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAA;KACvC,CAAA;CACF;AAED,oEAAoE;AACpE,eAAO,MAAM,sBAAsB,6GAC2E,CAAA;AAE9G,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,0DAC8B,CAAA;AAQ3D;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,SAAS,SAAS,EAAE,EAC1B,MAAM,EAAE,SAAS,YAAY,EAAE,GAC9B,SAAS,CAAC,SAAS,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,EAAE,CAuB9C;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,SAAS,SAAS,EAAE,EAC1B,MAAM,EAAE,SAAS,YAAY,EAAE,GAC9B,iBAAiB,CA0BnB;AASD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAgD9D"}

package/lib/report.js

@@ -0,0 +1,144 @@
+/**
+ * Pure /cache-health fold and render: joins ledger rows with session-event
+ * usage records and renders a plain-text report. No cordis or fs imports —
+ * unit-testable in isolation.
+ *
+ * @module @dsh-cc/cache-health/report
+ */
+/** Disclaimer for provider-metered cache counters (zero ≠ miss). */
+export const CACHE_METER_DISCLAIMER = 'provider-metered; zero-metered upstreams (e.g. glm-5.2 via llmbox) produce zeros, not evidence of misses';
+/** Disclaimer for tail-appends (they extend, not bust, the prefix). */
+export const TAIL_APPEND_NOTE = 'tail appends extend the prefix rather than busting it';
+function isTokenUsage(value) {
+    return typeof value === 'object' && value !== null
+        && typeof value.inputTokens === 'number'
+        && typeof value.outputTokens === 'number';
+}
+/**
+ * Fold session-event usage onto ledger rows by the interval rule: with rows
+ * sorted by seq, a usage event at seq s accrues to row i when
+ * `rows[i].seq < s <= rows[i+1].seq` (the last row takes all remaining
+ * usage); events at or before the first row's seq are dropped. Rows sharing
+ * a seq (same throughSeq) therefore split the boundary: only the LAST row
+ * with that seq can receive events strictly after it.
+ * @param rows - ledger rows in append order (any order is tolerated).
+ * @param events - the session's durable event log, in sequence order.
+ */
+export function foldUsage(rows, events) {
+    const sorted = [...rows].sort((a, b) => a.seq - b.seq);
+    const folds = sorted.map(() => ({ cacheReadTokens: 0, cacheWriteTokens: 0 }));
+    for (const event of events) {
+        if (event.type !== 'assistant/message')
+            continue;
+        const usage = event.data.usage;
+        if (usage === undefined || !isTokenUsage(usage))
+            continue;
+        // Usage belongs to the row that CLOSED the interval
+        // (rows[i].seq < s <= rows[i+1].seq): the last row with seq < s, or none
+        // when s <= rows[0].seq.
+        let target = -1;
+        for (let i = 0; i < sorted.length; i++) {
+            const row = sorted[i];
+            if (row !== undefined && row.seq < event.seq)
+                target = i;
+            else
+                break;
+        }
+        if (target === -1)
+            continue;
+        const fold = folds[target];
+        if (fold === undefined)
+            continue; // unreachable: target < sorted.length
+        fold.cacheReadTokens += usage.cacheReadTokens ?? 0;
+        fold.cacheWriteTokens += usage.cacheWriteTokens ?? 0;
+    }
+    return sorted.map((row, i) => [row, folds[i]]);
+}
+/**
+ * Build the report: join rows with usage, split drift rows into
+ * front-loaded suspects (driftSegmentIndex <= 2: system/tools/first message
+ * carry cwd and DSH_SESSION_* volatility) and tail appends.
+ */
+export function buildReport(rows, events) {
+    const perRow = foldUsage(rows, events);
+    const driftRows = [...rows].sort((a, b) => a.seq - b.seq).filter(row => row.prefixChanged);
+    const last = [...rows].sort((a, b) => a.seq - b.seq).at(-1);
+    let totalRead = 0;
+    let totalWrite = 0;
+    for (const [, fold] of perRow) {
+        totalRead += fold.cacheReadTokens;
+        totalWrite += fold.cacheWriteTokens;
+    }
+    return {
+        ...(last !== undefined
+            ? {
+                current: {
+                    stableSegments: last.stableSegments,
+                    stablePrefixHash: last.stablePrefixHash,
+                    stablePrefixTokensEst: last.stablePrefixTokensEst,
+                    changedSinceLastCall: last.prefixChanged,
+                },
+            }
+            : {}),
+        driftRows,
+        frontLoadedSuspects: driftRows.filter(row => (row.driftSegmentIndex ?? Number.MAX_SAFE_INTEGER) <= 2),
+        tailAppends: driftRows.filter(row => (row.driftSegmentIndex ?? Number.MAX_SAFE_INTEGER) > 2),
+        usage: { perRow, totalCacheReadTokens: totalRead, totalCacheWriteTokens: totalWrite },
+    };
+}
+/** Ratio display: read share of metered cache traffic (read / (read + write)). */
+function readShare(fold) {
+    const total = fold.cacheReadTokens + fold.cacheWriteTokens;
+    if (total === 0)
+        return 'n/a';
+    return `${Math.round((fold.cacheReadTokens / total) * 100)}%`;
+}
+/**
+ * Render the report as human shell text in the /cost style.
+ * @param report - the fold result.
+ * @returns the multi-line report text.
+ */
+export function renderReport(report) {
+    const lines = [];
+    if (report.current === undefined) {
+        return 'No cache-health data yet; no model call has been observed for this session.';
+    }
+    lines.push('Prompt-cache health', '');
+    lines.push(`Current stable prefix: ${report.current.stableSegments} segments,`
+        + ` ~${report.current.stablePrefixTokensEst} tokens (estimate),`
+        + ` hash ${report.current.stablePrefixHash.slice(0, 16)},`
+        + ` changed since last call: ${report.current.changedSinceLastCall ? 'yes' : 'no'}`);
+    lines.push('');
+    if (report.driftRows.length === 0) {
+        lines.push('No prefix drift observed.');
+    }
+    else {
+        lines.push('Prefix drift (changed segments):');
+        for (const row of report.driftRows) {
+            lines.push(`  seq ${row.seq} ${row.provider}/${row.model}`
+                + ` segment ${row.driftSegmentIndex ?? '?'}: ${row.driftExcerpt ?? '(n/a)'}`);
+        }
+    }
+    lines.push('');
+    if (report.frontLoadedSuspects.length > 0) {
+        lines.push('Front-loaded suspects (drift at segment <= 2: system/tools/first message):');
+        for (const row of report.frontLoadedSuspects) {
+            lines.push(`  seq ${row.seq} ${row.provider}/${row.model} segment ${row.driftSegmentIndex ?? '?'}`);
+        }
+    }
+    else {
+        lines.push('No front-loaded suspects.');
+    }
+    lines.push(`Not suspects: ${report.tailAppends.length} drift row(s) at later indexes — ${TAIL_APPEND_NOTE}.`);
+    lines.push('');
+    lines.push('Provider-metered cache usage per call:');
+    for (const [row, fold] of report.usage.perRow) {
+        lines.push(`  seq ${row.seq} ${row.provider}/${row.model}:`
+            + ` read ${fold.cacheReadTokens}, write ${fold.cacheWriteTokens} (read share ${readShare(fold)})`);
+    }
+    lines.push(`Session totals: read ${report.usage.totalCacheReadTokens},`
+        + ` write ${report.usage.totalCacheWriteTokens}`);
+    lines.push(`Note: ${CACHE_METER_DISCLAIMER}.`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=report.js.map

package/lib/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"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"}

package/lib/tracker.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Pure prefix-stability tracking for the prompt-cache health observer.
+ *
+ * The wire prefix of a model request is system → tools → messages, in order.
+ * Each segment is canonical-JSON serialized (recursive key sort) and hashed
+ * with sha256; per session we keep the previous call's hash list and report
+ * the longest common prefix. Hashing stops at the first difference (early
+ * exit), so a drift near the front of a long conversation is cheap.
+ *
+ * No cordis, fs, or dsh imports beyond dsh-llm types — fully unit-testable.
+ *
+ * @module @dsh-cc/cache-health/tracker
+ */
+import type { GenerateOptions } from '@deepseek-ai/dsh-llm';
+/** Injectable hash function signature (tests count calls to verify early exit). */
+export type HashFn = (text: string) => string;
+/** sha256 hex, first 16 chars — the shared project-key shape (context-crusher idiom). */
+export declare function shortHash(input: string): string;
+/** Default segment hash: sha256 hex. */
+export declare const sha256Hex: HashFn;
+/**
+ * Canonical JSON: deterministic, key-sorted serialization for hashing.
+ * Objects sort keys lexicographically; arrays keep order; `undefined`
+ * properties are dropped (JSON semantics). No dependency — ~20 lines.
+ */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * Build the drift excerpt: canonical-serialize, collapse whitespace runs,
+ * redact secret-shaped runs, truncate to 80 chars.
+ * @param text - the canonical serialization of the drifted segment source.
+ */
+export declare function excerpt(text: string): string;
+/**
+ * One observed model request's prefix-stability verdict against the session's
+ * previous call.
+ *
+ * Note: rows reflect the RAW PRE-MIDDLEWARE view of `llm/stream` options, not
+ * a wire-faithful rendering. A future middleware rewriting options in
+ * `llm/stream` would make this ledger under-report churn.
+ */
+export interface PrefixObservation {
+    /** Number of leading segments whose hash equals the previous call's. */
+    readonly stableSegments: number;
+    /** Fingerprint of the stable prefix (hash over its segment hashes); stable across calls sharing the prefix, comparable against the offline cache-trajectory analyzer. */
+    readonly stablePrefixHash: string;
+    /** Estimated tokens of the stable prefix (canonical length / 4, rounded). */
+    readonly stablePrefixTokensEst: number;
+    /** Whether a previously-stable segment changed (prefix bust, not a tail append). */
+    readonly prefixChanged: boolean;
+    /** Zero-based index of the first differing segment (system=0, tools=1, messages 2+). */
+    readonly driftSegmentIndex?: number;
+    /** Redacted, truncated serialization of the drifted segment source. */
+    readonly driftExcerpt?: string;
+}
+/**
+ * Per-session in-memory prefix tracker. One instance per mounted plugin.
+ * Segment 0 = system, 1 = tools, 2+ = messages in order. On drift the hash
+ * list stops at the drifted index, so the NEXT call verifies only that
+ * (shorter) prefix — stableSegments may temporarily under-count after a
+ * drift; `prefixChanged` stays correct.
+ */
+export declare class PrefixTracker {
+    private readonly hash;
+    private readonly prev;
+    constructor(hash?: HashFn);
+    /**
+     * Observe one model request for a session. Purely read-only on `options`;
+     * never mutates the request.
+     */
+    observe(sessionId: string, options: GenerateOptions): PrefixObservation;
+}
+//# sourceMappingURL=tracker.d.ts.map

package/lib/tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../src/tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAE3D,mFAAmF;AACnF,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;AAE7C,yFAAyF;AACzF,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,wCAAwC;AACxC,eAAO,MAAM,SAAS,EAAE,MAA0E,CAAA;AAElG;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD;AAeD;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAO5C;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,yKAAyK;IACzK,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,6EAA6E;IAC7E,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAA;IACtC,oFAAoF;IACpF,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;IAC/B,wFAAwF;IACxF,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;IACnC,uEAAuE;IACvE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAC/B;AAED;;;;;;GAMG;AAGH,qBAAa,aAAa;IAGZ,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAuC;gBAE/B,IAAI,GAAE,MAAkB;IAErD;;;OAGG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,iBAAiB;CAuCxE"}

package/lib/tracker.js

@@ -0,0 +1,116 @@
+/**
+ * Pure prefix-stability tracking for the prompt-cache health observer.
+ *
+ * The wire prefix of a model request is system → tools → messages, in order.
+ * Each segment is canonical-JSON serialized (recursive key sort) and hashed
+ * with sha256; per session we keep the previous call's hash list and report
+ * the longest common prefix. Hashing stops at the first difference (early
+ * exit), so a drift near the front of a long conversation is cheap.
+ *
+ * No cordis, fs, or dsh imports beyond dsh-llm types — fully unit-testable.
+ *
+ * @module @dsh-cc/cache-health/tracker
+ */
+import { createHash } from 'node:crypto';
+/** sha256 hex, first 16 chars — the shared project-key shape (context-crusher idiom). */
+export function shortHash(input) {
+    return createHash('sha256').update(input, 'utf8').digest('hex').slice(0, 16);
+}
+/** Default segment hash: sha256 hex. */
+export const sha256Hex = (text) => createHash('sha256').update(text, 'utf8').digest('hex');
+/**
+ * Canonical JSON: deterministic, key-sorted serialization for hashing.
+ * Objects sort keys lexicographically; arrays keep order; `undefined`
+ * properties are dropped (JSON semantics). No dependency — ~20 lines.
+ */
+export function canonicalJson(value) {
+    return serialize(value);
+}
+function serialize(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(serialize).join(',')}]`;
+    const keys = Object.keys(value).sort();
+    const parts = [];
+    for (const key of keys) {
+        const item = value[key];
+        if (item === undefined)
+            continue;
+        parts.push(`${JSON.stringify(key)}:${serialize(item)}`);
+    }
+    return `{${parts.join(',')}}`;
+}
+/**
+ * Build the drift excerpt: canonical-serialize, collapse whitespace runs,
+ * redact secret-shaped runs, truncate to 80 chars.
+ * @param text - the canonical serialization of the drifted segment source.
+ */
+export function excerpt(text) {
+    const collapsed = text.replace(/\s+/g, ' ');
+    const redacted = collapsed
+        .replace(/sk-[A-Za-z0-9]{8,}/g, '[redacted]')
+        .replace(/Bearer\s+\S+/gi, '[redacted]')
+        .replace(/[A-Za-z0-9+/=_-]{32,}/g, '[redacted]');
+    return redacted.length > 80 ? redacted.slice(0, 80) : redacted;
+}
+/**
+ * Per-session in-memory prefix tracker. One instance per mounted plugin.
+ * Segment 0 = system, 1 = tools, 2+ = messages in order. On drift the hash
+ * list stops at the drifted index, so the NEXT call verifies only that
+ * (shorter) prefix — stableSegments may temporarily under-count after a
+ * drift; `prefixChanged` stays correct.
+ */
+// ponytail: truncating the stored hash list after drift under-counts the next
+// call's stableSegments; store unhashed stubs if that ever matters.
+export class PrefixTracker {
+    hash;
+    prev = new Map();
+    constructor(hash = sha256Hex) {
+        this.hash = hash;
+    }
+    /**
+     * Observe one model request for a session. Purely read-only on `options`;
+     * never mutates the request.
+     */
+    observe(sessionId, options) {
+        const sources = [options.system ?? '', options.tools ?? [], ...options.messages];
+        const prev = this.prev.get(sessionId) ?? [];
+        const hashes = [];
+        let stable = 0;
+        let tokens = 0;
+        let prefixChanged = false;
+        let driftSegmentIndex;
+        let driftExcerpt;
+        for (let i = 0; i < sources.length; i++) {
+            const text = canonicalJson(sources[i]);
+            if (i < prev.length) {
+                const h = this.hash(text);
+                if (h === prev[i]) {
+                    stable += 1;
+                    tokens += text.length;
+                    hashes.push(h);
+                    continue;
+                }
+                // First difference: report and stop hashing (early exit).
+                prefixChanged = true;
+                driftSegmentIndex = i;
+                driftExcerpt = excerpt(text);
+                break;
+            }
+            // New tail segment beyond the previous list: extend, no bust.
+            hashes.push(this.hash(text));
+        }
+        this.prev.set(sessionId, hashes);
+        const stableCount = prefixChanged ? stable : hashes.length;
+        return {
+            stableSegments: stableCount,
+            stablePrefixHash: this.hash(hashes.slice(0, stableCount).join('\n')),
+            stablePrefixTokensEst: Math.round(tokens / 4),
+            prefixChanged,
+            ...(driftSegmentIndex !== undefined ? { driftSegmentIndex } : {}),
+            ...(driftExcerpt !== undefined ? { driftExcerpt } : {}),
+        };
+    }
+}
+//# sourceMappingURL=tracker.js.map

package/lib/tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracker.js","sourceRoot":"","sources":["../src/tracker.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@dsh-cc/cache-health",
+  "description": "Passive prompt-cache prefix-stability observer with the /cache-health slash command",
+  "version": "0.6.2",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dsh-cc/dsh-cc.git",
+    "directory": "packages/observability/cache-health"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./tracker": {
+      "types": "./lib/tracker.d.ts",
+      "default": "./lib/tracker.js"
+    },
+    "./ledger": {
+      "types": "./lib/ledger.d.ts",
+      "default": "./lib/ledger.js"
+    },
+    "./report": {
+      "types": "./lib/report.d.ts",
+      "default": "./lib/report.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib"
+  ],
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@dsh-cc/command-usage": "^0.6.2"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=0.1.2-rc.1",
+    "@deepseek-ai/dsh-commands": ">=0.1.2-rc.1",
+    "@deepseek-ai/dsh-llm": ">=0.1.2-rc.1",
+    "@deepseek-ai/dsh-session": ">=0.1.2-rc.1",
+    "@deepseek-ai/schemastery": ">=0.1.2-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "link:../../../../deepseek-harness/vendor/cordis",
+    "@deepseek-ai/cordis-plugin-loader": "link:../../../../deepseek-harness/vendor/loader",
+    "@deepseek-ai/dsh-agent": "link:../../../../deepseek-harness/packages/core/agent",
+    "@deepseek-ai/dsh-commands": "link:../../../../deepseek-harness/packages/interaction/commands",
+    "@deepseek-ai/dsh-llm": "link:../../../../deepseek-harness/packages/llm/llm",
+    "@deepseek-ai/dsh-session": "link:../../../../deepseek-harness/packages/core/session",
+    "@deepseek-ai/schemastery": "link:../../../../deepseek-harness/vendor/schemastery"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}