dsh-context-graph 0.3.0 → 0.6.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.
package/index.js CHANGED
@@ -1,424 +1,413 @@
1
- /**
2
- * dsh-context-graph: memory of past conversations as a small graph, so the model reads node
3
- * gists instead of old messages and fetches verbatim text only when it needs it.
4
- *
5
- * - `agent/turn-stopping`: every few human turns, one cheap auxiliary model call indexes the new
6
- * span into `<workspace>/.context-graph/graph.json` and stores the cited messages verbatim.
7
- * - `agent/pre-step`: on a human turn, lexically match the prompt against the graph and append one
8
- * short `[context-graph]` block to the admitted messages (end of the request, so the provider's
9
- * prefix cache survives). The first human turn of a session also gets the cross-session surface layer.
10
- * - Tool `recall`: verbatim source and neighbours of one node.
11
- * - `llm/stream`: meters main vs builder tokens and cache reads for `/context-graph stats`.
12
- * Stock compaction is untouched.
13
- */
14
-
15
- import { isAbsolute, join } from 'node:path'
16
- import { readFileSync } from 'node:fs'
17
- import { mkdir, stat, writeFile } from 'node:fs/promises'
18
-
19
- import { BlockAssembler, createUserMessage } from '@deepseek-ai/dsh-llm'
20
- import { defineTool } from '@deepseek-ai/dsh-tools'
21
-
22
- import {
23
- builderInstruction, collectSpan, emptyGraph, estimateTokens, foldKept, matchNodes, mergeDelta, neighbors, onlyFromSession,
24
- parseBuilderOutput, planFold, renderFoldIndex, renderHits, renderSurface, SOURCE_KIND, surfaceNodes, transcriptForBuilder,
25
- turnIndex, turnTranscript
26
- } from './graph.js'
27
- import { appendSource, loadGraph, readSource, saveGraph } from './store.js'
28
- import { startUpdateCheck } from './update.js'
29
-
30
- export const name = 'context-graph'
31
- export const inject = ['tools']
32
-
33
- const PURPOSE = 'context-graph'
34
- const { version } = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'))
35
-
36
- const DEFAULTS = {
37
- dir: '.context-graph',
38
- buildEveryTurns: 4,
39
- buildMinChars: 400,
40
- maxHits: 5,
41
- inlineMaxChars: 1200,
42
- surfaceMaxNodes: 40,
43
- builderMaxTokens: 8192,
44
- provider: '',
45
- model: '',
46
- fold: true,
47
- foldAtTokens: 24000,
48
- keepTurns: 2
49
- }
50
-
51
- const textOf = (content) => (Array.isArray(content) ? content : []).filter((b) => b?.type === 'text').map((b) => b.text).join('\n').trim()
52
-
53
- export function apply(ctx, config = {}) {
54
- const { _updates, ...rest } = config
55
- const cfg = { ...DEFAULTS, ...rest }
56
- // `_updates` lets tests stand in for the network check.
57
- const updates = _updates ?? startUpdateCheck(version)
58
- let noticeShown = false
59
- const sessions = new Map()
60
- const graphCache = new Map()
61
- const meter = {
62
- main: { requests: 0, input: 0, cacheRead: 0, cacheWrite: 0, output: 0 },
63
- builder: { requests: 0, input: 0, cacheRead: 0, cacheWrite: 0, output: 0 },
64
- builds: 0,
65
- folds: 0,
66
- foldSaved: 0,
67
- injected: 0,
68
- injectedTokens: 0,
69
- recalls: 0
70
- }
71
-
72
- const state = (sid) => {
73
- let st = sessions.get(sid)
74
- if (!st) { st = { lastBuiltSeq: -1, building: false, surfaceSent: false }; sessions.set(sid, st) }
75
- return st
76
- }
77
-
78
- function dirFor(agent) {
79
- const base = agent.options?.cwd ?? agent.session.header?.cwd ?? process.cwd()
80
- return isAbsolute(cfg.dir) ? cfg.dir : join(base, cfg.dir)
81
- }
82
-
83
- /** Graph read with an mtime check so other sessions' builds show up without a restart. */
84
- async function getGraph(dir) {
85
- let mtimeMs = 0
86
- try { mtimeMs = (await stat(join(dir, 'graph.json'))).mtimeMs } catch { return emptyGraph() }
87
- const cached = graphCache.get(dir)
88
- if (cached && cached.mtimeMs === mtimeMs) return cached.graph
89
- const graph = await loadGraph(dir)
90
- graphCache.set(dir, { mtimeMs, graph })
91
- return graph
92
- }
93
-
94
- function resolveTarget(agent) {
95
- if (cfg.provider && cfg.model) return { provider: cfg.provider, model: cfg.model }
96
- const routed = agent.session.requestHeader()?.config
97
- if (routed?.provider && routed?.model) return { provider: routed.provider, model: routed.model }
98
- const { provider, model } = agent.options ?? {}
99
- return provider && model ? { provider, model } : undefined
100
- }
101
-
102
- function surfaceAlreadyOnLog(session) {
103
- return session.surface.nodes.some((seq) => {
104
- const event = session.eventAt(seq)
105
- return event?.type === 'user/message' && event.data?.source?.kind === SOURCE_KIND && event.data.source.layer === 'surface'
106
- })
107
- }
108
-
109
- // ---------- builder ----------
110
- const isSubagent = (agent) => agent.options?.origin === 'subagent' || agent.session.header?.origin === 'subagent'
111
-
112
- async function build(agent, { force = false, turn = null } = {}) {
113
- const session = agent.session
114
- const sid = String(session.id)
115
- const st = state(sid)
116
- if (st.building) return { status: 'busy' }
117
- // ponytail: subagent chatter stays out of the project graph; revisit if delegated work holds decisions worth keeping.
118
- if (isSubagent(agent)) return { status: 'skipped', reason: 'subagent session' }
119
- st.building = true
120
- try {
121
- const span = collectSpan(session.surface.nodes, (seq) => session.eventAt(seq), st.lastBuiltSeq)
122
- const chars = span.messages.reduce((n, m) => n + m.text.length, 0)
123
- if (span.messages.length === 0) return { status: 'nothing', reason: 'no new messages since the last build' }
124
- if (!force && (span.userTurns < cfg.buildEveryTurns || chars < cfg.buildMinChars)) {
125
- return { status: 'skipped', reason: `${span.userTurns}/${cfg.buildEveryTurns} human turns, ${chars}/${cfg.buildMinChars} chars` }
126
- }
127
- const llm = ctx.get('llm')
128
- if (!llm) return { status: 'unavailable', reason: 'no llm service in this composition' }
129
- const target = resolveTarget(agent)
130
- if (!target) return { status: 'unavailable', reason: 'no provider/model routed yet' }
131
- const dir = dirFor(agent)
132
- const graph = await loadGraph(dir)
133
- const prompt = `${transcriptForBuilder(span.messages)}\n\n${builderInstruction(graph)}`
134
- const assembler = new BlockAssembler()
135
- for await (const chunk of llm.stream({
136
- provider: target.provider,
137
- model: target.model,
138
- messages: [{ role: 'user', content: [{ type: 'text', text: prompt }] }],
139
- maxTokens: cfg.builderMaxTokens,
140
- sessionId: session.id,
141
- purpose: PURPOSE
142
- })) assembler.push(chunk)
143
- const finish = assembler.finish
144
- if (finish?.kind === 'error' || finish?.kind === 'aborted') throw new Error(finish.failure?.message ?? finish.kind)
145
- const blocks = assembler.blocks()
146
- const answer = textOf(blocks)
147
- // Some thinking models put everything, JSON included, into reasoning blocks.
148
- const reasoning = blocks.filter((b) => b?.type === 'reasoning').map((b) => b.text).join('\n')
149
- const delta = parseBuilderOutput(answer) ?? parseBuilderOutput(reasoning)
150
- if (!delta || (delta.nodes.length === 0 && finish?.kind === 'max-tokens')) {
151
- const saved = join(dir, 'last-builder-output.txt')
152
- await mkdir(dir, { recursive: true })
153
- await writeFile(saved, `finish: ${finish?.kind}\n\n--- answer ---\n${answer}\n\n--- reasoning ---\n${reasoning}\n`, 'utf8')
154
- const why = finish?.kind === 'max-tokens'
155
- ? `the model ran out of output tokens (builderMaxTokens ${cfg.builderMaxTokens}) before finishing`
156
- : 'builder output was not the expected JSON'
157
- return { status: 'failed', reason: `${why}; raw output saved to ${saved}` }
158
- }
159
- // Reversibility rule: a node is written only when it cites text we can store verbatim.
160
- delta.nodes = delta.nodes.filter((n) => n.msgs.some((i) => span.messages[i]))
161
- const now = new Date().toISOString()
162
- const touched = mergeDelta(graph, delta, { session: sid, turn, now })
163
- for (const { id, msgs } of touched) {
164
- const cited = msgs.map((i) => span.messages[i]).filter(Boolean)
165
- if (cited.length > 0) await appendSource(dir, id, { session: sid, turn, at: now, messages: cited })
166
- }
167
- await saveGraph(dir, graph)
168
- st.lastBuiltSeq = span.lastSeq
169
- meter.builds++
170
- return { status: 'built', nodes: touched.length, newNodes: touched.filter((t) => t.isNew).length, totalNodes: Object.keys(graph.nodes).length, edges: graph.edges.length, dir }
171
- } catch (error) {
172
- console.error('context-graph: build failed (non-fatal)', error)
173
- return { status: 'failed', reason: String(error?.message ?? error) }
174
- } finally {
175
- st.building = false
176
- }
177
- }
178
-
179
- ctx.on('agent/turn-stopping', (payload) => {
180
- // Fire and forget: the build must never delay the turn's close.
181
- void build(payload.agent, { turn: payload.turn })
182
- })
183
-
184
- // ---------- fold: replace old turns of this chat with a table of contents ----------
185
- function rangeTokens(session, seqs) {
186
- const wanted = new Set(seqs)
187
- try {
188
- const nodes = ctx.get('tokenMeter')?.measure(session)?.nodes
189
- if (Array.isArray(nodes)) return nodes.filter((n) => wanted.has(n.seq)).reduce((sum, n) => sum + (n.tokens ?? n.heuristicTokens ?? 0), 0)
190
- } catch { /* fall back to the estimate */ }
191
- return seqs.reduce((sum, seq) => sum + estimateTokens(JSON.stringify(session.eventAt(seq)?.data ?? '')), 0)
192
- }
193
-
194
- async function fold(agent, { force = false } = {}) {
195
- const session = agent.session
196
- const sid = String(session.id)
197
- const eventAt = (seq) => session.eventAt(seq)
198
- const plan = planFold(session.surface.nodes, eventAt, { keepTurns: cfg.keepTurns, maxSeq: state(sid).lastBuiltSeq })
199
- if (!plan) return { status: 'skipped', reason: `nothing indexed outside the last ${cfg.keepTurns} turns yet` }
200
- const before = rangeTokens(session, plan.shadowedSeqs)
201
- if (!force && before < cfg.foldAtTokens) return { status: 'skipped', reason: `foldable part is ~${before} tokens, folds at ${cfg.foldAtTokens}` }
202
- const turns = turnIndex(eventAt, plan.endSeq)
203
- const index = renderFoldIndex(await getGraph(dirFor(agent)), sid, turns, { maxNodes: cfg.surfaceMaxNodes })
204
- const kept = foldKept(plan.shadowedSeqs, eventAt)
205
- const after = estimateTokens([index, ...kept.blocks.map((b) => b.text ?? '')].join('\n'))
206
- // Never-worse gate: a fold must at least halve what it replaces, or it is not worth breaking the cache.
207
- if (after * 2 > before) return { status: 'skipped', reason: `table of contents (~${after}) is not under half of the ~${before} tokens it would replace` }
208
- const message = createUserMessage({
209
- content: [{ type: 'text', text: index }, ...kept.blocks],
210
- source: { kind: SOURCE_KIND, fold: true, keptKinds: kept.kinds, foldedTurns: turns.length, foldedTokens: before }
211
- })
212
- session.append('user/message', message, {
213
- surfaceOp: { op: 'replace', startSeq: plan.startSeq, endSeq: plan.endSeq },
214
- sourceEventSeqs: [...plan.shadowedSeqs]
215
- })
216
- meter.folds++
217
- meter.foldSaved += before - after
218
- return { status: 'folded', turns: turns.length, before, after }
219
- }
220
-
221
- // ---------- matcher ----------
222
- ctx.on('agent/pre-step', async (payload, next) => {
223
- const agent = payload.agent
224
- const prompt = payload.messages.filter((m) => m.source?.kind === 'user').map((m) => textOf(m.content)).join('\n')
225
- // Fold only at the start of a human turn: the previous turn is closed, so no tool call is open.
226
- if (cfg.fold && prompt && !isSubagent(agent)) {
227
- try { await fold(agent) } catch (error) { console.error('context-graph: fold failed (non-fatal)', error) }
228
- }
229
- const decision = await next()
230
- if (decision.kind !== 'enter') return decision
231
- const result = await addMemory(agent, prompt, decision)
232
- return prompt && !isSubagent(agent) ? addUpdateNotice(result) : result
233
- })
234
-
235
- /** Once per app start, ask the model to pass an available update on to the user. */
236
- function addUpdateNotice(decision) {
237
- const notice = updates.current()
238
- if (!notice || noticeShown) return decision
239
- noticeShown = true
240
- const message = createUserMessage({
241
- content: [{ type: 'text', text: `[${SOURCE_KIND}] ${notice} At the end of your reply, tell the user this in one short line.` }],
242
- source: { kind: SOURCE_KIND, notice: true }
243
- })
244
- return { ...decision, messages: [...decision.messages, message] }
245
- }
246
-
247
- async function addMemory(agent, prompt, decision) {
248
- try {
249
- if (isSubagent(agent) || !prompt) return decision
250
- const dir = dirFor(agent)
251
- const graph = await getGraph(dir)
252
- if (Object.keys(graph.nodes).length === 0) return decision
253
- const sid = String(agent.session.id)
254
- const st = state(sid)
255
- const sessionCompacted = agent.session.surface.replaceGeneration > 0
256
- const parts = []
257
- let layer
258
- if (!st.surfaceSent) {
259
- st.surfaceSent = true
260
- // Nodes that only come from this very session are still in its context: no need to repeat them.
261
- const ids = surfaceNodes(graph, cfg.surfaceMaxNodes).filter((id) => sessionCompacted || !onlyFromSession(graph.nodes[id], sid))
262
- if (ids.length > 0 && !surfaceAlreadyOnLog(agent.session)) {
263
- parts.push(renderSurface(graph, ids))
264
- layer = 'surface'
265
- }
266
- }
267
- const hits = matchNodes(graph, prompt, { max: cfg.maxHits, session: sid, sessionCompacted })
268
- let inline
269
- if (hits.length === 1 || (hits.length > 1 && hits[0].score >= 2 * hits[1].score)) {
270
- const text = await readSource(dir, hits[0].id)
271
- if (text && text.length <= cfg.inlineMaxChars) inline = { id: hits[0].id, text }
272
- }
273
- const block = renderHits(graph, hits, { inline })
274
- if (block) parts.push(block)
275
- if (parts.length === 0) return decision
276
- const text = parts.join('\n\n')
277
- meter.injected++
278
- meter.injectedTokens += estimateTokens(text)
279
- const message = createUserMessage({ content: [{ type: 'text', text }], source: layer ? { kind: SOURCE_KIND, layer } : { kind: SOURCE_KIND } })
280
- return { ...decision, messages: [...decision.messages, message] }
281
- } catch (error) {
282
- console.error('context-graph: matcher failed (non-fatal)', error)
283
- return decision
284
- }
285
- }
286
-
287
- // ---------- meter ----------
288
- ctx.on('llm/stream', (options, next) => {
289
- const inner = next()
290
- const bucket = options.purpose === PURPOSE ? meter.builder : meter.main
291
- async function* tracked() {
292
- try {
293
- for await (const chunk of inner) {
294
- if (chunk?.type === 'usage' && chunk.usage) {
295
- bucket.input += chunk.usage.inputTokens ?? 0
296
- bucket.cacheRead += chunk.usage.cacheReadTokens ?? 0
297
- bucket.cacheWrite += chunk.usage.cacheWriteTokens ?? 0
298
- bucket.output += chunk.usage.outputTokens ?? 0
299
- }
300
- yield chunk
301
- }
302
- } finally {
303
- bucket.requests++
304
- }
305
- }
306
- return tracked()
307
- })
308
-
309
- // ---------- recall tool ----------
310
- ctx.tools.register(defineTool({
311
- name: 'recall',
312
- description: [
313
- 'Fetch verbatim text behind an id shown in a [context-graph] block: a topic id (n17) returns its source messages and neighbouring topics; a turn id (t7) returns that folded turn of this conversation exactly.',
314
- 'Call it when a gist is relevant but not precise enough to answer. Never invent an id; only use ids you were shown.'
315
- ].join(' '),
316
- parameters: {
317
- id: { type: 'string', required: true, description: 'Topic id such as n17, or turn id such as t7.' },
318
- depth: { type: 'integer', description: '0 (default): this node only. 1: also include each neighbour\'s gist.' }
319
- },
320
- output: {
321
- schema: {
322
- type: 'object',
323
- additionalProperties: false,
324
- properties: {
325
- status: { type: 'string', enum: ['ok', 'unknown'], required: true },
326
- text: { type: 'string', required: true }
327
- }
328
- },
329
- render: (_args, value) => [{ type: 'text', text: value.text }]
330
- },
331
- async execute(args, exec) {
332
- const agent = exec.agent
333
- if (!agent?.session) return { status: 'unknown', text: 'recall is unavailable: no session attached to this call.' }
334
- const id = String(args.id ?? '').trim()
335
- const turn = /^t(\d+)$/.exec(id)
336
- if (turn) {
337
- const text = turnTranscript((seq) => agent.session.eventAt(seq), Number(turn[1]))
338
- if (text === undefined) return { status: 'unknown', text: `No turn ${id} in this conversation.` }
339
- meter.recalls++
340
- return { status: 'ok', text: `# ${id} (verbatim)\n\n${text}` }
341
- }
342
- const dir = dirFor(agent)
343
- const graph = await getGraph(dir)
344
- const node = graph.nodes[id]
345
- if (!node) return { status: 'unknown', text: `No node "${id}" in this project's context graph. Only use ids shown in a [context-graph] block.` }
346
- meter.recalls++
347
- node.hits = (node.hits ?? 0) + 1
348
- saveGraph(dir, graph).catch((error) => console.error('context-graph: hit count save failed', error))
349
- const lines = [`# ${id} ${node.label}`, `${node.kind}. ${node.gist}`, '']
350
- const source = await readSource(dir, id)
351
- lines.push(source ? source.trim() : '(no verbatim source stored for this node)')
352
- const links = neighbors(graph, id)
353
- if (links.length > 0) {
354
- lines.push('', 'Neighbours:')
355
- for (const link of links) {
356
- const other = graph.nodes[link.id]
357
- const arrow = link.direction === 'out' ? `${id} ${link.relation} ${link.id}` : `${link.id} ${link.relation} ${id}`
358
- lines.push(`- ${arrow}: ${other.label}${args.depth >= 1 ? ` — ${other.gist}` : ''}`)
359
- }
360
- }
361
- return { status: 'ok', text: lines.join('\n') }
362
- }
363
- }))
364
-
365
- // ---------- /context-graph command (nested: only where a human-command surface exists) ----------
366
- ctx.plugin({
367
- name: 'context-graph-command',
368
- inject: ['commands'],
369
- apply(cmdCtx) {
370
- cmdCtx.effect(function* () {
371
- yield cmdCtx.commands.register({
372
- name: 'context-graph',
373
- description: 'Project memory graph: /context-graph [stats|build|fold|find <words>]',
374
- // Without `input`, dsh clients run the bare name and send any typed arguments to the model as chat.
375
- input: { hint: '[stats|build|fold|find <words>]' },
376
- async handler(invocation) {
377
- const [sub = 'stats', ...rest] = invocation.rawInput.trim().split(/\s+/).filter(Boolean)
378
- const agent = invocation.agent
379
- if (sub === 'fold') {
380
- const result = await agent.runMaintenance(async () => {
381
- await build(agent, { force: true })
382
- return fold(agent, { force: true })
383
- })
384
- if (result.status !== 'folded') return { kind: 'error', text: `Not folded: ${result.reason}` }
385
- return { kind: 'success', text: `Folded t1-t${result.turns} · ~${result.before} → ~${result.after} tokens per request
386
- }
387
- if (sub === 'build') {
388
- const result = await agent.runMaintenance(() => build(agent, { force: true }))
389
- if (result.status !== 'built') return { kind: 'error', text: `Build ${result.status}: ${result.reason ?? ''}`.trim() }
390
- return { kind: 'success', text: `${result.nodes} topics indexed (${result.newNodes} new) · graph has ${result.totalNodes} topics\nLinks: ${result.edges}\nFolder: ${result.dir}` }
391
- }
392
- const graph = await getGraph(dirFor(agent))
393
- if (sub === 'find') {
394
- const hits = matchNodes(graph, rest.join(' '), { max: cfg.maxHits })
395
- if (hits.length === 0) return { kind: 'success', text: 'No matching topics' }
396
- const lines = hits.map(({ id, node }) => `${id} ${node.label}: ${node.gist}`)
397
- return { kind: 'success', text: [`${hits.length} matching ${hits.length === 1 ? 'topic' : 'topics'}`, ...lines].join('\n') }
398
- }
399
- if (sub !== 'stats') return { kind: 'error', text: 'Usage: /context-graph [stats|build|fold|find <words>]' }
400
- const m = meter.main
401
- const cached = m.cacheRead + m.cacheWrite
402
- const hitRate = m.input + cached > 0 ? Math.round((m.cacheRead / (m.input + cached)) * 100) : 0
403
- const session = agent.session
404
- const pending = collectSpan(session.surface.nodes, (seq) => session.eventAt(seq), state(String(session.id)).lastBuiltSeq).userTurns
405
- return {
406
- kind: 'success',
407
- text: [
408
- `${Object.keys(graph.nodes).length} topics · ${graph.edges.length} links · ${pending} turns waiting to be indexed${updates.current() ? ' · update available' : ''}`,
409
- `Version ${version}: ${updates.current() ?? 'no newer version found'}`,
410
- `Graph folder: ${dirFor(agent)}`,
411
- `This chat indexes itself every ${cfg.buildEveryTurns} turns; /context-graph build indexes it now.`,
412
- 'Counters below are since the app started:',
413
- `Builds: ${meter.builds}; builder tokens in/out: ${meter.builder.input + meter.builder.cacheRead + meter.builder.cacheWrite}/${meter.builder.output}`,
414
- `Folds: ${meter.folds}; ~${meter.foldSaved} input tokens removed from every later request`,
415
- `Injected blocks: ${meter.injected} (~${meter.injectedTokens} tokens); recalls: ${meter.recalls}`,
416
- `Main requests: ${m.requests}; input ${m.input} uncached + ${m.cacheRead} cache-read + ${m.cacheWrite} cache-write; cache-hit ${hitRate}%`
417
- ].join('\n')
418
- }
419
- }
420
- })
421
- }, 'context-graph command')
422
- }
423
- })
424
- }
1
+ /**
2
+ * dsh-context-graph: memory of past chats as small per-chat graphs.
3
+ *
4
+ * On in every chat by default. `/context-graph off` stops one chat; switching the plugin off on
5
+ * dsh's Plugins page stops all of them. While on:
6
+ * - `agent/turn-stopping`: every few human turns, one auxiliary model call indexes the new span
7
+ * into `<workspace>/.context-graph/chats/<session>/graph.json` and stores the cited text verbatim.
8
+ * - `agent/pre-step`: on a human turn, match the prompt against the other shared chats (all chats unless unshared) of this
9
+ * workspace (a named day is searched first) and append one short `[context-graph]` block at the
10
+ * end of the request, so the provider's prefix cache survives. On a chat's first message, one block lists
11
+ * the shared chats, newest first.
12
+ * - Tool `recall`: a topic (c3n12), a chat (c3), a day (2026-11-01) or a turn of this chat (t7).
13
+ * - `llm/stream`: meters main vs builder tokens and cache reads for `/context-graph stats`.
14
+ * Nothing is merged between chats; sharing is a flag on the chat. Stock compaction is untouched.
15
+ */
16
+
17
+ import { isAbsolute, join } from 'node:path'
18
+ import { readFileSync } from 'node:fs'
19
+ import { mkdir, writeFile } from 'node:fs/promises'
20
+
21
+ import { BlockAssembler, createUserMessage } from '@deepseek-ai/dsh-llm'
22
+ import { defineTool } from '@deepseek-ai/dsh-tools'
23
+
24
+ import {
25
+ builderInstruction, collectSpan, estimateTokens, matchAcross, memoryOn, mergeDelta, sharedOn, neighbors, parseBuilderOutput, parseTimeRange,
26
+ renderChatIndex, renderChats, renderHits, renderMap, renderRange, SOURCE_KIND, titleOf, transcriptForBuilder, turnTranscript
27
+ } from './graph.js'
28
+ import { appendSource, chatDir, ensureMeta, listChats, loadGraph, loadMeta, readSource, saveGraph, saveMeta } from './store.js'
29
+ import { startUpdateCheck } from './update.js'
30
+
31
+ export const name = 'context-graph'
32
+ export const inject = ['tools']
33
+
34
+ const PURPOSE = 'context-graph'
35
+ const USAGE = '[on|off|share|unshare|stats|build|map|find <words>]'
36
+ const { version } = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'))
37
+
38
+ const DEFAULTS = {
39
+ dir: '.context-graph',
40
+ buildEveryTurns: 4,
41
+ buildMinChars: 400,
42
+ maxHits: 5,
43
+ inlineMaxChars: 1200,
44
+ surfaceMaxChats: 20,
45
+ builderMaxTokens: 8192,
46
+ provider: '',
47
+ model: ''
48
+ }
49
+
50
+ const textOf = (content) => (Array.isArray(content) ? content : []).filter((b) => b?.type === 'text').map((b) => b.text).join('\n').trim()
51
+
52
+ export function apply(ctx, config = {}) {
53
+ const { _updates, ...rest } = config
54
+ const cfg = { ...DEFAULTS, ...rest }
55
+ // `_updates` lets tests stand in for the network check.
56
+ const updates = _updates ?? startUpdateCheck(version)
57
+ let noticeShown = false
58
+ const sessions = new Map()
59
+ const meter = {
60
+ main: { requests: 0, input: 0, cacheRead: 0, cacheWrite: 0, output: 0 },
61
+ builder: { requests: 0, input: 0, cacheRead: 0, cacheWrite: 0, output: 0 },
62
+ builds: 0,
63
+ injected: 0,
64
+ injectedTokens: 0,
65
+ recalls: 0
66
+ }
67
+
68
+ const state = (sid) => {
69
+ let st = sessions.get(sid)
70
+ if (!st) { st = { lastBuiltSeq: -1, building: false, announce: true }; sessions.set(sid, st) }
71
+ return st
72
+ }
73
+
74
+ const sidOf = (agent) => String(agent.session.id)
75
+ const isSubagent = (agent) => agent.options?.origin === 'subagent' || agent.session.header?.origin === 'subagent'
76
+
77
+ function dirFor(agent) {
78
+ const base = agent.options?.cwd ?? agent.session.header?.cwd ?? process.cwd()
79
+ return isAbsolute(cfg.dir) ? cfg.dir : join(base, cfg.dir)
80
+ }
81
+
82
+ const metaFor = (agent) => loadMeta(dirFor(agent), sidOf(agent))
83
+
84
+ async function setFlags(agent, flags) {
85
+ const dir = dirFor(agent)
86
+ const session = agent.session
87
+ const now = new Date().toISOString()
88
+ const meta = await ensureMeta(dir, sidOf(agent), { title: titleOf((seq) => session.eventAt(seq)), workspace: dir, now })
89
+ Object.assign(meta, flags, { lastActiveAt: now })
90
+ await saveMeta(dir, sidOf(agent), meta)
91
+ return meta
92
+ }
93
+
94
+ /** Own chat plus every shared chat of the workspace, graphs loaded. ponytail: re-read per turn; cache by mtime if a workspace grows large. */
95
+ async function loadViews(agent) {
96
+ const dir = dirFor(agent)
97
+ const sid = sidOf(agent)
98
+ const views = []
99
+ for (const { sid: other, meta } of await listChats(dir)) {
100
+ const own = other === sid
101
+ if (!own && !sharedOn(meta)) continue
102
+ views.push({ sid: other, cid: meta.cid, meta, own, graph: await loadGraph(chatDir(dir, other)) })
103
+ }
104
+ return views
105
+ }
106
+
107
+ function resolveTarget(agent) {
108
+ if (cfg.provider && cfg.model) return { provider: cfg.provider, model: cfg.model }
109
+ const routed = agent.session.requestHeader()?.config
110
+ if (routed?.provider && routed?.model) return { provider: routed.provider, model: routed.model }
111
+ const { provider, model } = agent.options ?? {}
112
+ return provider && model ? { provider, model } : undefined
113
+ }
114
+
115
+ // ---------- builder ----------
116
+ async function build(agent, { force = false, turn = null } = {}) {
117
+ const session = agent.session
118
+ const sid = sidOf(agent)
119
+ const st = state(sid)
120
+ if (st.building) return { status: 'busy' }
121
+ // ponytail: subagent chatter stays out of the graph; revisit if delegated work holds decisions worth keeping.
122
+ if (isSubagent(agent)) return { status: 'skipped', reason: 'subagent session' }
123
+ st.building = true
124
+ try {
125
+ const meta = await metaFor(agent)
126
+ if (!memoryOn(meta)) return { status: 'off', reason: 'memory is off for this chat; /context-graph on resumes it' }
127
+ // A chat that never ran a command has no folder yet; give it one so it gets a chat number.
128
+ if (!meta) await setFlags(agent, {})
129
+ const span = collectSpan(session.surface.nodes, (seq) => session.eventAt(seq), st.lastBuiltSeq)
130
+ const chars = span.messages.reduce((n, m) => n + m.text.length, 0)
131
+ if (span.messages.length === 0) return { status: 'nothing', reason: 'no new messages since the last build' }
132
+ if (!force && (span.userTurns < cfg.buildEveryTurns || chars < cfg.buildMinChars)) {
133
+ return { status: 'skipped', reason: `${span.userTurns}/${cfg.buildEveryTurns} human turns, ${chars}/${cfg.buildMinChars} chars` }
134
+ }
135
+ const llm = ctx.get('llm')
136
+ if (!llm) return { status: 'unavailable', reason: 'no llm service in this composition' }
137
+ const target = resolveTarget(agent)
138
+ if (!target) return { status: 'unavailable', reason: 'no provider/model routed yet' }
139
+ const chat = chatDir(dirFor(agent), sid)
140
+ const graph = await loadGraph(chat)
141
+ const prompt = `${transcriptForBuilder(span.messages)}\n\n${builderInstruction(graph)}`
142
+ const assembler = new BlockAssembler()
143
+ for await (const chunk of llm.stream({
144
+ provider: target.provider,
145
+ model: target.model,
146
+ messages: [{ role: 'user', content: [{ type: 'text', text: prompt }] }],
147
+ maxTokens: cfg.builderMaxTokens,
148
+ sessionId: session.id,
149
+ purpose: PURPOSE
150
+ })) assembler.push(chunk)
151
+ const finish = assembler.finish
152
+ if (finish?.kind === 'error' || finish?.kind === 'aborted') throw new Error(finish.failure?.message ?? finish.kind)
153
+ const blocks = assembler.blocks()
154
+ const answer = textOf(blocks)
155
+ // Some thinking models put everything, JSON included, into reasoning blocks.
156
+ const reasoning = blocks.filter((b) => b?.type === 'reasoning').map((b) => b.text).join('\n')
157
+ const delta = parseBuilderOutput(answer) ?? parseBuilderOutput(reasoning)
158
+ if (!delta || (delta.nodes.length === 0 && finish?.kind === 'max-tokens')) {
159
+ const saved = join(chat, 'last-builder-output.txt')
160
+ await mkdir(chat, { recursive: true })
161
+ await writeFile(saved, `finish: ${finish?.kind}\n\n--- answer ---\n${answer}\n\n--- reasoning ---\n${reasoning}\n`, 'utf8')
162
+ const why = finish?.kind === 'max-tokens'
163
+ ? `the model ran out of output tokens (builderMaxTokens ${cfg.builderMaxTokens}) before finishing`
164
+ : 'builder output was not the expected JSON'
165
+ return { status: 'failed', reason: `${why}; raw output saved to ${saved}` }
166
+ }
167
+ // Reversibility rule: a node is written only when it cites text we can store verbatim.
168
+ delta.nodes = delta.nodes.filter((n) => n.msgs.some((i) => span.messages[i]))
169
+ const now = new Date().toISOString()
170
+ const touched = mergeDelta(graph, delta, { session: sid, turn, now })
171
+ for (const { id, msgs } of touched) {
172
+ const cited = msgs.map((i) => span.messages[i]).filter(Boolean)
173
+ if (cited.length > 0) await appendSource(chat, id, { session: sid, turn, at: now, messages: cited })
174
+ }
175
+ await saveGraph(chat, graph)
176
+ await saveMeta(dirFor(agent), sid, { ...meta, title: meta.title ?? titleOf((seq) => session.eventAt(seq)), lastActiveAt: now, turns: (meta.turns ?? 0) + span.userTurns })
177
+ st.lastBuiltSeq = span.lastSeq
178
+ meter.builds++
179
+ return { status: 'built', nodes: touched.length, newNodes: touched.filter((t) => t.isNew).length, totalNodes: Object.keys(graph.nodes).length, edges: graph.edges.length, dir: chat }
180
+ } catch (error) {
181
+ console.error('context-graph: build failed (non-fatal)', error)
182
+ return { status: 'failed', reason: String(error?.message ?? error) }
183
+ } finally {
184
+ st.building = false
185
+ }
186
+ }
187
+
188
+ ctx.on('agent/turn-stopping', (payload) => {
189
+ // Fire and forget: the build must never delay the turn's close.
190
+ void build(payload.agent, { turn: payload.turn })
191
+ })
192
+
193
+ // ---------- matcher ----------
194
+ ctx.on('agent/pre-step', async (payload, next) => {
195
+ const agent = payload.agent
196
+ const prompt = payload.messages.filter((m) => m.source?.kind === 'user').map((m) => textOf(m.content)).join('\n')
197
+ const decision = await next()
198
+ if (decision.kind !== 'enter') return decision
199
+ const result = await addMemory(agent, prompt, decision)
200
+ return prompt && !isSubagent(agent) ? addUpdateNotice(result) : result
201
+ })
202
+
203
+ /** Once per app start, ask the model to pass an available update on to the user. */
204
+ function addUpdateNotice(decision) {
205
+ const notice = updates.current()
206
+ if (!notice || noticeShown) return decision
207
+ noticeShown = true
208
+ const message = createUserMessage({
209
+ content: [{ type: 'text', text: `[${SOURCE_KIND}] ${notice} At the end of your reply, tell the user this in one short line.` }],
210
+ source: { kind: SOURCE_KIND, notice: true }
211
+ })
212
+ return { ...decision, messages: [...decision.messages, message] }
213
+ }
214
+
215
+ async function addMemory(agent, prompt, decision) {
216
+ try {
217
+ if (isSubagent(agent) || !prompt) return decision
218
+ if (!memoryOn(await metaFor(agent))) return decision
219
+ const st = state(sidOf(agent))
220
+ const views = await loadViews(agent)
221
+ const parts = []
222
+ let layer
223
+ if (st.announce) {
224
+ st.announce = false
225
+ const list = renderChats(views, { max: cfg.surfaceMaxChats })
226
+ if (list) { parts.push(list); layer = 'surface' }
227
+ }
228
+ const range = parseTimeRange(prompt)
229
+ const { hits, slice } = matchAcross(views, prompt, { max: cfg.maxHits, range })
230
+ if (hits.length === 0 && range) {
231
+ parts.push(renderRange(views.filter((v) => !v.own), range))
232
+ } else {
233
+ let inline
234
+ if (hits.length === 1 || (hits.length > 1 && hits[0].score >= 2 * hits[1].score)) {
235
+ const top = hits[0]
236
+ const text = await readSource(chatDir(dirFor(agent), top.view.sid), top.id.slice(top.id.indexOf('n')))
237
+ if (text && text.length <= cfg.inlineMaxChars) inline = { id: top.id, text }
238
+ }
239
+ const block = renderHits(hits, { inline, slice })
240
+ if (block) parts.push(block)
241
+ }
242
+ if (parts.length === 0) return decision
243
+ const text = parts.join('\n\n')
244
+ meter.injected++
245
+ meter.injectedTokens += estimateTokens(text)
246
+ const message = createUserMessage({ content: [{ type: 'text', text }], source: layer ? { kind: SOURCE_KIND, layer } : { kind: SOURCE_KIND } })
247
+ return { ...decision, messages: [...decision.messages, message] }
248
+ } catch (error) {
249
+ console.error('context-graph: matcher failed (non-fatal)', error)
250
+ return decision
251
+ }
252
+ }
253
+
254
+ // ---------- meter ----------
255
+ ctx.on('llm/stream', (options, next) => {
256
+ const inner = next()
257
+ const bucket = options.purpose === PURPOSE ? meter.builder : meter.main
258
+ async function* tracked() {
259
+ try {
260
+ for await (const chunk of inner) {
261
+ if (chunk?.type === 'usage' && chunk.usage) {
262
+ bucket.input += chunk.usage.inputTokens ?? 0
263
+ bucket.cacheRead += chunk.usage.cacheReadTokens ?? 0
264
+ bucket.cacheWrite += chunk.usage.cacheWriteTokens ?? 0
265
+ bucket.output += chunk.usage.outputTokens ?? 0
266
+ }
267
+ yield chunk
268
+ }
269
+ } finally {
270
+ bucket.requests++
271
+ }
272
+ }
273
+ return tracked()
274
+ })
275
+
276
+ // ---------- recall tool ----------
277
+ ctx.tools.register(defineTool({
278
+ name: 'recall',
279
+ description: [
280
+ 'Fetch the exact text behind an id shown in a [context-graph] block. A topic id (c3n12) returns its verbatim source and linked topics;',
281
+ 'a chat id (c3) returns that chat\'s topics; a day (2026-11-01) returns every chat and topic from that day; a turn id (t7) returns turn 7 of this chat word for word.',
282
+ 'Call it when a gist is relevant but not precise enough to answer. Never invent an id; only use ids you were shown.'
283
+ ].join(' '),
284
+ parameters: {
285
+ id: { type: 'string', required: true, description: 'c3n12 (topic), c3 (chat), 2026-11-01 (day) or t7 (turn of this chat).' },
286
+ depth: { type: 'integer', description: '0 (default): this topic only. 1: also include each linked topic\'s gist.' }
287
+ },
288
+ output: {
289
+ schema: {
290
+ type: 'object',
291
+ additionalProperties: false,
292
+ properties: {
293
+ status: { type: 'string', enum: ['ok', 'unknown'], required: true },
294
+ text: { type: 'string', required: true }
295
+ }
296
+ },
297
+ render: (_args, value) => [{ type: 'text', text: value.text }]
298
+ },
299
+ async execute(args, exec) {
300
+ const agent = exec.agent
301
+ if (!agent?.session) return { status: 'unknown', text: 'recall is unavailable: no session attached to this call.' }
302
+ const id = String(args.id ?? '').trim()
303
+ const ok = (text) => { meter.recalls++; return { status: 'ok', text } }
304
+ const turn = /^t(\d+)$/.exec(id)
305
+ if (turn) {
306
+ const text = turnTranscript((seq) => agent.session.eventAt(seq), Number(turn[1]))
307
+ return text === undefined ? { status: 'unknown', text: `No turn ${id} in this chat.` } : ok(`# ${id} (verbatim)\n\n${text}`)
308
+ }
309
+ const views = await loadViews(agent)
310
+ if (/^\d{4}-\d{2}-\d{2}$/.test(id)) return ok(renderRange(views.filter((v) => !v.own), parseTimeRange(id)))
311
+ const m = /^(?:c(\d+))?(n\d+)?$/.exec(id)
312
+ if (!m || (!m[1] && !m[2])) return { status: 'unknown', text: `"${id}" is not an id. Use c3n12, c3, 2026-11-01 or t7, and only ids you were shown.` }
313
+ const view = m[1] ? views.find((v) => String(v.cid) === m[1]) : views.find((v) => v.own)
314
+ if (!view) return { status: 'unknown', text: `No chat c${m[1]} shared in this workspace.` }
315
+ if (!m[2]) return ok(renderChatIndex(view))
316
+ const node = view.graph.nodes[m[2]]
317
+ if (!node) return { status: 'unknown', text: `No topic ${id}. Only use ids shown in a [context-graph] block.` }
318
+ node.hits = (node.hits ?? 0) + 1
319
+ const chat = chatDir(dirFor(agent), view.sid)
320
+ saveGraph(chat, view.graph).catch((error) => console.error('context-graph: hit count save failed', error))
321
+ const lines = [`# ${id} ${node.label}`, `${node.kind}. ${node.gist}`, '']
322
+ const source = await readSource(chat, m[2])
323
+ lines.push(source ? source.trim() : '(no verbatim source stored for this topic)')
324
+ const links = neighbors(view.graph, m[2])
325
+ if (links.length > 0) {
326
+ lines.push('', 'Linked topics:')
327
+ for (const link of links) {
328
+ const other = view.graph.nodes[link.id]
329
+ const otherId = `c${view.cid}${link.id}`
330
+ const arrow = link.direction === 'out' ? `${id} ${link.relation} ${otherId}` : `${otherId} ${link.relation} ${id}`
331
+ lines.push(`- ${arrow}: ${other.label}${args.depth >= 1 ? ` — ${other.gist}` : ''}`)
332
+ }
333
+ }
334
+ return ok(lines.join('\n'))
335
+ }
336
+ }))
337
+
338
+ // ---------- /context-graph command (nested: only where a human-command surface exists) ----------
339
+ ctx.plugin({
340
+ name: 'context-graph-command',
341
+ inject: ['commands'],
342
+ apply(cmdCtx) {
343
+ cmdCtx.effect(function* () {
344
+ yield cmdCtx.commands.register({
345
+ name: 'context-graph',
346
+ description: `Chat memory graph: /context-graph ${USAGE}`,
347
+ // Without `input`, dsh clients run the bare name and send any typed arguments to the model as chat.
348
+ input: { hint: USAGE },
349
+ async handler(invocation) {
350
+ const [sub = 'stats', ...rest] = invocation.rawInput.trim().split(/\s+/).filter(Boolean)
351
+ const agent = invocation.agent
352
+ const sid = sidOf(agent)
353
+ if (sub === 'on') {
354
+ await setFlags(agent, { memoryOff: false })
355
+ state(sid).announce = true
356
+ const result = await agent.runMaintenance(() => build(agent, { force: true }))
357
+ const shared = (await loadViews(agent)).filter((v) => !v.own).length
358
+ const indexed = result.status === 'built' ? `${result.totalNodes} topics in this chat` : `nothing indexed yet (${result.reason ?? result.status})`
359
+ return { kind: 'success', text: `Memory on · ${indexed} · ${shared} shared ${shared === 1 ? 'chat' : 'chats'} to draw on\nThis chat indexes itself every ${cfg.buildEveryTurns} turns. /context-graph share lets other chats use it; /context-graph off stops it.` }
360
+ }
361
+ if (sub === 'off') {
362
+ await setFlags(agent, { memoryOff: true })
363
+ return { kind: 'success', text: 'Memory off for this chat · nothing is added to its requests\nThe graph stays; /context-graph on resumes. To turn memory off in every chat, switch dsh-context-graph off on the Plugins page.' }
364
+ }
365
+ if (sub === 'share' || sub === 'unshare') {
366
+ const meta = await setFlags(agent, { private: sub === 'unshare' })
367
+ const topics = Object.keys((await loadGraph(chatDir(dirFor(agent), sid))).nodes).length
368
+ const hint = memoryOn(meta) ? '' : '\nMemory is off for this chat, so it has nothing new to share until /context-graph on.'
369
+ return { kind: 'success', text: sub === 'share' ? `Shared with the workspace · ${topics} topics\nOther chats with memory on can now match and recall this chat.${hint}` : `No longer shared · ${topics} topics stay private to this chat` }
370
+ }
371
+ if (sub === 'build') {
372
+ const result = await agent.runMaintenance(() => build(agent, { force: true }))
373
+ if (result.status !== 'built') return { kind: 'error', text: `Build ${result.status}: ${result.reason ?? ''}`.trim() }
374
+ return { kind: 'success', text: `${result.nodes} topics indexed (${result.newNodes} new) · this chat has ${result.totalNodes} topics\nLinks: ${result.edges}\nFolder: ${result.dir}` }
375
+ }
376
+ const views = await loadViews(agent)
377
+ if (sub === 'map') {
378
+ const all = []
379
+ for (const { sid: other, meta } of await listChats(dirFor(agent))) all.push({ sid: other, cid: meta.cid, meta, own: other === sid, graph: await loadGraph(chatDir(dirFor(agent), other)) })
380
+ return { kind: 'success', text: `${all.length} ${all.length === 1 ? 'chat' : 'chats'} in ${dirFor(agent)}\n${renderMap(all)}` }
381
+ }
382
+ if (sub === 'find') {
383
+ const query = rest.join(' ')
384
+ const { hits } = matchAcross(views, query, { max: cfg.maxHits, range: parseTimeRange(query) })
385
+ if (hits.length === 0) return { kind: 'success', text: 'No matching topics in shared chats' }
386
+ return { kind: 'success', text: [`${hits.length} matching ${hits.length === 1 ? 'topic' : 'topics'}`, ...hits.map(({ id, node }) => `${id} ${node.label}: ${node.gist}`)].join('\n') }
387
+ }
388
+ if (sub !== 'stats') return { kind: 'error', text: `Usage: /context-graph ${USAGE}` }
389
+ const own = views.find((v) => v.own)
390
+ const m = meter.main
391
+ const cached = m.cacheRead + m.cacheWrite
392
+ const hitRate = m.input + cached > 0 ? Math.round((m.cacheRead / (m.input + cached)) * 100) : 0
393
+ const session = agent.session
394
+ const pending = collectSpan(session.surface.nodes, (seq) => session.eventAt(seq), state(sid).lastBuiltSeq).userTurns
395
+ const shared = views.filter((v) => !v.own).length
396
+ return {
397
+ kind: 'success',
398
+ text: [
399
+ `Memory ${memoryOn(own?.meta) ? 'on' : 'off'} · ${Object.keys(own?.graph.nodes ?? {}).length} topics in this chat · ${sharedOn(own?.meta) ? 'shared' : 'private'} · ${shared} shared ${shared === 1 ? 'chat' : 'chats'} · ${pending} turns waiting to be indexed${updates.current() ? ' · update available' : ''}`,
400
+ `Version ${version}: ${updates.current() ?? 'no newer version found'}`,
401
+ `Graph folder: ${dirFor(agent)}`,
402
+ 'Counters below are since the app started:',
403
+ `Builds: ${meter.builds}; builder tokens in/out: ${meter.builder.input + meter.builder.cacheRead + meter.builder.cacheWrite}/${meter.builder.output}`,
404
+ `Injected blocks: ${meter.injected} (~${meter.injectedTokens} tokens); recalls: ${meter.recalls}`,
405
+ `Main requests: ${m.requests}; input ${m.input} uncached + ${m.cacheRead} cache-read + ${m.cacheWrite} cache-write; cache-hit ${hitRate}%`
406
+ ].join('\n')
407
+ }
408
+ }
409
+ })
410
+ }, 'context-graph command')
411
+ }
412
+ })
413
+ }