@theseus-whale/dsh-continuity 0.0.0-stage → 4.12.2

package/src/memory/event-model.mjs

@@ -0,0 +1,132 @@
+/**
+ * EventModel: stable situation slots and boundary strength.
+ *
+ * Unlike facets, these slots describe the current situation. A topic change
+ * alone is not a boundary; location/characters/goal changes are stronger.
+ */
+
+const WEIGHTS = Object.freeze({
+  location: 0.35,
+  characters: 0.30,
+  goal: 0.25,
+  objects: 0.10,
+  activity: 0.10,
+  topic: 0,
+});
+
+const LOCATION_STOP = new Set(['这里', '那里', '现在', '刚才', '地方', '时候', '什么', '一个']);
+const LOCATION_TERMS = ['灯室', '钟楼', '矿口', '石屋', '旧镇', '库房', '码头', '地窖', '院子', '木棚', '悬崖'];
+
+export function validateEventSlots(input = {}) {
+  const errors = [];
+  const allowed = new Set(['location', 'characters', 'goal', 'objects', 'activity', 'topic']);
+  for (const key of Object.keys(input)) {
+    if (!allowed.has(key)) errors.push({ key, reason: 'unknown-slot' });
+  }
+  for (const key of ['location', 'goal', 'activity', 'topic']) {
+    const value = input[key];
+    if (value !== undefined && value !== null && typeof value !== 'string') {
+      errors.push({ key, reason: 'not-a-string' });
+    } else if (typeof value === 'string' && value.length > 40) {
+      errors.push({ key, reason: 'too-long' });
+    }
+  }
+  for (const key of ['characters', 'objects']) {
+    const value = input[key];
+    if (value !== undefined && value !== null && !Array.isArray(value)) {
+      errors.push({ key, reason: 'not-an-array' });
+    } else if (Array.isArray(value)) {
+      if (value.length > 20) errors.push({ key, reason: 'too-many' });
+      for (const item of value) {
+        if (typeof item !== 'string') errors.push({ key, reason: 'item-not-string' });
+        else if (item.length > 40) errors.push({ key, reason: 'item-too-long' });
+      }
+    }
+  }
+  return { ok: errors.length === 0, errors, slots: normalizeEventSlots(input) };
+}
+
+export function normalizeEventSlots(input = {}) {
+  const array = (value) => (Array.isArray(value) ? value : value === undefined || value === null ? [] : [value])
+    .map((item) => String(item).trim())
+    .filter(Boolean);
+  const scalar = (value) => {
+    const text = value === undefined || value === null ? '' : String(value).trim();
+    return text.length === 0 ? null : text;
+  };
+  return {
+    location: scalar(input.location),
+    characters: [...new Set(array(input.characters))],
+    goal: scalar(input.goal),
+    objects: [...new Set(array(input.objects))],
+    activity: scalar(input.activity),
+    topic: scalar(input.topic),
+  };
+}
+
+function scalarChanged(a, b) {
+  if (a === null || b === null) return 0;
+  return a === b ? 0 : 1;
+}
+
+function setChanged(a, b) {
+  if (a.length === 0 || b.length === 0) return 0;
+  const left = new Set(a);
+  const right = new Set(b);
+  let same = 0;
+  for (const item of left) if (right.has(item)) same += 1;
+  const union = new Set([...left, ...right]).size;
+  return union === 0 ? 0 : 1 - same / union;
+}
+
+export function boundaryScore(previous, next) {
+  if (previous === null || previous === undefined) return 1;
+  const a = normalizeEventSlots(previous);
+  const b = normalizeEventSlots(next);
+  const changed = {
+    location: scalarChanged(a.location, b.location),
+    characters: setChanged(a.characters, b.characters),
+    goal: scalarChanged(a.goal, b.goal),
+    objects: setChanged(a.objects, b.objects),
+    activity: scalarChanged(a.activity, b.activity),
+    topic: scalarChanged(a.topic, b.topic),
+  };
+  const score = Object.entries(WEIGHTS).reduce((sum, [slot, weight]) => sum + weight * changed[slot], 0);
+  return { score: +score.toFixed(4), changed };
+}
+
+export class EventModelState {
+  constructor({ eventId = 0, slots = null, threshold = 0.35 } = {}) {
+    this.eventId = eventId;
+    this.slots = slots === null ? null : normalizeEventSlots(slots);
+    this.threshold = threshold;
+  }
+
+  observe({ slots, explicitBoundary = false } = {}) {
+    const checked = validateEventSlots(slots);
+    if (!checked.ok) {
+      return { eventId: this.eventId, boundary: false, score: 0, error: 'invalid-slots', errors: checked.errors, slots: this.slots };
+    }
+    const next = checked.slots;
+    const result = boundaryScore(this.slots, next);
+    const boundary = explicitBoundary || this.slots === null || result.score >= this.threshold;
+    if (boundary && this.slots !== null) this.eventId += 1;
+    this.slots = next;
+    return {
+      eventId: this.eventId,
+      boundary,
+      score: this.slots === null ? 1 : result.score,
+      changed: this.slots === null ? {} : result.changed,
+      slots: next,
+    };
+  }
+}
+
+export function extractEventSlots(text, { characters = [] } = {}) {
+  const source = String(text ?? '');
+  const location = [...LOCATION_TERMS].sort((a, b) => b.length - a.length).find((term) => source.includes(term)) ?? null;
+  const foundCharacters = characters.filter((name) => name.length > 0 && source.includes(name));
+  const objects = ['钥匙', '账册', '信', '名册', '收条', '罐子', '灯', '门', '钟', '船', '布标']
+    .filter((object) => source.includes(object));
+  return normalizeEventSlots({ location, characters: foundCharacters, objects });
+}

