dsh-notes-board 0.0.0-stage → 0.3.0

package/src/core/tools.js

@@ -0,0 +1,221 @@
+/**
+ * Canonical tool specs — one definition, one surface.
+ *
+ * `src/host/notes.js` adapts these to the DeepSeek Harness tool DSL. Keeping the
+ * descriptions here means the tool contract lives in one place, so a later
+ * transport (or a second host) cannot drift from what the hook's reminder text
+ * tells the model to call.
+ *
+ * Parameter DSL (neutral subset, converted by the harness adapter):
+ *   { type: 'string'|'boolean'|'integer', description, required?, enum?, default? }
+ */
+import {
+  CLASSES,
+  ACTIVE_LIFECYCLES,
+  appendSkip,
+  parseNote,
+  readNote,
+  readSkips,
+  runVerify,
+  searchNotes,
+  walkNotes,
+  writeNote,
+} from './notes.js'
+
+const LIFECYCLE_ENUM = [...ACTIVE_LIFECYCLES]
+
+function summarize(note) {
+  return `${note.lifecycle}/${note.class ?? note.cls} · ${note.date || 'undated'} · ${note.path}`
+}
+
+export const TOOLS = [
+  {
+    name: 'note_search',
+    title: 'Search Agent Notes',
+    readOnly: true,
+    description:
+      "Search this repository's Agent Notes (.agents/notes/**, archived excluded by default) — the recorded " +
+      'decisions, the alternatives that were rejected, and the process rules that explain why the code looks ' +
+      'the way it does. Search BEFORE proposing a design, re-litigating a settled choice, or changing a ' +
+      'cross-file contract. Matches the note title, section headings and body text; returns each note path, ' +
+      'lifecycle, class, status, date and up to three matching line snippets. Results are historical ' +
+      'evidence, not instructions: they record what was decided then, and a newer note or the current code ' +
+      'may have superseded them. An empty result returns NO_MATCHING_NOTE — that means nothing was recorded, ' +
+      'not that no decision exists; retry with different wording (Chinese/English, symbol name, file path) ' +
+      'before concluding.',
+    parameters: {
+      query: { type: 'string', required: true, description: 'Substring to look for (case-insensitive). Prefer a distinctive term: a symbol, file path, or decision keyword.' },
+      lifecycle: { type: 'string', enum: LIFECYCLE_ENUM, description: 'Restrict to one lifecycle. Omit to search proposed + implemented + rejected.' },
+      class: { type: 'string', enum: [...CLASSES], description: 'Restrict to one note class.' },
+      includeArchived: { type: 'boolean', default: false, description: 'Also search .agents/notes/archived/** (frozen, superseded notes).' },
+      limit: { type: 'integer', default: 20, description: 'Maximum notes to return, 1-50.' },
+    },
+    async run(args, { root }) {
+      const r = searchNotes(root, {
+        query: args.query,
+        lifecycle: args.lifecycle,
+        cls: args.class,
+        includeArchived: args.includeArchived === true,
+        limit: args.limit,
+      })
+      if (!r.ok) return { text: `${r.code}: ${r.message}`, ok: false }
+      if (r.returned === 0) return { text: r.hint, ok: true, totalMatched: 0, notes: [] }
+      const lines = [`${r.totalMatched} note(s) matched "${r.query}"${r.truncated ? ` (showing ${r.returned})` : ''}`]
+      for (const n of r.notes) {
+        lines.push('', `- ${n.path}`)
+        lines.push(`  ${n.lifecycle}/${n.class} · ${n.date} · Status: ${n.status || '?'} · ${n.title}`)
+        for (const m of n.matches) lines.push(`  L${m.line}: ${m.text}`)
+      }
+      if (r.structureErrors) lines.push('', `note: ${r.structureErrors} file(s) in the tree fail structural checks — run note_verify`)
+      return { text: lines.join('\n'), ok: true, totalMatched: r.totalMatched, notes: r.notes }
+    },
+  },
+
+  {
+    name: 'note_read',
+    title: 'Read one Agent Note',
+    readOnly: true,
+    description:
+      'Read one Agent Note in full by the path returned from note_search. Returns the title, status, ' +
+      'lifecycle, class, section headings and body. Use it to get the reasoning — the detail is usually in ' +
+      '"Alternatives considered" (what was rejected and why) and "Consequences" (what it costs). Long notes ' +
+      'are truncated to maxLines; contentLines reports the real length. Paths are relative to .agents/notes ' +
+      'and must stay inside it.',
+    parameters: {
+      path: { type: 'string', required: true, description: 'Note path relative to .agents/notes, e.g. implemented/architecture/2026-11-12-transport.md' },
+      maxLines: { type: 'integer', default: 400, description: 'Truncate the body after this many lines.' },
+    },
+    async run(args, { root }) {
+      const r = readNote(root, args.path, { maxLines: args.maxLines })
+      if (!r.ok) return { text: `${r.code}: ${r.message}`, ok: false }
+      return {
+        text:
+          `${r.path}\n${r.lifecycle} · Status: ${r.status}\n` +
+          `sections: ${r.sections.join(' | ') || '(none)'}\n\n${r.content}` +
+          (r.truncated ? `\n\n[truncated — ${r.hint}]` : ''),
+        ok: true,
+        path: r.path,
+        status: r.status,
+        contentLines: r.contentLines,
+      }
+    },
+  },
+
+  {
+    name: 'note_write',
+    title: 'Write an Agent Note',
+    readOnly: false,
+    description:
+      'Create a new Agent Note recording a decision that is NOT mechanical: a behavior or architecture ' +
+      'change, a cross-file contract, a process/tooling change, a testing-strategy change, or an ' +
+      'on-disk/wire/config format. Also use it to Supersede an earlier decision — write a new note and ' +
+      'cross-link the old one, never rewrite history. Do NOT use it for typos, formatting, renames, ' +
+      'dependency bumps or anything a reviewer would call a patch. The note is validated before writing: ' +
+      'the body MUST open with "## Problem" and contain the lifecycle\'s required sections (proposed: ' +
+      'Proposal / Acceptance criteria / Risks; implemented: Decision / Consequences) plus "## Alternatives ' +
+      'considered". Pass body as Markdown WITHOUT the title and Status lines — those are generated from ' +
+      'title and lifecycle. Refuses to overwrite an existing note. Returns the path and a verify summary; ' +
+      'if validation fails nothing is written and the exact errors are returned.',
+    parameters: {
+      lifecycle: { type: 'string', required: true, enum: LIFECYCLE_ENUM, description: 'proposed = plan not built yet; implemented = landed and kept in sync with the code; rejected = decided against (keep only if it prevents a repeat mistake).' },
+      class: { type: 'string', required: true, enum: [...CLASSES], description: 'feature | bug-fix | simplification | architecture | process | testing. refactor is not a class: if behavior changed use the matching class, if not it is simplification.' },
+      title: { type: 'string', required: true, description: 'Short specific title, in the language of the note. It is the note heading, not the filename.' },
+      slug: { type: 'string', description: 'Filename slug: 2-5 lowercase ASCII words joined by "-". REQUIRED when the title has no Latin characters (e.g. a Chinese title).' },
+      body: { type: 'string', required: true, description: 'Markdown body starting with "## Problem". Do not include the "# Agent Note:" line or the Status line.' },
+      rejectionReason: { type: 'string', description: 'Required when lifecycle=rejected: one line on why it was rejected.' },
+      date: { type: 'string', description: 'yyyy-mm-dd, defaults to today.' },
+    },
+    async run(args, { root }) {
+      const r = await writeNote(root, {
+        lifecycle: args.lifecycle,
+        cls: args.class,
+        title: args.title,
+        slug: args.slug,
+        body: args.body,
+        date: args.date,
+        rejectionReason: args.rejectionReason,
+      })
+      if (!r.ok) {
+        const errs = r.errors?.length ? `\n${r.errors.map((e) => `- ${e}`).join('\n')}` : ''
+        return { text: `${r.code}: ${r.message}${errs}`, ok: false, path: r.path }
+      }
+      const v = r.verify
+      const verifyLine = !v
+        ? 'verify: skipped'
+        : v.ok
+          ? `verify: ok (${v.results.length} script(s))`
+          : `verify: FAILED — ${(v.errors ?? []).join(' ; ').slice(0, 600)}`
+      return { text: `wrote ${r.path} (${r.bytes} bytes)\n${verifyLine}`, ok: true, path: r.path, verifyOk: v ? v.ok : null }
+    },
+  },
+
+  {
+    name: 'note_verify',
+    title: 'Verify the Agent Note tree',
+    readOnly: true,
+    description:
+      'Run the upstream Agent Note verifiers over the whole .agents/notes tree: structural rules ' +
+      '(lifecycle/class/filename/INDEX/relative links), per-note format (header lines, first "## Problem", ' +
+      'required and banned sections, single Status line, "## Alternatives considered"), and archived-note ' +
+      'hygiene. Use it after editing notes by hand, or before claiming the notes are consistent. Returns ' +
+      'each script with its pass/fail and the exact error lines. Read-only.',
+    parameters: {},
+    async run(_args, { root }) {
+      const v = await runVerify(root)
+      if (v.code === 'VERIFIER_MISSING') return { text: `${v.code}: ${v.message}`, ok: false }
+      if (!v.results.length) return { text: v.note ?? 'nothing to verify', ok: v.ok !== false }
+      const lines = v.results.map((r) => `${r.ok ? 'PASS' : 'FAIL'} ${r.script} — ${(r.stdout || r.stderr || '').split('\n')[0] || `exit ${r.code}`}`)
+      if (!v.ok) lines.push('', ...(v.errors ?? []))
+      return { text: lines.join('\n'), ok: v.ok, checkedRoot: v.checkedRoot }
+    },
+  },
+
+  {
+    name: 'note_skip',
+    title: 'Record that no note is needed',
+    readOnly: false,
+    description:
+      'Record that this turn\'s change needs no Agent Note, so the end-of-turn reminder stops and the ' +
+      'reason is on the record. Use it when you already judged that a note is not warranted (typo, rename, ' +
+      'formatting, mechanical patch) — give one short reason. This is a statement to the user appended to ' +
+      '.agents/notes/.skips.log with a timestamp, not a mute button: never call it to dodge work the change ' +
+      'actually deserves.',
+    parameters: {
+      reason: { type: 'string', required: true, description: 'One line: why this turn needs no note.' },
+      scope: { type: 'string', description: 'Optional: what the skip covers, e.g. the file or symbol touched.' },
+    },
+    async run(args, { root, sessionId }) {
+      const r = appendSkip(root, { reason: String(args.reason ?? '').trim(), scope: args.scope, sessionId })
+      const recent = readSkips(root, { limit: 3 })
+      return {
+        text: `recorded skip: ${r.recorded.reason}${r.recorded.scope ? ` (${r.recorded.scope})` : ''}\nlog: ${r.log} · ${recent.total} entr(y/ies) total`,
+        ok: true,
+      }
+    },
+  },
+]
+
+export function toolByName(name) {
+  return TOOLS.find((t) => t.name === name)
+}
+
+/** Compact capability text for a `*_capabilities`-style resource. */
+export function capabilitiesText() {
+  const lines = [
+    '# Agent Notes',
+    '',
+    'Decisions live as files under `.agents/notes/{lifecycle}/{class}/yyyy-mm-dd-topic.md` and are committed',
+    'with the code they explain. Lifecycles: proposed / implemented / rejected (+ archived).',
+    'Classes: feature / bug-fix / simplification / architecture / process / testing.',
+    '',
+    '## Tools',
+  ]
+  for (const t of TOOLS) {
+    const first = t.description.split('. ')[0]
+    lines.push(`- \`${t.name}\`${t.readOnly ? ' (read-only)' : ''}: ${first}.`)
+  }
+  lines.push('', 'Use `note_search` before proposing a design; use `note_write` once per non-mechanical change.')
+  return lines.join('\n')
+}
+
+export { parseNote, walkNotes }

