loopctl-mcp-server 2.73.0 → 2.75.0

package/index.js

@@ -1497,9 +1497,16 @@ async function knowledgeFacets({
   return toContent(result);
 }
 
-async function knowledgeSearch({ q, project_id, story_id, category, tags, match, mode, limit, offset }) {
+async function knowledgeSearch({ q, project_id, story_id, category, tags, match, mode, format, limit, offset }) {
   const params = new URLSearchParams();
   if (q != null && q !== "") params.set("q", q);
+  // `format` is the SHAPE of the response, not a different search (#678). The server
+  // dispatches `stubs` to the same progressive_index/3 and `bodies` to the same
+  // get_context/3 that knowledge_progressive_index and knowledge_context call, so those
+  // tools remain and are not retired — they are now siblings on one path rather than
+  // separate doors an agent has to choose between. That choice was unobservable and
+  // therefore confounded any measurement of the ranking behind it.
+  if (format) params.set("format", format);
   if (project_id) params.set("project_id", project_id);
   if (story_id) params.set("story_id", story_id);
   if (category) params.set("category", category);
@@ -4616,6 +4623,21 @@ const TOOLS = [
           enum: ["keyword", "semantic", "combined"],
           description: "Optional: search mode (keyword, semantic, or combined).",
         },
+        format: {
+          type: "string",
+          enum: ["results", "stubs", "bodies"],
+          description:
+            "Optional: the SHAPE of the response, not a different search. 'results' " +
+            "(default) is ranked results plus snippets and is the only shape that " +
+            "supports cursor pagination. 'stubs' returns capped stubs with one hop of hub " +
+            "enrichment — use it to survey a broad topic without pulling bodies into " +
+            "context, then knowledge_progressive_drill into a chosen stub. 'bodies' " +
+            "returns full article bodies plus linked references for one deep read. " +
+            "'stubs' and 'bodies' REQUIRE a query; sending either without one is a 400, " +
+            "as is an unknown value (it is never silently downgraded to 'results'). These " +
+            "dispatch to exactly the same code knowledge_progressive_index and " +
+            "knowledge_context call, which both remain available.",
+        },
         limit: {
           type: "integer",
           description: "Optional: maximum number of results to return.",
@@ -4643,7 +4665,12 @@ const TOOLS = [
       "trustworthy answer plus its provenance rather than a ranked list to triage yourself; " +
       "use knowledge_search when you want to browse/enumerate matches. Additive — existing " +
       "knowledge tools are unchanged. If semantic ranking is unavailable it degrades to " +
-      "keyword-only (meta.fallback/fallback_reason), same as knowledge_search.",
+      "keyword-only (meta.fallback/fallback_reason), same as knowledge_search.\n\n" +
+      "TODAY THE CURATED BRANCH IS UNREACHABLE ON THIS DEPLOYMENT: a source counts as " +
+      "curated only if its article has curated_at set, and no article does — so every " +
+      "call returns provenance 'retrieved' and a null curated_article_id. Read a " +
+      "'retrieved' verdict as the normal case, not as evidence that a curated answer " +
+      "was considered and rejected. This line comes out when something actually curates.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4839,8 +4866,10 @@ const TOOLS = [
       properties: {
         article_id: {
           type: "string",
-          format: "uuid",
-          description: "The UUID of the article.",
+          description:
+            "The UUID of the article. A unique ID PREFIX (>= 8 hex characters) also " +
+            "resolves, so copy what you have rather than reconstructing 36 characters " +
+            "from memory; an ambiguous prefix is a 404, never a guess.",
         },
         links: {
           type: "string",
@@ -6469,7 +6498,40 @@ const TOOLS = [
       "search_follow_through carries two further biases pointing OPPOSITE ways: the 20-row " +
       "recording cap hides opens of results ranked beyond it (DOWN on large pages), while " +
       "one open credits EVERY search in the window that surfaced that article, not just the " +
-      "preceding one (UP when an agent refines and re-searches).",
+      "preceding one (UP when an agent refines and re-searches).\n\n" +
+      "Exact attribution (unit: READS — not surfaced results, not calls): attributed_opens " +
+      "/ cross_key_opens / direct_opens count READ rows by how their originating search was " +
+      "established, resolved server-side at write time and never accepted from a caller. " +
+      "Not comparable with followed_through, which counts SURFACED RESULTS later opened. " +
+      "cross_key_opens is the population followed_through cannot see: it correlates on " +
+      "api_key_id, and the injected recall hook searches under a different key from the " +
+      "session that reads, so that channel scores a structural ZERO there — meaning " +
+      "UNMEASURABLE, not unread. Cross-key attribution is circumstantial (two agents in one " +
+      "tenant can reach one article independently), hence labelled rather than folded in. " +
+      "direct_opens is the agent going straight to an article by link or cited id, which " +
+      "used to look identical to 'surfaced and ignored' — close to its opposite.\n\n" +
+      "Disposition (unit: SEARCH CALLS): searches_scored_with_follow_through, " +
+      "searches_reformulated and searches_quiet PARTITION searches_scored — NOT searches. " +
+      "Treating every not-opened search as a failure is wrong — an agent answered by the " +
+      "result snippet correctly opens nothing, and that is a success. A reformulation (the " +
+      "SAME SESSION issuing a later search call with a DIFFERENT QUERY in-window, nothing " +
+      "opened) is the closest thing to an unambiguous failure, so it is split out; what " +
+      "remains is `quiet` and is STILL a mixture of 'snippet sufficed' and 'rows ignored'. " +
+      "This surface does not separate them — do not read quiet as either.\n\n" +
+      "searches_scored is SMALLER than searches and the gap is NOT quiet traffic. A search " +
+      "is scoreable only if it carries a session identity (stamped forward-looking, so a " +
+      "pre-migration row reports searches_scored: 0) and comes from a channel that can " +
+      "react to a result at all — the recall hook and the session-start auto-query emit one " +
+      "distilled query per prompt and never see what came back, so they cannot reformulate " +
+      "by construction. They stay in every other denominator here, precision included. " +
+      "Read searches - searches_scored as n/a, never as zero.\n\n" +
+      "COMPARE ROWS ONLY WITHIN A metric_version. Every row carries the version of the " +
+      "definition set that produced it. Three changes have already altered what a figure here " +
+      "MEANS — searched went from search calls to surfaced results, infrastructure traffic " +
+      "began being excluded, and the disposition trio was rescoped — each forward-looking and " +
+      "each previously leaving no mark on the row, so a series read across one of those " +
+      "boundaries compares definitions rather than days. 0 means the row predates the stamp " +
+      "and its definitions are unknown.",
     inputSchema: {
       type: "object",
       properties: {
@@ -6491,8 +6553,15 @@ const TOOLS = [
   {
     name: "knowledge_analytics_top",
     description:
-      "Return the top accessed knowledge articles for the tenant. " +
-      "Use to identify which articles agents actually read. Requires orchestrator role.",
+      "Return the top READ knowledge articles for the tenant — articles whose body was " +
+      "actually delivered (get/context/drill). Requires orchestrator role.\n\n" +
+      "access_type DEFAULTS TO READS, not to every event. `search` and `index` rows are " +
+      "IMPRESSIONS the ranker produced — one per surfaced result — and they outnumber reads " +
+      "roughly 50:1, so the old unfiltered default ranked ranker output while claiming to " +
+      "show what agents read. Pass access_type:'all' if you genuinely want impressions " +
+      "counted, or a single type to select one. unique_keys counts distinct API KEYS, not " +
+      "agents: v2 mints one ephemeral key per dispatch, so one agent dispatched N times is " +
+      "N keys.",
     inputSchema: {
       type: "object",
       properties: {
@@ -6525,8 +6594,12 @@ const TOOLS = [
   {
     name: "knowledge_article_stats",
     description:
-      "Return per-article usage statistics: total accesses, unique agents, " +
-      "by-type breakdown, and the 10 most recent events. Requires orchestrator role.",
+      "Return per-article usage statistics: total_events (impressions included), " +
+      "total_reads (bodies actually delivered — get/context/drill), unique_keys, a by-type " +
+      "breakdown, and the 10 most recent events. Requires orchestrator role.\n\n" +
+      "Read total_reads, not total_events, when you want usage: impressions outnumber reads " +
+      "roughly 50:1. unique_keys counts distinct API KEYS rather than agents — v2 mints one " +
+      "ephemeral key per dispatch.",
     inputSchema: {
       type: "object",
       properties: {
@@ -6541,7 +6614,8 @@ const TOOLS = [
   {
     name: "knowledge_agent_usage",
     description:
-      "Return knowledge usage for an agent: total reads, unique articles, top read articles. " +
+      "Return knowledge usage for an agent: total_reads (bodies actually delivered), " +
+      "total_events (impressions included), unique articles, top read articles. " +
       "Pass api_key_id (api_keys.id credential) OR agent_id (agents.id logical identity) — not both. " +
       "Requires orchestrator role.",
     inputSchema: {
@@ -6576,8 +6650,11 @@ const TOOLS = [
   {
     name: "knowledge_unused_articles",
     description:
-      "Return published articles that have not been accessed in the configured " +
-      "time window. Use to identify dead-weight knowledge. Requires orchestrator role.",
+      "Return published articles that have not been READ in the configured time window. " +
+      "Use to identify dead-weight knowledge. Requires orchestrator role.\n\n" +
+      "\"Not read\" means no get/context/drill. It deliberately does NOT mean \"no event\": " +
+      "on that definition an article the ranker surfaces constantly and nobody ever opens " +
+      "counted as USED, which made this blind to the largest class of dead weight there is.",
     inputSchema: {
       type: "object",
       properties: {

package/lib/client-context.js

@@ -12,18 +12,34 @@
  * remains the sole authority. The server stores these under a `client_` prefix so no later
  * reader mistakes them for server-derived facts.
  *
- * WHAT IS ACTUALLY AVAILABLE (verified on a live session, 2026-08-12):
+ * WHAT IS ACTUALLY AVAILABLE — re-measured 2026-08-12 by reading /proc/<mcp-pid>/environ on
+ * a live session, which corrected two entries an earlier pass got wrong:
  *
- *   CLAUDE_EFFORT=high              -> effort, available
- *   CLAUDE_SESSION_ID=<uuid>        -> session id, available
- *   CLAUDE_CODE_CHILD_SESSION=1     -> subagent vs main session, available
+ *   CLAUDE_CODE_SESSION_ID=<uuid>   -> session id, available
  *   CLAUDE_CODE_ENTRYPOINT=cli      -> entrypoint, available
+ *   CLAUDE_SESSION_ID               -> ABSENT (the CODE_ spelling is the one that is set)
+ *   CLAUDE_EFFORT                   -> ABSENT from THIS process. It is set for Bash-tool
+ *                                      invocations, which is where the earlier claim that
+ *                                      it was "available" came from; the MCP server does
+ *                                      not get it, so `effort` is enriched offline.
+ *   CLAUDE_CODE_CHILD_SESSION       -> ABSENT, and it would not mean what it looks like:
+ *                                      it is set to 1 for Bash-tool invocations of a MAIN
+ *                                      session, so it marks "a child PROCESS", not "a
+ *                                      dispatched agent".
  *   (no model variable)             -> MODEL IS NOT AVAILABLE
  *
- * The model is deliberately still sent when a variable for it appears, because the session
- * TRANSCRIPT does record it (`message.model`, e.g. `claude-opus-5`) keyed by session id —
- * so `client_session_id` is the join key that enriches model offline today, and the field
- * fills itself in the day the runtime exposes one.
+ * THE KIND REPORTED HERE IS THE SESSION'S, NOT THE CALLER'S. One MCP server process is
+ * spawned per session and serves the main session AND every agent it dispatches, and the
+ * environment above is read once and cached for the life of that process. So `kind` is a
+ * property of the session, and every search it labels comes back `main`. The three-way
+ * main/subagent/workflow split a measurement actually needs is recoverable only from the
+ * transcript, where `isSidechain` plus the file's path give it unambiguously.
+ *
+ * Two fields are therefore sent as JOIN KEYS rather than as answers: `session_id` is what
+ * lets `mix loopctl.enrich_search_events` find the transcript that records the model, the
+ * effort and the real kind. Note that a RESUMED session breaks even that — the new process
+ * reports a fresh session id while the transcript keeps appending under the original — so
+ * the enrichment carries a query-only fallback for exactly that case.
  */
 
 import { execFileSync } from "node:child_process";
@@ -87,15 +103,17 @@ function clientContext({ version } = {}) {
     version,
   };
 
-  // main vs child. A dispatched agent sets CLAUDE_CODE_CHILD_SESSION=1.
+  // The SESSION's kind — see the header. This process is shared by the main session and
+  // every agent it dispatches, so in practice this resolves to "main" for all of them and
+  // is NOT caller-level evidence. It is still worth sending: it is the only thing available
+  // before the offline enrichment runs, and the enrichment treats it as an assertion to be
+  // corrected rather than as a value to be preserved.
   //
-  // Only TWO values, on purpose. A workflow agent cannot be distinguished from an ordinary
-  // subagent here: CLAUDE_CODE_WORKFLOWS is a feature flag that is present in main sessions
-  // too, and nothing else marks one. Since an audit measured materially different failure
-  // rates across main/workflow/subagent, the third value matters — but it is recoverable
-  // only OFFLINE, by joining session_id to the transcript path (wf_* vs subagents/). Report
-  // what is observable and let the join supply the rest; do not guess a value that would
-  // then be analysed as fact.
+  // Do not try to widen it to three values from the environment. CLAUDE_CODE_WORKFLOWS is a
+  // feature flag present in main sessions too, and CLAUDE_CODE_CHILD_SESSION marks a child
+  // PROCESS rather than a dispatched agent. Guessing here would be worse than the null it
+  // replaces, because the number this column exists to support is a comparison BETWEEN
+  // kinds.
   const child = env("CLAUDE_CODE_CHILD_SESSION");
   if (child !== undefined) {
     ctx.kind = child === "1" || child.toLowerCase() === "true" ? "child" : "main";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopctl-mcp-server",
-  "version": "2.73.0",
+  "version": "2.75.0",
   "description": "MCP server for loopctl \u2014 structural trust for AI development loops",
   "type": "module",
   "main": "index.js",