A self-organizing Obsidian vault that gives AI coding agents persistent memory.
TypeScript ai-agentsclaude-codecodex-cligemini-cliknowledge-managementobsidianobsidian-vaultpersistent-memorysecond-braintemplate
fix: the markup refusal names the failure, not only the field (#207)
HoangThai186d4530839545
diff --git a/.claude/scripts/lib/mcp-capture.ts b/.claude/scripts/lib/mcp-capture.tsindex ed3ee75..c8cf73d 100644--- a/.claude/scripts/lib/mcp-capture.ts+++ b/.claude/scripts/lib/mcp-capture.ts@@ -249,15 +249,93 @@ export function resolveDestination(*/const TOOL_MARKUP = /<parameter\s+name=|<\/?(?:antml:)?invoke\b|<\/?(?:antml:)?function_calls\b/i;-/** The fields a malformed call can corrupt, named so the error can say which. */-export function findToolMarkup(input: Record<string, unknown>): string | null {- for (const [key, value] of Object.entries(input)) {+/**+ * Closing tags with nothing but whitespace after them.+ *+ * This separates the two failures that both produce a TOOL_MARKUP hit and that+ * need OPPOSITE repairs, so the refusal can say which one happened. The test is+ * exact rather than heuristic: if a field swallowed the one after it, the+ * swallowed `<parameter name=` opener sits BEFORE any trailing tags, so+ * stripping them leaves the markup behind and the case reports `trailing: false`.+ */+const TRAILING_TAGS = /(?:\s*<\/(?:antml:)?(?:invoke|function_calls|parameter)\s*>)+\s*$/i;++/** Where a serialization failure landed, and which of the two shapes it is. */+export interface ToolMarkupSite {+ /** The argument the match sits inside. */+ readonly field: string;+ /** The framing that matched, verbatim, so the caller can search for it. */+ readonly match: string;+ /** Offset of the match within the field's text — the item's text, for a list. */+ readonly offset: number;+ /** 1-based item number when the field is a list, else null. */+ readonly item: number | null;+ /** True when only closing tags trail the caller's content, which leaves it intact. */+ readonly trailing: boolean;+}++/** Locate a serialization failure and describe it well enough to be repaired. */+export function describeToolMarkup(input: Record<string, unknown>): ToolMarkupSite | null {+ for (const [field, value] of Object.entries(input)) {const texts = Array.isArray(value) ? value.map((v) => String(v)) : [String(value ?? "")];- if (texts.some((t) => TOOL_MARKUP.test(t))) return key;+ for (const [i, text] of texts.entries()) {+ const m = TOOL_MARKUP.exec(text);+ if (!m) continue;+ return {+ field,+ match: m[0],+ offset: m.index,+ item: Array.isArray(value) ? i + 1 : null,+ trailing: !TOOL_MARKUP.test(text.replace(TRAILING_TAGS, "")),+ };+ }}return null;}+/**+ * The refusal both write tools return, built once.+ *+ * Naming the field is not enough to act on, because the two shapes need+ * opposite repairs: an EMBEDDED hit means content was lost and the call must be+ * rewritten, while a TRAILING hit means the prose is untouched and only the+ * tags are wrong. The old wording was the embedded instruction unconditionally,+ * so a trailing case sent the caller to rewrite prose that was never at fault —+ * and nothing in the message contradicted that reading, so they would do it+ * again. The evidence is quoted so the caller can go to the exact offset rather+ * than hunt for what fired.+ */+export function toolMarkupRefusal(site: ToolMarkupSite): string {+ const where = site.item === null ? `"${site.field}"` : `item ${site.item} of "${site.field}"`;+ const diagnosis = site.trailing+ ? [+ "It sits at the END of the field with none of your content after it, so the",+ "CALL is malformed rather than the prose. Extra closing tags after your last",+ "parameter were folded into the preceding string. Re-send the same text with",+ "exactly one closing tag per parameter — do not rewrite the prose, it is fine.",+ ]+ : [+ "Your content CONTINUES past it, so this field swallowed the field after it.",+ "What it swallowed cannot be recovered by guessing where it ended. Re-send the",+ "call with every field as a separate argument in plain prose, and check that a",+ "long list field was not folded into the preceding string.",+ ];+ return [+ `Refused: "${site.field}" contains tool-call markup, so this call's arguments did not serialize correctly.`,+ "",+ `Found "${site.match}" at offset ${site.offset} of ${where}.`,+ "",+ ...diagnosis,+ "",+ "Nothing was written.",+ ].join("\n");+}++/** The fields a malformed call can corrupt, named so the error can say which. */+export function findToolMarkup(input: Record<string, unknown>): string | null {+ return describeToolMarkup(input)?.field ?? null;+}+/** Render the note body. Pure, so the shape can be asserted without writing. */export function renderCapture(input: CaptureInput,diff --git a/.claude/scripts/lib/mcp-server.ts b/.claude/scripts/lib/mcp-server.tsindex 34bb060..5f26be6 100644--- a/.claude/scripts/lib/mcp-server.ts+++ b/.claude/scripts/lib/mcp-server.ts@@ -30,7 +30,7 @@ import { expandNote } from "./mcp-graph.ts";import { qmdSearch, type QmdClient } from "./mcp-qmd-client.ts";import { callerProject, callerProjectSource, isVaultItself, PROJECT_MARKER, sumAuditField, sanitize } from "./mcp-caller.ts";import { callerPlatforms, digestsFrom, resolvableNames } from "./mcp-memory-bridge.ts";-import { captureNote, findToolMarkup } from "./mcp-capture.ts";+import { captureNote, describeToolMarkup, toolMarkupRefusal } from "./mcp-capture.ts";import { semanticMemoryOrder } from "./mcp-memory-bridge.ts";import { TOOLS } from "./mcp-tools.ts";import { recallFrom, readMemories, type MemoryEntry } from "./memory-recall.ts";@@ -436,15 +436,8 @@ export function createHandlers(deps: ServerDeps): Handlers {// other repo through `recall`, so the damage travels. Checked before// wikilink neutralisation, because a field that has swallowed the following// field is not text worth cleaning up.- const corruptedMemory = findToolMarkup(args);- if (corruptedMemory) {- return [- `Refused: the "${corruptedMemory}" field contains tool-call markup, so this call's arguments did not serialize correctly.`,- "",- "Nothing was written. Re-send with each field as plain prose, and check that",- "a long list field was not folded into the preceding string.",- ].join("\n");- }+ const corruptedMemory = describeToolMarkup(args);+ if (corruptedMemory) return toolMarkupRefusal(corruptedMemory);const who = caller();const resolvable = resolvableNames(visibleFiles(ctx.vaultRoot, policy));@@ -535,15 +528,8 @@ export function createHandlers(deps: ServerDeps): Handlers {// not that the author wrote something odd. Refuse: writing it produces a// corrupted note whose damage is invisible until a human reads the rendered// markup, which is exactly how one shipped unnoticed.- const corrupted = findToolMarkup(args);- if (corrupted) {- return [- `Refused: the "${corrupted}" field contains tool-call markup, so this call's arguments did not serialize correctly.`,- "",- "Nothing was written. Re-send with each field as plain prose, and check that",- "a long list field was not folded into the preceding string.",- ].join("\n");- }+ const corrupted = describeToolMarkup(args);+ if (corrupted) return toolMarkupRefusal(corrupted);const who = callerProject(session.roots);const resolvable = resolvableNames(visibleFiles(ctx.vaultRoot, policy));let r;diff --git a/.claude/scripts/tests/capture-markup-guard.test.ts b/.claude/scripts/tests/capture-markup-guard.test.tsindex 4fcb48a..a48178f 100644--- a/.claude/scripts/tests/capture-markup-guard.test.ts+++ b/.claude/scripts/tests/capture-markup-guard.test.ts@@ -12,7 +12,7 @@import { describe, test } from "node:test";import assert from "node:assert/strict";-import { findToolMarkup } from "../lib/mcp-capture.ts";+import { findToolMarkup, describeToolMarkup, toolMarkupRefusal } from "../lib/mcp-capture.ts";describe("detecting a serialization failure in a capture field", () => {test("the exact shape that corrupted a note is caught, and names its field", () => {@@ -76,3 +76,52 @@ describe("detecting a serialization failure in a capture field", () => {assert.equal(findToolMarkup({ title: "retries", body }), "body");});});++/**+ * Telling the two shapes apart, because they need OPPOSITE repairs: an embedded+ * hit lost content and the call must be rewritten, a trailing hit left the prose+ * intact and only the tags are wrong. A message that cannot distinguish them+ * sends half its readers to rewrite text that was never at fault.+ */+describe("describing a serialization failure well enough to repair it", () => {+ const PROSE = "Landed the parser rewrite behind a feature flag.";++ test("clean prose does not match, so the absence of a false positive is pinned", () => {+ assert.equal(describeToolMarkup({ title: "parser", summary: PROSE }), null);+ });++ test("closing tags after the content are TRAILING — the prose is not at fault", () => {+ const site = describeToolMarkup({ summary: `${PROSE}</invoke></function_calls>` });+ assert.equal(site?.trailing, true);+ const msg = toolMarkupRefusal(site!);+ assert.match(msg, /Found "<\/invoke" at offset \d+ of "summary"/);+ assert.match(msg, /do not rewrite the prose/);+ assert.ok(!msg.includes("swallowed"), "must not accuse the prose of swallowing a field");+ });++ test("a swallowed following field is EMBEDDED, since content continues past it", () => {+ const summary = [`${PROSE}</summary>`, '<parameter name="changes">["src/parser.ts"]'].join("\n");+ const site = describeToolMarkup({ summary });+ assert.equal(site?.trailing, false);+ const msg = toolMarkupRefusal(site!);+ assert.match(msg, /swallowed the field after it/);+ assert.ok(!msg.includes("do not rewrite the prose"), "embedded content cannot be salvaged");+ });++ test("a list field names the offending item, not just the field", () => {+ const site = describeToolMarkup({ changes: ["fine", '<parameter name="decisions">[]'] });+ assert.equal(site?.item, 2);+ assert.match(toolMarkupRefusal(site!), /of item 2 of "changes"/);+ });++ test("the named field is the field the match sits inside, not the largest one", () => {+ const site = describeToolMarkup({ title: "ok", kind: "</invoke>", summary: "a much longer body" });+ assert.equal(site?.field, "kind");+ });++ test("the reported offset indexes to the reported match", () => {+ const summary = `${PROSE} <function_calls> tail`;+ const site = describeToolMarkup({ summary })!;+ assert.equal(summary.slice(site.offset, site.offset + site.match.length), site.match);+ });+});