package/src/memory/event-segmenter.mjs

@@ -0,0 +1,36 @@
+/**
+ * Event segmentation for alias formation.
+ * A boundary is opened when activity or topic changes, or when the caller
+ * supplies an explicit boundary. Event IDs are stable for the session.
+ */
+export class EventSegmenter {
+  constructor({ eventId = 0, lastFacets = null } = {}) {
+    this.eventId = eventId;
+    this.lastFacets = lastFacets;
+    this.boundaries = [];
+  }
+
+  observe({ facets = {}, nowTurn = 0, explicitBoundary = false, reason = null } = {}) {
+    const changed = this.lastFacets !== null
+      && (this.lastFacets.activity !== facets.activity || this.lastFacets.topic !== facets.topic);
+    const boundary = this.lastFacets === null || changed || explicitBoundary;
+    if (boundary && this.lastFacets !== null) {
+      this.eventId += 1;
+      this.boundaries.push({ eventId: this.eventId, nowTurn, reason: reason ?? (changed ? 'facet-change' : 'explicit') });
+    }
+    this.lastFacets = { ...facets };
+    return { eventId: this.eventId, boundary, reason: boundary ? reason ?? 'start' : null };
+  }
+}
+
+export function segmentEvents(turns) {
+  const segmenter = new EventSegmenter();
+  return turns.map((turn, index) => {
+    const result = segmenter.observe({
+      facets: turn.facets,
+      nowTurn: turn.turn ?? index,
+      explicitBoundary: turn.boundary === true,
+    });
+    return { ...turn, eventId: result.eventId, boundary: result.boundary };
+  });
+}

package/src/memory/event-summary-tree.mjs

