dsh-trivium 0.4.21 → 0.5.0

package/lib/tool-defs.js

@@ -0,0 +1,93 @@
+/**
+ * The four tool definitions, kept as plain data with no @deepseek-ai imports.
+ *
+ * Two reasons this is a separate module:
+ * - the offline suite can serialise the exact registered projection and compare
+ *   it against docs/next-memory/TOOL_SCHEMA_BASELINE.json, and
+ * - the contract is "no new tools, no new model-facing parameters", which is
+ *   easier to audit when the surface is one frozen array.
+ *
+ * Source/history/supersede details are read through the management UI, never
+ * through new tool parameters.
+ */
+
+import { estimateTokens } from "./tokens.js";
+
+export const TOOL_DEFS = Object.freeze([
+  {
+    name: "ctx_find",
+    description:
+      "Search local Trivium graph memory by keywords, meaning (when embeddings are enabled), and entity relationships. Relevant expired decisions remain searchable, marked stale and ranked lower; treat them as historical, not current instructions. Set include_stale=false for current facts only. Returns L0 summaries and edge paths. Call ctx_read for full text.",
+    parameters: {
+      query: { type: "string", required: true, description: "Search query." },
+      top_k: { type: "integer", description: "Max hits, 1-20." },
+      include_stale: {
+        type: "boolean",
+        description: "Include relevant expired memories (default true). Expired hits are marked stale.",
+      },
+    },
+  },
+  {
+    name: "ctx_read",
+    description:
+      "Read one memory node by numeric id returned from ctx_find. Includes incoming about/decided/broke/fixed edges.",
+    parameters: {
+      id: { type: "integer", required: true, description: "Node id." },
+    },
+  },
+  {
+    name: "ctx_remember",
+    description:
+      "Store a durable fact as an entity, preference, decision, or experience. Do not store secrets or one-off task instructions.",
+    parameters: {
+      text: { type: "string", required: true, description: "Fact to store." },
+      type: {
+        type: "string",
+        description: "entity | preference | decision | experience",
+      },
+      name: { type: "string", description: "Short name for entities." },
+      until: {
+        type: "string",
+        description:
+          "Optional explicit expiry, only when the user states this fact expires: YYYY-MM-DD, weekday (Friday / 周五), or 下周. A date mentioned in the fact is not an expiry.",
+      },
+      link_to: { type: "integer", description: "Optional existing node id to link." },
+      link_label: { type: "string", description: "Edge label when link_to is set." },
+    },
+  },
+  {
+    name: "ctx_link",
+    description: "Create a directed edge between two memory node ids.",
+    parameters: {
+      from: { type: "integer", required: true, description: "Source node id." },
+      to: { type: "integer", required: true, description: "Target node id." },
+      label: { type: "string", description: "Edge label, default about." },
+    },
+  },
+]);
+
+/**
+ * Canonical name/description/parameters projection, in declaration order.
+ *
+ * This is the same shape as TOOL_SCHEMA_BASELINE.json: parameters is an object
+ * schema, and `required` collapses the per-parameter `required: true` flags.
+ * It is a relative size check, not the host wire format.
+ */
+export function schemaProjection(defs = TOOL_DEFS) {
+  return defs.map((def) => {
+    const properties = {};
+    const required = [];
+    for (const [key, spec] of Object.entries(def.parameters || {})) {
+      properties[key] = { type: spec.type, description: spec.description };
+      if (spec.required === true) required.push(key);
+    }
+    const parameters = { type: "object", properties };
+    if (required.length) parameters.required = required;
+    return { name: def.name, description: def.description, parameters };
+  });
+}
+
+/** Estimated tokens for the whole projection, using the plugin's own heuristic. */
+export function estimatedSchemaTokens(defs = TOOL_DEFS) {
+  return estimateTokens(JSON.stringify(schemaProjection(defs)));
+}

package/lib/tool-output.js

