dsh-context-graph 0.6.2 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,147 @@
1
+ /**
2
+ * Time words in a message: which days it names, and whether it asks about the past. Pure. Days are
3
+ * the machine's local calendar days, computed with calendar arithmetic, so a daylight-saving change
4
+ * can no longer shift a range by an hour (#25).
5
+ */
6
+
7
+ const dayAt = (now, offset) => new Date(now.getFullYear(), now.getMonth(), now.getDate() + offset)
8
+ const iso = (d) => `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`
9
+
10
+ /** A real calendar date, or undefined: "2026-02-31" is not March 3 (#25). */
11
+ function date(y, m, d) {
12
+ const x = new Date(y, m - 1, d)
13
+ return x.getFullYear() === y && x.getMonth() === m - 1 && x.getDate() === d ? x : undefined
14
+ }
15
+
16
+ /** A date named without a year: this year's, or last year's when this year's is still ahead. */
17
+ function pastDate(now, year, month, d) {
18
+ const x = date(year ? +year : now.getFullYear(), month, d)
19
+ return x && !year && x > now ? date(now.getFullYear() - 1, month, d) : x
20
+ }
21
+
22
+ const oneDay = (d) => ({ from: d, to: dayAt(d, 1), label: iso(d) })
23
+
24
+ // Chinese time words count only where they are words: 目前天气 is not 前天, 登上月球 is not 上月,
25
+ // 这周期 is not 这周 (#25). 大前天 is not 前天, 上上周 is not 上周, 二十天前 is not 十天前 (#84).
26
+ // 两天前端 is frontend and 三天前后 about three days, not 2 or 3 days ago (review of #84); 3天前端口
27
+ // and 3天前后端 still are (second review).
28
+ const ZH = {
29
+ threeDaysAgo: /大前天/,
30
+ dayBefore: /(?<![目之以提从先此日])前天(?!气)/,
31
+ yesterday: /昨天|昨日|昨晚/,
32
+ today: /今天|今早|今日|今晚/,
33
+ ago: /(?<![这那了续一两二三四五六七八九十\d])(\d+|[一两二三四五六七八九十])\s*(天|周|个?星期|个?礼拜)前(?!端(?!口)|后(?![端台]))/,
34
+ weekBeforeLast: /上上(?:周|个?星期|个?礼拜)/,
35
+ lastWeek: /上周(?![期边围])|上星期|上个星期|上礼拜/,
36
+ thisWeek: /(?:本|这)周(?![期边围到全正长])|这星期|这个星期|本星期/,
37
+ monthBeforeLast: /上上个?月(?![球亮光])/,
38
+ lastMonth: /上个月|(?<![登爬马])上月(?![球亮光])/,
39
+ thisMonth: /本月(?!球)|这个月/
40
+ }
41
+
42
+ // "two days ago", "a week ago", "nov 3", "on monday" (#84). Whole month names only: "market 5" and
43
+ // "decided 3" are not dates. "1.5 weeks ago" is not 5 weeks ago (review of #84).
44
+ const NUMBER = { a: 1, an: 1, one: 1, two: 2, three: 3, four: 4, five: 5, six: 6, seven: 7, eight: 8, nine: 9, ten: 10, 一: 1, 两: 2, 二: 2, 三: 3, 四: 4, 五: 5, 六: 6, 七: 7, 八: 8, 九: 9, 十: 10 }
45
+ const AGO = /\b((?<!\.)\d+|an?|one|two|three|four|five|six|seven|eight|nine|ten) (day|week)s? ago\b/
46
+ const MONTHS = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec']
47
+ const MONTH_DAY = /\b(jan(?:uary)?|feb(?:ruary)?|mar(?:ch)?|apr(?:il)?|may|june?|july?|aug(?:ust)?|sep(?:t(?:ember)?)?|oct(?:ober)?|nov(?:ember)?|dec(?:ember)?)\.? (\d{1,2})(?:st|nd|rd|th)?(?:,? (\d{4}))?\b/
48
+ const ON_MONTH_DAY = new RegExp(`\\bon ${MONTH_DAY.source.slice(2)}`)
49
+ const WEEKDAYS = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday']
50
+ const ON_WEEKDAY = new RegExp(`\\b(?:on|last) (${WEEKDAYS.join('|')})\\b`)
51
+
52
+ /**
53
+ * A from/to range (to exclusive) when the text names a time: yesterday, last night, today, N days or
54
+ * weeks ago, last/this week or month, on monday, nov 3, 2026-11-01, 2025年11月1日, 11月1日, 昨天,
55
+ * 大前天, 三天前, 上周, 上上周 ... `undefined` otherwise. No model call.
56
+ */
57
+ export function parseTimeRange(text, now = new Date()) {
58
+ const s = String(text ?? '').normalize('NFKC').toLowerCase()
59
+ const days = (offset, label, span = 1) => ({ from: dayAt(now, offset), to: dayAt(now, offset + span), label })
60
+ const monday = -((now.getDay() + 6) % 7)
61
+ const weeksAgo = (n) => days(monday - 7 * n, n === 1 ? 'last week' : `${n} weeks ago`, 7)
62
+ const y = now.getFullYear()
63
+ const mo = now.getMonth()
64
+ const monthsAgo = (n, label) => ({ from: new Date(y, mo - n, 1), to: new Date(y, mo - n + 1, 1), label })
65
+ let m
66
+ if ((m = /(?<!\d)(\d{4})-(\d{1,2})-(\d{1,2})(?!\d)/.exec(s))) {
67
+ const d = date(+m[1], +m[2], +m[3])
68
+ if (d) return oneDay(d)
69
+ }
70
+ if ((m = /(?:(\d{4})\s*年\s*)?(\d{1,2})\s*月\s*(\d{1,2})\s*[日号]/.exec(s))) {
71
+ const d = pastDate(now, m[1], +m[2], +m[3])
72
+ if (d) return oneDay(d)
73
+ }
74
+ // "on nov 10" is the day asked about, also in "... on nov 10? I need it for today's standup" (second
75
+ // review), when it is past: "yesterday ... the launch on dec 3" asks about yesterday (third check).
76
+ if ((m = ON_MONTH_DAY.exec(s))) {
77
+ const d = date(m[3] ? +m[3] : now.getFullYear(), MONTHS.indexOf(m[1].slice(0, 3)) + 1, +m[2])
78
+ if (d && d <= now) return oneDay(d)
79
+ }
80
+ if (ZH.threeDaysAgo.test(s)) return days(-3, '3 days ago')
81
+ if (/\bday before yesterday\b/.test(s) || ZH.dayBefore.test(s)) return days(-2, 'the day before yesterday')
82
+ if (/\b(?:yesterday|last night)\b/.test(s) || ZH.yesterday.test(s)) return days(-1, 'yesterday')
83
+ if (/\b(?:today|this morning|this afternoon|this evening|tonight)\b/.test(s) || ZH.today.test(s)) return days(0, 'today')
84
+ if ((m = AGO.exec(s) ?? ZH.ago.exec(s))) {
85
+ const n = NUMBER[m[1]] ?? Number(m[1])
86
+ // "a week ago" is fuzzy: the whole calendar week it falls in, like "last week".
87
+ return m[2] === 'day' || m[2] === '天' ? days(-n, `${n} days ago`) : weeksAgo(n)
88
+ }
89
+ if (ZH.weekBeforeLast.test(s)) return weeksAgo(2)
90
+ if (/\blast week\b/.test(s) || ZH.lastWeek.test(s)) return weeksAgo(1)
91
+ if (/\bthis week\b/.test(s) || ZH.thisWeek.test(s)) return days(monday, 'this week', 7)
92
+ if (ZH.monthBeforeLast.test(s)) return monthsAgo(2, '2 months ago')
93
+ if (/\blast month\b/.test(s) || ZH.lastMonth.test(s)) return monthsAgo(1, 'last month')
94
+ if (/\bthis month\b/.test(s) || ZH.thisMonth.test(s)) return monthsAgo(0, 'this month')
95
+ // After the phrases above: "on monday last week" is last week. The weekday is the latest one before today.
96
+ if ((m = ON_WEEKDAY.exec(s))) return oneDay(dayAt(now, -((now.getDay() - WEEKDAYS.indexOf(m[1]) + 7) % 7 || 7)))
97
+ // Last: a month date is often what the talk was about, "the may 1 launch last week" (review of #84).
98
+ if ((m = MONTH_DAY.exec(s))) {
99
+ const d = pastDate(now, m[3], MONTHS.indexOf(m[1].slice(0, 3)) + 1, +m[2])
100
+ if (d) return oneDay(d)
101
+ }
102
+ return undefined
103
+ }
104
+
105
+ // Phrases that point at shared earlier work, not bare connectives: "before lunch", "what was the
106
+ // score", 今天做了红烧肉 or 帮我总结一下新闻 name a day without asking about this memory.
107
+ // Every phrase names "we"/"you" or the conversation itself: "did we win", "the last time I smoked",
108
+ // 和朋友聊过 are about life, not about this memory (second review of #24).
109
+ const MEMORY_VERB = '(?:decide|decided|discuss|discussed|talk|talked|agree|agreed|choose|chose|pick|picked|fix|fixed|change|changed|try|tried|build|built|write|wrote|set up|settle|settled|say|said|do|did|done|plan|planned|use|used|work on|worked on)'
110
+ // "what did I do wrong" asks for a diagnosis, not for this memory (review of #80).
111
+ const PAST_EN = new RegExp(`\\b(?:(?:did|have|had) we (?:already |ever )?${MEMORY_VERB}|what (?:did|have) (?:we|you|i) (?:just |already )?${MEMORY_VERB}(?! wrong)|last time (?:we|you)|where were we|remind me (?:what|how|why|where|when|which) (?:we|you)|you (?:said|mentioned|suggested))\\b`)
112
+ // A bare "we <verb>" counts only in the past and after a relative word: "the port we picked", "how
113
+ // we fixed" name earlier work; "what should we do tonight", "yesterday we tried a new route" do not.
114
+ // Nor does a story that says how the thing went (review of #80, #84): its clause goes on with is or
115
+ // was and a word of how it went ("the restaurant we tried last night was amazing, find me a similar
116
+ // one"), or it opens the message and asks nothing ("the hotel we picked two days ago cancelled").
117
+ // "the bug we fixed yesterday is back", "the port we picked?" and "the config we changed, show it"
118
+ // ask about earlier work (second review of #80). Within the clause: a pasted transcript with no
119
+ // punctuation must not cost a scan to its end at every clause.
120
+ const PAST_VERB = '(?:decided|discussed|talked|agreed|chose|picked|fixed|changed|tried|built|wrote|set up|settled|said|did|done|planned|used|worked on|left off)'
121
+ const STORY_WORDS = '(?:so |too |really |very |pretty |quite )?(?:amazing|awesome|great|lovely|fun|delicious|beautiful|boring|awful|terrible|horrible|crazy|torn|steep|dry|cancell?ed|expensive)'
122
+ const RELATIVE_EN = new RegExp(`\\b(?:what|which|how|why|where|when|that|the [\\w-]+) we (?:already |just )?${PAST_VERB}\\b(?![^,.;!?]{0,40}\\b(?:is|are|was|were|looks?|seems?) ${STORY_WORDS}\\b)`)
123
+ const STORY_EN = new RegExp(`^the [\\w-]+ we (?:already |just )?${PAST_VERB}\\b(?![^?]*\\b(?:it|them|what|which|show|remind|recap|summari[sz]e|list|(?:is|are) back|anymore|(?:is|are|was|were) broken|failing|fails|failed|wrong|errors?)\\b)[^?]*$`)
124
+ // Nor does a plan in Chinese: 我们要讨论的, 我们打算定的 (#80); 我们主要讨论了 still counts, and so
125
+ // do 会话, 会议, 开会 and 想法, which are no plans (review of #80).
126
+ const PAST_ZH = /上次(?:我们|咱们|你|聊|说|讨论|提|定|做|改)|之前(?:我们|咱们|你|说|聊|讨论|提|定|做)|(?:我们|咱们)(?:之前|刚才|上次)|(?:我们|咱们)(?:(?!(?<!主)要|将|(?<!开)会(?![话议上])|想(?!法)|打算|准备)[^。??!!]){0,8}(?:聊|讨论|定|决定|说|谈)(?:过|了|的)|刚才(?:说|聊|提|讨论)|(?:说|聊|讨论|提到)的那个|(?:聊|讨论|做|干)了(?:什么|哪些|啥)|那天(?:我们|聊|说)/
127
+
128
+ /**
129
+ * Whether a message asks about earlier work in this memory ("what did we do", "last time", 之前我们,
130
+ * 上次). Only such a message gets a day digest: "today I want to learn rust" names a day but is not
131
+ * about memory (#24).
132
+ */
133
+ export function asksAboutPast(text) {
134
+ const s = String(text ?? '').normalize('NFKC').toLowerCase()
135
+ return PAST_EN.test(s) || (RELATIVE_EN.test(s) && !STORY_EN.test(s)) || PAST_ZH.test(s)
136
+ }
137
+
138
+ export const inRange = (iso, range) => Boolean(iso) && new Date(iso) >= range.from && new Date(iso) < range.to
139
+
140
+ /** A chat overlaps the range when it was active at any point inside it. */
141
+ export const chatInRange = (meta, range) => Boolean(meta?.startedAt) && new Date(meta.startedAt) < range.to && new Date(meta.lastActiveAt ?? meta.startedAt) >= range.from
142
+
143
+ /** Local calendar day (YYYY-MM-DD) of a timestamp, the same day recall("YYYY-MM-DD") and "today" search. */
144
+ export function day(value) {
145
+ const d = new Date(value ?? NaN)
146
+ return Number.isNaN(+d) ? '' : iso(d)
147
+ }
@@ -0,0 +1,39 @@
1
+ /**
2
+ * The memory as the tree the Memory tree page draws (#86): a workspace's chats, newest first, each
3
+ * with its topics grouped by kind. Pure and deterministic; the page lays it out itself, because the
4
+ * layout changes as branches open and close.
5
+ */
6
+
7
+ import { degree } from './graph.js'
8
+
9
+ /** Kinds in the order a chat lists them, so each kind's colour forms one band. */
10
+ export const KINDS = ['decision', 'fact', 'task', 'artifact', 'open-question']
11
+
12
+ const kindRank = (kind) => {
13
+ const i = KINDS.indexOf(kind)
14
+ return i < 0 ? KINDS.length : i
15
+ }
16
+
17
+ /**
18
+ * @param chats [{ cid, lastActiveAt, graph }] the chats to draw
19
+ * @param maxTopics a chat's topics listed at most (the most connected); the rest are counted
20
+ * @returns [{ cid, total, topics: [[id, label, kind]], links: [[from, to]] }], newest chat first
21
+ */
22
+ export function memoryTree(chats, { maxTopics = 120 } = {}) {
23
+ const newest = [...chats].sort((a, b) => String(b.lastActiveAt ?? '').localeCompare(String(a.lastActiveAt ?? '')))
24
+ return newest.map((chat) => {
25
+ const { nodes, edges } = chat.graph
26
+ const ids = Object.keys(nodes)
27
+ .map((id) => ({ id, d: degree(chat.graph, id), u: String(nodes[id].updated ?? '') }))
28
+ .sort((a, b) => b.d - a.d || b.u.localeCompare(a.u))
29
+ .slice(0, maxTopics)
30
+ .sort((a, b) => kindRank(nodes[a.id].kind) - kindRank(nodes[b.id].kind) || b.d - a.d || b.u.localeCompare(a.u))
31
+ const kept = new Set(ids.map((t) => t.id))
32
+ return {
33
+ cid: chat.cid,
34
+ total: Object.keys(nodes).length,
35
+ topics: ids.map(({ id }) => [id, nodes[id].label, nodes[id].kind]),
36
+ links: edges.filter(([from, to]) => kept.has(from) && kept.has(to)).map(([from, to]) => [from, to])
37
+ }
38
+ })
39
+ }
@@ -0,0 +1,416 @@
1
+ /**
2
+ * The builder: every few human turns, one auxiliary model call indexes the chat's new messages into
3
+ * its topic graph, refreshes the chat's one-line summary, and stores the messages the topics cite.
4
+ * Runs after a turn closes, never on the critical path of a reply.
5
+ */
6
+
7
+ import { mkdir, writeFile } from 'node:fs/promises'
8
+ import { join } from 'node:path'
9
+
10
+ import { BlockAssembler } from '@deepseek-ai/dsh-llm'
11
+
12
+ import { betterParse, builderPrompt, parseBuilderOutput, planSpan } from '../core/builder.js'
13
+ import { memoryOn, offPoint, walkGaps } from '../core/chat.js'
14
+ import { mergeDelta } from '../core/graph.js'
15
+ import { emptyCounters, usedIn } from '../core/ledger.js'
16
+ import { collectSpan, firstPromptSeq, lastAnswer, mergeGaps, titleOf } from '../core/session.js'
17
+ import { textOf } from '../core/text.js'
18
+ import { chatDir, loadGraph, saveGraph } from '../store/chats.js'
19
+ import { addToLedger } from '../store/ledger.js'
20
+ import { loadMessages, relabelTurns, saveMessages } from '../store/messages.js'
21
+ import { PURPOSE } from './config.js'
22
+
23
+ /** After this many unusable answers in a row for one span, the span is skipped instead of re-sent again. */
24
+ const MAX_FAILED_ANSWERS = 3
25
+
26
+ /** A chat's last-active time is refreshed at most this often on turns that do not index (#40). */
27
+ const TOUCH_MS = 3600000
28
+
29
+ /**
30
+ * A chat with turns too few to index yet is indexed once it has been quiet this long (#42): longer
31
+ * than an ordinary pause between two turns, which would cost an index each (review of #42).
32
+ */
33
+ const QUIET_MS = 1800000
34
+
35
+ /**
36
+ * A chat already indexed once quiet in this cycle is indexed this long after a new chat of its
37
+ * workspace starts, unless it runs again first: a quick side question in another chat costs no
38
+ * index, a chat really left still gets its tail (third check of #42).
39
+ */
40
+ const LEFT_MS = 300000
41
+
42
+ /** The seq just before the middle prompt of a span: the half a cut-off answer is retried with (#45). */
43
+ function firstHalfEnd(messages) {
44
+ const prompts = messages.filter((m) => m.role === 'user')
45
+ return prompts.length >= 2 ? prompts[Math.floor(prompts.length / 2)].seq - 1 : undefined
46
+ }
47
+
48
+ export function registerBuilder(ctx, rt, meter) {
49
+ const { cfg } = rt
50
+ const efforts = new Map()
51
+
52
+ /**
53
+ * The route's lowest reasoning effort (#44), chosen the way dsh's own title generator does;
54
+ * undefined for a route without efforts, or when this dsh cannot say (then nothing is sent, which
55
+ * is always valid). Topic extraction does not need paid thinking.
56
+ */
57
+ async function lowestEffort(llm, target, signal) {
58
+ const key = `${target.provider}\n${target.model}`
59
+ if (efforts.has(key)) return efforts.get(key)
60
+ if (typeof llm.resolveModelInfo !== 'function') return undefined
61
+ try {
62
+ const info = await llm.resolveModelInfo(target.provider, target.model, signal)
63
+ const effort = info?.reasoning?.efforts?.[0]?.id
64
+ efforts.set(key, effort)
65
+ return effort
66
+ } catch {
67
+ return undefined
68
+ }
69
+ }
70
+
71
+ /**
72
+ * Index the chat's messages since the last build.
73
+ * @param force build now even below the turn/char thresholds (the `build` and `on` commands).
74
+ * @param signal aborts the model call (the command's own signal, so cancelling it stops the build).
75
+ * @param completeOnly stop before a turn that is still running (builds started by a command).
76
+ */
77
+ async function build(agent, { force = false, signal, completeOnly = false } = {}) {
78
+ const session = agent.session
79
+ const eventAt = (seq) => session.eventAt(seq)
80
+ const sid = rt.sidOf(agent)
81
+ const st = rt.state(sid)
82
+ if (st.building) return { status: 'busy', reason: 'this chat is already being indexed' }
83
+ // ponytail: subagent chatter stays out of the graph; revisit if delegated work holds decisions worth keeping.
84
+ if (rt.isSubagent(agent)) return { status: 'skipped', reason: 'subagent session' }
85
+ st.building = true
86
+ let span
87
+ let read
88
+ let endSeq
89
+ const finish = (result) => {
90
+ if (['built', 'failed', 'cancelled'].includes(result.status)) st.lastBuild = { ...result, at: new Date().toISOString() }
91
+ return result
92
+ }
93
+ // What dsh drove from an off stretch (rounds of a goal set there, a reminder scheduled there)
94
+ // is not stored as gaps: every reader walks the log with the off stretches and finds it there
95
+ // (session.js walk), so meta.gaps stays one entry per off stretch however often a reminder
96
+ // fires (second review of #69).
97
+ const failed = (reason, { half = false } = {}) => {
98
+ if (span) {
99
+ st.retryAt = span.userTurns + cfg.buildEveryTurns
100
+ // The retry reads the same span, not the span plus every turn since (#45); after an answer
101
+ // cut off by the token cap, only its first half.
102
+ if (endSeq !== undefined) st.pin = (half && read ? firstHalfEnd(read) : undefined) ?? endSeq
103
+ }
104
+ return finish({ status: 'failed', reason })
105
+ }
106
+ try {
107
+ let meta = await rt.metaFor(agent)
108
+ // An off whose write has not landed yet already holds here (runtime.js withPending).
109
+ if (!memoryOn(meta)) return { status: 'off', reason: 'memory is off for this chat; /context-graph on resumes it' }
110
+ // A fork from before 0.10.0 takes its ancestors' off stretches first (runtime.js inheritOffs).
111
+ meta = await rt.inheritOffs(agent, meta)
112
+ // Read from the durable log after the last indexed seq, so compacted turns are not lost (#13).
113
+ const forkSeq = rt.forkSeqOf(session) ?? 0
114
+ // A fork's own titles start at its own first prompt (review of #60).
115
+ const titleFrom = forkSeq ? (firstPromptSeq(eventAt, forkSeq) ?? Infinity) : 0
116
+ span = collectSpan(eventAt, rt.indexStart(agent, meta), { completeOnly, gaps: walkGaps(meta), titleFrom })
117
+ // A command build that stopped before a running turn: that turn is indexed when it ends (#65).
118
+ if (span.open && force) st.indexAtEnd = true
119
+ if (span.messages.length === 0) return { status: 'nothing', reason: 'no new messages since the last build' }
120
+ const chars = span.messages.reduce((n, m) => n + m.text.length, 0)
121
+ const needTurns = Math.max(cfg.buildEveryTurns, st.retryAt)
122
+ if (!force && (span.userTurns < needTurns || chars < cfg.buildMinChars)) {
123
+ // What is waiting, so a chat that goes quiet below the threshold is still indexed (#42).
124
+ return { status: 'skipped', reason: `${span.userTurns}/${needTurns} human turns, ${chars}/${cfg.buildMinChars} chars`, userTurns: span.userTurns, chars }
125
+ }
126
+ const pinned = st.pin === undefined ? span.messages : span.messages.filter((m) => m.seq <= st.pin)
127
+ if (pinned.length === 0) st.pin = undefined
128
+ // Every prompt is read; a span too long for one call is read in whole turns, oldest first (#46).
129
+ const plan = planSpan(pinned.length > 0 ? pinned : span.messages, cfg.builderMaxInputChars)
130
+ read = plan.messages
131
+ // Never past what this build read: a pin left by a build that read into a running turn must
132
+ // not carry a command build (which stops before that turn) beyond its own span.
133
+ endSeq = plan.rest ? plan.rest.seq - 1 : Math.min(st.pin ?? Infinity, span.lastSeq)
134
+ const llm = ctx.get('llm')
135
+ if (!llm) return { status: 'unavailable', reason: 'no llm service in this composition' }
136
+ const target = rt.resolveTarget(agent)
137
+ if (!target) return { status: 'unavailable', reason: 'no provider/model routed yet' }
138
+ // A chat gets its folder and chat number only when it is first indexed (#38); a fork has its
139
+ // meta, with its inherited flags, from the moment it is first seen (runtime.js).
140
+ if (!meta) meta = await rt.updateFor(agent, (m) => m)
141
+ const chat = chatDir(rt.dirFor(agent), sid)
142
+ const graph = await loadGraph(chat, { writable: true })
143
+ // The indexing call's usage is this chat's cost in the savings estimate (meter.js).
144
+ st.chat = true
145
+ const prompt = builderPrompt({ graph, summary: meta.summary, messages: read, assistantCap: plan.assistantCap })
146
+ const effort = await lowestEffort(llm, target, signal)
147
+ const assembler = new BlockAssembler()
148
+ for await (const chunk of llm.stream({
149
+ provider: target.provider,
150
+ model: target.model,
151
+ ...(effort ? { reasoningEffort: effort } : {}),
152
+ messages: [{ role: 'user', content: [{ type: 'text', text: prompt }] }],
153
+ maxTokens: cfg.builderMaxTokens,
154
+ sessionId: session.id,
155
+ purpose: PURPOSE,
156
+ ...(signal ? { signal } : {})
157
+ })) assembler.push(chunk)
158
+ const end = assembler.finish
159
+ if (end?.kind === 'error' || end?.kind === 'aborted') throw new Error(end.failure?.message ?? end.kind)
160
+ const blocks = assembler.blocks()
161
+ const answer = textOf(blocks)
162
+ // Some thinking models put everything, JSON included, into reasoning blocks.
163
+ const reasoning = blocks.filter((b) => b?.type === 'reasoning').map((b) => b.text).join('\n')
164
+ const delta = betterParse(parseBuilderOutput(answer), parseBuilderOutput(reasoning))
165
+ // Reversibility rule: a topic is written only when it cites a message of this span.
166
+ const usable = delta ? delta.nodes.filter((n) => n.msgs.some((i) => i < read.length)) : []
167
+ // "Nothing worth remembering" is a complete answer whose nodes are empty (or that says skip);
168
+ // an answer cut off by the token cap never counts as one.
169
+ const nothing = usable.length === 0 && delta?.skip === true && end?.kind !== 'max-tokens'
170
+ if (!delta || (usable.length === 0 && !nothing)) {
171
+ // An unusable answer is a failure, not an empty build: the span stays unindexed and is
172
+ // retried later instead of being skipped for good (#14). The raw answer is kept for diagnosis.
173
+ const saved = join(chat, 'last-builder-output.txt')
174
+ await mkdir(chat, { recursive: true })
175
+ await writeFile(saved, `finish: ${end?.kind}\n\n--- answer ---\n${answer}\n\n--- reasoning ---\n${reasoning}\n`, 'utf8')
176
+ const cutOff = end?.kind === 'max-tokens'
177
+ const why = cutOff
178
+ ? `the model ran out of output tokens (builderMaxTokens ${cfg.builderMaxTokens}) before finishing`
179
+ : delta ? 'the model\'s answer had no topic citing a message of this span' : 'builder output was not the expected JSON'
180
+ st.failedAnswers = (st.failedAnswers ?? 0) + 1
181
+ if (st.failedAnswers >= MAX_FAILED_ANSWERS) {
182
+ // A span the model keeps failing on is skipped, and only that span: turns that arrived
183
+ // since stay unindexed for the next build, which waits the normal number of turns (#45, #53).
184
+ st.failedAnswers = 0
185
+ st.pin = undefined
186
+ st.retryAt = 0
187
+ await rt.updateFor(agent, (latest) => ({ ...latest, builtSeq: Math.max(latest.builtSeq ?? -1, endSeq) }))
188
+ return finish({ status: 'failed', reason: `${why}; skipped these turns after ${MAX_FAILED_ANSWERS} unusable answers in a row; raw output saved to ${saved}` })
189
+ }
190
+ return failed(`${why}; raw output saved to ${saved}`, { half: cutOff })
191
+ }
192
+ st.failedAnswers = 0
193
+ st.pin = undefined
194
+ delta.nodes = usable
195
+ const now = new Date().toISOString()
196
+ const refsOf = (msgs) => msgs.map((i) => read[i]?.seq).filter(Number.isInteger)
197
+ const touched = mergeDelta(graph, delta, { now, refsOf })
198
+ // Commit order: the cited text first (idempotent by seq), then the graph that points at it,
199
+ // then the index position. A crash in between can repeat work but never attaches the wrong
200
+ // text to a topic (#12).
201
+ const cited = [...new Set(usable.flatMap((n) => n.msgs))].map((i) => read[i]).filter(Boolean)
202
+ await saveMessages(chat, cited)
203
+ await relabelTurns(chat, span.turnAt).catch((error) => console.error('context-graph: stored turn ids not relabelled (non-fatal)', error))
204
+ await saveGraph(chat, graph)
205
+ await rt.updateFor(agent, (latest) => {
206
+ return {
207
+ ...latest,
208
+ // dsh's own title (model-made or the user's rename) once there is one (#41). A meta whose
209
+ // off stretches were lost (recovered, turnsClosed) takes no new title from the log (review).
210
+ // (Its first-prompt fingerprint is set by runtime.js upToDate before this change runs.)
211
+ title: latest.turnsClosed === true ? latest.title : span.title ?? latest.title ?? titleOf(eventAt, 60, forkSeq, mergeGaps(latest.gaps, span.hidden)),
212
+ ...(delta.summary ? { summary: delta.summary } : {}),
213
+ lastActiveAt: now,
214
+ builtSeq: endSeq
215
+ }
216
+ })
217
+ st.retryAt = 0
218
+ meter.builds++
219
+ return finish({ status: 'built', nodes: touched.length, newNodes: touched.filter((t) => t.isNew).length, totalNodes: Object.keys(graph.nodes).length, edges: graph.edges.length, dir: chat, more: Boolean(plan.rest) })
220
+ } catch (error) {
221
+ if (signal?.aborted) return finish({ status: 'cancelled', reason: 'the command was cancelled' })
222
+ console.error('context-graph: build failed (non-fatal)', error)
223
+ return failed(String(error?.message ?? error))
224
+ } finally {
225
+ st.building = false
226
+ }
227
+ }
228
+
229
+ /**
230
+ * A chat resumed for a few turns is active again even if nothing was indexed (#40): its
231
+ * last-active time moves, at most once an hour, so it ranks as recent and shows up for "today".
232
+ */
233
+ async function touch(agent) {
234
+ if (rt.isSubagent(agent)) return
235
+ const meta = await rt.metaFor(agent)
236
+ if (!meta || !memoryOn(meta)) return
237
+ if (Date.now() - Date.parse(meta.lastActiveAt ?? 0) < TOUCH_MS) return
238
+ await rt.updateFor(agent, (latest) => ({ ...latest, lastActiveAt: new Date().toISOString() }))
239
+ }
240
+
241
+ /**
242
+ * Close the turn's savings estimate (#35): topics shown this turn that the answer used count as
243
+ * saved, once per chat; then the turn's counters go to the workspace ledger in one write. A use
244
+ * judged now but not credited yet (the ledger cannot be read) waits in `toCredit` for the next
245
+ * turn instead of being lost (review).
246
+ */
247
+ async function settle(agent, turn = { pending: [], answer: '' }) {
248
+ if (rt.isSubagent(agent)) return
249
+ const sid = rt.sidOf(agent)
250
+ const st = rt.tracked(sid)
251
+ if (!st) return
252
+ const dir = rt.dirFor(agent)
253
+ for (const p of turn.pending) if (usedIn(turn.answer, p.node, p.prompt)) st.toCredit.push(p)
254
+ while (st.toCredit.length > 0) {
255
+ const p = st.toCredit[0]
256
+ // A source that cannot be read stands in for nothing; the use still counts.
257
+ await rt.creditUse(agent, { id: p.id, node: p.node, cid: p.cid, stored: await loadMessages(chatDir(dir, p.sid)).catch(() => ({})) })
258
+ st.toCredit.shift()
259
+ }
260
+ const delta = st.delta
261
+ const used = st.newlyUsed
262
+ const credited = st.newlyCredited
263
+ if (Object.values(delta).every((n) => n === 0) && used.length === 0) return
264
+ st.delta = emptyCounters()
265
+ st.newlyUsed = []
266
+ st.newlyCredited = []
267
+ try {
268
+ await addToLedger(dir, sid, delta, used, credited)
269
+ } catch (error) {
270
+ // Kept for the next turn's write instead of being lost.
271
+ for (const [key, n] of Object.entries(delta)) st.delta[key] += n
272
+ st.newlyUsed.push(...used)
273
+ st.newlyCredited.push(...credited)
274
+ throw error
275
+ }
276
+ }
277
+
278
+ /**
279
+ * Memory back on (#59): what was typed while it was off becomes a gap that is never indexed or
280
+ * served, and the chat is indexed up to its last finished turn (a running turn when it ends).
281
+ */
282
+ async function turnOn(agent, { deferred = false } = {}) {
283
+ const end = collectSpan((seq) => agent.session.eventAt(seq)).lastSeq
284
+ let applied = false
285
+ const meta = await rt.updateFor(agent, (m) => {
286
+ // A deferred on that an off has cancelled since does nothing: the later command wins (review).
287
+ if (deferred && m.onWhenIdle !== true) return m
288
+ applied = true
289
+ const { offSeq, onWhenIdle, ...rest } = m
290
+ const from = offPoint(m)
291
+ const gaps = Array.isArray(m.gaps) ? [...m.gaps] : []
292
+ if (from !== undefined && end > from) gaps.push([from + 1, end])
293
+ // Never drop a stretch: past 50 the two oldest merge, also covering the on stretch between them.
294
+ while (gaps.length > 50) gaps.splice(0, 2, [gaps[0][0], gaps[1][1]])
295
+ // A meta that lost its stretches is unsure only up to here: what follows is typed with memory on.
296
+ const closed = m.turnsClosed === true && !Number.isInteger(m.closedThrough) ? { closedThrough: end } : {}
297
+ return { ...rest, memoryOff: false, ...(gaps.length ? { gaps } : {}), ...closed, lastActiveAt: new Date().toISOString() }
298
+ })
299
+ if (!applied) return undefined
300
+ // The chat list may be sent again (memory.js), once.
301
+ const st = rt.state(rt.sidOf(agent))
302
+ Object.assign(st, { announce: true, listed: false })
303
+ // A turn end's own build may still be running: then the next turn end indexes (as for #65).
304
+ void build(agent, { force: true, completeOnly: true }).then((result) => { if (result.status === 'busy') st.indexAtEnd = true })
305
+ return meta
306
+ }
307
+
308
+ /**
309
+ * An `on` that waited for the chat to be idle (command.js) takes effect at a turn end, or when the
310
+ * agent goes idle (a stopped or failed turn has no turn end), once no input the user typed is
311
+ * still queued. Outside a turn end (`ending`), the chat must also have no turn running: the
312
+ * check also runs right after the command, when an agent is created (an app restart left the on
313
+ * waiting) and when queued input is removed, none of which brings a turn end (third review).
314
+ */
315
+ async function onAtIdle(agent, { ending = false } = {}) {
316
+ if (rt.isSubagent(agent) || rt.pendingInput(agent)) return false
317
+ if (!ending && (agent.status === 'running' || collectSpan((seq) => agent.session.eventAt(seq), -1, { completeOnly: true }).open)) return false
318
+ if ((await rt.metaFor(agent))?.onWhenIdle !== true) return false
319
+ return (await turnOn(agent, { deferred: true })) !== undefined
320
+ }
321
+
322
+ /**
323
+ * A chat left with turns too few to index (below buildEveryTurns, #42): short chats and the last
324
+ * turns of long ones, which often hold the conclusion. It is indexed once quiet for QUIET_MS, or
325
+ * at once when a new chat of its workspace starts (the user has moved on); a turn starting in it
326
+ * cancels that. Timers come from dsh's timer service, so they end with the plugin; without one,
327
+ * chats wait for their next turns as before. A chat cannot tell paused from left, so its timer runs at most once
328
+ * between two regular builds: one resumed after every pause would otherwise be indexed at every
329
+ * turn end (review of #42). A new chat flushes it at once if it had no quiet index yet in this
330
+ * cycle, else LEFT_MS later unless it runs again first (second review, third check). A flush that
331
+ * indexed or failed counts as the one: a model that keeps failing is not called at every pause. ponytail: an app quit before the timer
332
+ * fires leaves the tail until that chat's next turn; a startup scan (sessionQuery.listSessions)
333
+ * if it matters.
334
+ */
335
+ const quiet = new Map()
336
+ /** Chats indexed once quiet since their last regular build. */
337
+ const flushed = new Set()
338
+ function whenQuiet(agent, result) {
339
+ const sid = rt.sidOf(agent)
340
+ if (result?.status === 'built') flushed.delete(sid)
341
+ const timer = ctx.get('timer')
342
+ if (!timer || result?.status !== 'skipped' || !(result.userTurns >= 1 && result.chars >= cfg.buildMinChars)) return
343
+ quiet.get(sid)?.cancel()
344
+ const entry = { agent, dir: rt.dirFor(agent), cancel: () => {} }
345
+ if (!flushed.has(sid)) entry.cancel = timer.timeout(() => { if (quiet.get(sid) === entry) flush(sid) }, QUIET_MS)
346
+ quiet.set(sid, entry)
347
+ }
348
+ function flush(sid, { early = false } = {}) {
349
+ const entry = quiet.get(sid)
350
+ quiet.delete(sid)
351
+ if (early) entry.cancel()
352
+ // Stops before a running turn, so a flush that comes late never splits one. Memory off, a busy
353
+ // chat or an unusable answer leave the timer to the next turn end.
354
+ void build(entry.agent, { force: true, completeOnly: true }).then((result) => { if (result?.status === 'built' || result?.status === 'failed') flushed.add(sid) })
355
+ }
356
+ function started(agent) {
357
+ if (rt.isSubagent(agent)) return
358
+ const sid = rt.sidOf(agent)
359
+ quiet.get(sid)?.cancel()
360
+ quiet.delete(sid)
361
+ if (quiet.size === 0 || hasAnswer(agent)) return
362
+ const dir = rt.dirFor(agent)
363
+ for (const [other, entry] of quiet) {
364
+ if (entry.dir !== dir) continue
365
+ if (!flushed.has(other)) { flush(other, { early: true }); continue }
366
+ if (entry.left) continue
367
+ entry.left = true
368
+ entry.cancel()
369
+ entry.cancel = ctx.get('timer').timeout(() => { if (quiet.get(other) === entry) flush(other) }, LEFT_MS)
370
+ }
371
+ }
372
+ const hasAnswer = (agent) => {
373
+ for (let seq = 0; ; seq++) {
374
+ const event = agent.session.eventAt(seq)
375
+ if (!event) return false
376
+ if (event.type === 'assistant/message') return true
377
+ }
378
+ }
379
+
380
+ const whenIdle = (agent) => void onAtIdle(agent).catch((error) => console.error('context-graph: memory on at idle failed (non-fatal)', error))
381
+ ctx.on('agent/status', ({ agent, status }) => {
382
+ if (status === 'running') return started(agent)
383
+ if (status !== 'idle') return
384
+ // A turn that ended normally gave its shown topics to its turn end; a stopped or failed one did
385
+ // not, and they must not be judged against the next turn's answer (third review).
386
+ if (!rt.isSubagent(agent)) rt.state(rt.sidOf(agent)).pending = []
387
+ whenIdle(agent)
388
+ })
389
+ ctx.on('agent/created', ({ agent }) => whenIdle(agent))
390
+ ctx.on('agent/inbox/discarded', ({ agent }) => whenIdle(agent))
391
+
392
+ ctx.on('agent/turn-stopping', (payload) => {
393
+ const agent = payload.agent
394
+ const st = rt.state(rt.sidOf(agent))
395
+ const force = st.indexAtEnd === true
396
+ st.indexAtEnd = false
397
+ // This turn's shown topics and its answer, taken now: the index call below can outlast the
398
+ // turn, and a turn must be judged by its own answer, not the next one's (review of #35).
399
+ const turn = { pending: st.pending, answer: st.pending.length > 0 ? lastAnswer(agent.session.surface.nodes, (seq) => agent.session.eventAt(seq)) : '' }
400
+ st.pending = []
401
+ // Fire and forget: the build must never delay the turn's close.
402
+ void onAtIdle(payload.agent, { ending: true })
403
+ .then((resumed) => (resumed ? { status: 'resumed' } : build(payload.agent, { force })))
404
+ .then((result) => {
405
+ if (force && result.status === 'busy') st.indexAtEnd = true
406
+ whenQuiet(payload.agent, result)
407
+ return result.status === 'built' ? undefined : touch(payload.agent)
408
+ })
409
+ .catch((error) => console.error('context-graph: activity update failed (non-fatal)', error))
410
+ // The savings estimate is settled however the index went (review of #35).
411
+ .then(() => settle(payload.agent, turn))
412
+ .catch((error) => console.error('context-graph: savings not written this turn, kept for the next (non-fatal)', error))
413
+ })
414
+
415
+ return { build, turnOn, onAtIdle }
416
+ }