@@ -0,0 +1,122 @@
+/**
+ * Event-aligned summary tree.
+ *
+ * Leaves are turns. Segment nodes are event groups, never fixed-size windows.
+ * Chapters group consecutive event segments. Extractive and deterministic.
+ */
+import { createHash } from 'node:crypto';
+
+function sha256(text) {
+  return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+
+function clip(text, max) {
+  const clean = String(text ?? '').replace(/\s+/g, ' ').trim();
+  return clean.length <= max ? clean : `${clean.slice(0, max)}…`;
+}
+
+function nodeId(level, index) {
+  return `${level}-${String(index + 1).padStart(5, '0')}`;
+}
+
+export function buildEventSummaryTree(records, { eventIds = null, chapterSize = 8 } = {}) {
+  const ordered = [...records].sort((a, b) => a.turn - b.turn);
+  const eventOf = (record, index) => String(eventIds?.[record.turn] ?? eventIds?.[index] ?? `turn:${record.turn}`);
+
+  const leaves = ordered.map((record, index) => ({
+    id: nodeId('turn', index),
+    level: 'turn',
+    parentId: null,
+    childIds: [],
+    turn: record.turn,
+    eventId: eventOf(record, index),
+    seqStart: record.seqStart,
+    seqEnd: record.seqEnd,
+    summary: clip(record.text, 280),
+    sourceHash: record.hash,
+  }));
+
+  const groups = [];
+  for (const leaf of leaves) {
+    const last = groups[groups.length - 1];
+    if (last !== undefined && last.eventId === leaf.eventId) last.leaves.push(leaf);
+    else groups.push({ eventId: leaf.eventId, leaves: [leaf] });
+  }
+
+  const segments = groups.map((group, index) => {
+    const id = nodeId('segment', index);
+    const children = group.leaves;
+    const node = {
+      id,
+      level: 'segment',
+      parentId: null,
+      childIds: children.map((child) => child.id),
+      eventId: group.eventId,
+      seqStart: children[0].seqStart,
+      seqEnd: children[children.length - 1].seqEnd,
+      firstTurn: children[0].turn,
+      lastTurn: children[children.length - 1].turn,
+      summary: clip(children.map((child) => child.summary).join(' / '), 700),
+      sourceHash: sha256(children.map((child) => child.sourceHash).join('')),
+    };
+    for (const child of children) child.parentId = id;
+    return node;
+  });
+
+  const chapters = [];
+  for (let start = 0; start < segments.length; start += chapterSize) {
+    const children = segments.slice(start, start + chapterSize);
+    const id = nodeId('chapter', chapters.length);
+    const node = {
+      id,
+      level: 'chapter',
+      parentId: null,
+      childIds: children.map((child) => child.id),
+      eventIds: children.map((child) => child.eventId),
+      seqStart: children[0].seqStart,
+      seqEnd: children[children.length - 1].seqEnd,
+      firstTurn: children[0].firstTurn,
+      lastTurn: children[children.length - 1].lastTurn,
+      summary: clip(children.map((child) => child.summary).join(' / '), 1200),
+      sourceHash: sha256(children.map((child) => child.sourceHash).join('')),
+    };
+    for (const child of children) child.parentId = id;
+    chapters.push(node);
+  }
+
+  return {
+    schema: 1,
+    version: 1,
+    mode: 'event-aligned',
+    chapterSize,
+    nodeCount: leaves.length + segments.length + chapters.length,
+    levels: { turn: leaves.length, segment: segments.length, chapter: chapters.length },
+    treeRootHash: sha256([...leaves, ...segments, ...chapters].map((node) => node.sourceHash).join('')),
+    nodes: [...leaves, ...segments, ...chapters],
+  };
+}
+
+export function verifyEventSummaryTree(tree) {
+  const byId = new Map(tree.nodes.map((node) => [node.id, node]));
+  const errors = [];
+  for (const node of tree.nodes) {
+    for (const childId of node.childIds) {
+      const child = byId.get(childId);
+      if (child === undefined) {
+        errors.push({ id: node.id, reason: 'missing-child', childId });
+        continue;
+      }
+      if (child.parentId !== node.id) errors.push({ id: child.id, reason: 'parent-mismatch' });
+      if (child.seqStart < node.seqStart || child.seqEnd > node.seqEnd) {
+        errors.push({ id: child.id, reason: 'child-outside-parent' });
+      }
+    }
+  }
+  for (const segment of tree.nodes.filter((node) => node.level === 'segment')) {
+    const childEvents = new Set(segment.childIds.map((childId) => byId.get(childId)?.eventId));
+    if (childEvents.size !== 1 || !childEvents.has(segment.eventId)) {
+      errors.push({ id: segment.id, reason: 'segment-crosses-event' });
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}

package/src/memory/extraction-adapter.mjs

@@ -0,0 +1,76 @@
+/**
+ * Adapter from extractor output to EventModel slots and the pre-turn gate.
+ * Extractor output is validated before it can affect state.
+ */
+import { mapEntitiesToSlots } from './extraction-core.mjs';
+import { validateEventSlots } from './event-model.mjs';
+import { applyCorefToSlots } from './coref-slots.mjs';
+import { srlToSlots, normalizeEntityLinks } from './structured-adapters.mjs';
+
+export function attachExtraction(controller, { text, role = 'user', entities = [], slots = null, facets = {}, confidence = 1, nowTurn = 0, corefClusters = [] }) {
+  const mapped = slots ?? mapEntitiesToSlots(entities);
+  const withCoref = applyCorefToSlots(mapped, corefClusters);
+  const checked = validateEventSlots(withCoref.slots);
+  if (!checked.ok) {
+    return {
+      ok: false,
+      reason: 'invalid-slots',
+      errors: checked.errors,
+      entities,
+      slots: null,
+      gate: null,
+    };
+  }
+  const gate = controller.step({
+    text,
+    role,
+    facets,
+    confidence,
+    eventSlots: checked.slots,
+    nowTurn,
+  });
+  return { ok: true, entities, slots: checked.slots, referents: withCoref.referents, gate };
+}
+
+export function attachStructuredExtraction(controller, {
+  text,
+  role = 'user',
+  facets = {},
+  confidence = 1,
+  nowTurn = 0,
+  slots = null,
+  srl = null,
+  corefClusters = [],
+  entityLinks = [],
+}) {
+  const fromSrl = srl ? srlToSlots(srl) : null;
+  const withCoref = applyCorefToSlots(slots ?? fromSrl?.slots ?? {}, corefClusters);
+  const checked = validateEventSlots(withCoref.slots);
+  if (!checked.ok) {
+    return {
+      ok: false,
+      reason: 'invalid-slots',
+      errors: checked.errors,
+      slots: null,
+      referents: withCoref.referents,
+      entityLinks: normalizeEntityLinks(entityLinks),
+      gate: null,
+    };
+  }
+  const gate = controller.step({
+    text,
+    role,
+    facets,
+    confidence,
+    eventSlots: checked.slots,
+    nowTurn,
+  });
+  return {
+    ok: true,
+    predicate: fromSrl?.predicate ?? null,
+    slots: checked.slots,
+    referents: withCoref.referents,
+    entityLinks: normalizeEntityLinks(entityLinks),
+    gate,
+  };
+}

package/src/memory/extraction-composite.mjs

@@ -0,0 +1,75 @@
+/**
+ * Composite provider: NER is required; coref, SRL, and EL are optional.
+ * Optional failures are recorded but do not discard NER slots.
+ */
+function mergeSlots(base = {}, extra = {}) {
+  const slots = {
+    characters: [...(base.characters ?? [])],
+    location: base.location ?? null,
+    goal: base.goal ?? null,
+    objects: [...(base.objects ?? [])],
+  };
+  for (const name of extra.characters ?? []) {
+    if (!slots.characters.includes(name)) slots.characters.push(name);
+  }
+  for (const item of extra.objects ?? []) {
+    if (!slots.objects.includes(item)) slots.objects.push(item);
+  }
+  slots.location ??= extra.location ?? null;
+  slots.goal ??= extra.goal ?? null;
+  return slots;
+}
+
+function candidatesFrom(data) {
+  const names = [
+    ...(data?.slots?.characters ?? []),
+    ...(data?.slots?.objects ?? []),
+    ...(data?.entities ?? []).map((entity) => entity.text),
+  ];
+  return [...new Set(names.filter((item) => typeof item === 'string' && item.trim()))];
+}
+
+export function createCompositeProvider({ ner, coref = null, srl = null, el = null, candidates = candidatesFrom } = {}) {
+  if (!ner) throw new TypeError('ner provider is required');
+  return {
+    mode: 'composite',
+    close() {
+      for (const provider of [ner, coref, srl, el]) provider?.close?.();
+    },
+    async extract({ text } = {}) {
+      const started = Date.now();
+      const nerResult = await ner.extract({ text });
+      if (!nerResult.ok) return { ...nerResult, source: 'composite', latencyMs: Date.now() - started };
+      const parts = { ner: nerResult };
+      const optional = {};
+      if (coref) optional.coref = await coref.extract({ text });
+      if (srl) optional.srl = await srl.extract({ text });
+      if (el) optional.el = await el.extract({ text, candidates: candidates(nerResult.data) });
+
+      let slots = { ...(nerResult.data?.slots ?? {}) };
+      let srlData = null;
+      if (optional.srl?.ok) {
+        srlData = optional.srl.data?.srl ?? optional.srl.data;
+        const { srlToSlots } = await import('./structured-adapters.mjs');
+        slots = mergeSlots(slots, srlToSlots(srlData).slots);
+      }
+      return {
+        ok: true,
+        source: 'composite',
+        latencyMs: Date.now() - started,
+        data: {
+          ...nerResult.data,
+          slots,
+          srl: srlData,
+          corefClusters: optional.coref?.ok ? (optional.coref.data?.clusters ?? []) : [],
+          entityLinks: optional.el?.ok ? (optional.el.data?.links ?? []) : [],
+          partial: {
+            coref: optional.coref ? { ok: optional.coref.ok, reason: optional.coref.reason ?? null, stderr: optional.coref.stderr ?? null } : null,
+            srl: optional.srl ? { ok: optional.srl.ok, reason: optional.srl.reason ?? null, stderr: optional.srl.stderr ?? null } : null,
+            el: optional.el ? { ok: optional.el.ok, reason: optional.el.reason ?? null, stderr: optional.el.stderr ?? null } : null,
+          },
+        },
+      };
+    },
+  };
+}

package/src/memory/extraction-core.mjs

@@ -0,0 +1,76 @@
+/**
+ * Extraction core: route language, call a provider, validate entities and map
+ * them to EventModel slots. Providers are replaceable (HanLP, spaCy, XLM-R...).
+ */
+import { routeLanguage } from './language-router.mjs';
+import { validateEventSlots } from './event-model.mjs';
+
+const SLOT_BY_LABEL = Object.freeze({
+  PERSON: 'characters',
+  PER: 'characters',
+  NAME: 'characters',
+  LOC: 'location',
+  LOCATION: 'location',
+  GPE: 'location',
+  FAC: 'location',
+  ADDRESS: 'location',
+  SCENE: 'location',
+  OBJECT: 'objects',
+  MISC: 'objects',
+  PROPER: 'objects',
+  ORG: 'objects',
+  COMPANY: 'objects',
+  ORGANIZATION: 'objects',
+  GOVERNMENT: 'objects',
+  BOOK: 'objects',
+  MOVIE: 'objects',
+  GAME: 'objects',
+});
+
+function validEntity(entity) {
+  return entity !== null
+    && typeof entity === 'object'
+    && typeof entity.text === 'string'
+    && entity.text.length > 0
+    && typeof entity.label === 'string'
+    && (entity.start === undefined || Number.isInteger(entity.start))
+    && (entity.end === undefined || Number.isInteger(entity.end));
+}
+
+export function mapEntitiesToSlots(entities) {
+  const slots = { characters: [], location: null, objects: [] };
+  for (const entity of entities) {
+    const slot = SLOT_BY_LABEL[entity.label.toUpperCase()];
+    if (slot === 'characters') slots.characters.push(entity.text);
+    else if (slot === 'location' && slots.location === null) slots.location = entity.text;
+    else if (slot === 'objects') slots.objects.push(entity.text);
+  }
+  slots.characters = [...new Set(slots.characters)];
+  slots.objects = [...new Set(slots.objects)];
+  return slots;
+}
+
+export function createExtractionCore({ providers = {}, fallback = null } = {}) {
+  return {
+    extract(text) {
+      const route = routeLanguage(text);
+      const provider = providers[route.language] ?? providers.mixed ?? fallback;
+      if (typeof provider !== 'function') {
+        return { ok: false, language: route.language, reason: 'no-provider', entities: [], slots: null };
+      }
+      let output;
+      try {
+        output = provider(text, route);
+      } catch (error) {
+        return { ok: false, language: route.language, reason: 'provider-error', error: String(error), entities: [], slots: null };
+      }
+      const entities = Array.isArray(output?.entities) ? output.entities.filter(validEntity) : [];
+      const mapped = output?.slots ?? mapEntitiesToSlots(entities);
+      const checked = validateEventSlots(mapped);
+      if (!checked.ok) {
+        return { ok: false, language: route.language, reason: 'invalid-slots', errors: checked.errors, entities, slots: null };
+      }
+      return { ok: true, language: route.language, route, entities, slots: checked.slots };
+    },
+  };
+}

package/src/memory/extraction-pre-step.mjs

@@ -0,0 +1,161 @@
+/**
+ * Pre-step hook prototype for extraction.
+ * Not registered by index.mjs yet; registration is a separate, explicit switch.
+ */
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { userMessage } from '../threads.mjs';
+import { createExtractionProviderFromEnv } from './extraction-provider.mjs';
+import { attachStructuredExtraction } from './extraction-adapter.mjs';
+import { buildRecallIndex, findRecall, renderRecall } from './recall.mjs';
+
+const MACHINE_PREFIX = /^(?:Current runtime context|Current working directory|Current DSH file policy|Approval prompts|Time sampled|\[(?:抽取|工作线|标签|规则|习惯|技能|归位|候选|存\?|闸|回正|学习|追忆|记忆|continuity:[a-z-]+)\])/;
+
+function isHumanMessage(message, text) {
+  const source = message?.source ?? message?.data?.source;
+  if (source && typeof source.kind === 'string' && source.kind !== 'user') return false;
+  if (source && source.peer === true) return false;
+  if (MACHINE_PREFIX.test(text.trimStart())) return false;
+  return true;
+}
+
+function textOf(message) {
+  if (!message || message.role !== 'user') return '';
+  const content = message.content;
+  if (typeof content === 'string') return isHumanMessage(message, content) ? content : '';
+  if (!Array.isArray(content)) return '';
+  const text = content
+    .filter((part) => part?.type === 'text' && typeof part.text === 'string')
+    .map((part) => part.text)
+    .join('\n')
+    .trim();
+  return isHumanMessage(message, text) ? text : '';
+}
+
+export function lastUserText(messages = []) {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const text = textOf(messages[index]);
+    if (text) return text;
+  }
+  return '';
+}
+
+export function createExtractionPreStep({ provider = null, mode = 'off', prefix = '[抽取]', controller = null, recall = null } = {}) {
+  return async function extractionPreStep(payload, next) {
+    const decision = await next();
+    if (mode === 'off' || !provider || !decision || !Array.isArray(decision.messages)) return decision;
+    if (Number.isInteger(payload?.step) && payload.step !== 1) return decision;
+    const text = lastUserText(decision.messages);
+    if (!text) return decision;
+    let recallLine = null;
+    if (typeof recall === 'function') {
+      try {
+        recallLine = await recall({ text, agent: payload?.agent ?? null });
+      } catch {
+        recallLine = null;
+      }
+    }
+    const extraction = await provider.extract({ text });
+    if (!extraction?.ok) {
+      if (!recallLine) return { ...decision, extraction };
+      return {
+        ...decision,
+        messages: [...decision.messages, userMessage(recallLine)],
+        extraction,
+        recall: recallLine,
+      };
+    }
+    const data = extraction.data ?? {};
+    let attached = null;
+    if (controller) {
+      attached = attachStructuredExtraction(controller, {
+        text,
+        slots: data.slots ?? {},
+        srl: data.srl ?? null,
+        corefClusters: data.corefClusters ?? [],
+        entityLinks: data.entityLinks ?? [],
+      });
+      if (!attached.ok) return { ...decision, extraction, attached };
+    }
+    const slots = attached?.slots ?? data.slots ?? {};
+    const hasSignal = (slots.characters?.length ?? 0) > 0
+      || Boolean(slots.location)
+      || (slots.objects?.length ?? 0) > 0
+      || Boolean(slots.goal)
+      || Boolean(data.srl?.verb)
+      || (data.entityLinks?.length ?? 0) > 0;
+    if (!hasSignal) {
+      if (!recallLine) return { ...decision, extraction, gate: attached?.gate ?? null };
+      return {
+        ...decision,
+        messages: [...decision.messages, userMessage(recallLine)],
+        extraction,
+        recall: recallLine,
+        gate: attached?.gate ?? null,
+      };
+    }
+    const lines = [
+      `${prefix} ${data.lang ?? ''}`.trim(),
+      `characters: ${(slots.characters ?? []).join(', ') || '-'}`,
+      `location: ${slots.location ?? '-'}`,
+      `objects: ${(slots.objects ?? []).join(', ') || '-'}`,
+      `goal: ${slots.goal ?? '-'}`,
+    ];
+    if (data.srl?.verb) lines.push(`srl: ${data.srl.verb} (${data.srl.frame ?? '-'})`);
+    if (data.entityLinks?.length) lines.push(`links: ${data.entityLinks.map((link) => `${link.text}=${link.referent ?? link.entityId ?? link.id ?? 'NIL'}`).join(', ')}`);
+    if (recallLine) lines.push(recallLine);
+    return {
+      ...decision,
+      messages: [...decision.messages, userMessage(lines.join('\n'))],
+      extraction,
+      recall: recallLine,
+      gate: attached?.gate ?? null,
+    };
+  };
+}
+
+export function registerExtractionPreStep(ctx, options = {}) {
+  if (options.mode === 'off' || !options.provider) return false;
+  if (!ctx || typeof ctx.on !== 'function') return false;
+  ctx.on('agent/pre-step', createExtractionPreStep(options));
+  return true;
+}
+
+export function installExtractionPreStep(ctx, env = process.env, { sessionQuery = null } = {}) {
+  const mode = String(env.DSH_EXTRACTION_MODE ?? 'off').toLowerCase();
+  if (mode !== 'cache' && mode !== 'model') return { mode, registered: false, provider: null };
+  try {
+    const provider = createExtractionProviderFromEnv(env);
+    const recall = sessionQuery && typeof sessionQuery.readSession === 'function'
+      ? async ({ text, agent }) => {
+        const sessionId = agent?.session?.id;
+        if (sessionId === undefined || sessionId === null) return null;
+        const snapshot = await sessionQuery.readSession(sessionId);
+        const built = buildRecallIndex(snapshot?.events ?? [], {
+          beforeTurn: Number.isInteger(agent?.lastTurn) ? agent.lastTurn : Infinity,
+        });
+        const hits = findRecall(built, text, { topK: 1, minCoverage: 0.25 });
+        return hits.length > 0 ? renderRecall(hits[0], text) : null;
+      }
+      : null;
+    const registered = registerExtractionPreStep(ctx, { provider, mode, recall });
+    return { mode, registered, provider };
+  } catch (error) {
+    return { mode, registered: false, provider: null, error: error?.message ?? String(error) };
+  }
+}
+
+export function recordExtractionInstallError(error, { home = process.env.USERPROFILE ?? process.env.HOME ?? '', log = console } = {}) {
+  const message = String(error?.message ?? error);
+  try {
+    const file = join(home, '.dsh', 'continuity', 'gate-errors.jsonl');
+    mkdirSync(dirname(file), { recursive: true });
+    appendFileSync(file, JSON.stringify({
+      at: new Date().toISOString(),
+      name: error?.name ?? 'Error',
+      code: 'extraction-pre-step-register',
+      message,
+    }) + '\n', 'utf8');
+  } catch { /* best effort, same as the install catch */ }
+  log?.warn?.(`[dsh-continuity] extraction pre-step failed: ${message}`);
+}