@lorekit/cli 1.36.0 → 1.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.36.0",
+  "version": "1.37.0",
   "description": "Install the LoreKit shared-memory skill and run health checks for the LoreKit MCP server.",
   "license": "MIT",
   "repository": {

package/src/mcp-server.mjs

@@ -146,6 +146,17 @@ export const MEMORY_TOOL_DEFS = [
     description: 'Soft-archive a memory. Hidden from reads but restorable.',
     inputSchema: { type: 'object', required: ['scope', 'key'] },
   },
+  {
+    name: 'memory.scopes',
+    // The description tells the model WHEN to reach for this, not just what it
+    // returns: every other read tool needs a scope named up front, so this is
+    // the one that answers "what is there?" before you can ask "what is in it?".
+    description:
+      'List every scope in the store with how many active memories it holds — '
+      + 'the inventory to consult when you do not already know which scope to read. '
+      + 'Takes no arguments and is store-wide, NOT limited to the current directory.',
+    inputSchema: { type: 'object', properties: {} },
+  },
 ];
 
 // Org tools — always advertised regardless of memory mode. They always route
@@ -215,8 +226,117 @@ const MEMORY_DISPATCH = {
   'memory.search': (store, a) => store.search(a),
   'memory.delete': (store, a) => store.delete(a),
   'memory.archive': (store, a) => store.archive(a),
+  'memory.scopes': (store) => listScopes(store),
 };
 
+// `memory.scopes` — the store-wide inventory, normalised.
+//
+// This exists because an agent that cannot enumerate scopes cannot know what it
+// does not know. `memory.list` and `memory.search` both need a scope (or a
+// scope list) up front, so without this the only reachable lore is the lore
+// whose scope the agent could already name — and the SessionStart injection is
+// deliberately a bounded slice, not an index of the whole store. `GET
+// /memories/scopes` and the `lorekit scopes` command have answered this since
+// migration 00039; the MCP surface was the one caller that could not ask.
+//
+// THE TWO STORES ANSWER IN DIFFERENT SHAPES, and normalising here is the whole
+// job of this function. `LocalStore`/`TwoTierStore.listScopes()` return a BARE
+// ARRAY (`[{ scope, count }]`), while `RemoteStore.listScopes()` returns the
+// standard `{ ok, scopes }` envelope — or `{ ok: false, error, networkError,
+// unusable }`. A tool that passed either through verbatim would hand the model
+// two different contracts for one tool name depending on a config value it
+// cannot see.
+//
+// DEGRADATION IS EXIT-CLEAN, mirroring the `scopes` command, which reports an
+// unreachable remote as a short note at exit 0 rather than failing the run. An
+// inventory that cannot be built is `{ scopes: [], note }` with `ok: true`, so
+// `toolResult` does NOT mark it `isError`: "I could not enumerate" is a fact
+// about the store, not a failed tool call, and a model that receives a
+// tool-level error is liable to retry it rather than carry on with the lore it
+// can already reach. The note says which, in bounded, non-PII terms.
+export async function listScopes(store) {
+  let res;
+  try {
+    res = await store.listScopes();
+  } catch (e) {
+    // A store that cannot enumerate must not take the session down with it.
+    return { ok: true, scopes: [], note: `scope enumeration failed: ${errText(e)}` };
+  }
+
+  // Local/two-tier: the bare array form.
+  if (Array.isArray(res)) return { ok: true, scopes: sortScopes(res.map(shapeScope)) };
+
+  // Remote: the envelope form.
+  if (res && res.ok) {
+    return { ok: true, scopes: sortScopes((Array.isArray(res.scopes) ? res.scopes : []).map(shapeScope)) };
+  }
+
+  return { ok: true, scopes: [], note: scopeFailureNote(res) };
+}
+
+// Sorted by scope ascending, which is the contract `docs/mcp-tools.md`, the
+// tool catalog and `llms.txt` all state for `memory.scopes`. The HOSTED surface
+// gets that ordering from `lorekit_memory_scopes` (`order by m.scope asc`,
+// migration 00039/00049), but `LocalStore`/`TwoTierStore.listScopes()` both
+// return their `Map` insertion order — a walk order, not an ordering — so the
+// stdio server owns it here rather than the two surfaces answering differently.
+// Sorting BOTH shapes (not just the local one) makes the guarantee a property
+// of this function instead of an assumption about the store it was handed.
+// Codepoint comparison, deliberately not `localeCompare`: the ordering must not
+// depend on the HOST's locale.
+//
+// That is ascending-by-scope, not byte-identical parity with the hosted path,
+// and the difference is worth being precise about. `order by m.scope asc` sorts
+// under the DATABASE's collation (`en_US.UTF-8` on a default Supabase project),
+// which does not order like codepoint around punctuation — and a scope string
+// is mostly punctuation (`::`, `/`, `-`), so `repo::a-b` and `repo::ab` can come
+// out in the opposite relative order on the two surfaces. Case cannot differ
+// (every scope segment is lowercased, see docs/scope-format.md). Closing the
+// remaining gap means `collate "C"` on the RPC's `order by`, which changes the
+// order `GET /memories/scopes` has always returned — a public contract change
+// that belongs in its own migration, not here. Until then: both surfaces are
+// sorted ascending, neither is unordered, and nothing should depend on the two
+// agreeing on the exact position of a punctuated neighbour.
+function sortScopes(rows) {
+  return rows.sort((a, b) => (a.scope < b.scope ? -1 : a.scope > b.scope ? 1 : 0));
+}
+
+// One inventory row. `last_activity` is passed through when the store supplied
+// it (the hosted `GET /memories/scopes` has returned it since migration 00049)
+// and OMITTED — never null — when it did not, so a client can tell "this store
+// does not report freshness" from "this scope has no activity".
+function shapeScope(s) {
+  const scope = String(s?.scope ?? '');
+  const count = Number(s?.count);
+  const row = { scope, count: Number.isFinite(count) ? count : 0 };
+  const last = s?.last_activity ?? s?.lastActivity;
+  return last ? { ...row, last_activity: last } : row;
+}
+
+// A short, bounded reason an enumeration produced nothing. Deliberately built
+// here rather than reusing `lessons-view.mjs`'s `describeError`: that module
+// carries the whole render/`util` stack, and this server has kept clear of it.
+// The vocabulary matches what that helper reports, so the two read alike.
+function scopeFailureNote(res) {
+  if (!res) return 'the store returned no result';
+  if (res.unusable) return 'no usable store is configured';
+  if (res.networkError) return `network error: ${String(res.networkError).slice(0, 200)}`;
+  // `httpStatus` is the ONLY field that carries a real status: `restFetch`'s
+  // error object is `{ message, code }`, and `code` is the response body's own
+  // application code on a JSON error, so rendering it as "HTTP <code>" would
+  // print a non-status. Read the top-level field first — that is the one
+  // `RemoteStore.listScopes()` passes through — and keep the nested read as a
+  // tolerance for any store that nests it instead.
+  const status = res.httpStatus ?? res.error?.httpStatus;
+  if (status) return `request failed with HTTP ${status}`;
+  if (res.error?.message) return String(res.error.message).slice(0, 200);
+  return 'the store could not enumerate its scopes';
+}
+
+function errText(e) {
+  return String(e?.message ?? e).slice(0, 200);
+}
+
 // Provenance for a tool call: the caller's explicit values win, the working
 // directory and CI environment fill the rest. Best-effort — a failure to shell
 // out to git must never fail the write, so it degrades to no origin at all.

