dsh-context-guardian 0.1.0-alpha.2 → 0.1.0-alpha.4

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## dsh-context-guardian 0.1.0-alpha.4 - pinned goal survives compaction (2026-09-24)
+
+Engine only (`cg-engine-3`, unchanged). Every checkpoint now carries the
+session's original request byte-for-byte, so a local model cannot drift off
+the task across one or several compactions.
+
+**What.** `extractGoal(nodes)` recovers the pinned goal: a goal block already
+embedded in an earlier checkpoint wins; otherwise the first real user-text
+node (never a tool result, never harness-injected context) is the fallback.
+A later `Goal: ...` user message is captured as a numbered UPDATE, deduped by
+seq (first wins) and replayed in order -- it does not replace the original
+request. `renderGoal(g)` writes the pinned block back (`<<<GOAL ... GOAL>>>`,
+plus one `<<<GOAL update seq N ... GOAL>>>` block per update) at the TOP of
+every deterministic checkpoint, ahead of `RECALL_GUIDE`, and is never counted
+against or cut by any length cap. The same block is also prepended as a new
+first summary entry when the stock LLM summary succeeds, so the pin survives
+regardless of which summarization path a given compaction takes.
+
+**Tests.** `tests/goal_pin_smoke.mjs` (new, 11 checks): byte-for-byte survival
+of a 6000-character non-ASCII request across a second compaction, no
+duplication, `Goal:` updates captured/deduped/ordered, tool results and
+harness-injected messages never mistaken for the goal, no goal block at all
+when there is no user text, and the checkpoint-goal-wins-over-later-message
+rule. `tests/engine_smoke.mjs`'s `llm_success_passes_through_untouched` check
+was loosened to assert the stock summary block is present rather than at a
+fixed index, since a pinned-goal block may now be prepended as `summary[0]`.
+
+## dsh-context-guardian 0.1.0-alpha.3 - install from npm (2026-09-20)
+
+Docs only. `dsh plugin --profile <name> add dsh-context-guardian` now works by name; the DSH guide says where `engine.js` lands after an npm install and how to point the agent-preset row at it. No code change (engine `cg-engine-3`).
+
 ## dsh-context-guardian 0.1.0-alpha.2 - the DSH compaction engine (2026-09-20)
 
 The proxy (`context_guardian.py`) is unchanged. This adds the DSH side.

package/docs/dsh-integration.md

@@ -18,7 +18,9 @@ DSH mounts compaction inside the AGENT PRESET (the `compaction` group), not in t
 
 ## Install the engine (5 minutes)
 
-1. Get the code: `git clone https://github.com/LuminariSoftwares/context-guardian` (or use your existing checkout). Note the absolute path.
+1. Get the code — either way works, and you need the absolute path of `engine.js` for step 3:
+   - **From npm (recommended):** `dsh plugin --profile <your-profile> add dsh-context-guardian`. The engine then sits at `<DSH_HOME>/profiles/<your-profile>/node_modules/dsh-context-guardian/engine.js`.
+   - **From git:** `git clone https://github.com/LuminariSoftwares/context-guardian` anywhere on disk. No `pnpm install` is needed for the engine; it has no dependencies.
 
 2. Make your own agent preset if you do not have one: copy the shipped `standard` preset folder to `<DSH_HOME>/.agent-presets/<your-id>/` (it contains `agent.cordis.yml` and `preset.yml`). `<DSH_HOME>` is `~/.dsh` unless you set the `DSH_HOME` environment variable.
 
@@ -33,7 +35,7 @@ DSH mounts compaction inside the AGENT PRESET (the `compaction` group), not in t
            tools: [recall, search]
    ```
    In the shipped preset the sibling rows (`- id: tool-result-pruner`) start at 4 spaces; match whatever yours use.
-   Note: `name` is a `file:///` URL to YOUR checkout (forward slashes, also on Windows), or a path starting with `./` relative to the preset folder if you copy `engine.js`, `cg_recall.js` and `vendor/compiler.js` next to it. `numCtx` must be your model's real context window.
+   Note: `name` is a `file:///` URL to the `engine.js` from step 1 — for an npm install that is `file:///C:/Users/<you>/.dsh/profiles/<your-profile>/node_modules/dsh-context-guardian/engine.js`. It is a URL to YOUR copy (forward slashes, also on Windows), or a path starting with `./` relative to the preset folder if you copy `engine.js`, `cg_recall.js` and `vendor/compiler.js` next to it. `numCtx` must be your model's real context window.
 
 4. Start a NEW session with that preset selected. No restart is needed: DSH re-mounts a preset whose file changed when the next session starts.
 

