dsh-context-graph 0.0.0-stage → 0.2.2
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/LICENSE +21 -0
- package/README.md +130 -3
- package/cordis.patch.yml +18 -0
- package/graph.js +411 -0
- package/index.js +396 -0
- package/package.json +51 -4
- package/store.js +46 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 William20100221
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,130 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
1
|
+
# dsh-context-graph
|
|
2
|
+
|
|
3
|
+
A DeepSeek Harness (dsh) plugin that remembers your past conversations as a small graph.
|
|
4
|
+
New sessions start with a one-screen map of what was decided before, each turn gets the few
|
|
5
|
+
nodes that match what you just asked, and the model fetches the verbatim original text only
|
|
6
|
+
when it needs it. Old messages stop being re-sent; decisions stop getting lost.
|
|
7
|
+
|
|
8
|
+
**Folding (v0.2.0).** Every chat normally re-sends all earlier messages on every turn. Once the
|
|
9
|
+
older part of a chat costs more than `foldAtTokens` per request, the plugin replaces it with one
|
|
10
|
+
short table of contents: the topics found in it and a one-line list of what you asked in each
|
|
11
|
+
turn (t1, t2, ...). The model follows that table to the exact part it needs with `recall("t7")`
|
|
12
|
+
or `recall("n12")`. Your newest turns stay word for word. Nothing is deleted: the full turns stay
|
|
13
|
+
in the session log and in the chat window.
|
|
14
|
+
|
|
15
|
+
Status: v0.2.0. Installs and loads in the dsh desktop app; folding and indexing are not yet
|
|
16
|
+
verified with a live model. 18 tests pass against the published dsh packages.
|
|
17
|
+
|
|
18
|
+
## What it does
|
|
19
|
+
|
|
20
|
+
| Moment | What happens | Cost |
|
|
21
|
+
|---|---|---|
|
|
22
|
+
| Every 4 human turns (default) | After the turn closes, one small auxiliary model call indexes the new messages into `.context-graph/graph.json` and stores the cited messages verbatim under `.context-graph/src/`. | about the span's tokens in, under 1k out, off the critical path |
|
|
23
|
+
| First human turn of a session | A `[context-graph]` block lists the best-connected nodes from earlier sessions: id, label, one-line gist. | about 15 tokens per node, 40 nodes max |
|
|
24
|
+
| Every human turn | The prompt is matched against node labels and aliases by word overlap (no model call). Up to 5 hits are appended to the message. One clearly dominant short hit is included verbatim. | under about 150 tokens |
|
|
25
|
+
| Older part of this chat costs more than 24k tokens per request | At the start of your next turn it is replaced by a table of contents (topics plus one line per turn). The last 2 turns stay as they are. | breaks the provider cache once per fold, then every later request is smaller |
|
|
26
|
+
| Model calls `recall(id)` | `n12`: the topic's verbatim source and neighbours. `t7`: folded turn 7 exactly, including tool calls. | one tool round trip |
|
|
27
|
+
| `/context-graph` | `stats`, `build` (index now), `fold` (index and fold now), `find <words>`. | none |
|
|
28
|
+
|
|
29
|
+
Design rules, in order of importance:
|
|
30
|
+
|
|
31
|
+
1. **Nothing is written without its source.** A node is stored only together with the verbatim
|
|
32
|
+
messages it was drawn from. The gist is a pointer, never the record.
|
|
33
|
+
2. **Fold in batches, not every turn.** DeepSeek bills re-sent cached input at about 1/30 price,
|
|
34
|
+
and any fold restarts that cache. So a fold happens only when the old part is large
|
|
35
|
+
(24k tokens by default) and the table of contents is under half its size. Between folds the
|
|
36
|
+
prefix stays stable and cached. Matcher blocks ride at the end of the newest message.
|
|
37
|
+
3. **Old decisions resolve to new ones.** A `supersedes` edge makes a hit on the old node show
|
|
38
|
+
the replacement instead.
|
|
39
|
+
4. **Matching is lexical.** Labels, aliases and gists; English words, identifiers and Chinese
|
|
40
|
+
bigrams. The builder is asked to write aliases precisely so this works without embeddings.
|
|
41
|
+
|
|
42
|
+
The full design, including what was borrowed from `dsh-plugin-save-token` and why cache
|
|
43
|
+
economics make cross-session memory the main win, is in [docs/core-design.md](docs/core-design.md).
|
|
44
|
+
|
|
45
|
+
## Install
|
|
46
|
+
|
|
47
|
+
Desktop app: **Plugins → Add plugin**, official npm registry, enter `dsh-context-graph`,
|
|
48
|
+
install, then fully restart the app so the `/context-graph` command appears.
|
|
49
|
+
|
|
50
|
+
Command line (use the profile your app runs; the desktop app uses `desktop`):
|
|
51
|
+
|
|
52
|
+
```sh
|
|
53
|
+
dsh plugin --profile desktop add dsh-context-graph
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
**Updates.** Installed from npm, the plugin gets dsh's built-in updater: on the Plugins page
|
|
57
|
+
press **Refresh**, and when a newer version is published an **Update** button appears on the
|
|
58
|
+
plugin. Restart the app after updating. A `github:` install is not eligible for this; remove
|
|
59
|
+
it and add `dsh-context-graph` from npm once.
|
|
60
|
+
|
|
61
|
+
Remove with `dsh plugin --profile desktop remove dsh-context-graph`.
|
|
62
|
+
|
|
63
|
+
## Releasing a new version
|
|
64
|
+
|
|
65
|
+
```sh
|
|
66
|
+
npm test
|
|
67
|
+
npm version patch
|
|
68
|
+
npm publish
|
|
69
|
+
git push --follow-tags
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
`npm version patch` bumps the version, commits and tags it. `npm publish` needs `npm login`
|
|
73
|
+
once. Users then see the new version after pressing Refresh on the Plugins page.
|
|
74
|
+
|
|
75
|
+
## Configuration
|
|
76
|
+
|
|
77
|
+
Defaults live in [cordis.patch.yml](cordis.patch.yml). A patch replaces the row's whole
|
|
78
|
+
`config`, so restate every key you keep.
|
|
79
|
+
|
|
80
|
+
| Key | Default | Meaning |
|
|
81
|
+
|---|---|---|
|
|
82
|
+
| `dir` | `.context-graph` | Graph folder, relative to the agent workspace or absolute |
|
|
83
|
+
| `buildEveryTurns` | `4` | Index after this many new human turns |
|
|
84
|
+
| `buildMinChars` | `400` | ...and at least this much new text |
|
|
85
|
+
| `maxHits` | `5` | Nodes shown per human turn |
|
|
86
|
+
| `inlineMaxChars` | `1200` | A single dominant hit this short is shown verbatim |
|
|
87
|
+
| `surfaceMaxNodes` | `40` | Nodes listed at the start of a session |
|
|
88
|
+
| `builderMaxTokens` | `8192` | Output cap for the indexing call; thinking models spend part of it reasoning |
|
|
89
|
+
| `provider`, `model` | `''` | Empty: reuse the conversation's routed provider and model |
|
|
90
|
+
| `fold` | `true` | Fold old turns of the current chat into a table of contents |
|
|
91
|
+
| `foldAtTokens` | `24000` | Fold once the foldable part costs this much per request |
|
|
92
|
+
| `keepTurns` | `2` | Newest human turns never folded |
|
|
93
|
+
|
|
94
|
+
## Files
|
|
95
|
+
|
|
96
|
+
```
|
|
97
|
+
index.js dsh plugin: builder, matcher, recall tool, meter, /context-graph command
|
|
98
|
+
graph.js pure core: tokenize, match, merge, render, builder prompt and parser
|
|
99
|
+
store.js graph.json and src/<id>.md read/write
|
|
100
|
+
cordis.patch.yml mounts the plugin at the profile root with default config
|
|
101
|
+
test/ node --test; plugin.test.js needs DSH_NODE_MODULES (see below)
|
|
102
|
+
docs/ design
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
## Testing
|
|
106
|
+
|
|
107
|
+
Unit tests need nothing:
|
|
108
|
+
|
|
109
|
+
```sh
|
|
110
|
+
node --test test/graph.test.js
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
The wiring test imports the real dsh packages from an existing dsh install. Point it at that
|
|
114
|
+
install's `node_modules`:
|
|
115
|
+
|
|
116
|
+
```sh
|
|
117
|
+
DSH_NODE_MODULES=/path/to/dsh/node_modules npm test
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Without the variable it is skipped. Nothing here calls a model.
|
|
121
|
+
|
|
122
|
+
## Known limits
|
|
123
|
+
|
|
124
|
+
- Builds are indexed per process; after a restart the first build of a resumed session re-reads
|
|
125
|
+
its whole surface. Existing ids are reused, so this costs one larger call, not duplicates.
|
|
126
|
+
- Two agents writing the same workspace graph at once: last writer wins.
|
|
127
|
+
- Subagent sessions are neither indexed nor given memory blocks.
|
|
128
|
+
- Tool outputs are not indexed as topics, but they are folded and `recall("tN")` returns them (each capped at 2000 characters).
|
|
129
|
+
- Only indexed turns are folded. After an app restart the index position resets, so the first fold waits for one build.
|
|
130
|
+
- A skill list or runtime-context message inside the folded part is copied into the fold message so the model keeps it.
|
package/cordis.patch.yml
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# Mounted at the profile root so the recall tool, the matcher and the builder are available to
|
|
2
|
+
# every agent. Every value below is the default; restate the whole config block when you change one.
|
|
3
|
+
- insert:
|
|
4
|
+
- id: context-graph
|
|
5
|
+
name: dsh-context-graph
|
|
6
|
+
config:
|
|
7
|
+
dir: .context-graph # relative to the agent workspace, or an absolute path
|
|
8
|
+
buildEveryTurns: 4 # index after this many new human turns
|
|
9
|
+
buildMinChars: 400 # ...and at least this much new text
|
|
10
|
+
maxHits: 5 # nodes shown per human turn
|
|
11
|
+
inlineMaxChars: 1200 # one dominant hit this short is shown verbatim, no recall needed
|
|
12
|
+
surfaceMaxNodes: 40 # god nodes listed at the start of a session
|
|
13
|
+
builderMaxTokens: 8192 # thinking models spend part of this on reasoning
|
|
14
|
+
provider: '' # empty: reuse the conversation's routed provider/model
|
|
15
|
+
model: ''
|
|
16
|
+
fold: true # replace old turns of the current chat with a table of contents
|
|
17
|
+
foldAtTokens: 24000 # fold once the foldable part costs this much per request
|
|
18
|
+
keepTurns: 2 # newest human turns always kept word for word
|
package/graph.js
ADDED
|
@@ -0,0 +1,411 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* context-graph core. Pure: no I/O, no dsh imports, so `node --test` covers it without a harness.
|
|
3
|
+
*
|
|
4
|
+
* A graph is `{ version, nextId, nodes: { [id]: Node }, edges: [[from, to, relation], ...] }`.
|
|
5
|
+
* A Node is `{ label, gist, aliases, kind, src: [{ session, turn, at }], updated, hits }`.
|
|
6
|
+
* The verbatim source text of a node lives outside the graph (see store.js); `src` is provenance.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
export const GRAPH_VERSION = 1
|
|
10
|
+
export const SOURCE_KIND = 'context-graph'
|
|
11
|
+
export const RELATIONS = ['uses', 'part-of', 'supersedes', 'caused-by', 'relates-to']
|
|
12
|
+
export const KINDS = ['decision', 'fact', 'task', 'artifact', 'open-question']
|
|
13
|
+
|
|
14
|
+
const STOPWORDS = new Set((
|
|
15
|
+
'a an the and or but if then so of to in on at for with by from as is are was were be been being ' +
|
|
16
|
+
'do does did done have has had can could should would will shall may might must not no yes ' +
|
|
17
|
+
'i me my we our you your he she it its they them this that these those there here what which who ' +
|
|
18
|
+
'how when where why also just like get got make made use used using want need let please ok okay ' +
|
|
19
|
+
'now new one two about into over under again more most some any all each other than too very ' +
|
|
20
|
+
'的 了 是 在 我 你 他 她 它 们 这 那 个 和 与 或 吗 呢 吧 啊 把 被 给 让 就 都 也 还 很 不 没 有 要 会 能 可以 什么 怎么 这个 那个 一下 一个'
|
|
21
|
+
).split(/\s+/))
|
|
22
|
+
|
|
23
|
+
export function emptyGraph() {
|
|
24
|
+
return { version: GRAPH_VERSION, nextId: 1, nodes: {}, edges: [] }
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/** Rough token estimate for budget caps; CJK is close to one token per char. */
|
|
28
|
+
export function estimateTokens(text) {
|
|
29
|
+
let cjk = 0
|
|
30
|
+
for (const ch of text) if (/[-ヿ㐀-鿿가-]/.test(ch)) cjk++
|
|
31
|
+
return Math.ceil(cjk + (text.length - cjk) / 3.5)
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* Lowercased word tokens plus CJK bigrams, stopwords removed.
|
|
36
|
+
* "clear_conversation tool" -> ["clear_conversation", "clear", "conversation", "tool"]
|
|
37
|
+
* "清除上下文" -> ["清除", "除上", "上下", "下文"]
|
|
38
|
+
*/
|
|
39
|
+
export function tokenize(text) {
|
|
40
|
+
const out = new Set()
|
|
41
|
+
const lower = String(text ?? '').toLowerCase()
|
|
42
|
+
for (const run of lower.match(/[-ヿ㐀-鿿가-]+/g) ?? []) {
|
|
43
|
+
if (run.length === 1) { if (!STOPWORDS.has(run)) out.add(run); continue }
|
|
44
|
+
for (let i = 0; i + 1 < run.length; i++) {
|
|
45
|
+
const bigram = run.slice(i, i + 2)
|
|
46
|
+
if (!STOPWORDS.has(bigram)) out.add(bigram)
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
for (const word of lower.replace(/[-ヿ㐀-鿿가-]+/g, ' ').match(/[a-z0-9_./-]{2,}/g) ?? []) {
|
|
50
|
+
if (STOPWORDS.has(word)) continue
|
|
51
|
+
out.add(word)
|
|
52
|
+
if (/[_./-]/.test(word)) for (const part of word.split(/[_./-]+/)) if (part.length >= 2 && !STOPWORDS.has(part)) out.add(part)
|
|
53
|
+
}
|
|
54
|
+
return [...out]
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
function nodeTokens(node) {
|
|
58
|
+
return {
|
|
59
|
+
strong: new Set(tokenize([node.label, ...(node.aliases ?? [])].join(' '))),
|
|
60
|
+
weak: new Set(tokenize(node.gist ?? ''))
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** True when every provenance entry of `node` comes from `session` (its text is still in that session's context). */
|
|
65
|
+
export function onlyFromSession(node, session) {
|
|
66
|
+
return Boolean(session) && (node.src ?? []).length > 0 && node.src.every((s) => s.session === session)
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
export function degree(graph, id) {
|
|
70
|
+
let n = 0
|
|
71
|
+
for (const [a, b] of graph.edges) if (a === id || b === id) n++
|
|
72
|
+
return n
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/** Edges touching `id`, oriented from its point of view. */
|
|
76
|
+
export function neighbors(graph, id) {
|
|
77
|
+
const out = []
|
|
78
|
+
for (const [a, b, relation] of graph.edges) {
|
|
79
|
+
if (a === id && graph.nodes[b]) out.push({ id: b, relation, direction: 'out' })
|
|
80
|
+
else if (b === id && graph.nodes[a]) out.push({ id: a, relation, direction: 'in' })
|
|
81
|
+
}
|
|
82
|
+
return out
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** Follow `supersedes` edges forward so a stale decision resolves to its replacement. */
|
|
86
|
+
export function resolveSuperseded(graph, id) {
|
|
87
|
+
const seen = new Set()
|
|
88
|
+
let current = id
|
|
89
|
+
while (!seen.has(current)) {
|
|
90
|
+
seen.add(current)
|
|
91
|
+
const next = graph.edges.find(([from, to, rel]) => rel === 'supersedes' && to === current && graph.nodes[from])
|
|
92
|
+
if (!next) return current
|
|
93
|
+
current = next[0]
|
|
94
|
+
}
|
|
95
|
+
return current
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* Lexical match of a user message against node labels/aliases (weight 2) and gists (weight 1),
|
|
100
|
+
* with a small boost for well-connected nodes. Nodes whose every source is the current session are
|
|
101
|
+
* skipped while that session has not compacted: their text is still on the surface.
|
|
102
|
+
* @returns [{ id, node, score }] best first, at most `max`, only nodes with a strong (label/alias) hit.
|
|
103
|
+
*/
|
|
104
|
+
export function matchNodes(graph, query, { max = 5, session, sessionCompacted = false } = {}) {
|
|
105
|
+
const q = tokenize(query)
|
|
106
|
+
if (q.length === 0) return []
|
|
107
|
+
const scored = []
|
|
108
|
+
for (const [rawId, node] of Object.entries(graph.nodes)) {
|
|
109
|
+
if (!sessionCompacted && onlyFromSession(node, session)) continue
|
|
110
|
+
const { strong, weak } = nodeTokens(node)
|
|
111
|
+
let strongHits = 0
|
|
112
|
+
let weakHits = 0
|
|
113
|
+
for (const t of q) {
|
|
114
|
+
if (strong.has(t)) strongHits++
|
|
115
|
+
else if (weak.has(t)) weakHits++
|
|
116
|
+
}
|
|
117
|
+
if (strongHits === 0) continue
|
|
118
|
+
const score = strongHits * 2 + weakHits + 0.25 * Math.log1p(degree(graph, rawId))
|
|
119
|
+
const id = resolveSuperseded(graph, rawId)
|
|
120
|
+
scored.push({ id, node: graph.nodes[id], score, via: id === rawId ? undefined : rawId })
|
|
121
|
+
}
|
|
122
|
+
scored.sort((a, b) => b.score - a.score || (b.node.updated ?? '').localeCompare(a.node.updated ?? ''))
|
|
123
|
+
const seen = new Set()
|
|
124
|
+
return scored.filter(({ id }) => !seen.has(id) && seen.add(id)).slice(0, max)
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/** God nodes: most connected first, newest first among equals. */
|
|
128
|
+
export function surfaceNodes(graph, max = 40) {
|
|
129
|
+
return Object.keys(graph.nodes)
|
|
130
|
+
.map((id) => ({ id, d: degree(graph, id), u: graph.nodes[id].updated ?? '' }))
|
|
131
|
+
.sort((a, b) => b.d - a.d || b.u.localeCompare(a.u))
|
|
132
|
+
.slice(0, max)
|
|
133
|
+
.map(({ id }) => id)
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
function line(id, node) {
|
|
137
|
+
const date = (node.updated ?? '').slice(0, 10)
|
|
138
|
+
return `- ${id} ${node.label}: ${node.gist}${date ? ` (${date})` : ''}`
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
/** The per-turn block appended to the user's message. `inline` carries one node's verbatim text when it is short. */
|
|
142
|
+
export function renderHits(graph, hits, { inline } = {}) {
|
|
143
|
+
if (hits.length === 0) return ''
|
|
144
|
+
const lines = [`[${SOURCE_KIND}] Related past context. Call recall(id) for the verbatim source.`]
|
|
145
|
+
for (const { id, node, via } of hits) lines.push(line(id, node) + (via ? ` [replaces ${via}]` : ''))
|
|
146
|
+
if (inline) lines.push('', `Verbatim source of ${inline.id}:`, inline.text.trim())
|
|
147
|
+
return lines.join('\n')
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
/** The cross-session surface layer sent once at the start of a session. */
|
|
151
|
+
export function renderSurface(graph, ids) {
|
|
152
|
+
if (ids.length === 0) return ''
|
|
153
|
+
const lines = [
|
|
154
|
+
`[${SOURCE_KIND}] Memory of earlier sessions in this project (${Object.keys(graph.nodes).length} nodes). ` +
|
|
155
|
+
'Each line is one node: id, label, gist. Call recall(id) for the verbatim source and its neighbours. ' +
|
|
156
|
+
'Treat this as background; do not restate it.'
|
|
157
|
+
]
|
|
158
|
+
for (const id of ids) lines.push(line(id, graph.nodes[id]))
|
|
159
|
+
return lines.join('\n')
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
/** `[m0 user] ...` transcript the builder reads; each message capped so one huge paste cannot eat the call. */
|
|
163
|
+
export function transcriptForBuilder(messages, maxChars = 2000) {
|
|
164
|
+
return messages.map((m, i) => {
|
|
165
|
+
const text = m.text.length > maxChars ? `${m.text.slice(0, maxChars)}\n…[${m.text.length - maxChars} more chars]` : m.text
|
|
166
|
+
return `[m${i} ${m.role}]\n${text}`
|
|
167
|
+
}).join('\n\n')
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
export function builderInstruction(graph) {
|
|
171
|
+
const existing = Object.entries(graph.nodes).map(([id, n]) => `${id}: ${n.label}`).join('\n')
|
|
172
|
+
return [
|
|
173
|
+
'You are indexing the conversation span above into a memory graph for later sessions. Output ONE JSON object and nothing else.',
|
|
174
|
+
'',
|
|
175
|
+
'Shape: {"nodes":[{"id":"n12"|null,"label":"...","gist":"...","aliases":["..."],"kind":"decision|fact|task|artifact|open-question","msgs":[0,2]}],"edges":[["n12","n3","uses"]]}',
|
|
176
|
+
'',
|
|
177
|
+
'Rules:',
|
|
178
|
+
'- One node per decision, fact, task, artifact (file, tool, repo) or open question worth remembering later. Skip chit-chat and anything already obvious from the labels below unless it changed.',
|
|
179
|
+
'- label: at most 6 words, the name someone would search for. gist: one line under 120 characters, what is true now and why.',
|
|
180
|
+
'- aliases: other words a future message might use for this node, including the other language if the conversation mixes languages. Be precise; matching is by word overlap.',
|
|
181
|
+
'- msgs: indices of the [mN] messages the node is drawn from. Required, never empty.',
|
|
182
|
+
'- id: reuse an existing id below when the node is the same thing (update its gist); null for a new node.',
|
|
183
|
+
`- edges: [from, to, relation] with relation in ${RELATIONS.join(', ')}. For a changed decision add [new, old, "supersedes"]. Use existing ids where possible; refer to new nodes by their label in place of an id.`,
|
|
184
|
+
'- Keep file paths, commands, identifiers and numbers exact.',
|
|
185
|
+
'',
|
|
186
|
+
existing ? `Existing nodes:\n${existing}` : 'Existing nodes: (none)'
|
|
187
|
+
].join('\n')
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/** Complete top-level `{...}` objects inside the array that opens at `open`; an unfinished last one is dropped. */
|
|
191
|
+
function objectsInArray(text, open) {
|
|
192
|
+
const out = []
|
|
193
|
+
let depth = 0
|
|
194
|
+
let start = -1
|
|
195
|
+
let inString = false
|
|
196
|
+
for (let i = open + 1; i < text.length; i++) {
|
|
197
|
+
const ch = text[i]
|
|
198
|
+
if (inString) {
|
|
199
|
+
if (ch === '\\') i++
|
|
200
|
+
else if (ch === '"') inString = false
|
|
201
|
+
continue
|
|
202
|
+
}
|
|
203
|
+
if (ch === '"') inString = true
|
|
204
|
+
else if (ch === '{' || ch === '[') { if (depth++ === 0 && ch === '{') start = i }
|
|
205
|
+
else if (ch === '}' || ch === ']') {
|
|
206
|
+
if (depth === 0) break
|
|
207
|
+
if (--depth === 0 && ch === '}' && start >= 0) { out.push(text.slice(start, i + 1)); start = -1 }
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
return out
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
/**
|
|
214
|
+
* Tolerant extraction of the builder's JSON. Handles code fences, prose around it, `<think>` blocks,
|
|
215
|
+
* trailing commas, and output cut off mid-way (every complete node object is kept).
|
|
216
|
+
* `undefined` when there is no `"nodes"` array at all.
|
|
217
|
+
*/
|
|
218
|
+
export function parseBuilderOutput(text) {
|
|
219
|
+
const clean = String(text ?? '').replace(/<think>[\s\S]*?(?:<\/think>|$)/g, '')
|
|
220
|
+
const at = clean.search(/"nodes"\s*:\s*\[/)
|
|
221
|
+
if (at < 0) return undefined
|
|
222
|
+
const nodes = []
|
|
223
|
+
for (const raw of objectsInArray(clean, clean.indexOf('[', at))) {
|
|
224
|
+
try { nodes.push(JSON.parse(raw.replace(/,\s*([}\]])/g, '$1'))) } catch { /* skip a malformed node */ }
|
|
225
|
+
}
|
|
226
|
+
const edgesAt = clean.search(/"edges"\s*:/)
|
|
227
|
+
const edges = edgesAt < 0 ? [] : [...clean.slice(edgesAt).matchAll(/\[\s*"([^"]+)"\s*,\s*"([^"]+)"\s*,\s*"([^"]+)"\s*\]/g)].map((m) => [m[1], m[2], m[3]])
|
|
228
|
+
return {
|
|
229
|
+
nodes: nodes.filter((n) => n && typeof n.label === 'string' && n.label.trim() && Array.isArray(n.msgs) && n.msgs.length > 0),
|
|
230
|
+
edges
|
|
231
|
+
}
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
/**
|
|
235
|
+
* Apply a builder delta. New nodes get ids; existing ones are updated in place (gist replaced,
|
|
236
|
+
* aliases unioned, provenance appended). Edges may name new nodes by label. Returns the ids
|
|
237
|
+
* touched with the message indices they cite, so the caller can store verbatim text.
|
|
238
|
+
*/
|
|
239
|
+
export function mergeDelta(graph, delta, { session, turn, now }) {
|
|
240
|
+
const byLabel = new Map()
|
|
241
|
+
const touched = []
|
|
242
|
+
for (const n of delta.nodes) {
|
|
243
|
+
let id = typeof n.id === 'string' && graph.nodes[n.id] ? n.id : undefined
|
|
244
|
+
if (!id) {
|
|
245
|
+
const existing = Object.entries(graph.nodes).find(([, x]) => x.label.toLowerCase() === n.label.trim().toLowerCase())
|
|
246
|
+
id = existing ? existing[0] : `n${graph.nextId++}`
|
|
247
|
+
}
|
|
248
|
+
const prev = graph.nodes[id]
|
|
249
|
+
const aliases = [...new Set([...(prev?.aliases ?? []), ...(Array.isArray(n.aliases) ? n.aliases : [])].map((a) => String(a).trim()).filter(Boolean))]
|
|
250
|
+
graph.nodes[id] = {
|
|
251
|
+
label: n.label.trim(),
|
|
252
|
+
gist: String(n.gist ?? prev?.gist ?? '').trim().slice(0, 200),
|
|
253
|
+
aliases,
|
|
254
|
+
kind: KINDS.includes(n.kind) ? n.kind : prev?.kind ?? 'fact',
|
|
255
|
+
src: [...(prev?.src ?? []), { session, turn, at: now }],
|
|
256
|
+
updated: now,
|
|
257
|
+
hits: prev?.hits ?? 0
|
|
258
|
+
}
|
|
259
|
+
byLabel.set(n.label.trim().toLowerCase(), id)
|
|
260
|
+
if (typeof n.id === 'string') byLabel.set(n.id, id)
|
|
261
|
+
touched.push({ id, msgs: n.msgs.filter((i) => Number.isInteger(i) && i >= 0), isNew: !prev })
|
|
262
|
+
}
|
|
263
|
+
const resolve = (ref) => graph.nodes[ref] ? ref : byLabel.get(ref) ?? byLabel.get(String(ref).toLowerCase())
|
|
264
|
+
for (const [from, to, relation] of delta.edges) {
|
|
265
|
+
const a = resolve(from)
|
|
266
|
+
const b = resolve(to)
|
|
267
|
+
if (!a || !b || a === b || !RELATIONS.includes(relation)) continue
|
|
268
|
+
if (!graph.edges.some(([x, y, r]) => x === a && y === b && r === relation)) graph.edges.push([a, b, relation])
|
|
269
|
+
}
|
|
270
|
+
return touched
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
/**
|
|
274
|
+
* Pull the human/assistant exchange out of dsh session events in surface order.
|
|
275
|
+
* @param nodes surface seqs; @param eventAt session lookup; @param afterSeq only events past this seq.
|
|
276
|
+
* @returns { messages: [{ seq, role, text }], lastSeq, userTurns }
|
|
277
|
+
*/
|
|
278
|
+
export function collectSpan(nodes, eventAt, afterSeq = -1) {
|
|
279
|
+
const messages = []
|
|
280
|
+
let lastSeq = afterSeq
|
|
281
|
+
let userTurns = 0
|
|
282
|
+
for (const seq of nodes) {
|
|
283
|
+
if (seq <= afterSeq) continue
|
|
284
|
+
const event = eventAt(seq)
|
|
285
|
+
if (!event) continue
|
|
286
|
+
lastSeq = Math.max(lastSeq, seq)
|
|
287
|
+
if (event.type === 'user/message' && event.data?.source?.kind === 'user') {
|
|
288
|
+
const text = textOf(event.data.content)
|
|
289
|
+
if (text) { messages.push({ seq, role: 'user', text }); userTurns++ }
|
|
290
|
+
} else if (event.type === 'assistant/message') {
|
|
291
|
+
const text = textOf(event.data?.message?.content)
|
|
292
|
+
if (text) messages.push({ seq, role: 'assistant', text })
|
|
293
|
+
}
|
|
294
|
+
}
|
|
295
|
+
return { messages, lastSeq, userTurns }
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
function textOf(content) {
|
|
299
|
+
if (!Array.isArray(content)) return ''
|
|
300
|
+
return content.filter((b) => b?.type === 'text' && typeof b.text === 'string').map((b) => b.text).join('\n').trim()
|
|
301
|
+
}
|
|
302
|
+
|
|
303
|
+
// ---------- folding: replace old turns of the current chat with a table of contents ----------
|
|
304
|
+
|
|
305
|
+
/** Injected context kinds that must survive a fold (carried into the fold message verbatim). */
|
|
306
|
+
export const KEEP_KINDS = ['skill-catalog', 'runtime-context']
|
|
307
|
+
|
|
308
|
+
const isHuman = (event) => event?.type === 'user/message' && event.data?.source?.kind === 'user'
|
|
309
|
+
export const isFold = (event) => event?.type === 'user/message' && event.data?.source?.kind === SOURCE_KIND && event.data.source.fold === true
|
|
310
|
+
|
|
311
|
+
function toolDelta(event) {
|
|
312
|
+
if (event?.type === 'assistant/message') return (event.data?.message?.content ?? []).filter((b) => b.type === 'tool-call').length
|
|
313
|
+
return event?.type === 'tool/result' ? -1 : 0
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
/**
|
|
317
|
+
* Choose the surface range to fold: everything after the system prompt up to (not including) the
|
|
318
|
+
* human prompt that starts the last `keepTurns` turns. Only content already indexed (seq <= maxSeq)
|
|
319
|
+
* is folded, and the cut never splits a tool call from its result.
|
|
320
|
+
* @returns {{ startSeq, endSeq, shadowedSeqs } | undefined}
|
|
321
|
+
*/
|
|
322
|
+
export function planFold(nodes, eventAt, { keepTurns = 2, maxSeq = Infinity } = {}) {
|
|
323
|
+
const first = eventAt(nodes[0])?.type === 'system/message' ? 1 : 0
|
|
324
|
+
const humans = []
|
|
325
|
+
for (let i = first; i < nodes.length; i++) if (isHuman(eventAt(nodes[i]))) humans.push(i)
|
|
326
|
+
for (let h = humans.length - keepTurns; h >= 1; h--) {
|
|
327
|
+
const cut = humans[h]
|
|
328
|
+
const range = nodes.slice(first, cut)
|
|
329
|
+
if (!range.some((seq) => isHuman(eventAt(seq)))) return undefined
|
|
330
|
+
if (range.some((seq) => seq > maxSeq && !isFold(eventAt(seq)))) continue
|
|
331
|
+
let open = 0
|
|
332
|
+
for (const seq of nodes.slice(0, cut)) open += toolDelta(eventAt(seq))
|
|
333
|
+
if (open !== 0) continue
|
|
334
|
+
return { startSeq: range[0], endSeq: range.at(-1), shadowedSeqs: range }
|
|
335
|
+
}
|
|
336
|
+
return undefined
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
/** Every human prompt in the session log up to `endSeq`, numbered t1, t2, ... in log order. */
|
|
340
|
+
export function turnIndex(eventAt, endSeq = Infinity) {
|
|
341
|
+
const turns = []
|
|
342
|
+
for (let seq = 0; seq <= endSeq; seq++) {
|
|
343
|
+
const event = eventAt(seq)
|
|
344
|
+
if (!event) break
|
|
345
|
+
if (isHuman(event)) turns.push({ turn: turns.length + 1, seq, text: textOf(event.data.content) })
|
|
346
|
+
}
|
|
347
|
+
return turns
|
|
348
|
+
}
|
|
349
|
+
|
|
350
|
+
/** Verbatim text of turn `n` (its prompt through the step before the next human prompt). */
|
|
351
|
+
export function turnTranscript(eventAt, n, { maxToolChars = 2000 } = {}) {
|
|
352
|
+
let count = 0
|
|
353
|
+
let seq = 0
|
|
354
|
+
for (; ; seq++) {
|
|
355
|
+
const event = eventAt(seq)
|
|
356
|
+
if (!event) return undefined
|
|
357
|
+
if (isHuman(event) && ++count === n) break
|
|
358
|
+
}
|
|
359
|
+
const out = []
|
|
360
|
+
for (let s = seq; ; s++) {
|
|
361
|
+
const event = eventAt(s)
|
|
362
|
+
if (!event || (s > seq && isHuman(event))) break
|
|
363
|
+
if (isHuman(event)) out.push(`**user:**\n${textOf(event.data.content)}`)
|
|
364
|
+
else if (event.type === 'assistant/message') {
|
|
365
|
+
const blocks = event.data?.message?.content ?? []
|
|
366
|
+
const text = textOf(blocks)
|
|
367
|
+
if (text) out.push(`**assistant:**\n${text}`)
|
|
368
|
+
for (const b of blocks) if (b.type === 'tool-call') out.push(`**tool call** ${b.name} ${String(b.arguments ?? '').slice(0, 300)}`)
|
|
369
|
+
} else if (event.type === 'tool/result') {
|
|
370
|
+
const text = textOf(event.data?.message?.content)
|
|
371
|
+
out.push(`**tool result:**\n${text.length > maxToolChars ? `${text.slice(0, maxToolChars)}\n…[${text.length - maxToolChars} more chars]` : text}`)
|
|
372
|
+
}
|
|
373
|
+
}
|
|
374
|
+
return out.join('\n\n')
|
|
375
|
+
}
|
|
376
|
+
|
|
377
|
+
/** Content blocks the fold message must carry: latest standing context of each KEEP_KINDS kind. */
|
|
378
|
+
export function foldKept(shadowedSeqs, eventAt) {
|
|
379
|
+
const kept = new Map()
|
|
380
|
+
for (const seq of shadowedSeqs) {
|
|
381
|
+
const event = eventAt(seq)
|
|
382
|
+
if (isFold(event)) {
|
|
383
|
+
const kinds = event.data.source.keptKinds ?? []
|
|
384
|
+
kinds.forEach((kind, i) => kept.set(kind, event.data.content[i + 1]))
|
|
385
|
+
} else if (event?.type === 'user/message' && KEEP_KINDS.includes(event.data?.source?.kind)) {
|
|
386
|
+
kept.set(event.data.source.kind, { type: 'text', text: textOf(event.data.content) })
|
|
387
|
+
}
|
|
388
|
+
}
|
|
389
|
+
return { kinds: [...kept.keys()], blocks: [...kept.values()].filter(Boolean) }
|
|
390
|
+
}
|
|
391
|
+
|
|
392
|
+
/** The table of contents that replaces the folded turns. */
|
|
393
|
+
export function renderFoldIndex(graph, session, turns, { maxNodes = 40, maxTurns = 60, width = 90 } = {}) {
|
|
394
|
+
const lines = [
|
|
395
|
+
`[${SOURCE_KIND}] Turns t1-t${turns.length} of this conversation are folded to save tokens. They are not lost.`,
|
|
396
|
+
'Below is their table of contents. Before answering anything that depends on their details, call recall with a topic id (n12) for the facts, or a turn id (t7) for the exact messages of that turn. Do not guess folded details.'
|
|
397
|
+
]
|
|
398
|
+
const ids = surfaceNodes(graph, Infinity).filter((id) => (graph.nodes[id].src ?? []).some((s) => s.session === session)).slice(0, maxNodes)
|
|
399
|
+
if (ids.length > 0) {
|
|
400
|
+
lines.push('', 'Topics:')
|
|
401
|
+
for (const id of ids) lines.push(`- ${id} ${graph.nodes[id].label}: ${graph.nodes[id].gist}`)
|
|
402
|
+
}
|
|
403
|
+
lines.push('', 'Turns (what the user asked):')
|
|
404
|
+
const shown = turns.slice(-maxTurns)
|
|
405
|
+
if (shown.length < turns.length) lines.push(`- t1-t${turns.length - shown.length}: earlier turns, recall by id`)
|
|
406
|
+
for (const t of shown) {
|
|
407
|
+
const first = t.text.replace(/\s+/g, ' ').trim()
|
|
408
|
+
lines.push(`- t${t.turn}: ${first.length > width ? `${first.slice(0, width - 1)}…` : first}`)
|
|
409
|
+
}
|
|
410
|
+
return lines.join('\n')
|
|
411
|
+
}
|
package/index.js
ADDED
|
@@ -0,0 +1,396 @@
|
|
|
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 { mkdir, stat, writeFile } from 'node:fs/promises'
|
|
17
|
+
|
|
18
|
+
import { BlockAssembler, createUserMessage } from '@deepseek-ai/dsh-llm'
|
|
19
|
+
import { defineTool } from '@deepseek-ai/dsh-tools'
|
|
20
|
+
|
|
21
|
+
import {
|
|
22
|
+
builderInstruction, collectSpan, emptyGraph, estimateTokens, foldKept, matchNodes, mergeDelta, neighbors, onlyFromSession,
|
|
23
|
+
parseBuilderOutput, planFold, renderFoldIndex, renderHits, renderSurface, SOURCE_KIND, surfaceNodes, transcriptForBuilder,
|
|
24
|
+
turnIndex, turnTranscript
|
|
25
|
+
} from './graph.js'
|
|
26
|
+
import { appendSource, loadGraph, readSource, saveGraph } from './store.js'
|
|
27
|
+
|
|
28
|
+
export const name = 'context-graph'
|
|
29
|
+
export const inject = ['tools']
|
|
30
|
+
|
|
31
|
+
const PURPOSE = 'context-graph'
|
|
32
|
+
|
|
33
|
+
const DEFAULTS = {
|
|
34
|
+
dir: '.context-graph',
|
|
35
|
+
buildEveryTurns: 4,
|
|
36
|
+
buildMinChars: 400,
|
|
37
|
+
maxHits: 5,
|
|
38
|
+
inlineMaxChars: 1200,
|
|
39
|
+
surfaceMaxNodes: 40,
|
|
40
|
+
builderMaxTokens: 8192,
|
|
41
|
+
provider: '',
|
|
42
|
+
model: '',
|
|
43
|
+
fold: true,
|
|
44
|
+
foldAtTokens: 24000,
|
|
45
|
+
keepTurns: 2
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
const textOf = (content) => (Array.isArray(content) ? content : []).filter((b) => b?.type === 'text').map((b) => b.text).join('\n').trim()
|
|
49
|
+
|
|
50
|
+
export function apply(ctx, config = {}) {
|
|
51
|
+
const cfg = { ...DEFAULTS, ...config }
|
|
52
|
+
const sessions = new Map()
|
|
53
|
+
const graphCache = new Map()
|
|
54
|
+
const meter = {
|
|
55
|
+
main: { requests: 0, input: 0, cacheRead: 0, cacheWrite: 0, output: 0 },
|
|
56
|
+
builder: { requests: 0, input: 0, cacheRead: 0, cacheWrite: 0, output: 0 },
|
|
57
|
+
builds: 0,
|
|
58
|
+
folds: 0,
|
|
59
|
+
foldSaved: 0,
|
|
60
|
+
injected: 0,
|
|
61
|
+
injectedTokens: 0,
|
|
62
|
+
recalls: 0
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
const state = (sid) => {
|
|
66
|
+
let st = sessions.get(sid)
|
|
67
|
+
if (!st) { st = { lastBuiltSeq: -1, building: false, surfaceSent: false }; sessions.set(sid, st) }
|
|
68
|
+
return st
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
function dirFor(agent) {
|
|
72
|
+
const base = agent.options?.cwd ?? agent.session.header?.cwd ?? process.cwd()
|
|
73
|
+
return isAbsolute(cfg.dir) ? cfg.dir : join(base, cfg.dir)
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/** Graph read with an mtime check so other sessions' builds show up without a restart. */
|
|
77
|
+
async function getGraph(dir) {
|
|
78
|
+
let mtimeMs = 0
|
|
79
|
+
try { mtimeMs = (await stat(join(dir, 'graph.json'))).mtimeMs } catch { return emptyGraph() }
|
|
80
|
+
const cached = graphCache.get(dir)
|
|
81
|
+
if (cached && cached.mtimeMs === mtimeMs) return cached.graph
|
|
82
|
+
const graph = await loadGraph(dir)
|
|
83
|
+
graphCache.set(dir, { mtimeMs, graph })
|
|
84
|
+
return graph
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
function resolveTarget(agent) {
|
|
88
|
+
if (cfg.provider && cfg.model) return { provider: cfg.provider, model: cfg.model }
|
|
89
|
+
const routed = agent.session.requestHeader()?.config
|
|
90
|
+
if (routed?.provider && routed?.model) return { provider: routed.provider, model: routed.model }
|
|
91
|
+
const { provider, model } = agent.options ?? {}
|
|
92
|
+
return provider && model ? { provider, model } : undefined
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
function surfaceAlreadyOnLog(session) {
|
|
96
|
+
return session.surface.nodes.some((seq) => {
|
|
97
|
+
const event = session.eventAt(seq)
|
|
98
|
+
return event?.type === 'user/message' && event.data?.source?.kind === SOURCE_KIND && event.data.source.layer === 'surface'
|
|
99
|
+
})
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
// ---------- builder ----------
|
|
103
|
+
const isSubagent = (agent) => agent.options?.origin === 'subagent' || agent.session.header?.origin === 'subagent'
|
|
104
|
+
|
|
105
|
+
async function build(agent, { force = false, turn = null } = {}) {
|
|
106
|
+
const session = agent.session
|
|
107
|
+
const sid = String(session.id)
|
|
108
|
+
const st = state(sid)
|
|
109
|
+
if (st.building) return { status: 'busy' }
|
|
110
|
+
// ponytail: subagent chatter stays out of the project graph; revisit if delegated work holds decisions worth keeping.
|
|
111
|
+
if (isSubagent(agent)) return { status: 'skipped', reason: 'subagent session' }
|
|
112
|
+
st.building = true
|
|
113
|
+
try {
|
|
114
|
+
const span = collectSpan(session.surface.nodes, (seq) => session.eventAt(seq), st.lastBuiltSeq)
|
|
115
|
+
const chars = span.messages.reduce((n, m) => n + m.text.length, 0)
|
|
116
|
+
if (span.messages.length === 0) return { status: 'nothing', reason: 'no new messages since the last build' }
|
|
117
|
+
if (!force && (span.userTurns < cfg.buildEveryTurns || chars < cfg.buildMinChars)) {
|
|
118
|
+
return { status: 'skipped', reason: `${span.userTurns}/${cfg.buildEveryTurns} human turns, ${chars}/${cfg.buildMinChars} chars` }
|
|
119
|
+
}
|
|
120
|
+
const llm = ctx.get('llm')
|
|
121
|
+
if (!llm) return { status: 'unavailable', reason: 'no llm service in this composition' }
|
|
122
|
+
const target = resolveTarget(agent)
|
|
123
|
+
if (!target) return { status: 'unavailable', reason: 'no provider/model routed yet' }
|
|
124
|
+
const dir = dirFor(agent)
|
|
125
|
+
const graph = await loadGraph(dir)
|
|
126
|
+
const prompt = `${transcriptForBuilder(span.messages)}\n\n${builderInstruction(graph)}`
|
|
127
|
+
const assembler = new BlockAssembler()
|
|
128
|
+
for await (const chunk of llm.stream({
|
|
129
|
+
provider: target.provider,
|
|
130
|
+
model: target.model,
|
|
131
|
+
messages: [{ role: 'user', content: [{ type: 'text', text: prompt }] }],
|
|
132
|
+
maxTokens: cfg.builderMaxTokens,
|
|
133
|
+
sessionId: session.id,
|
|
134
|
+
purpose: PURPOSE
|
|
135
|
+
})) assembler.push(chunk)
|
|
136
|
+
const finish = assembler.finish
|
|
137
|
+
if (finish?.kind === 'error' || finish?.kind === 'aborted') throw new Error(finish.failure?.message ?? finish.kind)
|
|
138
|
+
const blocks = assembler.blocks()
|
|
139
|
+
const answer = textOf(blocks)
|
|
140
|
+
// Some thinking models put everything, JSON included, into reasoning blocks.
|
|
141
|
+
const reasoning = blocks.filter((b) => b?.type === 'reasoning').map((b) => b.text).join('\n')
|
|
142
|
+
const delta = parseBuilderOutput(answer) ?? parseBuilderOutput(reasoning)
|
|
143
|
+
if (!delta || (delta.nodes.length === 0 && finish?.kind === 'max-tokens')) {
|
|
144
|
+
const saved = join(dir, 'last-builder-output.txt')
|
|
145
|
+
await mkdir(dir, { recursive: true })
|
|
146
|
+
await writeFile(saved, `finish: ${finish?.kind}\n\n--- answer ---\n${answer}\n\n--- reasoning ---\n${reasoning}\n`, 'utf8')
|
|
147
|
+
const why = finish?.kind === 'max-tokens'
|
|
148
|
+
? `the model ran out of output tokens (builderMaxTokens ${cfg.builderMaxTokens}) before finishing`
|
|
149
|
+
: 'builder output was not the expected JSON'
|
|
150
|
+
return { status: 'failed', reason: `${why}; raw output saved to ${saved}` }
|
|
151
|
+
}
|
|
152
|
+
// Reversibility rule: a node is written only when it cites text we can store verbatim.
|
|
153
|
+
delta.nodes = delta.nodes.filter((n) => n.msgs.some((i) => span.messages[i]))
|
|
154
|
+
const now = new Date().toISOString()
|
|
155
|
+
const touched = mergeDelta(graph, delta, { session: sid, turn, now })
|
|
156
|
+
for (const { id, msgs } of touched) {
|
|
157
|
+
const cited = msgs.map((i) => span.messages[i]).filter(Boolean)
|
|
158
|
+
if (cited.length > 0) await appendSource(dir, id, { session: sid, turn, at: now, messages: cited })
|
|
159
|
+
}
|
|
160
|
+
await saveGraph(dir, graph)
|
|
161
|
+
st.lastBuiltSeq = span.lastSeq
|
|
162
|
+
meter.builds++
|
|
163
|
+
return { status: 'built', nodes: touched.length, newNodes: touched.filter((t) => t.isNew).length, totalNodes: Object.keys(graph.nodes).length, edges: graph.edges.length, dir }
|
|
164
|
+
} catch (error) {
|
|
165
|
+
console.error('context-graph: build failed (non-fatal)', error)
|
|
166
|
+
return { status: 'failed', reason: String(error?.message ?? error) }
|
|
167
|
+
} finally {
|
|
168
|
+
st.building = false
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
ctx.on('agent/turn-stopping', (payload) => {
|
|
173
|
+
// Fire and forget: the build must never delay the turn's close.
|
|
174
|
+
void build(payload.agent, { turn: payload.turn })
|
|
175
|
+
})
|
|
176
|
+
|
|
177
|
+
// ---------- fold: replace old turns of this chat with a table of contents ----------
|
|
178
|
+
function rangeTokens(session, seqs) {
|
|
179
|
+
const wanted = new Set(seqs)
|
|
180
|
+
try {
|
|
181
|
+
const nodes = ctx.get('tokenMeter')?.measure(session)?.nodes
|
|
182
|
+
if (Array.isArray(nodes)) return nodes.filter((n) => wanted.has(n.seq)).reduce((sum, n) => sum + (n.tokens ?? n.heuristicTokens ?? 0), 0)
|
|
183
|
+
} catch { /* fall back to the estimate */ }
|
|
184
|
+
return seqs.reduce((sum, seq) => sum + estimateTokens(JSON.stringify(session.eventAt(seq)?.data ?? '')), 0)
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
async function fold(agent, { force = false } = {}) {
|
|
188
|
+
const session = agent.session
|
|
189
|
+
const sid = String(session.id)
|
|
190
|
+
const eventAt = (seq) => session.eventAt(seq)
|
|
191
|
+
const plan = planFold(session.surface.nodes, eventAt, { keepTurns: cfg.keepTurns, maxSeq: state(sid).lastBuiltSeq })
|
|
192
|
+
if (!plan) return { status: 'skipped', reason: `nothing indexed outside the last ${cfg.keepTurns} turns yet` }
|
|
193
|
+
const before = rangeTokens(session, plan.shadowedSeqs)
|
|
194
|
+
if (!force && before < cfg.foldAtTokens) return { status: 'skipped', reason: `foldable part is ~${before} tokens, folds at ${cfg.foldAtTokens}` }
|
|
195
|
+
const turns = turnIndex(eventAt, plan.endSeq)
|
|
196
|
+
const index = renderFoldIndex(await getGraph(dirFor(agent)), sid, turns, { maxNodes: cfg.surfaceMaxNodes })
|
|
197
|
+
const kept = foldKept(plan.shadowedSeqs, eventAt)
|
|
198
|
+
const after = estimateTokens([index, ...kept.blocks.map((b) => b.text ?? '')].join('\n'))
|
|
199
|
+
// Never-worse gate: a fold must at least halve what it replaces, or it is not worth breaking the cache.
|
|
200
|
+
if (after * 2 > before) return { status: 'skipped', reason: `table of contents (~${after}) is not under half of the ~${before} tokens it would replace` }
|
|
201
|
+
const message = createUserMessage({
|
|
202
|
+
content: [{ type: 'text', text: index }, ...kept.blocks],
|
|
203
|
+
source: { kind: SOURCE_KIND, fold: true, keptKinds: kept.kinds, foldedTurns: turns.length, foldedTokens: before }
|
|
204
|
+
})
|
|
205
|
+
session.append('user/message', message, {
|
|
206
|
+
surfaceOp: { op: 'replace', startSeq: plan.startSeq, endSeq: plan.endSeq },
|
|
207
|
+
sourceEventSeqs: [...plan.shadowedSeqs]
|
|
208
|
+
})
|
|
209
|
+
meter.folds++
|
|
210
|
+
meter.foldSaved += before - after
|
|
211
|
+
return { status: 'folded', turns: turns.length, before, after }
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
// ---------- matcher ----------
|
|
215
|
+
ctx.on('agent/pre-step', async (payload, next) => {
|
|
216
|
+
const agent = payload.agent
|
|
217
|
+
const prompt = payload.messages.filter((m) => m.source?.kind === 'user').map((m) => textOf(m.content)).join('\n')
|
|
218
|
+
// Fold only at the start of a human turn: the previous turn is closed, so no tool call is open.
|
|
219
|
+
if (cfg.fold && prompt && !isSubagent(agent)) {
|
|
220
|
+
try { await fold(agent) } catch (error) { console.error('context-graph: fold failed (non-fatal)', error) }
|
|
221
|
+
}
|
|
222
|
+
const decision = await next()
|
|
223
|
+
if (decision.kind !== 'enter') return decision
|
|
224
|
+
try {
|
|
225
|
+
if (isSubagent(agent) || !prompt) return decision
|
|
226
|
+
const dir = dirFor(agent)
|
|
227
|
+
const graph = await getGraph(dir)
|
|
228
|
+
if (Object.keys(graph.nodes).length === 0) return decision
|
|
229
|
+
const sid = String(agent.session.id)
|
|
230
|
+
const st = state(sid)
|
|
231
|
+
const sessionCompacted = agent.session.surface.replaceGeneration > 0
|
|
232
|
+
const parts = []
|
|
233
|
+
let layer
|
|
234
|
+
if (!st.surfaceSent) {
|
|
235
|
+
st.surfaceSent = true
|
|
236
|
+
// Nodes that only come from this very session are still in its context: no need to repeat them.
|
|
237
|
+
const ids = surfaceNodes(graph, cfg.surfaceMaxNodes).filter((id) => sessionCompacted || !onlyFromSession(graph.nodes[id], sid))
|
|
238
|
+
if (ids.length > 0 && !surfaceAlreadyOnLog(agent.session)) {
|
|
239
|
+
parts.push(renderSurface(graph, ids))
|
|
240
|
+
layer = 'surface'
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
const hits = matchNodes(graph, prompt, { max: cfg.maxHits, session: sid, sessionCompacted })
|
|
244
|
+
let inline
|
|
245
|
+
if (hits.length === 1 || (hits.length > 1 && hits[0].score >= 2 * hits[1].score)) {
|
|
246
|
+
const text = await readSource(dir, hits[0].id)
|
|
247
|
+
if (text && text.length <= cfg.inlineMaxChars) inline = { id: hits[0].id, text }
|
|
248
|
+
}
|
|
249
|
+
const block = renderHits(graph, hits, { inline })
|
|
250
|
+
if (block) parts.push(block)
|
|
251
|
+
if (parts.length === 0) return decision
|
|
252
|
+
const text = parts.join('\n\n')
|
|
253
|
+
meter.injected++
|
|
254
|
+
meter.injectedTokens += estimateTokens(text)
|
|
255
|
+
const message = createUserMessage({ content: [{ type: 'text', text }], source: layer ? { kind: SOURCE_KIND, layer } : { kind: SOURCE_KIND } })
|
|
256
|
+
return { ...decision, messages: [...decision.messages, message] }
|
|
257
|
+
} catch (error) {
|
|
258
|
+
console.error('context-graph: matcher failed (non-fatal)', error)
|
|
259
|
+
return decision
|
|
260
|
+
}
|
|
261
|
+
})
|
|
262
|
+
|
|
263
|
+
// ---------- meter ----------
|
|
264
|
+
ctx.on('llm/stream', (options, next) => {
|
|
265
|
+
const inner = next()
|
|
266
|
+
const bucket = options.purpose === PURPOSE ? meter.builder : meter.main
|
|
267
|
+
async function* tracked() {
|
|
268
|
+
try {
|
|
269
|
+
for await (const chunk of inner) {
|
|
270
|
+
if (chunk?.type === 'usage' && chunk.usage) {
|
|
271
|
+
bucket.input += chunk.usage.inputTokens ?? 0
|
|
272
|
+
bucket.cacheRead += chunk.usage.cacheReadTokens ?? 0
|
|
273
|
+
bucket.cacheWrite += chunk.usage.cacheWriteTokens ?? 0
|
|
274
|
+
bucket.output += chunk.usage.outputTokens ?? 0
|
|
275
|
+
}
|
|
276
|
+
yield chunk
|
|
277
|
+
}
|
|
278
|
+
} finally {
|
|
279
|
+
bucket.requests++
|
|
280
|
+
}
|
|
281
|
+
}
|
|
282
|
+
return tracked()
|
|
283
|
+
})
|
|
284
|
+
|
|
285
|
+
// ---------- recall tool ----------
|
|
286
|
+
ctx.tools.register(defineTool({
|
|
287
|
+
name: 'recall',
|
|
288
|
+
description: [
|
|
289
|
+
'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.',
|
|
290
|
+
'Call it when a gist is relevant but not precise enough to answer. Never invent an id; only use ids you were shown.'
|
|
291
|
+
].join(' '),
|
|
292
|
+
parameters: {
|
|
293
|
+
id: { type: 'string', required: true, description: 'Topic id such as n17, or turn id such as t7.' },
|
|
294
|
+
depth: { type: 'integer', description: '0 (default): this node only. 1: also include each neighbour\'s gist.' }
|
|
295
|
+
},
|
|
296
|
+
output: {
|
|
297
|
+
schema: {
|
|
298
|
+
type: 'object',
|
|
299
|
+
additionalProperties: false,
|
|
300
|
+
properties: {
|
|
301
|
+
status: { type: 'string', enum: ['ok', 'unknown'], required: true },
|
|
302
|
+
text: { type: 'string', required: true }
|
|
303
|
+
}
|
|
304
|
+
},
|
|
305
|
+
render: (_args, value) => [{ type: 'text', text: value.text }]
|
|
306
|
+
},
|
|
307
|
+
async execute(args, exec) {
|
|
308
|
+
const agent = exec.agent
|
|
309
|
+
if (!agent?.session) return { status: 'unknown', text: 'recall is unavailable: no session attached to this call.' }
|
|
310
|
+
const id = String(args.id ?? '').trim()
|
|
311
|
+
const turn = /^t(\d+)$/.exec(id)
|
|
312
|
+
if (turn) {
|
|
313
|
+
const text = turnTranscript((seq) => agent.session.eventAt(seq), Number(turn[1]))
|
|
314
|
+
if (text === undefined) return { status: 'unknown', text: `No turn ${id} in this conversation.` }
|
|
315
|
+
meter.recalls++
|
|
316
|
+
return { status: 'ok', text: `# ${id} (verbatim)\n\n${text}` }
|
|
317
|
+
}
|
|
318
|
+
const dir = dirFor(agent)
|
|
319
|
+
const graph = await getGraph(dir)
|
|
320
|
+
const node = graph.nodes[id]
|
|
321
|
+
if (!node) return { status: 'unknown', text: `No node "${id}" in this project's context graph. Only use ids shown in a [context-graph] block.` }
|
|
322
|
+
meter.recalls++
|
|
323
|
+
node.hits = (node.hits ?? 0) + 1
|
|
324
|
+
saveGraph(dir, graph).catch((error) => console.error('context-graph: hit count save failed', error))
|
|
325
|
+
const lines = [`# ${id} ${node.label}`, `${node.kind}. ${node.gist}`, '']
|
|
326
|
+
const source = await readSource(dir, id)
|
|
327
|
+
lines.push(source ? source.trim() : '(no verbatim source stored for this node)')
|
|
328
|
+
const links = neighbors(graph, id)
|
|
329
|
+
if (links.length > 0) {
|
|
330
|
+
lines.push('', 'Neighbours:')
|
|
331
|
+
for (const link of links) {
|
|
332
|
+
const other = graph.nodes[link.id]
|
|
333
|
+
const arrow = link.direction === 'out' ? `${id} ${link.relation} ${link.id}` : `${link.id} ${link.relation} ${id}`
|
|
334
|
+
lines.push(`- ${arrow}: ${other.label}${args.depth >= 1 ? ` — ${other.gist}` : ''}`)
|
|
335
|
+
}
|
|
336
|
+
}
|
|
337
|
+
return { status: 'ok', text: lines.join('\n') }
|
|
338
|
+
}
|
|
339
|
+
}))
|
|
340
|
+
|
|
341
|
+
// ---------- /context-graph command (nested: only where a human-command surface exists) ----------
|
|
342
|
+
ctx.plugin({
|
|
343
|
+
name: 'context-graph-command',
|
|
344
|
+
inject: ['commands'],
|
|
345
|
+
apply(cmdCtx) {
|
|
346
|
+
cmdCtx.effect(function* () {
|
|
347
|
+
yield cmdCtx.commands.register({
|
|
348
|
+
name: 'context-graph',
|
|
349
|
+
description: 'Project memory graph: /context-graph [stats|build|fold|find <words>]',
|
|
350
|
+
// Without `input`, dsh clients run the bare name and send any typed arguments to the model as chat.
|
|
351
|
+
input: { hint: '[stats|build|fold|find <words>]' },
|
|
352
|
+
async handler(invocation) {
|
|
353
|
+
const [sub = 'stats', ...rest] = invocation.rawInput.trim().split(/\s+/).filter(Boolean)
|
|
354
|
+
const agent = invocation.agent
|
|
355
|
+
if (sub === 'fold') {
|
|
356
|
+
const result = await agent.runMaintenance(async () => {
|
|
357
|
+
await build(agent, { force: true })
|
|
358
|
+
return fold(agent, { force: true })
|
|
359
|
+
})
|
|
360
|
+
if (result.status !== 'folded') return { kind: 'error', text: `Not folded: ${result.reason}` }
|
|
361
|
+
return { kind: 'success', text: `Folded turns t1-t${result.turns}: ~${result.before} tokens replaced by a ~${result.after}-token table of contents.` }
|
|
362
|
+
}
|
|
363
|
+
if (sub === 'build') {
|
|
364
|
+
const result = await agent.runMaintenance(() => build(agent, { force: true }))
|
|
365
|
+
if (result.status !== 'built') return { kind: 'error', text: `Build ${result.status}: ${result.reason ?? ''}`.trim() }
|
|
366
|
+
return { kind: 'success', text: `Indexed ${result.nodes} nodes (${result.newNodes} new); graph now ${result.totalNodes} nodes, ${result.edges} edges at ${result.dir}` }
|
|
367
|
+
}
|
|
368
|
+
const graph = await getGraph(dirFor(agent))
|
|
369
|
+
if (sub === 'find') {
|
|
370
|
+
const hits = matchNodes(graph, rest.join(' '), { max: cfg.maxHits })
|
|
371
|
+
return { kind: 'success', text: hits.length ? renderHits(graph, hits) : 'No matching nodes.' }
|
|
372
|
+
}
|
|
373
|
+
if (sub !== 'stats') return { kind: 'error', text: 'Usage: /context-graph [stats|build|fold|find <words>]' }
|
|
374
|
+
const m = meter.main
|
|
375
|
+
const cached = m.cacheRead + m.cacheWrite
|
|
376
|
+
const hitRate = m.input + cached > 0 ? Math.round((m.cacheRead / (m.input + cached)) * 100) : 0
|
|
377
|
+
const session = agent.session
|
|
378
|
+
const pending = collectSpan(session.surface.nodes, (seq) => session.eventAt(seq), state(String(session.id)).lastBuiltSeq).userTurns
|
|
379
|
+
return {
|
|
380
|
+
kind: 'success',
|
|
381
|
+
text: [
|
|
382
|
+
`Graph: ${Object.keys(graph.nodes).length} nodes, ${graph.edges.length} edges (${dirFor(agent)})`,
|
|
383
|
+
`This chat: ${pending} human turns not indexed yet; auto-index at ${cfg.buildEveryTurns}, or run /context-graph build now.`,
|
|
384
|
+
'Counters below are since the app started:',
|
|
385
|
+
`Builds: ${meter.builds}; builder tokens in/out: ${meter.builder.input + meter.builder.cacheRead + meter.builder.cacheWrite}/${meter.builder.output}`,
|
|
386
|
+
`Folds: ${meter.folds}; ~${meter.foldSaved} input tokens removed from every later request`,
|
|
387
|
+
`Injected blocks: ${meter.injected} (~${meter.injectedTokens} tokens); recalls: ${meter.recalls}`,
|
|
388
|
+
`Main requests: ${m.requests}; input ${m.input} uncached + ${m.cacheRead} cache-read + ${m.cacheWrite} cache-write; cache-hit ${hitRate}%`
|
|
389
|
+
].join('\n')
|
|
390
|
+
}
|
|
391
|
+
}
|
|
392
|
+
})
|
|
393
|
+
}, 'context-graph command')
|
|
394
|
+
}
|
|
395
|
+
})
|
|
396
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,53 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-context-graph",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.2.2",
|
|
4
|
+
"description": "DeepSeek Harness plugin: remembers past conversations as a small graph and folds old turns of a long chat into a table of contents, so fewer input tokens are sent; exact text is recalled on demand",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "index.js",
|
|
7
|
+
"exports": {
|
|
8
|
+
".": "./index.js",
|
|
9
|
+
"./graph": "./graph.js",
|
|
10
|
+
"./package.json": "./package.json"
|
|
11
|
+
},
|
|
12
|
+
"files": [
|
|
13
|
+
"index.js",
|
|
14
|
+
"graph.js",
|
|
15
|
+
"store.js",
|
|
16
|
+
"cordis.patch.yml",
|
|
17
|
+
"README.md",
|
|
18
|
+
"LICENSE"
|
|
19
|
+
],
|
|
20
|
+
"scripts": {
|
|
21
|
+
"test": "node --import ./test/resolve-dsh.mjs --test test/graph.test.js test/fold.test.js test/plugin.test.js"
|
|
22
|
+
},
|
|
23
|
+
"keywords": [
|
|
24
|
+
"dsh-plugin",
|
|
25
|
+
"deepseek-harness",
|
|
26
|
+
"deepseek",
|
|
27
|
+
"memory",
|
|
28
|
+
"context",
|
|
29
|
+
"knowledge-graph"
|
|
30
|
+
],
|
|
31
|
+
"license": "MIT",
|
|
32
|
+
"repository": {
|
|
33
|
+
"type": "git",
|
|
34
|
+
"url": "git+https://github.com/William20100221/dsh-context-graph.git"
|
|
35
|
+
},
|
|
36
|
+
"homepage": "https://github.com/William20100221/dsh-context-graph#readme",
|
|
37
|
+
"bugs": {
|
|
38
|
+
"url": "https://github.com/William20100221/dsh-context-graph/issues"
|
|
39
|
+
},
|
|
40
|
+
"engines": {
|
|
41
|
+
"dsh": ">=0.2.1-rc.5 <0.3.0",
|
|
42
|
+
"node": ">=20"
|
|
43
|
+
},
|
|
44
|
+
"peerDependencies": {
|
|
45
|
+
"@deepseek-ai/dsh-llm": ">=0.2.1-rc.5 <0.3.0",
|
|
46
|
+
"@deepseek-ai/dsh-tools": ">=0.2.1-rc.5 <0.3.0"
|
|
47
|
+
},
|
|
48
|
+
"dsh": {
|
|
49
|
+
"bundle": {
|
|
50
|
+
"patch": "./cordis.patch.yml"
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
}
|
package/store.js
ADDED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* On-disk layout under `<dir>` (default `<workspace>/.context-graph`):
|
|
3
|
+
* graph.json the graph (see graph.js)
|
|
4
|
+
* src/<id>.md verbatim source text of one node, one section appended per build
|
|
5
|
+
* ponytail: last writer wins across concurrent sessions; add a lock file if two agents share a workspace.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
import { mkdir, readFile, rename, writeFile, appendFile } from 'node:fs/promises'
|
|
9
|
+
import { join } from 'node:path'
|
|
10
|
+
|
|
11
|
+
import { emptyGraph, GRAPH_VERSION } from './graph.js'
|
|
12
|
+
|
|
13
|
+
export async function loadGraph(dir) {
|
|
14
|
+
try {
|
|
15
|
+
const graph = JSON.parse(await readFile(join(dir, 'graph.json'), 'utf8'))
|
|
16
|
+
if (graph?.version !== GRAPH_VERSION || typeof graph.nodes !== 'object' || !Array.isArray(graph.edges)) return emptyGraph()
|
|
17
|
+
return graph
|
|
18
|
+
} catch (error) {
|
|
19
|
+
if (error?.code === 'ENOENT') return emptyGraph()
|
|
20
|
+
throw error
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
export async function saveGraph(dir, graph) {
|
|
25
|
+
await mkdir(dir, { recursive: true })
|
|
26
|
+
const target = join(dir, 'graph.json')
|
|
27
|
+
const tmp = `${target}.${process.pid}.tmp`
|
|
28
|
+
await writeFile(tmp, JSON.stringify(graph, null, 1), 'utf8')
|
|
29
|
+
await rename(tmp, target)
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** Append one build's verbatim messages to the node's source file. */
|
|
33
|
+
export async function appendSource(dir, id, { session, turn, at, messages }) {
|
|
34
|
+
await mkdir(join(dir, 'src'), { recursive: true })
|
|
35
|
+
const body = messages.map((m) => `**${m.role}** (seq ${m.seq}):\n\n${m.text}`).join('\n\n')
|
|
36
|
+
await appendFile(join(dir, 'src', `${id}.md`), `## ${at} session ${session} turn ${turn}\n\n${body}\n\n`, 'utf8')
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
export async function readSource(dir, id) {
|
|
40
|
+
try {
|
|
41
|
+
return await readFile(join(dir, 'src', `${id}.md`), 'utf8')
|
|
42
|
+
} catch (error) {
|
|
43
|
+
if (error?.code === 'ENOENT') return undefined
|
|
44
|
+
throw error
|
|
45
|
+
}
|
|
46
|
+
}
|