package/src/store/remote.mjs

@@ -217,11 +217,43 @@ class RemoteStore {
   // is not relied upon (the server sorts by scope asc; the view re-sorts by
   // scope type). Failures use this store's standard `{ ok:false, error,
   // networkError }` envelope so the caller can degrade gracefully.
+  //
+  // `httpStatus` is carried through VERBATIM from `restFetch`, which is the ONLY
+  // place the real status lives: its error object holds `{ message, code }`,
+  // where `code` is the response body's own application code on a JSON error
+  // (a string like `permission_denied`) and only incidentally the status on a
+  // non-JSON one. A consumer that wants to say "HTTP 403" must therefore read
+  // `httpStatus`, never `error.code` — `mcp-server.mjs`'s `scopeFailureNote`
+  // does exactly that, and it had nothing to read until this field was passed
+  // through. Additive: `scopes.mjs`, `stats.mjs` and `lessons-view.mjs` all
+  // branch on `ok` / `unusable` / `networkError` and ignore the extra key.
   async listScopes() {
     const res = await this._rest('/memories/scopes');
-    if (!res.ok) return { ok: false, error: res.error, networkError: res.networkError, unusable: res.unusable };
+    if (!res.ok) {
+      return {
+        ok: false,
+        error: res.error,
+        httpStatus: res.httpStatus,
+        networkError: res.networkError,
+        unusable: res.unusable,
+      };
+    }
     const scopes = Array.isArray(res.data?.scopes) ? res.data.scopes : [];
-    return { ok: true, scopes: scopes.map((s) => ({ scope: s.scope, count: Number(s.count) || 0 })) };
+    // `last_activity` (migration 00049) is `max(created_at)` over exactly the
+    // counted rows — per-scope freshness without listing rows to reduce them,
+    // which is the row-cap trap this endpoint exists to avoid. It is passed
+    // through when present and OMITTED when absent (an older backend, or the
+    // offline store, which has no equivalent), so a consumer can tell "this
+    // store does not report freshness" from "this scope has none". Callers that
+    // read only `{ scope, count }` — `scopes.mjs`, `stats.mjs` — are unaffected.
+    return {
+      ok: true,
+      scopes: scopes.map((s) => ({
+        scope: s.scope,
+        count: Number(s.count) || 0,
+        ...(s.last_activity ? { last_activity: s.last_activity } : {}),
+      })),
+    };
   }
 
   // Authentication probe for doctor — does the configured token STILL work?