Add brain_delete_events MCP tool

[selfcontained]

Agents could append and query Brain events but never prune them, so noisy collections grew without bound. brain_delete_events closes that gap.

Shape

Two mutually exclusive modes:

• ids — specific events, from brain_query_events (uuid-validated, max 200)
• filter — a required collection, optionally narrowed by kind, subject, tags, since, until

dryRun returns { deleted: 0, matched: n } by counting through the same WHERE/params the delete would use, so a preview can't drift from what a subsequent delete removes. Real deletes return { deleted, matched }. Everything is repo_root-scoped from server-side agent context, never from tool input.

Why a collection is required

This repo's job prompts all record kind: "run" in their own collection — docs-audit, tech-debt, test-enforcer, componentizer, persona-review. An unscoped brain_delete_events({ kind: "run" }) reads as pruning one job's history while actually deleting all five. Filter deletes now name a collection; the ids path is unaffected since ids are unique and already repo-scoped.

The constraint is not a dead end: the tool description and the error message both point at brain_query_events without a collection, which returns each event's collection and so enumerates what exists.

Guardrails worth calling out

• since/until must be real ISO 8601 instants. Postgres accepts now, epoch, infinity, yesterday as timestamptz literals, so a loose string would have silently matched the entire log. Date.parse alone is insufficient too — it rolls Feb 30 to Mar 2 and accepts year 0 — hence an explicit calendar check. isIsoInstant is the single rule; the zod schema refines against it rather than restating it, and .meta({ format: "date-time" }) keeps the published schema informative.
• Selectors are legal by construction.BrainEventDeleteSelector is a union, and one exported toEventDeleteSelector owns the ids-XOR-collection-scoped-filter rule — the MCP handler calls it to narrow its args, and deleteEvents calls it again so untyped callers hit the same gate. Guarding on presence rather than length matters: { collection, ids: [] } must be rejected, not silently widened to a collection-wide delete.
• deleteEvent delegates to deleteEvents, so one DELETE statement remains and the existing HTTP route's id path is provably identical.

Not included

No bulk-delete HTTP route and no UI affordance — the Brains UI still deletes events one at a time. Those can follow.

Testing

pnpm run check clean · pnpm run test 3344 passed · pnpm run test:e2e 178 passed

~20 new tests, plus live verification against a dev MCP endpoint after each change: unscoped filters, Postgres special literals, impossible dates, empty ids, and ids-plus-filter all rejected as typed errors with nothing deleted; dry run and scoped delete behave. Two guards were confirmed by mutation — dropping the repo_root predicate from the ids branch, and reverting the presence-based ids check, each make their test fail.

Reviewed by the backend-security-review and architecture-review personas; all nine findings resolved.

🤖 Generated with Claude Code