@@ -0,0 +1,88 @@
+/**
+ * Tool output budgets.
+ *
+ * `ctx_find` used to return whatever the search produced. Model context is the
+ * scarce resource, so the default output is now capped and whole records are
+ * dropped when they do not fit — never sliced, so an id is never half-written.
+ *
+ * All numbers are `estimateTokens` results (CJK ≈ 1, ASCII ≈ 1/4) and must be
+ * presented as estimates, not model tokens or billing.
+ */
+
+import { estimateTokens } from "./tokens.js";
+
+/** Default total for one ctx_find call, truncation notice included. */
+export const CTX_FIND_OUTPUT_BUDGET = 1200;
+
+/** Payload keys ctx_read may echo. New provenance/trace fields stay out. */
+export const CTX_READ_PAYLOAD_KEYS = Object.freeze([
+  "type",
+  "name",
+  "text",
+  "until",
+  "untilAt",
+  "status",
+  "uri",
+  "aliases",
+  "fail",
+  "fix",
+  "createdAt",
+  "updatedAt",
+]);
+
+/**
+ * Project a payload for tool output.
+ *
+ * The node payload also carries provenance, revision chains and other UI-only
+ * metadata. Serialising the payload wholesale made ctx_read grow every time a
+ * UI feature added a field, so the default projection is an explicit allowlist.
+ * `source` keeps only the session id it had before this change.
+ */
+export function projectPayloadForTool(payload) {
+  const out = {};
+  for (const key of CTX_READ_PAYLOAD_KEYS) {
+    const value = payload?.[key];
+    if (value === undefined || value === null || value === "") continue;
+    out[key] = value;
+  }
+  const sessionId = payload?.source?.sessionId;
+  if (sessionId) out.source = { sessionId: String(sessionId) };
+  return out;
+}
+
+function defaultNotice(omitted) {
+  return `… ${omitted} more hit(s) omitted to keep this result within ~${CTX_FIND_OUTPUT_BUDGET} estimated tokens. Narrow the query or raise top_k.`;
+}
+
+/**
+ * Keep whole blocks while the rendered result, notice included, fits the budget.
+ *
+ * @returns text, how many blocks were kept, how many were omitted, estimate.
+ */
+export function packTextBlocks(blocks, { budget = CTX_FIND_OUTPUT_BUDGET, separator = "\n\n", noticeFor = defaultNotice } = {}) {
+  const list = (blocks || []).filter((block) => typeof block === "string" && block.length > 0);
+  if (!list.length) return { text: "", kept: 0, omitted: 0, tokens: 0, budget, truncated: false };
+  const notice = (omitted) => (typeof noticeFor === "function" ? noticeFor(omitted) : defaultNotice(omitted));
+  const kept = [];
+  for (let i = 0; i < list.length; i += 1) {
+    const attempt = [...kept, list[i]];
+    const rest = list.length - attempt.length;
+    const text = rest > 0 ? [...attempt, notice(rest)].join(separator) : attempt.join(separator);
+    if (estimateTokens(text) <= budget) {
+      kept.push(list[i]);
+      continue;
+    }
+    const omitted = list.length - i;
+    const rendered = [...kept, notice(omitted)].join(separator);
+    return {
+      text: rendered,
+      kept: kept.length,
+      omitted,
+      tokens: estimateTokens(rendered),
+      budget,
+      truncated: true,
+    };
+  }
+  const text = kept.join(separator);
+  return { text, kept: kept.length, omitted: 0, tokens: estimateTokens(text), budget, truncated: false };
+}

package/lib/tools.js

@@ -1,6 +1,10 @@
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import { EDGE_LABELS } from "./schema.js";
 import { sanitizeForWrite, writeGateMessage } from "./hygiene.js";
+import { TOOL_DEFS } from "./tool-defs.js";
+import { makeRevisionResolver } from "./revisions.js";
+import { isStalePayload } from "./until.js";
+import { CTX_FIND_OUTPUT_BUDGET, packTextBlocks, projectPayloadForTool } from "./tool-output.js";
 import {
   dbPathFor,
   embedQueryVector,
@@ -36,6 +40,11 @@ function textTool(definition) {
   });
 }
 
+/** Definition lookup by name; the array order is the registration order. */
+function defOf(name) {
+  return TOOL_DEFS.find((def) => def.name === name);
+}
+
 export function cwdOf(agentOrExec) {
   const agent = agentOrExec?.agent ?? agentOrExec;
   return (
@@ -57,13 +66,7 @@ export function registerTools(ctx, optionsOrFn) {
     () =>
       ctx.tools.register(
         textTool({
-          name: "ctx_find",
-          description:
-            "Search local Trivium graph memory. If the query names a known entity, also returns its unexpired about/decided/broke/fixed neighbors. Returns L0 summaries plus edge paths (incoming as <-label-id). Call ctx_read for full text. Do not paste find results verbatim into later thinking.",
-          parameters: {
-            query: { type: "string", required: true, description: "Search query." },
-            top_k: { type: "integer", description: "Max hits, 1-20." },
-          },
+          ...defOf("ctx_find"),
           async execute(args, exec) {
             try {
               const options = optionsOf();
@@ -74,21 +77,51 @@ export function registerTools(ctx, optionsOrFn) {
                 topK: k,
                 expandDepth: options.expandDepth ?? 1,
                 queryVector: queryVector || undefined,
+                // `include_stale` stays a deadline-only switch: revision history
+                // is a separate axis and is never expanded by this flag.
+                includeStale: args.include_stale !== false,
               });
               if (!hits.length) return "No memory hits.";
-              const grouped = [];
-              let lastType = "";
+              /*
+               * A keyword hit on an old version is answered with the current
+               * head: mapped, de-duplicated, and carrying one short pointer so
+               * the model knows a newer decision exists. The old body stays
+               * readable through ctx_read(id).
+               */
+              const resolveCurrent = makeRevisionResolver(db);
+              const seen = new Set();
+              const candidates = [];
+              const mapped = new Map();
               for (const hit of hits) {
                 const row = formatHit(db, hit);
-                if (row.type !== lastType) {
-                  grouped.push(`## ${row.type}`);
-                  lastType = row.type;
+                const resolved = resolveCurrent(row.id);
+                if (!resolved) continue;
+                const targetId = Number(resolved.currentId);
+                if (targetId !== row.id) {
+                  // A superseded chain whose head is archived or expired is not
+                  // resurrected as its old version either.
+                  if (resolved.archived || resolved.stale) continue;
+                  mapped.set(targetId, { from: row.id, current: targetId });
                 }
-                grouped.push(
-                  `[${row.score.toFixed(3)}] id=${row.id} type=${row.type}${row.until ? ` until=${row.until}` : ""}${row.stale ? " stale" : ""}\n${row.l0}\npath: ${row.path.join(" | ") || "(none)"}`,
-                );
+                if (seen.has(targetId)) continue;
+                seen.add(targetId);
+                candidates.push({ row, targetId, matchedHistory: mapped.get(targetId) || null });
               }
-              return grouped.join("\n\n");
+              if (!candidates.length) return "No memory hits.";
+              const blocks = candidates.map(({ row, targetId, matchedHistory }) => {
+                const node = targetId === row.id ? null : db.get(targetId);
+                const payload = node?.payload || {};
+                const type = targetId === row.id ? row.type : payload.type || "unknown";
+                const body = targetId === row.id ? row.l0 : String(payload.text || payload.name || "").slice(0, 200);
+                const until = targetId === row.id ? row.until : payload.until || "";
+                const stale = targetId === row.id ? row.stale : isStalePayload(payload);
+                const pointer = matchedHistory
+                  ? `\nmatched_history=#${matchedHistory.from} → current=#${matchedHistory.current}`
+                  : "";
+                return `[${row.score.toFixed(3)}] id=${targetId} type=${type}${until ? ` until=${until}` : ""}${stale ? " stale" : ""}\n${body}\npath: ${row.path.slice(0, 2).join(" | ") || "(none)"}${pointer}`;
+              });
+              const packed = packTextBlocks(blocks, { budget: CTX_FIND_OUTPUT_BUDGET });
+              return packed.text;
             } catch (err) {
               return `ctx_find unavailable: ${err.message}`;
             }
@@ -102,20 +135,22 @@ export function registerTools(ctx, optionsOrFn) {
     () =>
       ctx.tools.register(
         textTool({
-          name: "ctx_read",
-          description: "Read one memory node by numeric id returned from ctx_find. Includes incoming about/decided/broke/fixed edges.",
-          parameters: {
-            id: { type: "integer", required: true, description: "Node id." },
-          },
+          ...defOf("ctx_read"),
           async execute(args, exec) {
             try {
               const db = await dbOf(exec);
               const node = db.get(Number(args.id));
               if (!node) return `Not found: ${args.id}`;
+              /*
+               * Explicit full read: the body is never truncated. Only the
+               * payload projection is narrowed, so provenance/revision metadata
+               * cannot grow this result. Sources and history are read from the
+               * management UI.
+               */
               return JSON.stringify(
                 {
                   id: node.id,
-                  payload: node.payload,
+                  payload: projectPayloadForTool(node.payload),
                   edges: node.edges,
                   incoming: listIncomingBusiness(db, node.id),
                 },
@@ -135,19 +170,7 @@ export function registerTools(ctx, optionsOrFn) {
     () =>
       ctx.tools.register(
         textTool({
-          name: "ctx_remember",
-          description:
-            "Store a durable fact as an entity, preference, decision, or experience. Do not store secrets or one-off task instructions.",
-          parameters: {
-            text: { type: "string", required: true, description: "Fact to store." },
-            type: {
-              type: "string",
-              description: "entity | preference | decision | experience",
-            },
-            name: { type: "string", description: "Short name for entities." },
-            link_to: { type: "integer", description: "Optional existing node id to link." },
-            link_label: { type: "string", description: "Edge label when link_to is set." },
-          },
+          ...defOf("ctx_remember"),
           async execute(args, exec) {
             try {
               const gate = sanitizeForWrite(args.text);
@@ -162,8 +185,12 @@ export function registerTools(ctx, optionsOrFn) {
                 type,
                 name: args.name || undefined,
                 text: args.text,
+                ...(args.until !== undefined ? { until: args.until } : {}),
                 uri: `ctx://${type}/${Date.now()}`,
-                source: { sessionId: String(exec?.agent?.session?.header?.id || exec?.agent?.id || "") },
+                source: {
+                  kind: "tool",
+                  sessionId: String(exec?.agent?.session?.header?.id || exec?.agent?.id || ""),
+                },
               };
               const existing = findMergeTarget(db, incoming);
               const id =
@@ -186,17 +213,16 @@ export function registerTools(ctx, optionsOrFn) {
     () =>
       ctx.tools.register(
         textTool({
-          name: "ctx_link",
-          description: "Create a directed edge between two memory node ids.",
-          parameters: {
-            from: { type: "integer", required: true, description: "Source node id." },
-            to: { type: "integer", required: true, description: "Target node id." },
-            label: { type: "string", description: "Edge label, default about." },
-          },
+          ...defOf("ctx_link"),
           async execute(args, exec) {
             try {
               const db = await dbOf(exec);
               const label = args.label || EDGE_LABELS.about;
+              // Revision relations are confirmed in the management UI only, so
+              // a model cannot invent a supersedes chain here.
+              const { refuseModelRevisionLabel } = await import("./revisions.js");
+              const refused = refuseModelRevisionLabel(label);
+              if (refused) return refused;
               ensureLink(db, Number(args.from), Number(args.to), label);
               return `Linked ${args.from} -[${label}]-> ${args.to}`;
             } catch (err) {

package/lib/turn-ledger.js

@@ -0,0 +1,184 @@
+/**
+ * Per-turn delivery ledger.
+ *
+ * The plugin can be asked to plan the same user turn several times (one per
+ * tool step). Without a ledger the same pins/recall text is injected again on
+ * every step. The ledger records what was actually accepted for this turn, so
+ * the second step sees "already delivered" instead of re-sending.
+ *
+ * Rules this file enforces:
+ * - A turn is identified by host ids only (see turnKeyOf); never by clock or text.
+ * - Only delivered records are recorded; budget-evicted ones are not.
+ * - A failed send leaves nothing behind, so the next attempt can retry.
+ * - Compaction clears the turn so necessary context can be rebuilt; a fork is a
+ *   different session id and therefore inherits nothing.
+ *
+ * State is in-memory by design: it describes this process's view of one turn.
+ */
+
+import { turnKeyOf } from "./context-budget.js";
+
+const sessions = new Map();
+
+function stateOf(sessionId) {
+  const key = String(sessionId || "");
+  let state = sessions.get(key);
+  if (!state) {
+    state = {
+      sessionId: key,
+      turnKey: "",
+      delivered: new Set(),
+      spent: 0,
+      mapText: "",
+      mapTurnKey: "",
+      corrections: [],
+      generation: 0,
+    };
+    sessions.set(key, state);
+  }
+  return state;
+}
+
+/**
+ * Start (or continue) a turn. A new turn key clears the delivered set and the
+ * spent counter; queued corrections survive because they are still pending.
+ */
+export function beginTurn(sessionId, turnKey) {
+  const state = stateOf(sessionId);
+  const key = String(turnKey || "");
+  if (state.turnKey !== key) {
+    state.turnKey = key;
+    state.delivered = new Set();
+    state.spent = 0;
+    state.mapText = "";
+    state.mapTurnKey = "";
+  }
+  return state;
+}
+
+export function deliveredOf(sessionId, turnKey) {
+  const state = beginTurn(sessionId, turnKey);
+  return state.delivered;
+}
+
+export function spentOf(sessionId, turnKey) {
+  return beginTurn(sessionId, turnKey).spent;
+}
+
+/** Budget still available in this turn (never negative). */
+export function remainingOf(sessionId, turnKey, budget) {
+  const cap = Math.max(0, Number(budget) || 0);
+  return Math.max(0, cap - spentOf(sessionId, turnKey));
+}
+
+/** Remember the map text when it landed in the same turn as the records. */
+export function noteMap(sessionId, turnKey, text) {
+  const state = beginTurn(sessionId, turnKey);
+  state.mapText = String(text || "");
+  state.mapTurnKey = String(turnKey || "");
+  return state;
+}
+
+export function mapTextOf(sessionId, turnKey) {
+  const state = beginTurn(sessionId, turnKey);
+  return state.mapTurnKey === String(turnKey || "") ? state.mapText : "";
+}
+
+/** Queue a correction (superseded/archived/expired after this turn's send). */
+export function queueCorrection(sessionId, correction) {
+  const state = stateOf(sessionId);
+  const id = Number(correction?.id);
+  if (!Number.isFinite(id)) return state.corrections;
+  if (state.corrections.some((c) => Number(c.id) === id && c.note === correction.note)) return state.corrections;
+  state.corrections.push({ ...correction, id, queuedAt: Date.now() });
+  if (state.corrections.length > 20) state.corrections = state.corrections.slice(-20);
+  return state.corrections;
+}
+
+export function pendingCorrections(sessionId) {
+  return [...stateOf(sessionId).corrections];
+}
+
+/**
+ * Reserve a delivery. The reservation is only a claim; call {@link commit} once
+ * the messages were handed to the host, or {@link rollback} if anything threw.
+ * `delivered` is deliberately untouched here, so a retry still sees its content.
+ */
+export function reserve(sessionId, turnKey, records = []) {
+  const state = beginTurn(sessionId, turnKey);
+  const list = (records || []).filter((r) => Number.isFinite(Number(r?.id)));
+  return {
+    sessionId: state.sessionId,
+    turnKey: state.turnKey,
+    generation: state.generation,
+    records: list.map((r) => ({
+      id: Number(r.id),
+      channel: r.channel || "recall",
+      fingerprint: String(r.fingerprint || ""),
+      tokens: Number(r.tokens) || 0,
+    })),
+    tokens: list.reduce((sum, r) => sum + (Number(r.tokens) || 0), 0),
+    committed: false,
+    rolledBack: false,
+  };
+}
+
+/** Mark the reservation delivered. Idempotent; ignores stale generations. */
+export function commit(reservation) {
+  if (!reservation || reservation.rolledBack) return reservation;
+  const state = stateOf(reservation.sessionId);
+  if (state.turnKey !== reservation.turnKey || state.generation !== reservation.generation) {
+    return reservation;
+  }
+  for (const record of reservation.records) {
+    if (record.fingerprint) state.delivered.add(record.fingerprint);
+    state.spent += record.tokens;
+  }
+  reservation.committed = true;
+  return reservation;
+}
+
+/** Undo an uncommitted reservation. Nothing was marked, so a retry re-sends. */
+export function rollback(reservation) {
+  if (!reservation || reservation.committed) return reservation;
+  reservation.rolledBack = true;
+  return reservation;
+}
+
+/**
+ * Compaction rebuild: drop this turn's delivered set and the spent counter so
+ * the next turn may re-establish necessary context, and bump the generation so
+ * an in-flight reservation cannot commit against the new state.
+ */
+export function clearAfterCompaction(sessionId) {
+  const state = stateOf(sessionId);
+  state.turnKey = "";
+  state.delivered = new Set();
+  state.spent = 0;
+  state.mapText = "";
+  state.mapTurnKey = "";
+  state.generation += 1;
+  return state;
+}
+
+export function clearSession(sessionId) {
+  sessions.delete(String(sessionId || ""));
+}
+
+export function snapshot(sessionId) {
+  const state = stateOf(sessionId);
+  return {
+    sessionId: state.sessionId,
+    turnKey: state.turnKey,
+    generation: state.generation,
+    delivered: [...state.delivered],
+    spent: state.spent,
+    corrections: state.corrections.map((c) => ({ ...c })),
+  };
+}
+
+export function resetAll() {
+  sessions.clear();
+}
+
+export { turnKeyOf };

package/lib/until.js

@@ -10,19 +10,7 @@ const WEEKDAYS = {
   saturday: 6,
 };
 
-/** Pull a display `until` label out of a fact sentence. */
-export function parseUntilFromText(text) {
-  const s = String(text || "");
-  if (/下周/.test(s)) return "下周";
-  const day = s.match(/\buntil\s+(Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday)\b/i);
-  if (day) return day[1];
-  const iso = s.match(/\b(\d{4}-\d{2}-\d{2})\b/);
-  if (iso) return iso[1];
-  const cn = s.match(/到?(\d{1,2}\s*月\d{1,2}\s*日|周五|周末)/);
-  if (cn) return cn[1];
-  return undefined;
-}
-
+// Only resolve an explicit expiry field. Dates mentioned in prose are not expiry.
 export function resolveUntilAt(until, from = new Date()) {
   const raw = String(until || "").trim();
   if (!raw) return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-trivium",
-  "version": "0.4.21",
+  "version": "0.5.0",
   "description": "In-process graph memory for DeepSeek Harness, backed by TriviumDB.",
   "license": "MIT",
   "type": "module",
@@ -48,6 +48,12 @@
     "smoke-p12": "node scripts/smoke-p12.mjs",
     "smoke-p13": "node scripts/smoke-p13.mjs",
     "smoke-p14": "node scripts/smoke-p14.mjs",
+    "smoke-p15": "node scripts/smoke-p15.mjs",
+    "smoke-p16": "node scripts/smoke-p16.mjs",
+    "smoke-p17": "node scripts/smoke-p17.mjs",
+    "smoke-p18": "node scripts/smoke-p18.mjs",
+    "smoke-p19": "node scripts/smoke-p19.mjs",
+    "smoke-p20": "node scripts/smoke-p20.mjs",
     "preuninstall": "node ./lib/purge.js",
     "verify-live-p2": "node scripts/verify-live-p2.mjs"
   },
@@ -55,11 +61,11 @@
     "node": "^22.19.0 || >=24"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-llm": ">=0.1.0-rc.8 <0.1.1 || >=0.1.1-rc.2 <0.3.0",
-    "@deepseek-ai/dsh-tools": ">=0.1.0-rc.8 <0.1.1 || >=0.1.1-rc.2 <0.3.0"
+    "@deepseek-ai/dsh-llm": ">=0.1.0-rc.8 <0.1.1 || >=0.1.1-rc.2 <0.3.0 || >=0.1.5-rc.1 <0.1.6 || >=0.2.0-rc.0 <0.2.1 || >=0.2.1-rc.0 <0.3.0",
+    "@deepseek-ai/dsh-tools": ">=0.1.0-rc.8 <0.1.1 || >=0.1.1-rc.2 <0.3.0 || >=0.1.5-rc.1 <0.1.6 || >=0.2.0-rc.0 <0.2.1 || >=0.2.1-rc.0 <0.3.0"
   },
   "dependencies": {
-    "triviumdb": "^0.8.9"
+    "triviumdb": "^0.8.11"
   },
   "keywords": [
     "dsh-plugin",