@noesis-brain/mcp-server 2.1.5 → 2.3.1

package/scripts/start-agent.sh

@@ -23,6 +23,7 @@
 #         ./scripts/start-agent.sh --local    # this checkout's dist/ (after npm run build)
 #         ./scripts/start-agent.sh --status   # report running daemons, exit 1 if any is unfixed
 #         ./scripts/start-agent.sh --stop     # stop everything, start nothing
+#         ./scripts/start-agent.sh --grade <package-dir>   # grade one build; touches no process
 
 set -euo pipefail
 
@@ -39,8 +40,11 @@ MIN_FIXED_VERSION="2.1.5"
 MODE="${1:-}"
 case "$MODE" in
   ''|--local|--stop|--status) ;;
+  --grade)
+    [ -n "${2:-}" ] || { echo "usage: $(basename "$0") --grade <package-dir>" >&2; exit 2; }
+    ;;
   *)
-    echo "usage: $(basename "$0") [--local | --status | --stop]" >&2
+    echo "usage: $(basename "$0") [--local | --status | --stop | --grade <package-dir>]" >&2
     # Deliberately NOT a silent fallback: a typo'd flag used to start the PUBLISHED build
     # instead of the local one — the same "wrong build served the job" signature.
     exit 2
@@ -121,7 +125,27 @@ pkg_dir_for_pid() {
 # comments before looking for code.
 strip_js_comments() { perl -0pe 's{/\*.*?\*/}{}gs; s{^[[:space:]]*//.*$}{}gm' "$1" 2>/dev/null || true; }
 
-# Prints "<version> <FIXED|UNFIXED(reason)|PARENT>" for a pid.
+# True when compiled runner.js (comments already stripped, on stdin) restricts the SDK's
+# built-in tools. Two accepted shapes:
+#   - `tools: []`              — 2.1.5 to 2.1.x: no built-ins at all;
+#   - `tools: webTools` built by `clampWebTools(` over the literal two-name list
+#                              — 2.2.0+: none, or at most WebFetch + WebSearch, which have
+#                                no filesystem access (web Navis; see runner.ts).
+# Recognising ONLY the first shape graded every 2.2.0 daemon UNFIXED and the assert at the
+# bottom then killed it: a guaranteed outage on the first restart after publishing.
+# The version floor stays 2.1.5 — the filesystem boundary is what this guards.
+has_tool_boundary() {
+  local code; code="$(cat)"
+  # Here-strings, not `printf | grep -q`: under pipefail an early-exiting grep can SIGPIPE
+  # the writer once the file outgrows the pipe buffer, turning a match into a failure.
+  grep -q 'canUseTool:' <<<"$code" || return 1
+  grep -q 'tools: \[\]' <<<"$code" && return 0
+  grep -q 'tools: webTools,' <<<"$code" \
+    && grep -q 'const webTools = clampWebTools(' <<<"$code" \
+    && grep -q "ALLOWED_WEB_TOOLS = \['WebFetch', 'WebSearch'\]" <<<"$code"
+}
+
+# Prints "<version> <FIXED|UNFIXED(reason)>" for a package directory.
 #
 # TWO INDEPENDENT SIGNALS, both required:
 #   - the package version is >= MIN_FIXED_VERSION (the same signal the backend's
@@ -129,25 +153,40 @@ strip_js_comments() { perl -0pe 's{/\*.*?\*/}{}gs; s{^[[:space:]]*//.*$}{}gm' "$
 #   - the compiled output actually contains both halves of the fix, comments removed.
 # An earlier version compared neither: MIN_FIXED_VERSION was assigned and never used, and
 # the content check matched documentation. "v2.1.5 FIXED" was two non-facts side by side.
-describe_pid() {
-  local pid="$1" dir ver stripped ver_ok=0 code_ok=0
-  dir="$(pkg_dir_for_pid "$pid")"
-  # No package dir = the `npm exec` wrapper, not a daemon. Its child is graded separately;
-  # counting the parent as "unknown, therefore exposed" cried wolf on every healthy npx
-  # launch, which is the mode that becomes correct once the fix is published.
-  if [ -z "$dir" ] || [ ! -f "$dir/package.json" ]; then echo "- PARENT"; return; fi
+describe_dir() {
+  local dir="$1" ver ver_ok=0 code_ok=0
   ver="$(node -e "process.stdout.write(String(require('$dir/package.json').version||'0.0.0'))" 2>/dev/null || echo '0.0.0')"
   version_ge "$ver" "$MIN_FIXED_VERSION" && ver_ok=1
   if [ -f "$dir/dist/agent/runner.js" ]; then
-    stripped="$(strip_js_comments "$dir/dist/agent/runner.js")"
-    if printf '%s' "$stripped" | grep -q 'tools: \[\]' \
-       && printf '%s' "$stripped" | grep -q 'canUseTool:'; then code_ok=1; fi
+    if strip_js_comments "$dir/dist/agent/runner.js" | has_tool_boundary; then code_ok=1; fi
   fi
   if [ "$ver_ok" = 1 ] && [ "$code_ok" = 1 ]; then echo "$ver FIXED"
   elif [ "$ver_ok" = 0 ]; then echo "$ver UNFIXED(v<$MIN_FIXED_VERSION)"
   else echo "$ver UNFIXED(code)"; fi
 }
 
+# Prints "<version> <FIXED|UNFIXED(reason)|PARENT>" for a pid.
+describe_pid() {
+  local dir
+  dir="$(pkg_dir_for_pid "$1")"
+  # No package dir = the `npm exec` wrapper, not a daemon. Its child is graded separately;
+  # counting the parent as "unknown, therefore exposed" cried wolf on every healthy npx
+  # launch, which is the mode that becomes correct once the fix is published.
+  if [ -z "$dir" ] || [ ! -f "$dir/package.json" ]; then echo "- PARENT"; return; fi
+  describe_dir "$dir"
+}
+
+# --grade <dir>: grade one package directory and touch no process. The test suite runs
+# this against a fresh compile of runner.ts, so a change the check above stops recognising
+# fails a test instead of killing every user's daemon on their next restart.
+if [ "$MODE" = "--grade" ]; then
+  grade_dir="$(cd "$2" && pwd)"
+  read -r ver state <<<"$(describe_dir "$grade_dir")"
+  echo "$ver $state"
+  if [ "$state" = "FIXED" ]; then exit 0; fi
+  exit 1
+fi
+
 # --status: the one command that answers "is my machine exposed right now?".
 if [ "$MODE" = "--status" ]; then
   exposed=0 total=0

package/skill-templates/noesis-refine-relations.md

@@ -0,0 +1,163 @@
+---
+description: Refine the typed relations (Related Notes) of a SET of Noesis notes so the Graph view shows real structure. Scopes by timeframe, topic, catalog or signal — "last two weeks", "notes about BTC", "BTO printing in the last month", "points over 100". Proposes a diff per note and writes only on approval. Use when the user says 'refine relations', 'refine note relations', 'fix my graph', 'link my notes', 'these notes have no relations', or names a batch of notes to connect.
+argument-hint: "[recent <N> days|weeks|months] [topic <words>] [catalog <NAME>] [points over <N>] [<note path | note ID | query>]"
+---
+
+# /noesis-refine-relations — Batch relation refinement
+
+You are executing `/noesis-refine-relations`. It selects a **set** of notes, works out which
+other notes each one should formally link to, shows you the diff, and writes only what you
+approve.
+
+Relations live in the Noesis **database**, not in the markdown. This skill therefore never
+edits a note body and never needs a sync.
+
+## What this is NOT
+
+The app already has a per-note **"Suggest relations"** in the graph's node menu. It reasons
+over ≤20 candidates carrying only a title and a short description — **it never reads note
+bodies**, and it runs on one note at a time.
+
+This skill is the complement: many notes at once, and it *reads the content*, so it can find
+the links a note states in its own text (cited file paths, note URLs, quoted titles). Where
+the in-app suggester is the right tool for one note, say so and stop.
+
+## Step 0 — Route on the argument
+
+The raw arguments string is: `$ARGUMENTS`
+
+First match wins:
+
+| Argument looks like | Mode |
+|---|---|
+| "last N days/weeks/months", "recent", "this week" | **RECENT** |
+| a topic phrase *and* a timeframe | **TOPIC ∩ RECENT** |
+| a topic phrase ("about BTC", "BTO printing") | **TOPIC** |
+| "points over N", "score above N", "favorite", "pinned", "starred" | **SIGNAL** |
+| "catalog X" | **CATALOG** |
+| a note ID, a `.md` path, or a bare query | **SINGLE** |
+| empty | **ASK** — `AskUserQuestion` offering the modes above |
+
+State the mode and the resolved parameters before doing anything.
+
+## Step 1 — Resolve the note set
+
+- **RECENT** — `mcp__noesis__list_notes(recent: <N_DAYS>, limit: 100)`.
+- **TOPIC** — `mcp__noesis__search_semantic(query, limit: 20)` **and**
+  `mcp__noesis__search_notes(query, limit: 50)`; union by ID.
+- **TOPIC ∩ RECENT** — run both of the above and intersect.
+- **SIGNAL** — `list_notes(limit: 100)`, then filter client-side on the `⭐` and `[N pts]`
+  markers in the output.
+- **CATALOG** — `list_notes(catalog: <NAME>, limit: 100)`.
+- **SINGLE** — resolve directly (`get_note` by id/path, or `search_notes` then pick).
+
+Then **always**:
+
+1. **Drop capture notes** — anything under a `captures/` folder is an auto-pushed session
+   mirror, not a note the user authored. Never link them unless explicitly asked.
+2. **Cap the batch.** Default to 15 notes. If the scope resolved to more, take the 15 most
+   recently modified and **say how many you dropped** — never present a truncated sweep as
+   a complete one.
+3. Print the candidate table (ID, title, path, current relation count) and confirm the set
+   before moving on.
+
+### Selection limits you must respect
+
+These are properties of the MCP tools, not preferences:
+
+- `list_notes` caps `limit` at **100** server-side and exposes no offset. A scope wider than
+  100 notes cannot be enumerated in one call — narrow it and say so.
+- When `recent` is set, `root` and `catalog` are **silently ignored**. Combined filters must
+  be applied client-side.
+- `list_notes` prints `⭐` and `[N pts]` but **not the note ID**, so resolve IDs from paths
+  before writing anything.
+- `search_semantic` and `find_similar_notes` need embeddings and fail without a Gemini key.
+  Degrade to keyword-only and note it; never abort the run over it.
+
+## Step 2 — Per note: build the proposed set
+
+For each note in the confirmed set, in order:
+
+**2a. Read the current relations.** `mcp__noesis__get_note(id)`. This is the only reliable
+read — use it every time, even when you expect none.
+
+**2b. Gather candidates**, in one parallel batch:
+- `mcp__noesis__find_similar_notes(note_id, limit: 15)`
+- `mcp__noesis__search_semantic(query: title + description, limit: 10)`
+- **The body scan — the highest-precision source, and the reason this skill exists.**
+  Read the note content and extract every note it already cites:
+  - file paths ending in `.md` (absolute, `~/Noesis/...`, or bare filenames)
+  - `noesisbrain.com/notes/<id>` URLs — the `<id>` is the target, use it directly
+  - quoted note titles
+  Resolve each to an ID with `mcp__noesis__search_notes`. An edge grounded in a line of the
+  note's own text is worth more than any similarity score; keep the line as evidence.
+
+**2c. Filter.** Drop captures, drop the note itself (the MCP write path does **not** reject
+self-links), drop anything that fails to resolve. Never invent an ID — if a cited note cannot
+be resolved, report it as unresolved rather than guessing.
+
+**2d. Choose a type** per edge, from exactly these five:
+`related` · `references` · `implements` · `extends` · `supersedes`.
+Default to `references` when the note merely cites the target, `related` when the connection
+is thematic.
+
+**2e. Union with the existing set from 2a.** Keep every existing entry unless the user has
+explicitly asked to prune. This matters — see the write contract below.
+
+**2f. Apply a cap.** 2–5 relations for a focused note; up to 8 for a comprehensive
+architecture, workflow, or strategy note. **Tracker, sprint and index notes are exempt** —
+being a hub is their job, and a tracker citing 25 notes should link to 25.
+
+## Step 3 — Propose
+
+Print, per note:
+
+```
+Note 2923  BTO 12.3 Aug Sprint 0        edges 0 -> 25
+  = keep  references  4424  IDEA-1579 HTTPS support
+  + add   references  3611  BPLAT-14016 UltraLite Simple Serialization
+          evidence: "my-git/issues/BPLAT-14016-phoenix-tsc-ultralite...md"
+  + add   related     2924  Epsilon Branch Merge Convention
+          evidence: similar 0.81, both cover the Epsilon merge workflow
+  ! unresolved: "support-https-print-portal-investigation.md" (no match)
+```
+
+Then ask once, for the whole batch, via `AskUserQuestion`: apply all / pick per note / cancel.
+**Never write before this point.**
+
+## Step 4 — Write
+
+For each approved note, issue **exactly one** `mcp__noesis__update_relations` call carrying
+the **complete** desired set.
+
+> **The write REPLACES the note's whole relation set.** It clears the column and stores what
+> you send. One call per relation — a pattern that exists elsewhere in this repo's older
+> commands — leaves the note with only the last relation written and silently deletes the
+> rest. Send the union from 2e, always.
+
+No inverse relation is created on the target, and you must not try to write one. Backlinks
+are **derived**: the app scans every note's one-way array to build the graph, so a single
+edge already shows up on both notes — as "linked to" on the source and "linked by" on the
+target. Writing the mirror by hand would double-store derived data and turn every edge into
+"mutual", destroying the direction the user can currently see.
+
+Do **not** write a "Related Notes" section into the markdown body. Relations are database
+metadata; a section in the file is a stale duplicate. If a previous run left one, remove it.
+
+## Step 5 — Report
+
+A table of note · edges before → after · skipped-and-why, plus every unresolved citation.
+Then suggest `mcp__noesis__get_relation_graph(note_id, depth: 1)` or the Graph view to
+confirm the shape.
+
+## Implementation notes
+
+- **Read before write, every time.** The write is a replace; skipping 2a loses relations.
+- **The body scan is the differentiator.** If you skip it, this skill is just a slower
+  version of the in-app suggester.
+- **Evidence or no edge.** Every proposed link needs either a quoted line from the note or a
+  similarity score. "These feel related" is not a reason.
+- **Sequential per note.** Parallel `get_note` batches race the API rate limit; the
+  *candidate gathering* inside one note (2b) is the part to parallelize.
+- **Report every cap.** A truncated batch, a dropped candidate, an unresolved citation — all
+  of it goes in the Step 5 report. A sweep that hides what it skipped is worse than no sweep.