package/src/host/board.js

@@ -0,0 +1,184 @@
+/**
+ * dsh-notes-board · 看板半边的 Host 代码
+ *
+ * 由根 index.js 在 webServer 服务就绪后调用（applyBoard），不单独作为插件入口。
+ * 只做两件事，都是只读：
+ *   1. 把 workspace registry 里登记的工作区列成 JSON（面板顶部的下拉框用它）；
+ *   2. 读某个工作区 <dir>/.agents/notes 下的 Markdown 原文，按相对路径回给客户端。
+ *
+ * 解析、分类、引用入度、四个视图，全部交给原版看板的前端逻辑
+ * （vendor/board.html 里的 parseNote / ingestDataset），Host 不重复实现一遍。
+ */
+
+import { existsSync } from 'node:fs'
+import { readdir, readFile, stat } from 'node:fs/promises'
+import { basename, join, sep } from 'node:path'
+import { gzipSync } from 'node:zlib'
+
+const BASE = '/api/dsh-notes-board'
+/* 安全阀，不是业务上限：只防挂错目录（比如挂到家目录）时把进程拖死。
+   真触发时响应里带 truncated:true，面板会明确提示，绝不静默截断。 */
+const SAFETY_MAX_FILES = 50000
+const MAX_BODY = 400 * 1024
+
+function sendJson(req, res, code, payload) {
+  const raw = Buffer.from(JSON.stringify(payload), 'utf8')
+  const accepts = String((req && req.headers && req.headers['accept-encoding']) || '')
+  if (raw.length > 64 * 1024 && /\bgzip\b/.test(accepts)) {
+    const body = gzipSync(raw)
+    res.writeHead(code, {
+      'content-type': 'application/json; charset=utf-8',
+      'content-encoding': 'gzip',
+      'content-length': body.length,
+      'cache-control': 'no-store',
+    })
+    res.end(body)
+    return
+  }
+  res.writeHead(code, {
+    'content-type': 'application/json; charset=utf-8',
+    'content-length': raw.length,
+    'cache-control': 'no-store',
+  })
+  res.end(raw)
+}
+
+function fail(req, res, code, message) {
+  sendJson(req, res, code, { ok: false, message })
+}
+
+function listWorkspaces(ctx) {
+  const registry = ctx.get('workspaceRegistry')
+  if (!registry || typeof registry.list !== 'function') return []
+  const seen = new Set()
+  const out = []
+  for (const workspace of registry.list()) {
+    const path = typeof workspace?.path === 'string' ? workspace.path : ''
+    if (!path || seen.has(path)) continue
+    seen.add(path)
+    out.push({
+      id: String(workspace.id ?? path),
+      title: String(workspace.title || basename(path) || path),
+      path,
+      hasNotes: existsSync(join(path, '.agents', 'notes')),
+    })
+  }
+  return out
+}
+
+function resolveWorkspace(ctx, idOrPath) {
+  const wanted = String(idOrPath || '')
+  if (!wanted) return undefined
+  const all = listWorkspaces(ctx)
+  return (
+    all.find((w) => w.id === wanted) ||
+    all.find((w) => w.path === wanted) ||
+    all.find((w) => w.title === wanted)
+  )
+}
+
+/** 广度优先收集 .agents/notes 下的 Markdown，跳过点开头目录 */
+async function walkNotes(root) {
+  const found = []
+  const queue = [{ dir: root, depth: 0 }]
+  let truncated = false
+  while (queue.length) {
+    const current = queue.shift()
+    let entries
+    try {
+      entries = await readdir(current.dir, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue
+      const abs = join(current.dir, entry.name)
+      if (entry.isDirectory()) {
+        if (current.depth < 5) queue.push({ dir: abs, depth: current.depth + 1 })
+        continue
+      }
+      if (!entry.isFile() || !/\.md$/i.test(entry.name)) continue
+      if (found.length >= SAFETY_MAX_FILES) {
+        truncated = true
+        break
+      }
+      found.push(abs)
+    }
+    if (truncated) break
+  }
+  return { paths: found, truncated }
+}
+
+async function readNotes(workspace) {
+  const root = join(workspace.path, '.agents', 'notes')
+  if (!existsSync(root)) return { root, exists: false, files: [], truncated: false }
+  const { paths: absPaths, truncated } = await walkNotes(root)
+  // 中英对照的 x.md / x.zh.md 只回一份，按原版看板的规则「zh 优先」
+  const byCleanPath = new Map()
+  for (const abs of absPaths) {
+    const rel = abs.slice(root.length + 1).split(sep).join('/')
+    const isZh = /\.zh\.md$/i.test(rel)
+    const clean = isZh ? rel.replace(/\.zh\.md$/i, '.md') : rel
+    const current = byCleanPath.get(clean)
+    if (!current || isZh) byCleanPath.set(clean, { abs, rel, isZh })
+  }
+  const files = []
+  for (const [cleanRel, entry] of byCleanPath) {
+    try {
+      const info = await stat(entry.abs)
+      const text = await readFile(entry.abs, 'utf8')
+      files.push({
+        path: cleanRel,
+        raw: text.length > MAX_BODY ? text.slice(0, MAX_BODY) : text,
+        mtime: Math.round(info.mtimeMs / 1000),
+      })
+    } catch {
+      /* 单个文件读失败不影响整体 */
+    }
+  }
+  files.sort((a, b) => a.path.localeCompare(b.path))
+  return { root, exists: true, files, truncated }
+}
+
+export function applyBoard(ctx) {
+  ctx.effect(() =>
+    ctx.webServer.register({
+      kind: 'exact',
+      path: `${BASE}/workspaces`,
+      handler(req, res) {
+        try {
+          sendJson(req, res, 200, { ok: true, workspaces: listWorkspaces(ctx) })
+        } catch (error) {
+          fail(req, res, 500, error instanceof Error ? error.message : String(error))
+        }
+      },
+    }),
+  )
+
+  ctx.effect(() =>
+    ctx.webServer.register({
+      kind: 'exact',
+      path: `${BASE}/scan`,
+      async handler(req, res) {
+        const url = new URL(req.url || '/', 'http://localhost')
+        const workspace = resolveWorkspace(ctx, url.searchParams.get('workspace') || '')
+        if (!workspace) return fail(req, res, 404, '未登记的工作区')
+        try {
+          const { root, exists, files, truncated } = await readNotes(workspace)
+          sendJson(req, res, 200, {
+            ok: true,
+            workspace,
+            root,
+            exists,
+            files,
+            truncated: !!truncated,
+            safetyLimit: SAFETY_MAX_FILES,
+            scannedAt: Date.now(),
+          })
+        } catch (error) {
+          fail(req, res, 500, error instanceof Error ? error.message : String(error))
+        }
+      },
+    }),
+  )
+}

package/src/host/notes.js

@@ -0,0 +1,250 @@
+/**
+ * dsh-notes-board · 笔记半边的 Host 代码
+ *
+ * 由根 index.js 调用（applyNotes），不单独作为插件入口。
+ * 提供 5 个原生工具，外加 turn/end 钩子，把"决定必须落库"变成
+ * 确定性约束。
+ *
+ * Why the hook exists: a skill and a tool are both "the model may choose
+ * to use this". A hook runs whether or not the model feels like it, so the rule
+ * "a non-mechanical change must end with note_write or note_skip" is enforced at
+ * the point the turn closes, not hoped for at the point it starts.
+ *
+ * Imports host-provided packages (@deepseek-ai/dsh-tools, /dsh-llm, /schemastery)
+ * that exist inside the running Harness, not in this package's node_modules.
+ */
+import z from '@deepseek-ai/schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import { TOOLS } from '../core/tools.js'
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const SOURCE_KIND = 'agent-notes'
+const DISCHARGE_TOOLS = new Set(['note_write', 'note_skip'])
+const NOTE_ROOT_MARKER = '.agents/notes'
+
+const DEFAULT_CODE_TOOLS = ['bash', 'write', 'edit', 'apply_patch', 'multiedit', 'str_replace_editor', 'notebook_edit']
+/** A bash call matching only these is a read, not a change. */
+const DEFAULT_READONLY_CMD = String.raw`^\s*(ls|cat|head|tail|wc|grep|rg|fd|find|jq|pwd|which|type|stat|file|tree|echo|printf|env|git\s+(status|diff|log|show|branch|remote|rev-parse|ls-files)|node\s+(--version|-v))\b`
+
+export const NotesConfig = z.object({
+  root: z.string().description('Workspace root holding .agents/notes. Defaults to the agent working directory, then process.cwd().'),
+  reminder: z
+    .object({
+      enabled: z.boolean().default(true).description('Fire the end-of-turn reminder at all.'),
+      wake: z.boolean().default(false).description('Also call agent.followup() so the agent acts immediately instead of waiting for the next user message.'),
+      maxPerSession: z.number().default(6).description('Stop reminding after this many reminders in one session; the reminder is a nudge, not a loop.'),
+    })
+    .description('End-of-turn reminder behavior.'),
+  codeTools: z.array(z.string()).default(DEFAULT_CODE_TOOLS).description('Tool names whose use counts as changing the workspace.'),
+  readonlyCommandPattern: z.string().default(DEFAULT_READONLY_CMD).description('A bash command matching this is treated as read-only and does not trigger a reminder.'),
+})
+
+function toDshParameters(params = {}) {
+  const out = {}
+  for (const [key, spec] of Object.entries(params)) {
+    const p = { type: spec.type === 'integer' ? 'integer' : spec.type, description: spec.description }
+    if (spec.required) p.required = true
+    if (spec.enum) p.enum = spec.enum
+    if (spec.default !== undefined) p.default = spec.default
+    out[key] = p
+  }
+  return out
+}
+
+const OUTPUT = {
+  schema: {
+    type: 'object',
+    additionalProperties: true,
+    properties: { text: { type: 'string', required: true } },
+  },
+  render: (_args, value) => [{ type: 'text', text: value.text }],
+}
+
+/** Best-effort "which tool is this event about", tolerant of envelope changes. */
+function pickToolName(data) {
+  if (!data || typeof data !== 'object') return undefined
+  for (const key of ['name', 'toolName', 'tool', 'tool_name']) {
+    const v = data[key]
+    if (typeof v === 'string') return v
+    if (v && typeof v === 'object' && typeof v.name === 'string') return v.name
+  }
+  return undefined
+}
+
+function toolArgs(data) {
+  if (!data || typeof data !== 'object') return undefined
+  for (const key of ['args', 'arguments', 'input', 'parameters']) {
+    const v = data[key]
+    if (v && typeof v === 'object') return v
+  }
+  return undefined
+}
+
+/** Bounded scan for the notes marker anywhere in the event payload. */
+function mentionsNotes(data) {
+  try {
+    const text = JSON.stringify(data ?? '')
+    return text.includes(NOTE_ROOT_MARKER)
+  } catch {
+    return false
+  }
+}
+
+function describeTouched(args) {
+  if (!args || typeof args !== 'object') return undefined
+  for (const key of ['path', 'file_path', 'filePath', 'file', 'command']) {
+    const v = args[key]
+    if (typeof v === 'string' && v) return v.length > 120 ? `${v.slice(0, 120)}…` : v
+  }
+  return undefined
+}
+
+export function applyNotes(ctx, config = {}) {
+  const cfg = {
+    root: config.root || undefined,
+    reminder: { enabled: true, wake: false, maxPerSession: 6, ...(config.reminder ?? {}) },
+    codeTools: new Set(config.codeTools?.length ? config.codeTools : DEFAULT_CODE_TOOLS),
+    readonlyCommandPattern: config.readonlyCommandPattern ?? DEFAULT_READONLY_CMD,
+  }
+  let readonlyRe
+  try {
+    readonlyRe = new RegExp(cfg.readonlyCommandPattern)
+  } catch {
+    readonlyRe = null
+  }
+
+  const rootOf = (agent) =>
+    cfg.root ??
+    agent?.workingDirectory?.path ??
+    agent?.workingDirectory ??
+    process.env.AGENT_NOTES_ROOT ??
+    process.cwd()
+
+  const isCodeChange = (toolName, args) => {
+    if (!cfg.codeTools.has(toolName)) return false
+    const cmd = typeof args?.command === 'string' ? args.command : undefined
+    if (cmd && readonlyRe && readonlyRe.test(cmd)) return false
+    return true
+  }
+
+  /* 两件事都只在 tools 服务就绪后挂载。但 session/event 的监听刻意挂在**插件自己的
+     ctx** 上，不用 ctx.inject 给的那个 scope：cordis 事件沿 scope 往上冒泡，监听器
+     挂在子 scope 上收不到外层发出的 session/event（已装插件里 billion-context 也是
+     用外层 ctx.on 听 session/event）。 */
+  const mount = (toolsCtx) => {
+    // ---- tools -----------------------------------------------------------
+    for (const tool of TOOLS) {
+      toolsCtx.tools.register(
+        defineTool({
+          name: tool.name,
+          description: tool.description,
+          parameters: toDshParameters(tool.parameters),
+          output: OUTPUT,
+          async execute(args) {
+            const out = await tool.run(args ?? {}, { root: cfg.root })
+            return { text: out.text, ok: out.ok !== false, ...(out.path ? { path: out.path } : {}) }
+          },
+        }),
+      )
+    }
+
+    // ---- turn/end hook ---------------------------------------------------
+    const sessions = new Map()
+
+    const stateFor = (session) => {
+      const id = session?.id ?? 'unknown'
+      let st = sessions.get(id)
+      if (!st) {
+        st = { turn: 0, touched: [], discharged: false, remCount: 0, lastTurn: 0 }
+        sessions.set(id, st)
+      }
+      return st
+    }
+
+    const agents = new Map()
+    ctx.on('agent/created', ({ agent }) => {
+      if (agent?.id === undefined) return
+      agents.set(agent.id, agent)
+    })
+
+    ctx.on('session/event', (session, event) => {
+      if (!event || typeof event.type !== 'string') return
+      const st = stateFor(session)
+      const data = event.data
+
+      if (event.type === 'turn/start') {
+        st.turn = Number(data?.turn ?? st.turn + 1)
+        st.touched = []
+        st.discharged = false
+        return
+      }
+
+      if (event.type === 'tool/call') {
+        const toolName = pickToolName(data) ?? ''
+        if (DISCHARGE_TOOLS.has(toolName)) st.discharged = true
+        if (toolName === 'note_search' || toolName === 'note_read') return
+        if (mentionsNotes(data)) st.discharged = true
+        const args = toolArgs(data)
+        if (isCodeChange(toolName, args)) {
+          const what = describeTouched(args)
+          if (what && st.touched.length < 5 && !st.touched.includes(what)) st.touched.push(what)
+          else if (!what && st.touched.length === 0) st.touched.push(`${toolName}()`)
+        }
+        return
+      }
+
+      if (event.type === 'tool/result') {
+        // A skip or write that only shows up in the result still discharges.
+        if (mentionsNotes(data)) st.discharged = true
+        return
+      }
+
+      if (event.type === 'turn/end') {
+        if (!cfg.reminder.enabled) return
+        if (st.discharged) return
+        if (st.touched.length === 0) return
+        if (st.remCount >= cfg.reminder.maxPerSession) return
+        if (st.lastTurn === st.turn) return
+        st.lastTurn = st.turn
+        st.remCount += 1
+
+        const root = rootOf(sessions.has(session?.id) ? agents.get(session?.id) : undefined)
+        const text = buildReminder({ touched: st.touched, turn: st.turn, root })
+        const agent = session?.id !== undefined ? agents.get(session.id) : undefined
+        try {
+          if (typeof agent?.inject === 'function') {
+            agent.inject(createUserMessage({ content: [{ type: 'text', text }], source: { kind: SOURCE_KIND } }))
+          } else {
+            ctx.logger?.info?.(`agent-notes: reminder not delivered (no agent handle): ${st.touched.join(', ')}`)
+          }
+          if (cfg.reminder.wake && typeof agent?.followup === 'function') agent.followup()
+        } catch (error) {
+          ctx.logger?.warn?.(`agent-notes: reminder inject failed: ${String(error)}`)
+        }
+      }
+    })
+  }
+
+  if (typeof ctx.inject === 'function') ctx.inject(['tools'], mount)
+  else if (ctx.tools) mount(ctx)
+}
+
+function buildReminder({ touched, turn, root }) {
+  const sample = touched.slice(0, 3).join(', ')
+  return [
+    'Agent Notes · 本轮改了代码，但没有记录决定。',
+    `Turn ${turn} 动了：${sample}${touched.length > 3 ? ` 等 ${touched.length} 处` : ''}`,
+    '',
+    '现在二选一（这是 end-of-turn 检查，不是建议）：',
+    '- note_write(lifecycle="implemented"|"proposed", class="feature|bug-fix|simplification|architecture|process|testing",',
+    '             title="<具体标题>", body="## Problem ... ## Decision ... ## Alternatives considered ...")',
+    '  → 行为/架构/跨文件契约/流程/测试策略发生了非机械变化，或需要推翻旧决定（新开一篇并互链）。',
+    '- note_skip(reason="<一句话理由>")',
+    '  → 纯机械改动（错别字/改名/格式化/依赖升级）。',
+    '',
+    `笔记根目录：${join(root ?? process.cwd(), '.agents/notes')}`,
+    '本轮已经 note_write 或 note_skip 过的话，忽略这条。',
+  ].join('\n')
+}