@theronap/agnoclast-mcp 0.9.310 → 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
package/lib/server.mjs CHANGED
@@ -2997,7 +2997,7 @@ function renderNudge(payload) {
2997
2997
  'place_split_records',
2998
2998
  {
2999
2999
  title: 'Place a split\'s records, sorted by a full read',
3000
- description: 'Place the records of a split you APPLIED, in ONE transaction: child = attach to the child and detach from the source; both = attach to the child too; parent = leave. PROCEDURE, every split: (a) FULL READ — list the whole worklist with split_records. Read EVERY candidate in full with read_record part "all" and max_chars at least its length. Each recording over ~20k chars gets its OWN sub-agent that reads every word: no keyword search, no skimming (a trial agent once keyword-searched two 150k transcripts). Decide child (only about the moved text), parent (only about what stayed) or both; anything unclear → both. (b) SHADOW — also run the FROZEN rules that split_records prints on its first page, without looking at the full read (Haiku segments each recording; Opus decides with rules 1–5, incl. the 0.7 confidence floor), and send them as `shadow` for the same records. Only the full read is applied. (c) INBOUND LINKS — grep "[[<source title>]]" in substring mode; judge each link from its snippet; edit_page the ones you may edit to point at the child when they meant the moved text; list the rest for their owners. (d) GOVERNANCE NEVER MOVES — a record governed by the source stays on it even when you say child (it goes on both). Every readable candidate needs a decision (parent leaves it). Idempotent: a second call returns the first result. Replies with the shadow diff (harmful = the rules put a record on fewer pages or the opposite one; clutter = the rules said both) and the rules\' streak (they graduate after 10 clean splits in a row).',
3000
+ description: 'Place the records of a split you APPLIED, in ONE transaction: child = attach to the child and detach from the source; both = attach to the child too; parent = leave. PROCEDURE, every split: (a) FULL READ — list the whole worklist with split_records. Read EVERY candidate in full with read_record part "all" and max_chars at least its length. Each recording over ~20k chars gets its OWN sub-agent that reads every word: no keyword search, no skimming (a trial agent once keyword-searched two 150k transcripts). BOTH IS THE DEFAULT: a record goes on one page only when its own content clearly rules it out of the other (mostly-about is not enough); one with nothing readable (a header-only email) can never rule itself out → both. (b) SHADOW — also run the FROZEN rules that split_records prints on its first page, without looking at the full read (Haiku segments each recording; Opus decides with rules 1–5, incl. the 0.7 confidence floor), and send them as `shadow` for the same records. Only the full read is applied. (c) INBOUND LINKS — grep "[[<source title>]]" in substring mode; judge each link from its snippet; edit_page the ones you may edit to point at the child when they meant the moved text; list the rest for their owners. (d) GOVERNANCE NEVER MOVES — a record governed by the source stays on it even when you say child (it goes on both). Every readable candidate needs a decision (parent leaves it). Idempotent: a second call returns the first result. Replies with the shadow diff (harmful = the rules put a record on fewer pages or the opposite one; clutter = the rules said both) and the rules\' streak (they graduate after 10 clean splits in a row).',
3001
3001
  inputSchema: {
3002
3002
  plan: z.string().describe('the `plan` token of the applied split'),
3003
3003
  decisions: z.array(z.object({
@@ -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.310",
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": {