dsh-engram 0.6.0 → 0.7.1

package/lib/entity-page.js

@@ -0,0 +1,200 @@
+/**
+ * dsh-engram entity pages (PROPOSAL-evolution §4 v0.7-B).
+ *
+ * `esr_node` used to be a dot on the graph: a name, a kind, edges. An entity
+ * PAGE is the readable projection of everything the workspace knows about that
+ * thing:
+ *
+ *   truth      — current claims (superseded rows excluded), preference first
+ *   timeline   — newest anchored memories
+ *   open loops — active ESR tasks hanging on the entity
+ *   conflicts  — rows contradicted by / contradicting another row
+ *   relations  — typed links in and out
+ *
+ * Two renderings:
+ *   - `renderEntityCard` — ONE line for the [ENGRAM] index (the model sees it
+ *     every session and drills with `engram_detail(entity=…)`);
+ *   - `renderEntityPage` — the full page returned by that drill / the GUI.
+ *
+ * Pure functions over the store; zero LLM, deterministic ordering.
+ */
+
+import { escapeLt, fmtDate, shortId, truncate } from "./util.js";
+import { evidenceGaps } from "./index-block.js";
+import { memoryIsStale } from "./anchor.js";
+
+const TRUTH_KINDS = new Set(["preference", "decision", "fact", "insight", "procedure"]);
+
+/** Find an entity by id or name (case-insensitive), or return a virtual one. */
+export function resolveEntity(store, workspace, key) {
+  const raw = String(key ?? "").trim();
+  if (raw.length === 0) return null;
+  const entities = typeof store?.listEntities === "function" ? store.listEntities(workspace) : [];
+  const lower = raw.toLowerCase();
+  const found = entities.find(
+    (entity) => String(entity.id).toLowerCase() === lower || String(entity.name).toLowerCase() === lower,
+  );
+  if (found !== void 0) return found;
+  // A name that has memories/tasks anchored but no registered node still
+  // deserves a page — the anchor itself is the identity.
+  return { id: raw, workspace, name: raw, kind: "", description: "", createdAt: 0, updatedAt: 0, sessionId: "" };
+}
+
+function byUpdatedDesc(a, b) {
+  return (b.updatedAt ?? b.createdAt ?? 0) - (a.updatedAt ?? a.createdAt ?? 0);
+}
+
+function matchesAnchor(memory, entity, key) {
+  const anchor = memory?.entity;
+  if (typeof anchor !== "string" || anchor.length === 0) return false;
+  return anchor === entity.id || anchor === entity.name || anchor === key;
+}
+
+/**
+ * Build the page projection for one entity.
+ *
+ * @param {object} store opened engram domain
+ * @param {string} workspace normalized workspace key
+ * @param {string} key entity id or display name
+ */
+export function buildEntityPage(store, workspace, key, { timelineLimit = 8 } = {}) {
+  const entity = resolveEntity(store, workspace, key);
+  if (entity === null) return null;
+  const anchored = (store.timeline?.(workspace, entity.name || key, 100) ?? [])
+    .filter((memory) => matchesAnchor(memory, entity, String(key).trim()));
+  const relations = store.memoryRelations?.(workspace) ?? { supersededBy: new Map(), contradictedBy: new Map() };
+  const supersededBy = relations.supersededBy ?? new Map();
+  const contradictedBy = relations.contradictedBy ?? new Map();
+  const fresh = anchored.filter((memory) => !supersededBy.has(memory.id));
+
+  const truth = fresh
+    .filter((memory) => TRUTH_KINDS.has(memory.kind))
+    .filter((memory) => !memoryIsStale(memory))
+    .sort((a, b) => (Number(b.kind === "preference") - Number(a.kind === "preference")) || byUpdatedDesc(a, b))
+    .slice(0, 6);
+  const timeline = fresh.slice().sort(byUpdatedDesc).slice(0, timelineLimit);
+  const openTasks = (store.listTasks?.(workspace) ?? []).filter(
+    (task) => task.entity === entity.id || task.entity === entity.name || task.entity === String(key).trim(),
+  );
+  const links = [];
+  const seen = new Set();
+  for (const relation of [
+    ...(store.linksFor?.(workspace, entity.id) ?? []),
+    ...(entity.name !== entity.id ? store.linksFor?.(workspace, entity.name) ?? [] : []),
+  ]) {
+    if (seen.has(relation.id)) continue;
+    seen.add(relation.id);
+    links.push(relation);
+  }
+  const conflictSeen = new Set();
+  const conflicts = [];
+  for (const memory of anchored) {
+    const contradicted = contradictedBy.get(memory.id)?.[0]?.id ?? null;
+    const contradicts = typeof memory.contradicts === "string" && memory.contradicts.length > 0 ? memory.contradicts : null;
+    const other = contradicted ?? contradicts;
+    if (other === null) continue;
+    const pair = [memory.id, other].sort().join("|");
+    if (conflictSeen.has(pair)) continue;
+    conflictSeen.add(pair);
+    conflicts.push({ memory, contradictedById: contradicted, contradictsId: contradicts });
+  }
+
+  const updatedAt = Math.max(
+    entity.updatedAt ?? 0,
+    ...anchored.map((memory) => memory.updatedAt ?? memory.createdAt ?? 0),
+    ...openTasks.map((task) => task.updatedAt ?? 0),
+    0,
+  );
+
+  return {
+    entity,
+    anchored,
+    truth,
+    timeline,
+    openTasks,
+    links,
+    conflicts,
+    counts: {
+      memories: fresh.length,
+      openTasks: openTasks.filter((task) => task.state === "active").length,
+      conflicts: conflicts.length,
+      links: links.length,
+    },
+    updatedAt,
+  };
+}
+
+/**
+ * ONE index line for an entity with something worth surfacing. The drill
+ * pointer is never truncated away: the head (and truth excerpt) shrink first.
+ */
+export function renderEntityCard(page, { maxChars = 160 } = {}) {
+  if (page === null) return "";
+  const name = page.entity.name || page.entity.id;
+  const pointer = ` · page: engram_detail(entity="${escapeLt(name)}")`;
+  const kind = page.entity.kind ? ` · ${page.entity.kind}` : "";
+  let head = `[ENT] ${escapeLt(truncate(name, 40))}${kind} · ${page.counts.memories} mem · ${page.counts.openTasks} open`;
+  if (head.length + pointer.length > maxChars) {
+    head = truncate(head, Math.max(12, maxChars - pointer.length - 1));
+  }
+  const truth = page.truth[0];
+  if (truth !== void 0) {
+    const room = maxChars - head.length - pointer.length - " · truth: ".length - 9;
+    if (room >= 12) {
+      const text = truncate(String(truth.text).replace(/\s+/g, " ").trim(), room);
+      head += ` · truth: ${text} #${shortId(truth.id)}`;
+    }
+  }
+  return `${head}${pointer}`;
+}
+
+/** Full page text (engram_detail drill / GUI later). */
+export function renderEntityPage(page, { maxChars = 2400 } = {}) {
+  if (page === null) return "no such entity";
+  const name = page.entity.name || page.entity.id;
+  const lines = [];
+  const header = [`ent:${name}`, page.entity.kind, `${page.counts.memories} memory`, `${page.counts.openTasks} open`]
+    .filter((part) => typeof part === "string" && part.length > 0)
+    .join(" · ");
+  lines.push(`${header} · updated ${fmtDate(page.updatedAt)} #${page.entity.id}`);
+  if (typeof page.entity.description === "string" && page.entity.description.length > 0) {
+    lines.push(`description: ${truncate(page.entity.description, 200)}`);
+  }
+  if (page.truth.length > 0) {
+    lines.push("truth:");
+    for (const memory of page.truth) {
+      lines.push(`- [${memory.kind}] ${truncate(String(memory.text).replace(/\s+/g, " "), 180)} #${shortId(memory.id)}`);
+    }
+  }
+  if (page.timeline.length > 0) {
+    lines.push("timeline:");
+    for (const memory of page.timeline) {
+      const stale = memoryIsStale(memory) ? " · stale" : "";
+      lines.push(`- ${fmtDate(memory.createdAt)} [${memory.kind}] ${truncate(String(memory.text).replace(/\s+/g, " "), 120)} #${shortId(memory.id)}${stale}`);
+    }
+  }
+  if (page.openTasks.length > 0) {
+    lines.push("open loops:");
+    for (const task of page.openTasks) {
+      const gaps = evidenceGaps(task);
+      const state = task.state === "stable" ? "STABLE" : gaps.length === 0 ? "READY" : `gap: ${gaps.join(", ")}`;
+      lines.push(`- ${task.id} ${truncate(String(task.name), 80)} — ${state}`);
+    }
+  }
+  if (page.links.length > 0) {
+    lines.push("relations:");
+    for (const relation of page.links.slice(0, 10)) {
+      lines.push(`- ${relation.source} --${relation.relation}--> ${relation.target} (${Math.round((relation.confidence ?? 1) * 100)}%)`);
+    }
+  }
+  if (page.conflicts.length > 0) {
+    lines.push("conflicts:");
+    for (const conflict of page.conflicts) {
+      const other = conflict.contradictedById ?? conflict.contradictsId;
+      lines.push(`- #${shortId(conflict.memory.id)} ${other === null ? "(unresolved)" : `vs #${shortId(other)}`}`);
+    }
+  }
+  lines.push("drill: engram_detail(id=…) · engram_recall(query) · esr_status");
+  const text = lines.join("\n");
+  return text.length <= maxChars ? text : `${text.slice(0, maxChars - 1)}…`;
+}

package/lib/episode.js

@@ -0,0 +1,163 @@
+/**
+ * dsh-engram session episode (PROPOSAL-evolution §4 v0.7-A).
+ *
+ * At the session's teardown edge we distill the event log into ONE compact
+ * `episode` memory: what was touched, what ran, what failed (and whether it
+ * later succeeded), the written commit subjects, and what is still open.
+ *
+ * Design constraints:
+ *   - zero LLM, pure function over `session.events` (survives restarts);
+ *   - 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);
+ *   - retention is capped per workspace by the sink in index.js, not by TTL.
+ *
+ * This is the raw material for the resume brief and, later, entity pages.
+ */
+
+import { cmdTag } from "./capture.js";
+import { pendingTodosFromSession } from "./todo-sink.js";
+
+const EDIT_TOOLS = new Set(["write", "edit", "str_replace_editor"]);
+const RUN_TOOLS = new Set(["bash", "shell", "exec"]);
+
+function parseArgs(raw) {
+  if (raw !== null && typeof raw === "object") return raw;
+  if (typeof raw !== "string" || raw.length === 0) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed !== null && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function clip(text, max) {
+  const flat = String(text ?? "").replace(/\s+/g, " ").trim();
+  return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`;
+}
+
+function stamp(now) {
+  const d = new Date(now);
+  const p = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+}
+
+/** Repo-relative display path when the file lives under the session cwd. */
+function displayPath(path, cwd) {
+  const p = String(path ?? "");
+  if (typeof cwd === "string" && cwd.length > 0 && p.startsWith(`${cwd}/`)) return p.slice(cwd.length + 1);
+  return p;
+}
+
+function commitSubject(command) {
+  if (!/^\s*git\s+commit\b/.test(command)) return null;
+  const m = command.match(/-m\s+["']([^"']{1,80})["']/);
+  return m === null ? null : clip(m[1], 60);
+}
+
+/**
+ * Build the episode record from a disposed session.
+ *
+ * @param {object} session session with `.events` + `.header.cwd`
+ * @param {object} [opts]
+ * @returns {{text: string, tags: string[], signal: number, summary: object}|null}
+ */
+export function buildEpisode(session, { now = Date.now() } = {}) {
+  if (session === null || typeof session !== "object") return null;
+  const events = Array.isArray(session.events) ? session.events : [];
+  if (events.length === 0) return null;
+  const cwd = session?.header?.cwd;
+
+  const files = new Map(); // display path -> count
+  const commands = new Map(); // cmd tag -> row
+  const decisions = [];
+  const callMeta = new Map(); // callId -> { tag, row }
+  let failedRuns = 0;
+
+  for (const event of events) {
+    if (event === null || typeof event !== "object") continue;
+    const type = event.type;
+    if (type === "tool/call") {
+      const data = event.data ?? {};
+      const name = String(data.name ?? "").toLowerCase();
+      const args = parseArgs(data.arguments);
+      const callId = typeof data.callId === "string" ? data.callId : null;
+      if (EDIT_TOOLS.has(name)) {
+        const path = String(args.path ?? args.file_path ?? args.filePath ?? "");
+        if (path.length > 0) {
+          const shown = displayPath(path, cwd);
+          files.set(shown, (files.get(shown) ?? 0) + 1);
+        }
+      }
+      if (RUN_TOOLS.has(name) && typeof args.command === "string") {
+        const tag = cmdTag(args.command);
+        if (tag !== null) {
+          const row = commands.get(tag) ?? { tag, count: 0, failed: false, fixed: false };
+          row.count += 1;
+          commands.set(tag, row);
+          if (callId !== null) callMeta.set(callId, { tag, row });
+        }
+        const subject = commitSubject(args.command);
+        if (subject !== null) decisions.push(subject);
+      }
+      continue;
+    }
+    if (type === "tool/result") {
+      const content = event?.data?.message?.content;
+      const block = Array.isArray(content) ? content.find((c) => c?.type === "tool-result") : null;
+      const callId = block?.toolCallId ?? event?.data?.message?.source?.callId;
+      const meta = typeof callId === "string" ? callMeta.get(callId) : void 0;
+      if (meta === void 0) continue;
+      const isError = block?.isError === true || event?.data?.error !== void 0;
+      if (isError) {
+        if (!meta.row.failed) failedRuns += 1;
+        meta.row.failed = true;
+      } else if (meta.row.failed) {
+        meta.row.fixed = true;
+      }
+    }
+  }
+
+  const open = pendingTodosFromSession(session).slice(0, 3);
+  const hasSubstance = files.size > 0 || decisions.length > 0 || failedRuns > 0 || open.length > 0;
+  if (!hasSubstance) return null;
+
+  const parts = [];
+  if (files.size > 0) {
+    const shown = [...files.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 4)
+      .map(([path]) => clip(path, 48));
+    parts.push(`files ${shown.join(", ")}`);
+  }
+  if (commands.size > 0) {
+    const rows = [...commands.values()]
+      .sort((a, b) => Number(b.failed) - Number(a.failed) || b.count - a.count)
+      .slice(0, 4)
+      .map((row) => {
+        const head = row.tag.replace(/^cmd:/, "").replace(/_/g, " ");
+        const mark = row.failed ? (row.fixed ? "→fixed" : "→failed") : "";
+        return `${clip(head, 32)}×${row.count}${mark}`;
+      });
+    parts.push(`cmds ${rows.join(", ")}`);
+  }
+  if (decisions.length > 0) {
+    parts.push(`decisions ${decisions.slice(0, 2).map((d) => `"${clip(d, 40)}"`).join(", ")}`);
+  }
+  if (open.length > 0) parts.push(`open ${open.map((t) => clip(t, 40)).join("; ")}`);
+
+  const text = clip(`session episode ${stamp(now)}: ${parts.join(" · ")}`, 900);
+  return {
+    text,
+    signal: 0.25,
+    tags: ["episode", "auto-captured", ...(failedRuns > 0 ? ["fix"] : [])],
+    summary: {
+      files: [...files.keys()],
+      commands: [...commands.values()],
+      decisions,
+      open,
+      failedRuns,
+    },
+  };
+}

package/lib/index-block.js

@@ -10,6 +10,8 @@
  */
 
 import { label, shortId, fmtDate, escapeLt, truncate, byRecency } from "./util.js";
+import { buildEntityPage, renderEntityCard } from "./entity-page.js";
+import { memoryIsStale } from "./anchor.js";
 
 /** Deterministic index line prefix per memory kind. */
 export function prefixFor(kind) {
@@ -21,6 +23,7 @@ export function prefixFor(kind) {
     case "handoff": return "H";
     case "task": return "T";
     case "preference": return "R";
+    case "episode": return "S";
     default: return "F";
   }
 }
@@ -57,6 +60,12 @@ export function selectIndexMemories(store, workspace, config) {
   const { supersededBy } = store.memoryRelations?.(workspace) ?? { supersededBy: new Map() };
   return all
     .filter((m) => !supersededBy.has(m.id))
+    // Session episodes are background context, never index lines (they are
+    // long and only useful as a resume brief or through engram_detail).
+    .filter((m) => m.kind !== "episode")
+    // A memory whose file source changed/vanished is no longer current truth
+    // for an auto-injected index line (still re-fetchable via engram_detail).
+    .filter((m) => !memoryIsStale(m))
     .filter(
       (m) =>
         (isGitPlumbingEcho(m) && (m.hits ?? 0) < config.promoteHits
@@ -108,22 +117,58 @@ function taskStateLine(t) {
   return `[T] ${fmtDate(t.createdAt)} ${name} — ${suffix} #${t.id.slice(0, 8)}`;
 }
 
+/**
+ * Entity cards for the index (v0.7-B): entities with anchored memories or open
+ * tasks, ranked by activity. Each card is ONE line; the model drills with
+ * `engram_detail(entity=…)`. Bounded and deterministic.
+ */
+export function selectEntityCards(store, workspace, config = {}) {
+  if (config.entityCardsEnabled === false) return [];
+  if (store === null || typeof store.listEntities !== "function") return [];
+  const max = Math.max(1, Math.min(4, Number.isFinite(config.entityCardsMax) ? Math.trunc(config.entityCardsMax) : 2));
+  const pages = [];
+  for (const entity of store.listEntities(workspace)) {
+    const page = buildEntityPage(store, workspace, entity.id);
+    if (page === null) continue;
+    if (page.counts.memories === 0 && page.counts.openTasks === 0) continue;
+    pages.push(page);
+  }
+  pages.sort((a, b) => {
+    const score = (page) => page.counts.memories + page.counts.openTasks * 2;
+    return score(b) - score(a) || String(a.entity.name).localeCompare(String(b.entity.name));
+  });
+  return pages.slice(0, max);
+}
+
 /**
  * Render the full [ENGRAM] block (or "" when nothing to show). Pure function;
  * called by the section provider and cached per session.
  */
 export function renderIndex(store, workspace, cwd, config) {
   const entries = store.workspaceEntries(workspace);
-  const memories = selectIndexMemories(store, workspace, config);
+  const cards = selectEntityCards(store, workspace, config);
+  const cardKeys = new Set();
+  for (const page of cards) {
+    cardKeys.add(page.entity.id);
+    cardKeys.add(page.entity.name);
+  }
+  // Memories already represented by an entity card are not repeated as flat
+  // lines — the card carries their current truth and the drill pointer.
+  const memories = selectIndexMemories(store, workspace, config)
+    .filter((memory) => !(typeof memory.entity === "string" && cardKeys.has(memory.entity)));
   const tasks = store.listTasks(workspace, { includeStable: false });
   const links = entries.links;
 
-  if (memories.length === 0 && tasks.length === 0 && links === 0) return "";
+  if (memories.length === 0 && tasks.length === 0 && links === 0 && cards.length === 0) return "";
 
   const lines = [];
   lines.push(`[ENGRAM] workspace: ${label(cwd)} · ${entries.memories} memories · ${tasks.length} task(s) active · ${links} links · ${entries.nodes} node(s)`);
-  const entityNames = store.listEntities(workspace).map((e) => e.name);
-  if (entityNames.length > 0) lines.push(`nodes: ${truncate(entityNames.join(", "), 72)}`);
+  for (const page of cards) {
+    lines.push(renderEntityCard(page, { maxChars: config.entityCardChars ?? 120 }));
+  }
+  const shownNames = new Set(cards.map((page) => page.entity.name));
+  const otherNames = store.listEntities(workspace).map((e) => e.name).filter((name) => !shownNames.has(name));
+  if (otherNames.length > 0) lines.push(`nodes: ${truncate(otherNames.join(", "), 72)}`);
   for (const m of memories.slice(0, config.indexMaxLines)) lines.push(memoryLine(m, config));
   for (const t of tasks.slice(0, 4)) lines.push(taskStateLine(t));
   lines.push("drill: use [RECALL] below · engram_detail <id> (full record) · engram_recall <query> (more) · esr_task/esr_node/esr_link (work)");
@@ -560,3 +605,28 @@ function taskGapSuffix(t) {
   const gaps = evidenceGaps(t);
   return gaps.length === 0 ? " · READY to close" : ` · gap: ${gaps.join(", ")}`;
 }
+
+/**
+ * [RESUME] brief (PROPOSAL-evolution §4 v0.7-D): the newest recent session
+ * episode, rendered as ≤ N chars plus a drill pointer. Frozen per session by
+ * the same cache as [ENGRAM]; empty when no recent episode exists.
+ */
+export function renderResumeBrief(store, workspace, config = {}, opts = {}) {
+  if (config?.resumeBriefEnabled === false) return "";
+  if (store === null || typeof store?.listMemories !== "function") return "";
+  const days = Number.isFinite(config?.resumeBriefMaxAgeDays)
+    ? Math.max(0, config.resumeBriefMaxAgeDays)
+    : 7;
+  const maxChars = Number.isFinite(config?.resumeBriefMaxChars) && config.resumeBriefMaxChars > 0
+    ? Math.trunc(config.resumeBriefMaxChars)
+    : 240;
+  const now = opts.now ?? Date.now();
+  const cutoff = now - days * 86_400_000;
+  const episodes = store
+    .listMemories(workspace, 200)
+    .filter((m) => m.kind === "episode" && (m.createdAt ?? m.updatedAt ?? 0) >= cutoff);
+  if (episodes.length === 0) return "";
+  const latest = episodes[0]; // listMemories is recency-sorted
+  const body = truncate(String(latest.text).replace(/^session episode[^:]*:\s*/, ""), maxChars);
+  return `[RESUME] last episode ${fmtDate(latest.createdAt)}: ${body}\ncontext: engram_detail ${latest.id} (full) · continue or esr_status`;
+}