Skip to content

feat: build piyaz_note MCP tool on the v2 ref-first surface#197

Merged
FrkAk merged 5 commits into
mainfrom
feat/PYZ-251-piyaz-note-tool
Jul 7, 2026
Merged

feat: build piyaz_note MCP tool on the v2 ref-first surface#197
FrkAk merged 5 commits into
mainfrom
feat/PYZ-251-piyaz-note-tool

Conversation

@FrkAk

@FrkAk FrkAk commented Jul 7, 2026

Copy link
Copy Markdown
Owner

Summary

Task Reference: [PYZ-251]

Adds piyaz_note as the 9th MCP tool: the agent write-back surface over the Notes data ring. Eleven actions: create (1-10 notes, idempotent by exact folder+title, agent defaults visibility=team, feed_mode=none), read (meta / exact fields / one heading section / revision list / one snapshot), edit (1-20 ordered ops via the shared text-op engine, ifUpdatedAt CAS), list (the folder tree humans see), move (note or folder subtree), delete (preview-by-default) / restore, request_share, link/unlink (reference|spec_of note-task relations), and search (RLS-scoped: team notes any feed mode plus the caller's own private notes).

Supporting work:

  • Note refs (PYZ-N12) become first-class: NOTE_REF_PATTERN, resolveNoteRef (ref / slug+project / UUID) with near-miss and ambiguity errors, requireNoteId, and entity-aware translateError copy. Every response emits refs (sequenceNumber + projectIdentifier added to note summaries, tree rows, search hits, and linked-note rows).
  • Text-op engine extracted from lib/data/task-edit.ts into lib/data/text-ops.ts; both editors share str_replace/append/set semantics and error copy. Note body ops fold inside updateNote's FOR UPDATE transaction.
  • Data ring additions: createNotesBatch, applyNoteEditOps, createNoteTaskLink/removeNoteTaskLink (mention stays derivation-owned), listNoteRevisions/getNoteRevision (first read surface over note_revisions; the mistake-recovery path), getNoteTreeForAgent, searchNotesForMcp, and fence-aware extractSection/listSections in note-parse.ts.
  • Governance by construction: visibility, locked, agent_writable are absent from the tool schema; locked and the creator-only private flip are already enforced in the data ring. PYZ-252 layers agent_writable and the agent team-flip ban onto these handlers.
  • Rate tiers: search, fields=['body'], and revision snapshots bill heavy; granular reads stay light.
  • Doctrine shipped with the tool: server INSTRUCTIONS (9-tool inventory plus a Notes write-back section), the /piyaz skill tool table and heuristic across all four plugin brands (sync:plugins run, check:plugins green).

Type of change

  • New feature

Testing

  • Tested locally with bun run dev
  • Linting passes (bun run lint)
  • Typecheck passes (bun run typecheck)

bun test: 1447 pass / 0 fail. New tests/graph/tools-note.test.ts (13 tests): batch idempotency and dedupe, ref/slug/UUID resolution with near-miss copy, edit-op parity (occurrence counts, CAS carrying fresh updatedAt+version, governance fields rejected), heading reads without body egress, revision recovery round-trip, tree list and folder moves with the cycle guard, delete preview/execute/restore, link kinds with duplicate-as-success, search scope (team any-feed plus own private), locked-note copy, request_share states, and taskRef-bearing feedTaskIds. Transport pin now expects 9 tools; docs generator emits the piyaz_note page.

Notes for reviewer

  • Contract decisions recorded on PYZ-251/PYZ-264: agent-created notes default team + feed=none (searchable immediately, injected only when a feed mode is deliberately set; supersedes the earlier §14.4 wording), and search is RLS-scoped rather than feed-resolver-gated (§14.3: feed=none means searchable but never auto-fed).
  • NoteSummary/NoteTreeRow/LinkedNoteSlim gained ref fields; the one web-visible behavior change is additive (optimistic rows fabricate sequenceNumber: 0).
  • Bundle injection (guidance parts, note pointers) is PYZ-253; runtime agent_writable rejections are PYZ-252.

Docs impact

Generated MCP tool reference picks up piyaz_note automatically via the Docs Sync workflow; no hand-written pages affected.

@FrkAk FrkAk requested review from ZeyNor and ulascanzorer as code owners July 7, 2026 17:47
@FrkAk FrkAk self-assigned this Jul 7, 2026
@FrkAk FrkAk merged commit f2a6c2a into main Jul 7, 2026
4 checks passed
@FrkAk FrkAk deleted the feat/PYZ-251-piyaz-note-tool branch July 7, 2026 19:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant