dsh-context-graph 0.6.2 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,210 @@
1
+ /**
2
+ * The indexing call: what the model reads (fixed rules, existing topics, the span) and how its
3
+ * answer is parsed. Pure.
4
+ */
5
+
6
+ import { RELATIONS } from './graph.js'
7
+ import { sliceChars } from './text.js'
8
+
9
+ /** A human prompt is read up to this many characters; assistant text is shortened further when a span is long (#46). */
10
+ export const USER_CAP = 2000
11
+ const ASSISTANT_CAPS = [2000, 800, 300]
12
+
13
+ /** `[m0 user] ...` transcript the builder reads; each message capped so one huge paste cannot eat the call. */
14
+ export function transcriptForBuilder(messages, { userCap = USER_CAP, assistantCap = USER_CAP } = {}) {
15
+ return messages.map((m, i) => {
16
+ const cap = m.role === 'user' ? userCap : assistantCap
17
+ const text = m.text.length > cap ? `${sliceChars(m.text, cap)}\n…[${m.text.length - cap} more chars]` : m.text
18
+ return `[m${i} ${m.role}]\n${text}`
19
+ }).join('\n\n')
20
+ }
21
+
22
+ /**
23
+ * The fixed part of every indexing prompt, byte for byte the same for every build of every chat, so
24
+ * it is the cached prefix of the call (#28). Anything that changes comes after it.
25
+ */
26
+ export const BUILDER_RULES = [
27
+ 'You index a conversation into a memory of topics that later chats search. Output ONE JSON object and nothing else:',
28
+ '{"summary":"...","nodes":[{"id":"n12"|null,"label":"...","gist":"...","aliases":["..."],"kind":"decision|fact|task|artifact|open-question","msgs":[0,2]}],"edges":[["n12","n3","uses"]]}',
29
+ '',
30
+ 'Rules:',
31
+ '- summary: one line of at most 12 words saying what the whole chat is about so far; update the current summary.',
32
+ '- One node per decision, fact, task, artifact (file, tool, repo) or open question worth remembering later. Skip chit-chat and anything an existing topic already says, unless it changed.',
33
+ '- label: at most 6 words, the name someone would search for. gist: one line under 120 characters, what is true now and why.',
34
+ '- aliases: other words a later message might use for it, including the other language when the chat mixes languages. Matching is by word overlap.',
35
+ '- msgs: the numbers N of the [mN] messages the node comes from, as integers (e.g. [0, 2]). Required, never empty.',
36
+ '- id: reuse an existing topic\'s id when the node is the same thing (and update its gist); null for a new node.',
37
+ `- edges: [from, to, relation] with relation in ${RELATIONS.join(', ')}. For a changed decision add [new, old, "supersedes"]. Name new nodes by their label in place of an id.`,
38
+ '- Keep file paths, commands, identifiers and numbers exact.',
39
+ '- If nothing is worth remembering, output {"summary":"...","nodes":[],"edges":[],"skip":true}.'
40
+ ].join('\n')
41
+
42
+ const idNumber = (id) => Number(/\d+/.exec(id)?.[0] ?? 0)
43
+
44
+ /**
45
+ * The whole indexing prompt, ordered from most to least stable (#28): the fixed rules, then the
46
+ * chat's existing topics in id order (new topics only ever append, so the previous build's list is a
47
+ * prefix of this one), then the current summary and the span, which change every time.
48
+ */
49
+ export function builderPrompt({ graph, summary, messages, assistantCap = USER_CAP }) {
50
+ const existing = Object.entries(graph.nodes)
51
+ .sort(([a], [b]) => idNumber(a) - idNumber(b))
52
+ .map(([id, n]) => `${id}: ${n.label}`)
53
+ .join('\n')
54
+ return [
55
+ BUILDER_RULES,
56
+ '',
57
+ existing ? `Existing topics:\n${existing}` : 'Existing topics: (none)',
58
+ '',
59
+ `Current summary: ${summary || '(none yet)'}`,
60
+ '',
61
+ 'Conversation to index:',
62
+ transcriptForBuilder(messages, { assistantCap }),
63
+ '',
64
+ 'Output the JSON object now.'
65
+ ].join('\n')
66
+ }
67
+
68
+ /** Complete top-level `{...}` objects inside the array that opens at `open`; an unfinished last one is dropped. */
69
+ function objectsInArray(text, open) {
70
+ const out = []
71
+ let depth = 0
72
+ let start = -1
73
+ let inString = false
74
+ for (let i = open + 1; i < text.length; i++) {
75
+ const ch = text[i]
76
+ if (inString) {
77
+ if (ch === '\\') i++
78
+ else if (ch === '"') inString = false
79
+ continue
80
+ }
81
+ if (ch === '"') inString = true
82
+ else if (ch === '{' || ch === '[') { if (depth++ === 0 && ch === '{') start = i }
83
+ else if (ch === '}' || ch === ']') {
84
+ if (depth === 0) break
85
+ if (--depth === 0 && ch === '}' && start >= 0) { out.push(text.slice(start, i + 1)); start = -1 }
86
+ }
87
+ }
88
+ return out
89
+ }
90
+
91
+ /**
92
+ * Message citations as integers: models write `[0, 2]`, but also `["m0", "m2"]` (the transcript
93
+ * labels messages `[m0 user]`) or `["1"]`. Anything else is dropped (#14).
94
+ */
95
+ const citations = (msgs) => (Array.isArray(msgs) ? msgs : [])
96
+ .map((i) => (typeof i === 'number' ? i : Number(String(i).trim().replace(/^m/i, ''))))
97
+ .filter((i) => Number.isInteger(i) && i >= 0)
98
+
99
+ /**
100
+ * One `"nodes": [` array: how many objects it holds (`raw`) and which are usable (complete, with a
101
+ * label and at least one citation).
102
+ */
103
+ function nodesAt(clean, open) {
104
+ const nodes = []
105
+ const objects = objectsInArray(clean, open)
106
+ for (const raw of objects) {
107
+ let node
108
+ try { node = JSON.parse(raw.replace(/,\s*([}\]])/g, '$1')) } catch { continue }
109
+ if (!node || typeof node.label !== 'string' || !node.label.trim()) continue
110
+ const msgs = citations(node.msgs)
111
+ if (msgs.length > 0) nodes.push({ ...node, msgs })
112
+ }
113
+ return { nodes, raw: objects.length }
114
+ }
115
+
116
+ /**
117
+ * Tolerant extraction of the builder's JSON. Handles code fences, prose around it, `<think>` blocks,
118
+ * trailing commas, and output cut off mid-way (every complete node object is kept). When the text
119
+ * holds several `"nodes"` arrays (a schema echoed back, a draft before the answer), the one with the
120
+ * most usable nodes wins, the later one on a tie (#14).
121
+ * `skip` means "nothing worth remembering": `"skip": true`, or every `"nodes"` array is empty. An
122
+ * array that holds objects none of which is usable (bad citations) is NOT a skip: that span is
123
+ * retried instead of being marked as indexed. `undefined` when there is no `"nodes"` array at all.
124
+ */
125
+ export function parseBuilderOutput(text) {
126
+ const clean = String(text ?? '').replace(/<think>[\s\S]*?(?:<\/think>|$)/g, '')
127
+ let best
128
+ let objects = 0
129
+ for (const match of clean.matchAll(/"nodes"\s*:\s*\[/g)) {
130
+ const open = match.index + match[0].length - 1
131
+ const found = nodesAt(clean, open)
132
+ objects += found.raw
133
+ if (!best || found.nodes.length >= best.nodes.length) best = { ...found, open }
134
+ }
135
+ if (!best) return undefined
136
+ const after = clean.slice(best.open)
137
+ // Edges normally follow the chosen nodes; a model that writes them first is still read.
138
+ const scope = after.search(/"edges"\s*:/) >= 0 ? after : clean
139
+ const edgesAt = scope.search(/"edges"\s*:/)
140
+ const edges = edgesAt < 0 ? [] : [...scope.slice(edgesAt).matchAll(/\[\s*"([^"]+)"\s*,\s*"([^"]+)"\s*,\s*"([^"]+)"\s*\]/g)].map((m) => [m[1], m[2], m[3]])
141
+ const skip = best.nodes.length === 0 && (/"skip"\s*:\s*true/.test(after) || objects === 0)
142
+ return { nodes: best.nodes, edges, skip, raw: best.raw, summary: summaryNear(clean, best.open) }
143
+ }
144
+
145
+ /**
146
+ * The chat summary of the chosen answer (#27): the last `"summary"` before its nodes (the shape puts
147
+ * it first), else the first one after them. The schema's own "..." placeholder does not count.
148
+ */
149
+ function summaryNear(clean, open) {
150
+ const all = [...clean.matchAll(/"summary"\s*:\s*("(?:[^"\\]|\\.)*")/g)]
151
+ const pick = all.filter((m) => m.index < open).at(-1) ?? all.find((m) => m.index > open)
152
+ if (!pick) return undefined
153
+ let text
154
+ try { text = JSON.parse(pick[1]) } catch { return undefined }
155
+ text = String(text).replace(/\s+/g, ' ').trim()
156
+ return text && !/^\.+$/.test(text) ? text.slice(0, 160) : undefined
157
+ }
158
+
159
+ /** The better of two parses (answer text and reasoning text): the one with more usable nodes. */
160
+ export function betterParse(a, b) {
161
+ if (!a) return b
162
+ if (!b) return a
163
+ if (b.nodes.length > a.nodes.length) return b
164
+ return a.nodes.length === 0 && !a.skip && b.skip ? b : a
165
+ }
166
+
167
+ /**
168
+ * What one build reads (#46). Every human prompt is read (up to USER_CAP characters); assistant
169
+ * text is shortened 2,000 -> 800 -> 300 characters until the span fits `maxChars`. A span that
170
+ * still does not fit is read in whole turns from the oldest, and the rest waits for the next build,
171
+ * so nothing is skipped; only a single turn too long on its own loses its oldest assistant steps.
172
+ * @returns { messages, assistantCap, rest } `rest` is the first message left for a later build, if any.
173
+ */
174
+ export function planSpan(messages, maxChars) {
175
+ const cost = (m, cap) => Math.min(m.text.length, m.role === 'user' ? USER_CAP : cap) + 20
176
+ const sum = (list, cap) => list.reduce((n, m) => n + cost(m, cap), 0)
177
+ for (const cap of ASSISTANT_CAPS) if (sum(messages, cap) <= maxChars) return { messages, assistantCap: cap, rest: undefined }
178
+ const cap = ASSISTANT_CAPS.at(-1)
179
+ const turns = []
180
+ for (const m of messages) {
181
+ if (turns.length === 0 || m.role === 'user') turns.push([])
182
+ turns.at(-1).push(m)
183
+ }
184
+ const picked = []
185
+ let used = 0
186
+ let next = 0
187
+ for (; next < turns.length; next++) {
188
+ const turn = turns[next]
189
+ const c = sum(turn, cap)
190
+ if (picked.length > 0 && used + c > maxChars) break
191
+ if (picked.length === 0 && c > maxChars) {
192
+ // One turn alone is too long: its prompts, then its newest assistant steps that fit.
193
+ const prompts = turn.filter((m) => m.role === 'user')
194
+ let room = maxChars - sum(prompts, cap)
195
+ const steps = []
196
+ for (const m of turn.filter((x) => x.role !== 'user').reverse()) {
197
+ if (cost(m, cap) > room) break
198
+ room -= cost(m, cap)
199
+ steps.unshift(m)
200
+ }
201
+ const keep = new Set([...prompts, ...steps])
202
+ picked.push(...turn.filter((m) => keep.has(m)))
203
+ next++
204
+ break
205
+ }
206
+ picked.push(...turn)
207
+ used += c
208
+ }
209
+ return { messages: picked, assistantCap: cap, rest: turns[next]?.[0] }
210
+ }
@@ -0,0 +1,34 @@
1
+ /**
2
+ * Chat-level protocol shared by every layer. Pure.
3
+ */
4
+
5
+ /** `source.kind` of every message this plugin adds to a chat, and the marker that opens its blocks. */
6
+ export const SOURCE_KIND = 'context-graph'
7
+
8
+ /** Memory is on in every chat unless `/context-graph off` was run there; the Plugins page switch turns the whole plugin off. */
9
+ export const memoryOn = (meta) => meta?.memoryOff !== true
10
+
11
+ /** Chats are shared with the rest of the workspace unless `/context-graph unshare` was run there. */
12
+ export const sharedOn = (meta) => meta?.private !== true
13
+
14
+ /**
15
+ * Where a chat's memory went off, or undefined while it is on: the point `off` recorded, else (off
16
+ * under 0.8.0, a meta recovered fail-closed, a fork that starts off) the chat's last index, so all
17
+ * of what came after counts as typed while off (#59).
18
+ */
19
+ export const offPoint = (meta) => (Number.isInteger(meta?.offSeq) ? meta.offSeq : memoryOn(meta) ? undefined : Number.isInteger(meta?.builtSeq) ? meta.builtSeq : -1)
20
+
21
+ /**
22
+ * Whether `seq` of a chat lies where its off stretches were lost: a meta recovered after damage
23
+ * (turnsClosed) cannot tell, up to where memory was turned on again (`closedThrough`, set by on).
24
+ */
25
+ /**
26
+ * The stretches a chat's log is read with as private: its gaps, and for a meta whose off stretches
27
+ * were lost (turnsClosed), everything up to where memory was turned on again, so a goal set in a
28
+ * lost stretch stays private when it is resumed (third check of #69).
29
+ */
30
+ export const walkGaps = (meta) => {
31
+ const gaps = Array.isArray(meta?.gaps) ? meta.gaps : []
32
+ return meta?.turnsClosed === true ? [[0, Number.isInteger(meta.closedThrough) ? meta.closedThrough : Infinity], ...gaps] : gaps
33
+ }
34
+ export const closedAt = (meta, seq) => meta?.turnsClosed === true && seq <= (Number.isInteger(meta.closedThrough) ? meta.closedThrough : Infinity)
@@ -0,0 +1,134 @@
1
+ /**
2
+ * One chat's topic graph and the operations on it. Pure.
3
+ *
4
+ * Graph (version 2): `{ version, nextId, nodes: { [id]: Node }, edges: [[from, to, relation], ...] }`.
5
+ * Node: `{ label, gist, aliases, kind, refs, at, updated }`:
6
+ * refs seqs of the chat's messages the topic was drawn from; their text is stored once per
7
+ * chat in msgs.json (src/store), never copied into the topic
8
+ * at when the topic was first written; `updated` when it last changed
9
+ * Ids inside a graph are `n12`; across chats they are prefixed by the chat's number: `c3n12`.
10
+ * Version 1 graphs (v0.1-v0.6) carried `src` provenance and per-topic source files; src/store
11
+ * upgrades them on first load.
12
+ */
13
+
14
+ import { sliceChars } from './text.js'
15
+
16
+ export const GRAPH_VERSION = 2
17
+ export const RELATIONS = ['uses', 'part-of', 'supersedes', 'caused-by', 'relates-to']
18
+ export const KINDS = ['decision', 'fact', 'task', 'artifact', 'open-question']
19
+
20
+ /** Caps on what the builder model may write, so one oversized answer cannot bloat every later block (#15). */
21
+ export const LIMITS = { label: 80, gist: 200, alias: 40, aliases: 12, refs: 16 }
22
+
23
+ /** Own-key check: graph.nodes is a plain object, so `nodes.constructor` must not count as a topic (#15). */
24
+ export const has = (graph, id) => typeof id === 'string' && Object.hasOwn(graph.nodes, id)
25
+
26
+ const clip = (value, max) => sliceChars(String(value ?? '').replace(/\s+/g, ' ').trim(), max)
27
+ const labelKey = (label) => clip(label, LIMITS.label).toLowerCase()
28
+
29
+ export function emptyGraph() {
30
+ return { version: GRAPH_VERSION, nextId: 1, nodes: {}, edges: [] }
31
+ }
32
+
33
+ /**
34
+ * Repair what an older version or a hand edit can leave behind: a missing or stale `nextId` (which
35
+ * would hand out an id already in use) and edges whose ends no longer exist.
36
+ */
37
+ export function normalizeGraph(graph) {
38
+ if (!graph || typeof graph.nodes !== 'object' || graph.nodes === null || Array.isArray(graph.nodes)) return emptyGraph()
39
+ let max = 0
40
+ for (const id of Object.keys(graph.nodes)) {
41
+ const n = /^n(\d+)$/.exec(id)
42
+ if (n) max = Math.max(max, Number(n[1]))
43
+ }
44
+ if (!Number.isInteger(graph.nextId) || graph.nextId <= max) graph.nextId = max + 1
45
+ graph.edges = (Array.isArray(graph.edges) ? graph.edges : [])
46
+ .filter((e) => Array.isArray(e) && e.length === 3 && has(graph, e[0]) && has(graph, e[1]) && RELATIONS.includes(e[2]))
47
+ return graph
48
+ }
49
+
50
+ export function degree(graph, id) {
51
+ let n = 0
52
+ for (const [a, b] of graph.edges) if (a === id || b === id) n++
53
+ return n
54
+ }
55
+
56
+ /** Edges touching `id`, oriented from its point of view. */
57
+ export function neighbors(graph, id) {
58
+ const out = []
59
+ for (const [a, b, relation] of graph.edges) {
60
+ if (a === id && has(graph, b)) out.push({ id: b, relation, direction: 'out' })
61
+ else if (b === id && has(graph, a)) out.push({ id: a, relation, direction: 'in' })
62
+ }
63
+ return out
64
+ }
65
+
66
+ /** Follow `supersedes` edges forward so a stale decision resolves to its replacement. */
67
+ export function resolveSuperseded(graph, id) {
68
+ const seen = new Set()
69
+ let current = id
70
+ while (!seen.has(current)) {
71
+ seen.add(current)
72
+ const next = graph.edges.find(([from, to, rel]) => rel === 'supersedes' && to === current && has(graph, from))
73
+ if (!next) return current
74
+ current = next[0]
75
+ }
76
+ return current
77
+ }
78
+
79
+ /** God nodes: most connected first, newest first among equals. */
80
+ export function surfaceNodes(graph, max = 40) {
81
+ return Object.keys(graph.nodes)
82
+ .map((id) => ({ id, d: degree(graph, id), u: graph.nodes[id].updated ?? '' }))
83
+ .sort((a, b) => b.d - a.d || b.u.localeCompare(a.u))
84
+ .slice(0, max)
85
+ .map(({ id }) => id)
86
+ }
87
+
88
+ /**
89
+ * Apply a builder delta. A topic is matched to an existing one by its id (only real `nN` ids of this
90
+ * graph) or by its label anywhere in the graph, else it gets the next id. The gist is replaced,
91
+ * aliases keep the newest ones first, and `refs` gains the seqs of the messages it cites
92
+ * (`refsOf(msgs)` maps the builder's message indices to seqs). Edges may name topics by id or by
93
+ * label, including labels of topics written by earlier builds (#15).
94
+ * @returns [{ id, isNew }] for every topic written.
95
+ */
96
+ export function mergeDelta(graph, delta, { now, refsOf = () => [] }) {
97
+ const byLabel = new Map()
98
+ for (const [id, node] of Object.entries(graph.nodes)) byLabel.set(labelKey(node.label), id)
99
+ // Only ids that existed before this answer are existing topics. An id the model invented to
100
+ // name a new topic (to link it) may equal one allocated a moment ago for another new topic,
101
+ // which would then be overwritten and given the wrong source (#61).
102
+ const before = new Set(Object.keys(graph.nodes))
103
+ const named = new Map()
104
+ const touched = []
105
+ for (const n of delta.nodes) {
106
+ const label = clip(n.label, LIMITS.label)
107
+ if (!label) continue
108
+ const given = typeof n.id === 'string' && /^n\d+$/.test(n.id) && before.has(n.id) ? n.id : undefined
109
+ const id = given ?? byLabel.get(labelKey(label)) ?? `n${graph.nextId++}`
110
+ const prev = has(graph, id) ? graph.nodes[id] : undefined
111
+ const aliases = [...new Set([...(Array.isArray(n.aliases) ? n.aliases : []), ...(prev?.aliases ?? [])].map((a) => clip(a, LIMITS.alias)).filter(Boolean))].slice(0, LIMITS.aliases)
112
+ const refs = [...new Set([...(prev?.refs ?? []), ...refsOf(n.msgs ?? [])])].filter(Number.isInteger).sort((a, b) => a - b).slice(-LIMITS.refs)
113
+ graph.nodes[id] = {
114
+ label,
115
+ gist: clip(n.gist ?? prev?.gist ?? '', LIMITS.gist),
116
+ aliases,
117
+ kind: KINDS.includes(n.kind) ? n.kind : prev?.kind ?? 'fact',
118
+ refs,
119
+ at: prev?.at ?? now,
120
+ updated: now
121
+ }
122
+ byLabel.set(labelKey(label), id)
123
+ if (typeof n.id === 'string' && n.id.trim()) named.set(n.id.trim(), id)
124
+ touched.push({ id, isNew: !prev })
125
+ }
126
+ const resolve = (ref) => named.get(String(ref).trim()) ?? (has(graph, ref) ? ref : byLabel.get(labelKey(ref)))
127
+ for (const [from, to, relation] of delta.edges) {
128
+ const a = resolve(from)
129
+ const b = resolve(to)
130
+ if (!a || !b || a === b || !RELATIONS.includes(relation)) continue
131
+ if (!graph.edges.some(([x, y, r]) => x === a && y === b && r === relation)) graph.edges.push([a, b, relation])
132
+ }
133
+ return touched
134
+ }
@@ -0,0 +1,14 @@
1
+ /**
2
+ * The pure core in one import (also exported as `dsh-context-graph/graph` for compatibility).
3
+ * Nothing under src/core does I/O or imports dsh, so all of it is testable with plain `node --test`.
4
+ */
5
+ export * from './text.js'
6
+ export * from './chat.js'
7
+ export * from './graph.js'
8
+ export * from './time.js'
9
+ export * from './match.js'
10
+ export * from './render.js'
11
+ export * from './builder.js'
12
+ export * from './session.js'
13
+ export * from './ledger.js'
14
+ export * from './tree.js'
@@ -0,0 +1,108 @@
1
+ /**
2
+ * What memory costs and what it saves, per chat (#35). Pure: the host feeds it what it sees, the
3
+ * store persists the counters, and this module turns them into an honest estimate.
4
+ *
5
+ * Counters of one chat (all tokens, the plugin's own estimate unless noted):
6
+ * sent blocks the plugin appended (topic lines, sources, the chat list, day digests), once
7
+ * resent the same blocks sent again as cached input with every later request of the chat
8
+ * tool the recall tool's definition, cached input on every request
9
+ * recalled recall results, once (they stay in context like a block: also in resent)
10
+ * indexIn / indexCached / indexOut the indexing calls for this chat, as dsh reported them
11
+ * stoodIn for each topic the chat USED, its newest cited messages (up to 3) as stored, each
12
+ * counted once per chat (one answer often gives several topics): what the user
13
+ * would otherwise have had to bring back into the chat (an estimate that errs low).
14
+ * What memory sent instead is the cost.
15
+ * used topics used, once each per chat
16
+ * Prices differ by kind, so the balance is in input-token equivalents: cached input and output are
17
+ * weighted (WEIGHTS), uncached input counts 1.
18
+ */
19
+
20
+ import { nodeTokens, wordsIn } from './match.js'
21
+ import { capText, estimateTokens, tokenize } from './text.js'
22
+
23
+ /** Price of a token relative to an uncached input token (DeepSeek: cache hits ~1/10, output ~4x). */
24
+ export const WEIGHTS = { cached: 0.1, output: 4 }
25
+
26
+ export const emptyCounters = () => ({ sent: 0, resent: 0, tool: 0, recalled: 0, indexIn: 0, indexCached: 0, indexOut: 0, stoodIn: 0, used: 0, requests: 0 })
27
+
28
+ const COUNTERS = Object.keys(emptyCounters())
29
+
30
+ /** Counters with every field present and numeric (a hand-edited or older ledger reads safely). */
31
+ export function counters(value) {
32
+ const out = emptyCounters()
33
+ for (const key of COUNTERS) {
34
+ const n = Number(value?.[key])
35
+ if (Number.isFinite(n) && n > 0) out[key] = n
36
+ }
37
+ return out
38
+ }
39
+
40
+ /** Element-wise sum, for workspace totals. */
41
+ export function addCounters(a, b) {
42
+ const out = emptyCounters()
43
+ for (const key of COUNTERS) out[key] = (a?.[key] ?? 0) + (b?.[key] ?? 0)
44
+ return out
45
+ }
46
+
47
+ /** What memory cost and what it stood in for, in input-token equivalents. */
48
+ export function balance(c, weights = WEIGHTS) {
49
+ const cost = c.sent + c.recalled + c.indexIn + weights.cached * (c.resent + c.tool + c.indexCached) + weights.output * c.indexOut
50
+ return { cost: Math.round(cost), saved: Math.round(c.stoodIn), net: Math.round(c.stoodIn - cost) }
51
+ }
52
+
53
+ const OMITTED = /…\[(\d+) chars omitted; the full turn is in the chat's dsh log\]…/
54
+
55
+ /**
56
+ * Tokens of a stored message as it is stored now: its head and tail. A source kept whole by an
57
+ * older version (migrated from v0.4-v0.6) counts as if it had been cut the same way (review).
58
+ */
59
+ export const storedTokens = (text) => estimateTokens(capText(text).replace(OMITTED, ''))
60
+
61
+ /**
62
+ * Whether an answer used a topic it was shown: it says two of the topic's words (label, aliases or
63
+ * gist) that the prompt did not bring, counted as matching counts words (one Chinese word once, an
64
+ * exact identifier of its label twice). The prompt's words count as already said, so an answer
65
+ * that only repeats the question does not count, nor does a new word written next to them twice
66
+ * (review of #35). Checked once per turn, off the critical path.
67
+ */
68
+ export function usedIn(answer, node, prompt = '') {
69
+ return wordsIn(answer, nodeTokens(node), tokenize(prompt)) >= 2
70
+ }
71
+
72
+ /**
73
+ * What a used topic stood in for, erring low: its newest `max` cited messages at their stored size,
74
+ * each counted once per chat (one answer often gives several topics). `credited` holds the
75
+ * `<cid>:<seq>` keys already counted; returns the tokens and the keys this topic adds.
76
+ */
77
+ export function standIn(node, stored, cid, credited, max = 3) {
78
+ const newest = [...new Set(node.refs ?? [])].sort((a, b) => b - a).slice(0, max)
79
+ const fresh = newest.filter((seq) => !credited.has(`${cid}:${seq}`))
80
+ return { tokens: fresh.reduce((n, seq) => n + storedTokens(stored[String(seq)]?.x), 0), keys: fresh.map((seq) => `${cid}:${seq}`) }
81
+ }
82
+
83
+ /** "about 8,600": rounded so a reader does not take the estimate for an exact count. */
84
+ export function approx(n) {
85
+ const abs = Math.abs(n)
86
+ const step = abs >= 100000 ? 1000 : abs >= 1000 ? 100 : 10
87
+ return (Math.sign(n) * Math.round(abs / step) * step).toLocaleString('en-US')
88
+ }
89
+
90
+ const nothing = (c) => Object.values(c).every((n) => n === 0)
91
+ const said = (n) => (n >= 0 ? `saved about ${approx(n)} tokens` : `cost about ${approx(-n)} tokens more than it saved`)
92
+
93
+ /** One line for the /context-graph card: what memory did for this chat and the workspace. */
94
+ export function savingsLine(chat, workspace) {
95
+ if (nothing(chat) && nothing(workspace)) return 'Savings: nothing measured yet'
96
+ const here = nothing(chat) ? 'nothing yet in this chat' : `${said(balance(chat).net)} in this chat`
97
+ return `Savings (estimate): ${here} · ${said(balance(workspace).net)} in this workspace`
98
+ }
99
+
100
+ /** The card's details: each term of the estimate, so the number can be checked. */
101
+ export function savingsDetail(c, weights = WEIGHTS) {
102
+ const { cost, saved } = balance(c, weights)
103
+ return [
104
+ `Estimate (input-token equivalents; cached input x${weights.cached}, output x${weights.output}):`,
105
+ `- stood in for: ${saved} (${c.used} topic${c.used === 1 ? '' : 's'} used: their newest messages as stored, each counted once)`,
106
+ `- memory cost: ${cost} = notes sent ${c.sent} + recalls ${c.recalled} + re-sent as cached ${c.resent} + recall tool ${c.tool} + indexing in ${c.indexIn} / cached ${c.indexCached} / out ${c.indexOut}`
107
+ ].join('\n')
108
+ }