dsh-engram 0.7.0 → 0.7.2

package/lib/client.js

@@ -2209,11 +2209,11 @@ function EngramTelemetry({ api, workspace }) {
           /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { style: { ...hb2.grid, marginTop: 8 }, children: [
             /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { style: hb2.statCard, children: [
               /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: { ...hb2.statNum, color: "#059669" }, children: tokenCount(ledgerBucket.avoidedTokens) }),
-              /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: hb2.statLabel, children: "\u8282\u7701 \xB7 \u526A\u679D/\u538B\u7F29" })
+              /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: hb2.statLabel, children: "\u8282\u7701 \xB7 \u526A\u679D/\u538B\u7F29\uFF08\u5DF2\u5165\u8D26\uFF09" })
             ] }),
             /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { style: hb2.statCard, children: [
               /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: { ...hb2.statNum, color: "#d97706" }, children: tokenCount(-ledgerBucket.injectedTokens) }),
-              /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: hb2.statLabel, children: "\u6CE8\u5165\u6210\u672C \xB7 \u7D22\u5F15/\u53EC\u56DE/ESR" })
+              /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: hb2.statLabel, children: "\u6CE8\u5165\u6210\u672C \xB7 \u7D22\u5F15/\u53EC\u56DE/ESR\uFF08\u6BCF\u8BF7\u6C42\u91CD\u8BA1\uFF09" })
             ] }),
             /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { style: hb2.statCard, children: [
               /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: { ...hb2.statNum, color: "#dc2626" }, children: tokenCount(-Math.round(ledgerBucket.rewritesCostChars / ledger.charsPerToken)) }),
@@ -2224,6 +2224,7 @@ function EngramTelemetry({ api, workspace }) {
               ] })
             ] })
           ] }),
+          ledgerBucket.avoidedTokens === 0 && (ledgerBucket.injectedTokens > 0 || ledgerBucket.rewriteCount > 0) && /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: { ...hb2.sub, marginTop: 6 }, children: "\u8282\u7701\u4ECD\u4E3A 0\uFF1A\u672C\u5DE5\u4F5C\u533A\u8FD8\u6CA1\u6709\u526A\u679D/\u538B\u7F29\u8282\u7701\u5165\u8D26\u2014\u2014L1 \u8FB9\u754C\u526A\u679D\u9700\u8981 host \u5E73\u9762\u7684 toolResultPruner\uFF08DSH \u2265 0.2.0 \u7531 bundle patch \u91CD\u65B0\u542F\u7528\u8BE5\u884C\uFF09\uFF0C\u538B\u7F29\u8282\u7701\u7531 Context GC \u5F15\u64CE\u5728 checkpoint \u65F6\u4E0A\u62A5\uFF1B\u51C0\u503C\u4E3A\u8D1F = \u6CE8\u5165\u6210\u672C + \u91CD\u5199\u7F5A\u91D1\u7684\u5408\u8BA1\u3002" }),
           /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { style: { ...hb2.sub, marginTop: 6 }, children: [
             "\u53E3\u5F84\uFF1Achars/",
             ledger.charsPerToken,

package/lib/compaction.js

@@ -62,6 +62,17 @@ export function apply(ctx, config = {}) {
             if (!domain) return null;
             return collectPointerContext(domain, wk(workspace), report);
           },
+          // Context Ledger bridge: this row runs inside the agent preset's
+          // isolate realm, where the host plugin's ledger closure is not
+          // reachable. The host plugin provides `engramLedger` as a plain
+          // (non-isolated) service, so compaction savings are credited to the
+          // one durable ledger instead of vanishing with the realm.
+          onCompacted: ({ session, workspace, charsSaved }) => {
+            try {
+              const hub = ctx.get("engramLedger");
+              hub?.noteCompaction?.(session?.id, workspace, { charsSaved });
+            } catch { /* contained: accounting never breaks compaction */ }
+          },
         }
       : {};
 

package/lib/context-gc.js

@@ -73,6 +73,38 @@ export function blockText(content) {
   return out.trim();
 }
 
+/** Recursive visible-text char count over DSH content blocks (code points). */
+function contentTextChars(value) {
+  if (typeof value === "string") return [...value].length;
+  if (Array.isArray(value)) {
+    let chars = 0;
+    for (const part of value) chars += contentTextChars(part);
+    return chars;
+  }
+  if (value === null || typeof value !== "object") return 0;
+  let chars = 0;
+  // Text blocks, tool-call arguments and nested tool-result content are all
+  // replayed context — count each once.
+  if (typeof value.text === "string") chars += [...value.text].length;
+  if (typeof value.arguments === "string") chars += [...value.arguments].length;
+  if (value.content !== undefined) chars += contentTextChars(value.content);
+  return chars;
+}
+
+/**
+ * Total visible text characters (Unicode code points) across a message list —
+ * the size side of the Context Ledger credit: a compaction replaces this span
+ * with the checkpoint, so `span − summary` is the part that stops replaying.
+ * @param {Array<object>} messages
+ * @returns {number}
+ */
+export function messagesTextChars(messages) {
+  if (!Array.isArray(messages)) return 0;
+  let chars = 0;
+  for (const message of messages) chars += contentTextChars(message?.content);
+  return chars;
+}
+
 /**
  * The durable checkpoint framing the harness applies to a compaction summary
  * before accepting it (`frameSummary()` in dsh-compaction-basic): the summary
@@ -762,6 +794,21 @@ export async function loadContextGcEngine(ctx, config = {}, deps = {}) {
       }
       summaryText = fit.text;
 
+      // Context Ledger credit: the span the checkpoint replaces stops
+      // replaying, so `span − summary` is a measured saving the accounting
+      // layer never had (the host does not expose compaction sizes). Best
+      // effort — accounting must never break the compaction path.
+      try {
+        if (typeof this.gcDeps?.onCompacted === "function") {
+          const spanChars = messagesTextChars(messages);
+          const summaryChars = [...summaryText].length;
+          const charsSaved = spanChars - summaryChars;
+          if (charsSaved > 0) {
+            this.gcDeps.onCompacted({ session: agent?.session, workspace: ws, charsSaved, spanChars, summaryChars });
+          }
+        }
+      } catch { /* contained: a credit bug must never fail a compaction */ }
+
       const result = { summary: [{ type: "text", text: summaryText }] };
       if (narrative.llm && typeof narrative.llm === "object") Object.assign(result, narrative.llm);
       // The harness's durable `compaction/summary` record ALWAYS carries

