Skip to content

A self-organizing Obsidian vault that gives AI coding agents persistent memory.

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.ts
index 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.ts
index 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.ts
index 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);
+ });
+});