@theronap/agnoclast-mcp 0.9.311 → 0.9.312
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/bin/cortex-mcp.mjs +10 -0
- package/lib/editors/claude.mjs +52 -2
- package/lib/turn_check.mjs +126 -0
- package/package.json +1 -1
package/bin/cortex-mcp.mjs
CHANGED
|
@@ -126,6 +126,7 @@ if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
|
|
|
126
126
|
` skills push <file> publish a SKILL.md to your org (owner/manager/admin)\n` +
|
|
127
127
|
` closeout-sweep close out one quiet Claude Code session in the background (--dry-run to preview)\n` +
|
|
128
128
|
` closeout-install run closeout-sweep every 30 minutes on this Mac (--remove to stop)\n` +
|
|
129
|
+
` turn-check-install hold each Claude Code turn until it says whether it updated the knowledge base (--remove to stop)\n` +
|
|
129
130
|
` docs-scan detect new/changed local docs pending Agnoclast authoring (used by /cortex-author-docs)\n` +
|
|
130
131
|
` graphify-sync [path] [--brain <name-or-id>] rebuild the local code graph + log a timeline event\n` +
|
|
131
132
|
` snapshot-context save the exact startup context Agnoclast served to a local snapshot\n` +
|
|
@@ -214,12 +215,21 @@ if (cmd === 'login') {
|
|
|
214
215
|
const { healPageNudge } = await import('../lib/editors/claude.mjs')
|
|
215
216
|
healPageNudge()
|
|
216
217
|
} catch { /* never fail session start over this */ }
|
|
218
|
+
// And the turn-end check, only where `turn-check-install` wired it.
|
|
219
|
+
try {
|
|
220
|
+
const { healTurnCheck } = await import('../lib/editors/claude.mjs')
|
|
221
|
+
healTurnCheck()
|
|
222
|
+
} catch { /* never fail session start over this */ }
|
|
217
223
|
} else if (cmd === 'closeout-sweep') {
|
|
218
224
|
const { runCloseoutSweep } = await import('../lib/closeout.mjs')
|
|
219
225
|
await runCloseoutSweep(process.argv.slice(3))
|
|
220
226
|
} else if (cmd === 'closeout-install') {
|
|
221
227
|
const { installCloseout } = await import('../lib/closeout.mjs')
|
|
222
228
|
installCloseout(process.argv.slice(3))
|
|
229
|
+
} else if (cmd === 'turn-check-install') {
|
|
230
|
+
const { installTurnCheck } = await import('../lib/editors/claude.mjs')
|
|
231
|
+
const did = installTurnCheck({ remove: process.argv.slice(3).includes('--remove') })
|
|
232
|
+
console.log(`Turn-end knowledge check ${did}. It applies to Claude Code sessions started from now on.`)
|
|
223
233
|
} else if (cmd === 'capture') {
|
|
224
234
|
const { runCapture } = await import('../lib/capture.mjs')
|
|
225
235
|
await runCapture()
|
package/lib/editors/claude.mjs
CHANGED
|
@@ -2,8 +2,8 @@
|
|
|
2
2
|
// setup.mjs. setup.mjs imports THESE SAME functions (and re-exports them), so the config bytes are
|
|
3
3
|
// structurally identical, not merely "supposed to match".
|
|
4
4
|
import { homedir } from 'node:os'
|
|
5
|
-
import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
|
|
6
|
-
import { join } from 'node:path'
|
|
5
|
+
import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync } from 'node:fs'
|
|
6
|
+
import { join, dirname } from 'node:path'
|
|
7
7
|
import { readJson, backupFile, ensureDir, writeJson } from './_fsutil.mjs'
|
|
8
8
|
import { markCommand, isManagedSubcommand } from '../managed.mjs'
|
|
9
9
|
|
|
@@ -187,6 +187,56 @@ export function healPageNudge({ home = homedir() } = {}) {
|
|
|
187
187
|
return true
|
|
188
188
|
}
|
|
189
189
|
|
|
190
|
+
// The turn-end knowledge check (lib/turn_check.mjs; Theron, 2026-11-06). OPT-IN, on purpose: it holds the end of every
|
|
191
|
+
// turn until the session says whether it learned anything new, so setup never wires it — `turn-check-install` does,
|
|
192
|
+
// on one machine, while it is measured. mergeClaudeSettings leaves it alone (it strips only managed `capture`).
|
|
193
|
+
export const TURN_CHECK_COMMAND =
|
|
194
|
+
`[ -f "$HOME/.cortex/hooks/turn-check.mjs" ] && node "$HOME/.cortex/hooks/turn-check.mjs" --agnoclast-managed || true`
|
|
195
|
+
|
|
196
|
+
const hasTurnCheckIn = (s) => (s?.hooks?.Stop ?? []).some((g) => (g.hooks ?? []).some((h) => h.command === TURN_CHECK_COMMAND))
|
|
197
|
+
|
|
198
|
+
/** Copy lib/turn_check.mjs to where its hook runs it. Rewrites only on change. */
|
|
199
|
+
function copyTurnCheck(home) {
|
|
200
|
+
const src = readFileSync(new URL('../turn_check.mjs', import.meta.url), 'utf8')
|
|
201
|
+
const dir = join(home, '.cortex', 'hooks')
|
|
202
|
+
const dest = join(dir, 'turn-check.mjs')
|
|
203
|
+
let cur = null
|
|
204
|
+
try { cur = readFileSync(dest, 'utf8') } catch { /* not installed yet */ }
|
|
205
|
+
if (cur === src) return
|
|
206
|
+
mkdirSync(dir, { recursive: true, mode: 0o700 })
|
|
207
|
+
writeFileSync(dest, src, { mode: 0o600 })
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
/** `turn-check-install [--remove]`: wire (or unwire) the turn-end check on this machine. Returns what it did. */
|
|
211
|
+
export function installTurnCheck({ home = homedir(), remove = false } = {}) {
|
|
212
|
+
const file = join(home, '.claude', 'settings.json')
|
|
213
|
+
const s = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {}
|
|
214
|
+
s.hooks = s.hooks ?? {}
|
|
215
|
+
s.hooks.Stop = Array.isArray(s.hooks.Stop) ? s.hooks.Stop : []
|
|
216
|
+
if (remove) {
|
|
217
|
+
for (const g of s.hooks.Stop) if (Array.isArray(g.hooks)) g.hooks = g.hooks.filter((h) => h.command !== TURN_CHECK_COMMAND)
|
|
218
|
+
s.hooks.Stop = s.hooks.Stop.filter((g) => (g.hooks ?? []).length)
|
|
219
|
+
rmSync(join(home, '.cortex', 'hooks', 'turn-check.mjs'), { force: true })
|
|
220
|
+
mkdirSync(dirname(file), { recursive: true })
|
|
221
|
+
writeFileSync(file, JSON.stringify(s, null, 2))
|
|
222
|
+
return 'removed'
|
|
223
|
+
}
|
|
224
|
+
copyTurnCheck(home)
|
|
225
|
+
if (hasTurnCheckIn(s)) return 'already installed'
|
|
226
|
+
s.hooks.Stop.push({ matcher: '', hooks: [{ type: 'command', command: TURN_CHECK_COMMAND, timeout: 10 }] })
|
|
227
|
+
mkdirSync(dirname(file), { recursive: true })
|
|
228
|
+
writeFileSync(file, JSON.stringify(s, null, 2))
|
|
229
|
+
return 'installed'
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
/** SessionStart self-heal: refresh the copy where the check is wired. Never wires it. */
|
|
233
|
+
export function healTurnCheck({ home = homedir() } = {}) {
|
|
234
|
+
const file = join(home, '.claude', 'settings.json')
|
|
235
|
+
if (!existsSync(file) || !hasTurnCheckIn(JSON.parse(readFileSync(file, 'utf8')))) return false
|
|
236
|
+
copyTurnCheck(home)
|
|
237
|
+
return true
|
|
238
|
+
}
|
|
239
|
+
|
|
190
240
|
/** Merge Agnoclast's Claude Code hooks into a ~/.claude/settings.json object. Pure + idempotent: drops
|
|
191
241
|
* any prior cortex entry (old token/path/version) from each hook array before appending the current
|
|
192
242
|
* one — capture (Stop), status + skills-repair + snapshot-context (SessionStart), hydrate
|
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
// THE TURN-END KNOWLEDGE CHECK (Stop). Theron, 2026-11-06: the knowledge base stays current only if the session
|
|
2
|
+
// notices, as it works, that something it just learned is not written down yet, and writes it then. Information
|
|
3
|
+
// arrives in every kind of turn (something said, an email read, a finding, a decision), not just at a merge, so this
|
|
4
|
+
// asks at the end of EVERY turn. A turn cannot end until its last message says one of:
|
|
5
|
+
//
|
|
6
|
+
// Knowledge base: nothing new
|
|
7
|
+
// Knowledge base: updated <the pages>
|
|
8
|
+
//
|
|
9
|
+
// "updated" is checked: the turn must contain a write to Agnoclast (edit_page, author, …), or it is sent back.
|
|
10
|
+
// It is the cheapest, least invasive approach of several to be tried in order (ADR-0107, 2026-11-06); the
|
|
11
|
+
// background close-out still audits what slips through.
|
|
12
|
+
//
|
|
13
|
+
// Self-contained (Node built-ins only): setup copies it to ~/.cortex/hooks/turn-check.mjs and the hook runs it with
|
|
14
|
+
// plain `node`. It never writes to Agnoclast, and it gives up after MAX_BLOCKS sends-back in one turn so it can never
|
|
15
|
+
// trap a session.
|
|
16
|
+
import { readFileSync, writeFileSync, mkdirSync, openSync, readSync, fstatSync, closeSync } from 'node:fs'
|
|
17
|
+
import { homedir } from 'node:os'
|
|
18
|
+
import { join, dirname } from 'node:path'
|
|
19
|
+
import { createHash } from 'node:crypto'
|
|
20
|
+
|
|
21
|
+
export const MAX_BLOCKS = 2
|
|
22
|
+
const TAIL_BYTES = 4_000_000
|
|
23
|
+
export const DECLARED = /knowledge base:\s*(nothing new|updated)\b/i
|
|
24
|
+
// A tool call that writes what the session learned into Agnoclast.
|
|
25
|
+
export const KB_WRITE = /^mcp__.+__(?:edit_page|author|capture_record|capture_meeting|track_obligation|resolve_obligation|absorb|intake_materialize|rename_section|merge_sections|split_page|set_page_validity|create_event|update_event|log_session)$/
|
|
26
|
+
|
|
27
|
+
const textOf = (content) =>
|
|
28
|
+
typeof content === 'string' ? content : Array.isArray(content) ? content.filter((b) => b?.type === 'text').map((b) => b.text).join('\n') : ''
|
|
29
|
+
|
|
30
|
+
/** PURE. A user entry that starts a turn: something the person (or the app) sent, not a tool result or this hook's own feedback. */
|
|
31
|
+
export function isTurnStart(d) {
|
|
32
|
+
if (d?.type !== 'user' || d.isMeta || d.isCompactSummary || d.isSidechain) return false
|
|
33
|
+
const c = d.message?.content
|
|
34
|
+
if (Array.isArray(c) && c.some((b) => b?.type === 'tool_result')) return false
|
|
35
|
+
const t = textOf(c)
|
|
36
|
+
return Boolean(t.trim()) && !/^\s*Stop hook feedback/i.test(t) && !t.includes('Knowledge base check (Agnoclast)')
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/** PURE. The current turn, from the tail of a transcript: its key, whether it wrote to Agnoclast, its last text. */
|
|
40
|
+
export function readTurn(text) {
|
|
41
|
+
const lines = text.split('\n')
|
|
42
|
+
let start = -1
|
|
43
|
+
const entries = []
|
|
44
|
+
for (const l of lines) {
|
|
45
|
+
if (!l) continue
|
|
46
|
+
let d
|
|
47
|
+
try { d = JSON.parse(l) } catch { continue }
|
|
48
|
+
entries.push(d)
|
|
49
|
+
}
|
|
50
|
+
for (let i = entries.length - 1; i >= 0; i--) if (isTurnStart(entries[i])) { start = i; break }
|
|
51
|
+
const turn = start >= 0 ? entries.slice(start + 1) : entries
|
|
52
|
+
let wrote = false
|
|
53
|
+
let last = ''
|
|
54
|
+
for (const d of turn) {
|
|
55
|
+
if (d.type !== 'assistant' || d.isSidechain || !Array.isArray(d.message?.content)) continue
|
|
56
|
+
for (const b of d.message.content) {
|
|
57
|
+
if (b?.type === 'tool_use' && KB_WRITE.test(b.name)) wrote = true
|
|
58
|
+
if (b?.type === 'text' && b.text.trim()) last = b.text
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
return { key: start >= 0 ? entries[start].uuid ?? String(start) : 'none', wrote, last }
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** PURE. Whether the turn may end, and if not, what the session is told. */
|
|
65
|
+
export function turnDecision({ wrote, last }) {
|
|
66
|
+
const m = DECLARED.exec(last)
|
|
67
|
+
if (m && m[1].toLowerCase() === 'nothing new') return null
|
|
68
|
+
if (m && wrote) return null
|
|
69
|
+
if (m) return `Knowledge base check (Agnoclast): your last message says "Knowledge base: updated", but nothing was written to Agnoclast this turn (no edit_page, author, capture_record, track_obligation…). Make the update now, then end with "Knowledge base: updated <pages>" — or, if there was in fact nothing new, "Knowledge base: nothing new".`
|
|
70
|
+
return `Knowledge base check (Agnoclast): before this turn ends, look at what it brought in — what the person said, what tools returned, what you found or decided. Is any of it new: a fact, decision, rule, finding or status change that the Agnoclast pages don't already say, or that makes what they say wrong? If so, update those pages now (edit_page, or author for a new page), then end your reply with the line "Knowledge base: updated <the pages>". If nothing is new, end your reply with the line "Knowledge base: nothing new". Don't repeat the rest of your answer.`
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
function tail(path) {
|
|
74
|
+
let fd
|
|
75
|
+
try {
|
|
76
|
+
fd = openSync(path, 'r')
|
|
77
|
+
const size = fstatSync(fd).size
|
|
78
|
+
const len = Math.min(size, TAIL_BYTES)
|
|
79
|
+
const buf = Buffer.alloc(len)
|
|
80
|
+
readSync(fd, buf, 0, len, size - len)
|
|
81
|
+
const s = buf.toString('utf8')
|
|
82
|
+
return len < size ? s.slice(s.indexOf('\n') + 1) : s
|
|
83
|
+
} catch { return '' } finally { if (fd !== undefined) try { closeSync(fd) } catch {} }
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
const statePath = (home, sessionId) =>
|
|
87
|
+
join(home, '.cortex', 'turn-check', createHash('sha256').update(String(sessionId)).digest('hex').slice(0, 32) + '.json')
|
|
88
|
+
|
|
89
|
+
/** The hook: reads the Stop payload, returns `{decision:'block', reason}` or null (let the turn end). */
|
|
90
|
+
export function runTurnCheck({ input, home = homedir(), env = process.env }) {
|
|
91
|
+
if (env.CORTEX_SUMMARIZING || env.AGNOCLAST_TURN_CHECK === 'off') return null
|
|
92
|
+
let p
|
|
93
|
+
try { p = JSON.parse(input) } catch { return null }
|
|
94
|
+
if (!p?.session_id || !p.transcript_path) return null
|
|
95
|
+
const turn = readTurn(tail(p.transcript_path))
|
|
96
|
+
const reason = turnDecision(turn)
|
|
97
|
+
const file = statePath(home, p.session_id)
|
|
98
|
+
let state = {}
|
|
99
|
+
try { state = JSON.parse(readFileSync(file, 'utf8')) } catch { /* first stop this session */ }
|
|
100
|
+
const blocks = state.key === turn.key ? state.blocks ?? 0 : 0
|
|
101
|
+
const log = { at: new Date().toISOString(), key: turn.key, outcome: reason ? (blocks >= MAX_BLOCKS ? 'gave_up' : 'blocked') : (DECLARED.exec(turn.last)?.[1].toLowerCase() ?? 'ok'), wrote: turn.wrote }
|
|
102
|
+
save(file, { key: turn.key, blocks: reason && blocks < MAX_BLOCKS ? blocks + 1 : blocks, log: [...(state.log ?? []).slice(-199), log] })
|
|
103
|
+
if (!reason || blocks >= MAX_BLOCKS) return null
|
|
104
|
+
return { decision: 'block', reason }
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
function save(file, state) {
|
|
108
|
+
try {
|
|
109
|
+
mkdirSync(dirname(file), { recursive: true, mode: 0o700 })
|
|
110
|
+
writeFileSync(file, JSON.stringify(state), { mode: 0o600 })
|
|
111
|
+
} catch { /* a hook never fails the session */ }
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
// Run directly (the hook), never on import (setup and tests import it).
|
|
115
|
+
if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
|
|
116
|
+
let input = ''
|
|
117
|
+
process.stdin.setEncoding('utf8')
|
|
118
|
+
process.stdin.on('data', (c) => { input += c })
|
|
119
|
+
process.stdin.on('end', () => {
|
|
120
|
+
try {
|
|
121
|
+
const out = runTurnCheck({ input })
|
|
122
|
+
if (out) process.stdout.write(JSON.stringify(out))
|
|
123
|
+
} catch { /* never fail the session */ }
|
|
124
|
+
process.exit(0)
|
|
125
|
+
})
|
|
126
|
+
}
|
package/package.json
CHANGED