dsh-engram 0.7.2 → 0.7.4

package/lib/episode.js

@@ -6,7 +6,9 @@
  * later succeeded), the written commit subjects, and what is still open.
  *
  * Design constraints:
- *   - zero LLM, pure function over `session.events` (survives restarts);
+ *   - zero LLM, pure function over the session event log (read through
+ *     `readSessionEvents`, so it survives restarts and DSH ≥0.2.x, where the
+ *     old `session.events` getter no longer exists);
  *   - never enters the [ENGRAM] index (long background context, not a symbol);
  *   - bounded by construction (≤4 files / ≤4 commands / ≤2 decisions / ≤3 open);
  *   - stored only when there is substance (a bare `ls` session produces none);
@@ -17,6 +19,7 @@
 
 import { cmdTag } from "./capture.js";
 import { pendingTodosFromSession } from "./todo-sink.js";
+import { readSessionEvents } from "./session-events.js";
 
 const EDIT_TOOLS = new Set(["write", "edit", "str_replace_editor"]);
 const RUN_TOOLS = new Set(["bash", "shell", "exec"]);
@@ -59,13 +62,15 @@ function commitSubject(command) {
 /**
  * Build the episode record from a disposed session.
  *
- * @param {object} session session with `.events` + `.header.cwd`
+ * @param {object} session host session (`.header.cwd` + a readable event log)
  * @param {object} [opts]
+ * @param {number} [opts.now] clock injection for the header stamp
+ * @param {object} [opts.sessionQuery] `ctx.sessionQuery` — how ≥0.2.x logs are read
  * @returns {{text: string, tags: string[], signal: number, summary: object}|null}
  */
-export function buildEpisode(session, { now = Date.now() } = {}) {
+export function buildEpisode(session, { now = Date.now(), sessionQuery = void 0 } = {}) {
   if (session === null || typeof session !== "object") return null;
-  const events = Array.isArray(session.events) ? session.events : [];
+  const events = readSessionEvents(session, sessionQuery);
   if (events.length === 0) return null;
   const cwd = session?.header?.cwd;
 
@@ -119,7 +124,7 @@ export function buildEpisode(session, { now = Date.now() } = {}) {
     }
   }
 
-  const open = pendingTodosFromSession(session).slice(0, 3);
+  const open = pendingTodosFromSession(session, sessionQuery).slice(0, 3);
   const hasSubstance = files.size > 0 || decisions.length > 0 || failedRuns > 0 || open.length > 0;
   if (!hasSubstance) return null;
 

package/lib/index-block.js

@@ -12,6 +12,7 @@
 import { label, shortId, fmtDate, escapeLt, truncate, byRecency } from "./util.js";
 import { buildEntityPage, renderEntityCard } from "./entity-page.js";
 import { memoryIsStale } from "./anchor.js";
+import { readSessionEvents } from "./session-events.js";
 
 /** Deterministic index line prefix per memory kind. */
 export function prefixFor(kind) {
@@ -190,13 +191,18 @@ function enforceCharCap(lines, maxChars) {
 }
 
 /** Text of the session's first user message (the opening instruction of the
- *  conversation). Walk `session.events` for the first `user/message` event and
+ *  conversation). Walk the session log for the first `user/message` event and
  *  join its `data.content` text blocks; fall back to the first text-bearing
  *  event ("goal"/reminder start) guardedly. Returns "" when there is none.
- *  Pure, deterministic — the auto-recall (B) keys its query off this. */
-export function firstUserMessageText(session) {
+ *  Pure, deterministic — the auto-recall (B) keys its query off this.
+ *
+ *  The log is read through `readSessionEvents` because DSH 0.2.x dropped the
+ *  `session.events` getter: reading it directly returned `[]` on every real
+ *  session, which silently killed the whole [RECALL] push leg (and, via
+ *  `pendingRecall`, kept the index block from ever being cached). */
+export function firstUserMessageText(session, sessionQuery = void 0) {
   if (session === null || typeof session !== "object") return "";
-  const events = Array.isArray(session.events) ? session.events : [];
+  const events = readSessionEvents(session, sessionQuery);
   if (events.length === 0) return "";
   const textOf = (data) => {
     if (data === null || typeof data !== "object") return "";

package/lib/index.js

@@ -32,6 +32,7 @@ import { createJit } from "./jit.js";
 import { buildEpisode } from "./episode.js";
 import { collectStaleAnchors } from "./anchor.js";
 import { renderIndex, renderStartRecall, renderResumeBrief, firstUserMessageText, renderEsr, esrMethodology, buildEsrSnapshot, buildFrozenEsrBlock } from "./index-block.js";
+import { sessionEventsSource, sessionSeq } from "./session-events.js";
 import { makeTriggerRecorder } from "./trigger.js";
 import { pendingTodosFromSession, sinkPendingTodos } from "./todo-sink.js";
 import { installEngramSettings, makeEngineConfigSchema, SETTINGS_KEYS } from "./settings.js";
@@ -522,6 +523,8 @@ export function apply(ctx, config) {
   // [ESR] block below follows the same frozen-snapshot rule but additionally
   // accumulates this-session actionables (see esrBlockFor).
   const sessionCache = new WeakMap();
+  /** One-time-per-process notice: the host's session log is unreadable. */
+  let warnedUnreadableLog = false;
   const blockFor = (agent) => {
     if (agent === void 0) return "";
     const session = agent.session;
@@ -560,9 +563,20 @@ export function apply(ctx, config) {
       // next assembly retry, so a new conversation never permanently misses its
       // recalled memory.
       if (resolved.autoRecallOnStart !== false) {
-        const query = firstUserMessageText(session);
+        const query = firstUserMessageText(session, sessionQuery);
         if (query.length === 0) {
-          pendingRecall = true;
+          // Retry on the next assembly ONLY when the log is readable and the
+          // opening message simply has not been appended yet. An unreadable
+          // log (host API drift — see lib/session-events.js) will never gain
+          // one, and retrying forever would also keep the [ENGRAM] block
+          // uncached, churning the prefix every turn.
+          pendingRecall = sessionEventsSource(session, sessionQuery) !== "none";
+          if (!pendingRecall && !warnedUnreadableLog) {
+            warnedUnreadableLog = true;
+            log?.warn?.(
+              "engram: this host exposes no readable session event log (no session.events, no ctx.sessionQuery, no snapshotEvents) — [RECALL] / episode / todo-sink stay dormant. Reporting once per session.",
+            );
+          }
         } else {
           const recall = renderStartRecall(opened, workspace, resolved, { query, allowRecencyFallback: false });
           if (recall.length > 0) {
@@ -901,7 +915,7 @@ export function apply(ctx, config) {
       const sessionId = session?.id;
       if (typeof cwd !== "string" || cwd.length === 0) return;
       if (typeof sessionId !== "string" || sessionId.length === 0) return;
-      const todos = pendingTodosFromSession(session);
+      const todos = pendingTodosFromSession(session, sessionQuery);
       if (todos.length === 0) return;
       const workspace = wk(cwd);
       service
@@ -932,7 +946,7 @@ export function apply(ctx, config) {
       const sessionId = session?.id;
       if (typeof cwd !== "string" || cwd.length === 0) return;
       if (typeof sessionId !== "string" || sessionId.length === 0) return;
-      const episode = buildEpisode(session);
+      const episode = buildEpisode(session, { sessionQuery });
       if (episode === null) return;
       const workspace = wk(cwd);
       const maxEpisodes = Number.isFinite(resolved.episodeMaxPerWorkspace)
@@ -950,7 +964,7 @@ export function apply(ctx, config) {
               signal: episode.signal,
               filePath: null,
               sessionId,
-              seq: Array.isArray(session.events) ? session.events.length : 0,
+              seq: sessionSeq(session, sessionQuery),
             },
             resolved,
           );

package/lib/preference.js

@@ -28,6 +28,7 @@
  */
 
 import { workspaceKey as wk } from "./util.js";
+import { sessionSeq } from "./session-events.js";
 
 /** Direction of the preference statement, used in the captured text. */
 export const PREFERENCE_DIRECTION = {
@@ -244,7 +245,7 @@ export function installPreferenceCapture(ctx, storeAdapter, config, log, stats)
             signal: PREFERENCE_SIGNAL,
             filePath: null,
             sessionId,
-            seq: Array.isArray(session.events) ? session.events.length : 0,
+            seq: sessionSeq(session),
           },
           config,
         )

package/lib/session-events.js

@@ -0,0 +1,126 @@
+/**
+ * Session event-log access across DSH generations.
+ *
+ * WHY THIS EXISTS (2026-10-20, the second "silent zero"):
+ * DSH ≤0.1.x exposed the conversation log as `session.events`, a plain frozen
+ * array. DSH 0.2.x removed that getter — `Session.prototype` now carries only
+ * `eventAt` / `snapshotEvents` / `ownEvents` / `deriveEventMessage`, and the
+ * synchronous full-log read is deprecated host-internally in favour of
+ * `ctx.sessionQuery.live(session)` leases. Every
+ * `Array.isArray(session.events)` read in this plugin therefore yielded `[]`
+ * on the running host, silently disabling three whole features while their
+ * unit tests (which mock `{ events: [...] }`) stayed green:
+ *
+ *   - `[RECALL]` session-start auto-recall never materialized (no first user
+ *     message → no query), and worse, `index.js` refused to cache the
+ *     `[ENGRAM]` block ("pendingRecall") on every assembly, so the index was
+ *     re-rendered per turn and never metered into the ledger;
+ *   - session episodes were never written → `[RESUME]` briefs never fired;
+ *   - the session-end todo sink never found a pending todo → no ESR drafts.
+ *
+ * The lesson is the same one as the session-log rename (memory #8): a
+ * host-API read must feature-detect and REPORT, never silently degrade to an
+ * empty value. `sessionEventsSource()` names the path taken so the status
+ * snapshot can surface `none` instead of pretending the log was empty.
+ *
+ * Resolution order (first working wins):
+ *   1. `session.events`            — legacy hosts (≤0.1.x), and every unit test;
+ *   2. `sessionQuery.live(session)`— sanctioned ≥0.2.x lease (lazy snapshot);
+ *   3. `session.snapshotEvents()`  — context-free fallback (deprecated host-side,
+ *                                    still the only sync full-log read a plugin has);
+ *   4. `[]`                        — nothing readable; callers degrade and
+ *                                    `sessionEventsSource` reports "none".
+ */
+
+/** Shared empty array: callers only read, so one frozen instance is enough. */
+const NO_EVENTS = Object.freeze([]);
+
+/**
+ * Which read path a session exposes, without materializing the log.
+ * @param {object} session
+ * @param {object} [sessionQuery] the `ctx.sessionQuery` service, if mounted
+ * @returns {"legacy"|"sessionQuery"|"snapshotEvents"|"none"}
+ */
+export function sessionEventsSource(session, sessionQuery = void 0) {
+  if (session === null || typeof session !== "object") return "none";
+  if (Array.isArray(session.events)) return "legacy";
+  if (hasLive(sessionQuery)) return "sessionQuery";
+  if (typeof session.snapshotEvents === "function") return "snapshotEvents";
+  return "none";
+}
+
+function hasLive(sessionQuery) {
+  return (
+    sessionQuery !== null &&
+    typeof sessionQuery === "object" &&
+    typeof sessionQuery.live === "function"
+  );
+}
+
+/**
+ * Read a session's event log across DSH generations (see module header).
+ *
+ * Returns a frozen-or-plain array of events; never throws. A session that
+ * genuinely has no events and a session whose log is unreadable both return
+ * `[]` — use {@link sessionEventsSource} when the difference matters.
+ *
+ * @param {object} session host session (`agent.session`, or the arg of
+ *   `session/disposed`)
+ * @param {object} [sessionQuery] the `ctx.sessionQuery` service, if mounted
+ * @returns {ReadonlyArray<object>}
+ */
+export function readSessionEvents(session, sessionQuery = void 0) {
+  if (session === null || typeof session !== "object") return NO_EVENTS;
+
+  // 1. Legacy: DSH ≤0.1.x (and every unit-test double).
+  if (Array.isArray(session.events)) return session.events;
+
+  // 2. Sanctioned ≥0.2.x: a live lease exposes a lazily materialized snapshot
+  //    up to the session's current seq. Dispose it immediately — we only need
+  //    the array, not the retention or the projection payload.
+  if (hasLive(sessionQuery)) {
+    let lease;
+    try {
+      lease = sessionQuery.live(session);
+      const events = lease?.events;
+      if (Array.isArray(events)) return events;
+    } catch {
+      // fall through to snapshotEvents
+    } finally {
+      try {
+        lease?.[Symbol.dispose]?.();
+      } catch {
+        // best-effort lease release
+      }
+    }
+  }
+
+  // 3. Context-free fallback.
+  if (typeof session.snapshotEvents === "function") {
+    try {
+      const end = typeof session.seq === "number" ? session.seq : void 0;
+      const events = end === void 0 ? session.snapshotEvents() : session.snapshotEvents(0, end);
+      if (Array.isArray(events)) return events;
+    } catch {
+      // unreadable — degrade
+    }
+  }
+
+  // 4. Nothing.
+  return NO_EVENTS;
+}
+
+/**
+ * The session's current event count, for provenance `seq` stamps.
+ *
+ * `seq` is the next free seq on ≥0.2.x (`session.seq`), so it equals the log
+ * length; on legacy hosts the array length is the same number. Kept here so
+ * the four write sites (capture / tools / preference / episode) agree.
+ */
+export function sessionSeq(session, sessionQuery = void 0) {
+  if (session === null || typeof session !== "object") return 0;
+  const seq = session.seq;
+  if (typeof seq === "number" && Number.isFinite(seq) && seq >= 0) return Math.trunc(seq);
+  const events = readSessionEvents(session, sessionQuery);
+  return events.length;
+}

package/lib/todo-sink.js

@@ -24,6 +24,7 @@
 
 import { pendingTodos } from "./trigger.js";
 import { shortId, uuid } from "./util.js";
+import { readSessionEvents } from "./session-events.js";
 
 /** Description stamped on every auto-sunk draft (mirrors the GUI button's note). */
 export const SINK_DESCRIPTION = "源自会话计划（会话结束自动沉淀）";
@@ -35,9 +36,9 @@ export const SINK_DESCRIPTION = "源自会话计划（会话结束自动沉淀
  * Deterministic — this is a pure function of the session log, so it survives
  * process restarts (no reliance on the process-local recorder snapshot).
  */
-export function pendingTodosFromSession(session) {
+export function pendingTodosFromSession(session, sessionQuery = void 0) {
   if (session === null || typeof session !== "object") return [];
-  const events = Array.isArray(session.events) ? session.events : [];
+  const events = readSessionEvents(session, sessionQuery);
   for (let i = events.length - 1; i >= 0; i--) {
     const event = events[i];
     if (event === null || typeof event !== "object" || event.type !== "todo/write") continue;

package/lib/tools.js

@@ -22,6 +22,7 @@ import { buildEsrStatusView } from "./index-block.js";
 import { buildEntityPage, renderEntityPage } from "./entity-page.js";
 import { truncate, shortId, slugId, fmtDate, escapeLt, workspaceKey as wk, uuid } from "./util.js";
 import { hasCJK, searchSessionsCJK } from "./session-cjk.js";
+import { sessionSeq } from "./session-events.js";
 
 const KINDS = [
   "preference",
@@ -51,7 +52,7 @@ function callerOf(exec) {
   if (agent === void 0) throw new EngramError("ENGRAM_MISSING_AGENT", "engram tools require an agent-bound caller");
   const cwd = agent.session?.header?.cwd;
   if (cwd === void 0 || cwd.length === 0) throw new EngramError("ENGRAM_UNAUTHORIZED", "this session has no workspace cwd; engram memory is workspace-scoped");
-  return { agent, cwd: wk(cwd), sessionId: agent.session.id, seq: agent.session.events?.length ?? 0 };
+  return { agent, cwd: wk(cwd), sessionId: agent.session.id, seq: sessionSeq(agent.session) };
 }
 
 function parse(zodSchema, raw, tool) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-engram",
   "description": "Minimalist long-term memory for DeepSeek Harness, distilling symbolic-index + pi-esr ideas: zero-LLM auto-capture, a symbolic [ENGRAM] index with progressive disclosure, and an ESR-lite evidence-closure protocol (esr_task / esr_node / esr_close / esr_link). Real agent-behaviour telemetry (usage rollup + /stats) and a deterministic offline recall benchmark (npm run eval). Hot path is model-free; storage on ctx.storageDomain; web memory viewer, observability panel and config card through DSH's native settings slots.",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "packageManager": "pnpm@11.22.0",
   "license": "MIT",
   "repository": {