package/lib/index.js

@@ -24,7 +24,7 @@ import { registerTools } from "./tools.js";
 import { makeCaptureHandler } from "./capture.js";
 import { installGoalCapture } from "./goal-capture.js";
 import { installPreferenceCapture } from "./preference.js";
-import { installBoundaryPrune } from "./boundary-prune.js";
+import { boundaryPruneAvailability, installBoundaryPrune } from "./boundary-prune.js";
 import { resultPackDir, archivePrunedResults, resultRecallTool, sweepExpired } from "./result-pack.js";
 import { recordBoundaryPruneFire, recordRecallInjection, readPackTelemetry, engramHome } from "./pack-telemetry.js";
 import { createLedger, estimatePrefixChars } from "./ledger.js";
@@ -359,6 +359,27 @@ export function apply(ctx, config) {
       log,
     });
 
+  // Expose the ledger to the per-session web plane. Agent presets mount
+  // `dsh-engram/compaction` in their own isolate realm, so a closure from this
+  // apply() is unreachable there; a plain (non-isolated) service value is the
+  // bridge: the row credits compaction savings through it and `ledger` stays
+  // the single writer of the durable rollup.
+  if (ledger !== null) {
+    try {
+      // `ctx.provide` is fiber-scoped (cordis removes the service when this
+      // plugin unloads), so the returned disposer needs no bookkeeping here.
+      ctx.provide?.("engramLedger", {
+        noteCompaction: (sessionId, workspace, opts) => ledger.noteCompaction(sessionId, workspace, opts),
+        notePrune: (sessionId, workspace, opts) => ledger.notePrune(sessionId, workspace, opts),
+        noteRewrite: (sessionId, workspace, opts) => ledger.noteRewrite(sessionId, workspace, opts),
+        summary: () => ledger.summary(),
+        flush: () => ledger.flush(),
+      });
+    } catch (error) {
+      log?.warn?.(`engram ledger service unavailable: ${String(error?.message ?? error)}`);
+    }
+  }
+
   // Ledger-driven off-switch for BoundaryPrune (PROPOSAL-evolution v0.6-B):
   // per-workspace, 30s-cached, reads the same summary /stats exposes. Evidence
   // can only turn pruning OFF. No ledger → allow (repayment gate still runs).
@@ -422,7 +443,9 @@ export function apply(ctx, config) {
     /** Live Context GC status (API overview + durable status file). */
     compactionStatus: {
       host: "pending",
-      web: { action: "pending", presets: [] },
+      // `disabled` (not `pending`) when the web opt-in is off: the status file
+      // must not look like a wiring run that never finished.
+      web: resolved.autoWebCompaction === false ? { action: "disabled", presets: [] } : { action: "pending", presets: [] },
       config: { autoWebCompaction: resolved.autoWebCompaction, gcReplacesCompaction: resolved.gcReplacesCompaction, gcNarrative: resolved.gcNarrative },
     },
     /** Recompute the exact [ENGRAM] block for a workspace (GUI overview cost). */
@@ -666,6 +689,16 @@ export function apply(ctx, config) {
           return null;
         }
       },
