@noesis-brain/mcp-server 2.1.5 → 2.5.0

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.

package/skill-templates/noesis-ticket.md

@@ -0,0 +1,79 @@
+---
+description: Work a Noesis Jot ticket (TCK-<n>) from this Claude Code session — bind it, link the running session to it, keep its status current, refine its text within the word limit, reset the binding, or list your tickets.
+argument-hint: TCK-<n> | link TCK-<n> [status] [--force] | status [<status>] | refine | reset | list
+---
+
+The Noesis Jot page is the user's quick-note board. Each ticket (TCK-<n>) shows a work status and which Claude Code session, on which computer, is working on it. This skill keeps that page true while you work.
+
+The ticket tools (`mcp__noesis__backlog_bind`, `backlog_set_status`, `backlog_unbind`, `backlog_refine`, `backlog_get`) are bookkeeping on the user's own ticket, which the user asked for. Calling them in plan mode is expected.
+
+## Arguments
+
+$ARGUMENTS
+
+## The status ladder
+
+| Status | Set it when |
+|---|---|
+| `planning` | you start reading the ticket and the code, and writing a plan (plan mode) |
+| `ready_to_implement` | your plan is presented and waits for the user's approval |
+| `implementing` | the user approved the plan and you are building it |
+| `iterating` | the first version is delivered; the user is testing it and asking for changes |
+| `ready_to_merge` | you judge the work complete: every piece of feedback is done, or a `/cc-loop` reached LOOP COMPLETE. You wait for the user to say "ship it" |
+| `deploying` | you are merging, pushing and verifying the deployment |
+| `shipped` | the change is live in production |
+
+`created` and `dropped` are the user's to set, on the page. Never skip a step you actually went through, and never claim a status you have not reached.
+
+## Sub-commands
+
+### `TCK-<n>` — start a ticket
+
+1. `backlog_get(key)` and read the ticket: the refined text if there is one, otherwise the draft.
+2. `backlog_bind(key)`. It sets `planning`.
+3. Work on it. Move the status up the ladder as you go.
+
+### `link TCK-<n> [status] [--force]` — link the session you are already in
+
+Use it when this session is already working and the ticket was never handed over, or after `/clear`: you then no longer remember the ticket, and `link` tells you again which ticket it is and what status it has. (The binding keeps the session id the MCP server started with, which does not change on `/clear`.)
+
+1. With a status, bind with that status. Without one, pick the status that matches where this session really is:
+   - in plan mode → `planning`;
+   - a plan presented and waiting → `ready_to_implement`;
+   - an approved plan, and code being changed → `implementing`;
+   - a first version delivered, and the user giving feedback → `iterating`;
+   - a `/cc-loop` whose state file says COMPLETE → `ready_to_merge`.
+2. `backlog_bind(key, status)`. Pass `force` only when the user wrote `--force`.
+3. If the session has already made a plan, refine the ticket once (see `refine`).
+
+If the ticket is bound to another session (`BOUND_ELSEWHERE`), tell the user which computer holds it and change nothing unless they wrote `--force`.
+
+### `status [<status>]`
+
+"This session's ticket" is the one you bound earlier in this conversation, or the one the `tck-session` reminder names. If you are not sure which it is, ask.
+
+Without a status, show the bound ticket's key, status, computer and session. With one, `backlog_set_status(key, status)`.
+
+### `refine`
+
+Rewrite the ticket's text so it matches the agreed plan, and store it with `backlog_refine`. It must stay a jot:
+
+- 70%–120% of the draft's word count (5 words of slack for short drafts; each Chinese, Japanese or Korean character counts as one word);
+- the same language as the draft;
+- plain sentences or a short list — no headings, no code fences, no increments, acceptance criteria or plan sections.
+
+Refine once when your plan is ready, just before `ExitPlanMode`. Refine again only if the plan changes or the user asks. On `REFINE_LENGTH`, read `draft_words`, `min` and `max` from the error and rewrite to fit. The user's draft is never changed.
+
+### `reset`
+
+`backlog_unbind(key)` for this session's ticket. The status stays as it is.
+
+### `list`
+
+Call `backlog_get` with no filter, and keep the tickets whose status is in progress (`planning` to `deploying`). Show key, status, computer and the first line of each.
+
+## Rules
+
+- One ticket per session. `SESSION_BUSY` means this session holds another ticket: switch (`switch: true`) only when the user clearly hands over the new one, never because a ticket is merely mentioned.
+- `RESET_BY_OWNER` means the user reset this session's binding on the page. Bind again (`force: true`) only if the user asks.
+- Never put the full plan on the ticket. Nobody reads the long version; the ticket stays a jot.

package/templates/claude-md-block.md

@@ -12,6 +12,13 @@
 - Note relations and codebase links live in the Noesis **database**, not in `.md` frontmatter — don't grep `.md` files for them.
 - Use `mcp__noesis__get_note` (read by ID or path), `mcp__noesis__find_similar_notes` (semantic similarity), `mcp__noesis__search_semantic` / `mcp__noesis__search_notes` (meaning / keyword search), `mcp__noesis__update_relations` (read-only when called without the `relations` param).
 
+### Noesis tickets (Jot page, TCK-<n>)
+- The Jot page shows each ticket's work status and which session, on which computer, is working on it. Keep both true.
+- When the user hands you a ticket (pastes `TCK-<n>: …`, or asks you to read, plan or work on TCK-<n>), bind it to this session with `mcp__noesis__backlog_bind`. The ticket tools are bookkeeping the user asked for, so calling them in plan mode is expected.
+- Keep the status current with `mcp__noesis__backlog_set_status`: planning → ready_to_implement (plan presented) → implementing (plan approved) → iterating (first version delivered, user giving feedback) → ready_to_merge (you judge the work complete) → deploying (merging, pushing, verifying) → shipped (live). `created` and `dropped` are the user's.
+- Refine the ticket text once, when your plan is ready, with `mcp__noesis__backlog_refine`: 70%–120% of the draft's words, in the draft's language. Never add increments, acceptance criteria or plan sections to a ticket — it stays a jot.
+- The `noesis-ticket` skill covers start, `link` (bind the session you are already in, also after `/clear`), status, refine, reset and list.
+
 ### Path-as-identifier (cross-machine)
 For any path inside a Noesis-watched root, the path is a Noesis identifier — the cloud copy is always authoritative, and the local copy on this machine may be **missing** (other machine) or **stale** (the user edited the note via the Noesis web UI's Quick Fix; the web UI surfaces that state with the badge 「在线编辑 · 等待本地同步」). Either way, the local copy is not a trustworthy source of truth — reading it directly silently feeds outdated content into the rest of the turn.