package/engine.js

@@ -47,6 +47,13 @@ export const name = 'context-guardian-engine'
 export const inject = ['compaction']
 export const ENGINE_REV = 'cg-engine-3'
 
+// Pinned goal markers. The session's original request is pinned into every
+// checkpoint byte-for-byte so a local model never drifts from the task after
+// one (or two) compactions.
+export const GOAL_OPEN = '<<<GOAL'
+export const GOAL_CLOSE = 'GOAL>>>'
+export const GOAL_UPDATE_RE = /^\s*goal\s*:/i
+
 const PACKAGE_ROOT = dirname(fileURLToPath(import.meta.url))
 const MODES = ['llm-then-deterministic', 'deterministic', 'off']
 const ALL_TOOLS = ['recall', 'search', 'context_rewrite_cost', 'context_compact']
@@ -250,6 +257,83 @@ export function splitInjected(nodes, dropSources) {
 /** Identifier-like: a path, a dotted/underscored/hyphenated name, or anything with a digit -- not an English word. */
 const IDENTIFIER_RE = /[_/\\.\-\d]/
 
+// ── pinned goal ─────────────────────────────────────────────────────────────
+// A `<<<GOAL ... >>>`-delimited block survives compaction inside the checkpoint
+// text; extractGoal reads it back out (from earlier checkpoints and from the
+// live user messages) and renderGoal writes it verbatim onto a fresh one.
+
+const GOAL_BLOCK_RE = new RegExp(`${GOAL_OPEN}\\n([\\s\\S]*?)\\n${GOAL_CLOSE}`)
+const GOAL_UPDATE_BLOCK_RE = new RegExp(`${GOAL_OPEN} update seq (\\d+)\\n([\\s\\S]*?)\\n${GOAL_CLOSE}`, 'g')
+
+/** Every text block of a message joined with "\n". */
+function messageText(message) {
+  const blocks = Array.isArray(message?.content) ? message.content : []
+  return blocks.filter(block => block?.type === 'text').map(block => String(block.text ?? '')).join('\n')
+}
+
+/** A real user turn: role user, not a checkpoint, no injected source, first block text. */
+function isUserTextNode(message) {
+  if (message?.role !== 'user') return false
+  if (isCheckpointSource(message.source)) return false
+  const source = message.source
+  if (source !== undefined && source !== null) return false
+  return message.content?.[0]?.type === 'text'
+}
+
+/**
+ * The session's pinned goal and its `goal:` updates, recovered from `nodes`
+ * (walked in the given order). A goal carried by any checkpoint node wins; the
+ * first user-text node is the fallback goal. Updates are de-duplicated by seq
+ * (first wins) and returned sorted by seq ascending.
+ */
+export function extractGoal(nodes) {
+  let goal = null
+  let goalNode = null
+  let firstUserText = null
+  const collected = []
+  for (const node of nodes ?? []) {
+    const message = node?.message
+    if (message === undefined || message === null) continue
+    if (isCheckpointSource(message.source)) {
+      const text = messageText(message)
+      if (goal === null) {
+        const match = text.match(GOAL_BLOCK_RE)
+        if (match !== null) goal = match[1]
+      }
+      for (const match of text.matchAll(GOAL_UPDATE_BLOCK_RE)) {
+        collected.push({ seq: Number(match[1]), text: match[2], node: null })
+      }
+    } else if (isUserTextNode(message)) {
+      const text = messageText(message)
+      if (firstUserText === null) firstUserText = { node, text }
+      if (GOAL_UPDATE_RE.test(text)) collected.push({ seq: node.seq, text, node })
+    }
+  }
+  if (goal === null && firstUserText !== null) {
+    goal = firstUserText.text
+    goalNode = firstUserText.node
+  }
+  const bySeq = new Map()
+  for (const update of collected) {
+    // Skip the goal node's own text; checkpoint updates carry node=null, so
+    // only a real goalNode may suppress an update.
+    if ((goalNode !== null && update.node === goalNode) || bySeq.has(update.seq)) continue
+    bySeq.set(update.seq, { seq: update.seq, text: update.text })
+  }
+  return { goal, updates: [...bySeq.values()].sort((a, b) => a.seq - b.seq) }
+}
+
+/** Render a pinned-goal block for a checkpoint head. '' when there is no goal. */
+export function renderGoal(g) {
+  if (g?.goal === null || g?.goal === undefined) return ''
+  let out = "[pinned goal -- the session's first request, verbatim; later 'goal:' updates follow. Keep working toward it.]"
+  out += `\n${GOAL_OPEN}\n${g.goal}\n${GOAL_CLOSE}`
+  for (const update of g.updates ?? []) {
+    out += `\n${GOAL_OPEN} update seq ${update.seq}\n${update.text}\n${GOAL_CLOSE}`
+  }
+  return out
+}
+
 /** The deterministic checkpoint body for one region. Pure. */
 export function buildCheckpoint(allRegionNodes, options, pressure, allNodes) {
   const { kept: nodes, dropped } = splitInjected(allRegionNodes, options.dropSources)
@@ -274,10 +358,16 @@ export function buildCheckpoint(allRegionNodes, options, pressure, allNodes) {
   })
   const real = allRegionNodes.filter(node => node.seq >= 0).map(node => node.seq)
   const range = real.length === 0 ? 'unmapped' : `${Math.min(...real)}-${Math.max(...real)}`
+  // The goal is computed from the region PLUS the whole session (region first),
+  // so a goal carried by a checkpoint inside the region wins over a later user
+  // message. It is never counted against or cut by any cap.
+  const goalNodes = allNodes === undefined || allNodes === null ? allRegionNodes : [...allRegionNodes, ...allNodes]
+  const goalBlock = renderGoal(extractGoal(goalNodes))
   const parts = [
     `[context-guardian checkpoint · deterministic · ${allRegionNodes.length} nodes · seqs ${range} · ~${regionTokens} -> ~${compiled.stats.tokens} tokens · ${COMPILER_REV}]`,
-    RECALL_GUIDE,
   ]
+  if (goalBlock.length > 0) parts.push(goalBlock)
+  parts.push(RECALL_GUIDE)
   if (dropped.length > 0) parts.push(`[${dropped.length} harness-injected context messages omitted (instructions, skill list, runtime notes -- the harness re-injects them): seqs ${dropped.map(node => node.seq).join(', ')}]`)
   parts.push(...compiled.entries)
   const files = filesWritten(nodes, options.filesListed)
@@ -396,6 +486,17 @@ export function apply(ctx, config) {
       const result = await original.call(this, input, agent, signal)
       if (hasText(result)) {
         record({ event: 'llm', session: String(agent?.session?.id ?? ''), provider: result.provider, model: result.model })
+        // Pin the goal on top of the stock summary too, as a NEW first text block.
+        let goalBlock = ''
+        try {
+          const region = mapRegionSeqs(agent?.session, input.messages).nodes
+          const session = agent?.session
+          const goalNodes = session === undefined || session === null ? region : [...region, ...sessionNodes(session)]
+          goalBlock = renderGoal(extractGoal(goalNodes))
+        } catch { goalBlock = '' }
+        if (goalBlock.length > 0) {
+          return { ...result, summary: [{ type: 'text', text: goalBlock }, ...(Array.isArray(result.summary) ? result.summary : [])] }
+        }
         return result
       }
       return deterministic(input, agent, 'llm summary was empty')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-context-guardian",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.4",
   "description": "Context Guardian as a native DeepSeek Harness (DSH) bundle: deterministic, seq-pointer-preserving compaction with model-facing recall and search. Companion to dsh-tool-guardian.",
   "type": "module",
   "main": "index.js",