+      // Context Ledger credit: the Context GC engine measures the span it
+      // replaced with a checkpoint (`span − summary` chars) and reports it
+      // here; the ledger stops the "savings are always 0" asymmetry.
+      onCompacted: ({ session, workspace, charsSaved }) => {
+        try {
+          ledger?.noteCompaction(session?.id, workspace ?? wk(session?.header?.cwd), { charsSaved });
+        } catch (error) {
+          log?.warn?.(`engram ledger compaction credit failed: ${String(error)}`);
+        }
+      },
     });
     disposers.push(() => {
       // The engine's service registration is fiber-scoped and auto-removed on
@@ -680,6 +713,10 @@ export function apply(ctx, config) {
     let hostSettled = false;
     let webSettled = resolved.autoWebCompaction === false;
     let statusTimer = void 0;
+    // Authoritative L1 availability, captured where BoundaryPrune is actually
+    // installed (the pruner may land after the first status flush on a slow
+    // boot; the live check is only a fallback).
+    let boundaryPruneState = void 0;
     const flushStatus = () => {
       if (!hostSettled || !webSettled) return;
       if (statusTimer !== void 0) { clearTimeout(statusTimer); statusTimer = void 0; }
@@ -687,6 +724,9 @@ export function apply(ctx, config) {
         planes: resolved.autoWebCompaction === false ? ["host"] : ["host", "web"],
         host: service.compactionStatus.host,
         web: service.compactionStatus.web,
+        // L1 availability is the missing credit path behind a "节省 always 0"
+        // ledger: record whether BoundaryPrune can actually fire here.
+        boundaryPrune: boundaryPruneState ?? boundaryPruneAvailability(ctx, resolved),
         config: service.compactionStatus.config,
         configSource: {
           autoWebCompaction: resolved.autoWebCompaction,
@@ -713,12 +753,15 @@ export function apply(ctx, config) {
     // inside the agent preset's own realm, which a profile patch cannot reach.
     // When the `agentPresets` service is present, swap the stock
     // `compaction-basic` row for `dsh-engram/compaction` in every stock-layout
-    // preset — the default one plus the whole roster (shipped + user roots) —
-    // so a session composed from any preset gets Context GC. Surgical,
-    // idempotent, backed up, validated; a preset with a custom compaction
-    // layout (or none) is never touched. The row's engine config is derived
-    // from the settings knobs (`gcReplacesCompaction` / `gcNarrative`), so
-    // changing them re-provisions the web rows on the next boot. Flip
+    // preset. The row is located structurally (indentation-agnostic) inside the
+    // `compaction` group, so both preset generations are covered: legacy
+    // compositions with `preset.path` (DSH ≤ 0.1.x) and the declarative
+    // `@deepseek-ai/dsh-web-app/presets/<id>.patch.yml` files (DSH ≥ 0.2.0,
+    // where the row sits at 14 spaces and the id maps to the shipped file).
+    // Surgical, idempotent, backed up, validated; a preset with a custom
+    // compaction layout (or none) is never touched. The row's engine config is
+    // derived from the settings knobs (`gcReplacesCompaction` / `gcNarrative`),
+    // so changing them re-provisions the web rows on the next boot. Flip
     // `autoWebCompaction:false` to stop auto-wiring on later boots (it does
     // not un-wire already-wired presets — use `npm run web-compaction:revert`
     // for that). Best-effort: a failure only warns.
@@ -976,7 +1019,7 @@ export function apply(ctx, config) {
       // over-threshold tool results at todo/goal subtask boundaries through
       // DSH's own deterministic toolResultPruner, gated by a repayment clock.
       const l2Dir = resultPackDir();
-      const disposeBoundaryPrune = installBoundaryPrune(ctx, resolved, log, {
+      const boundaryHooks = {
         // ResultPack L2 hook: archive the pruned middles (redacted) + append
         // a handle tail on each pruned node. Fail-contained in result-pack.js.
         // Also records durable activation telemetry (SoL-Pi M15/C13) —
@@ -1008,8 +1051,28 @@ export function apply(ctx, config) {
             log,
           });
         },
-      }, { allowFire: boundaryGate });
-      disposers.push(disposeBoundaryPrune);
+      };
+      // Arm L1 through `ctx.inject`, never a bare `ctx.get`: on a full web
+      // profile the host pruner's fiber activates a tick or two after this
+      // plugin (measured ~100 ms with dsh-context + dshmarket mounted), and a
+      // strict lookup at install time is then empty — the old direct install
+      // gave up and L1 stayed dormant for the whole process, silently killing
+      // the only ledger credit path. `ctx.inject` runs the callback as soon as
+      // the service is active (and re-runs it after a reload).
+      if (resolved.boundaryPrune !== false) {
+        ctx.inject(["toolResultPruner"], (prunerCtx) => {
+          const dispose = installBoundaryPrune(prunerCtx, resolved, log, boundaryHooks, {
+            allowFire: boundaryGate,
+          });
+          // L1 provably can (or cannot) fire from here on: record it for the
+          // durable snapshot, then rewrite it — the first flush may have landed
+          // before the pruner activated, and this status line is what users
+          // read when "节省" stays at 0.
+          boundaryPruneState = boundaryPruneAvailability(prunerCtx, resolved);
+          flushStatus();
+          return dispose;
+        });
+      }
 
       // ResultPack L2 tool (default ON with L1 since v0.6): `result_recall(callId,
       // offset?)` pages back an archived middle. Independent of the memory