@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.
@@ -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()
@@ -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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theronap/agnoclast-mcp",
3
- "version": "0.9.311",
3
+ "version": "0.9.312",
4
4
  "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
5
5
  "type": "module",
6
6
  "bin": {