@oka-core/reason 0.2.15 → 0.2.16

package/dist/tools/read.js

@@ -1,4 +1,8 @@
 import { z } from "zod";
+import { toUserMessage, toSafeTelemetryMessage } from "../errors.js";
+import { validateInput } from "../validation.js";
+import { analytics } from "../analytics.js";
+import { buildTool, registerToolPool } from "../tool-contract.js";
 // ─── Formatters ────────────────────────────────────────────────────
 function formatEvents(events) {
     if (events.length === 0)
@@ -88,547 +92,668 @@ function formatHybridResults(query, results, totalCandidates, pipeline) {
     }
     return lines.join("\n");
 }
-// ─── Tool registration ─────────────────────────────────────────────
-/**
- * Register read tools on the MCP server.
- *
- * Tools:
- * - context — ranked learnings for a topic (flagship query)
- * - learnings — browse institutional knowledge
- * - decisions — decision log
- * - patterns — recurring patterns
- * - suggest — evidence-ranked priorities
- * - backlog — agentic product backlog
- * - priorities — evidence-ranked priorities from approved backlog
- * - consolidate — manually trigger a consolidation run
- */
-export function registerReadTools(server, client) {
-    // ─── context (THE DIFFERENTIATOR) ──────────────────────────────
-    server.tool("context", "Get consolidated institutional knowledge about a topic. " +
-        "Returns ranked Learnings derived from cross-source consolidation " +
-        "(agent reasoning, code, docs, meetings, tickets, chat). " +
-        "Each learning has a relevance score, confidence, and evidence count. " +
-        "Falls back to raw events if no learnings exist.", {
-        topic: z
-            .string()
-            .describe("Topic to query (e.g., 'auth', 'billing', 'deployment')"),
-        file_patterns: z
-            .string()
-            .optional()
-            .describe("Comma-separated file patterns to boost matching"),
-        limit: z.number().optional().default(10).describe("Max results"),
-        min_confidence: z
-            .number()
-            .optional()
-            .default(0.3)
-            .describe("Minimum confidence threshold"),
-        visibility: z
-            .enum(["user_repo", "account_wide", "user_private"])
-            .optional()
-            .describe("Visibility scope: user_repo (default), account_wide (cross-repo), user_private"),
-    }, async (params) => {
-        try {
-            // 1. Try hybrid search first (BM25 + vector + RRF)
-            const hybridResult = await client.hybridSearch(params.topic, {
-                file_patterns: params.file_patterns,
-                limit: params.limit,
-                min_confidence: params.min_confidence,
-                visibility: params.visibility,
-            });
-            if (hybridResult.results.length > 0) {
-                const text = formatHybridResults(params.topic, hybridResult.results, hybridResult.total_candidates, hybridResult.pipeline);
-                return { content: [{ type: "text", text }] };
-            }
-            // 2. Fall back to legacy context endpoint
-            const contextResult = await client.getContext(params.topic, {
-                file_patterns: params.file_patterns,
-                limit: params.limit,
-                min_confidence: params.min_confidence,
-                visibility: params.visibility,
-            });
-            if (contextResult.learnings.length > 0) {
-                const text = formatContextLearnings(params.topic, contextResult.learnings, contextResult.total_matched);
-                return { content: [{ type: "text", text }] };
-            }
-            // 3. Fall back to raw event query
-            const rawResult = await client.query({
-                area: params.topic,
-            });
-            if (rawResult.results.length > 0) {
-                const text = formatEvents(rawResult.results);
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: `## Raw Events: ${params.topic}\n\n> No consolidated learnings yet. Showing ${rawResult.source_count} raw event(s).\n\n${text}`,
-                        },
-                    ],
-                };
-            }
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `No knowledge found for topic "${params.topic}". This area hasn't been explored yet.`,
-                    },
-                ],
-            };
-        }
-        catch (error) {
-            return {
-                content: [{ type: "text", text: `Error: ${error}` }],
-                isError: true,
-            };
-        }
-    });
-    // ─── learnings ─────────────────────────────────────────────────
-    server.tool("learnings", "Browse institutional knowledge. Filter by category, status, " +
-        "confidence, or repo. Returns consolidated learnings with evidence counts.", {
-        category: z
-            .enum([
-            "architecture",
-            "bug_pattern",
-            "convention",
-            "decision",
-            "performance",
-            "security",
-            "workflow",
-            "domain_knowledge",
-        ])
-            .optional()
-            .describe("Filter by learning category"),
-        status: z
-            .enum(["active", "reinforced", "contradicted", "obsolete"])
-            .optional()
-            .describe("Filter by learning status"),
-        min_confidence: z
-            .number()
-            .optional()
-            .describe("Minimum confidence (0.0-1.0)"),
-        limit: z.number().optional().default(30).describe("Max results"),
-        visibility: z
-            .enum(["user_repo", "account_wide", "user_private"])
-            .optional()
-            .describe("Visibility scope: user_repo (default), account_wide (cross-repo), user_private"),
-    }, async (params) => {
-        try {
-            const result = await client.getLearnings({
-                category: params.category,
-                status: params.status,
-                min_confidence: params.min_confidence,
-                limit: params.limit,
-                visibility: params.visibility,
-            });
-            if (!result.learnings || result.learnings.length === 0) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: "No learnings found matching the filters. " +
-                                "Learnings are generated when the consolidation engine processes reasoning events.",
-                        },
-                    ],
-                };
-            }
-            const lines = [
-                `## Learnings (${result.total} total, showing ${result.learnings.length})`,
-                "",
-            ];
-            for (const l of result.learnings) {
-                const confidence = ((l.confidence || 0) * 100).toFixed(0);
-                lines.push(`### ${l.summary}`);
-                lines.push(`**Confidence:** ${confidence}% | **Category:** ${l.category || "general"} | **Status:** ${l.status || "active"}`);
-                if (l.evidence_count > 1) {
-                    lines.push(`**Evidence:** ${l.evidence_count} source(s)`);
+// ─── Tool definitions ─────────────────────────────────────────────────
+export function buildReadTools(client) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Each tool has its own specific schema;
+    // the variance between ToolDef<SpecificShape> and ToolDef<ZodRawShape> is safe at runtime.
+    return [
+        // ─── context (THE DIFFERENTIATOR) ──────────────────────────────
+        buildTool({
+            name: "context",
+            description: "Get consolidated institutional knowledge about a topic. " +
+                "Returns ranked Learnings derived from cross-source consolidation " +
+                "(agent reasoning, code, docs, meetings, tickets, chat). " +
+                "Each learning has a relevance score, confidence, and evidence count. " +
+                "Falls back to raw events if no learnings exist.",
+            inputSchema: {
+                topic: z
+                    .string()
+                    .describe("Topic to query (e.g., 'auth', 'billing', 'deployment')"),
+                file_patterns: z
+                    .string()
+                    .optional()
+                    .describe("Comma-separated file patterns to boost matching"),
+                limit: z.number().optional().default(10).describe("Max results"),
+                min_confidence: z
+                    .number()
+                    .optional()
+                    .default(0.3)
+                    .describe("Minimum confidence threshold"),
+                visibility: z
+                    .enum(["user_repo", "account_wide", "user_private"])
+                    .optional()
+                    .describe("Visibility scope: user_repo (default), account_wide (cross-repo), user_private"),
+            },
+            isReadOnly: true,
+            call: async (params) => {
+                analytics.track("tool.invoked", { tool: "context" });
+                try {
+                    validateInput(params.topic, 100_000);
+                    // 1. Try hybrid search first (BM25 + vector + RRF)
+                    const hybridResult = await client.hybridSearch(params.topic, {
+                        file_patterns: params.file_patterns,
+                        limit: params.limit,
+                        min_confidence: params.min_confidence,
+                        visibility: params.visibility,
+                    });
+                    if (hybridResult.results.length > 0) {
+                        const text = formatHybridResults(params.topic, hybridResult.results, hybridResult.total_candidates, hybridResult.pipeline);
+                        return { content: [{ type: "text", text }] };
+                    }
+                    // 2. Fall back to legacy context endpoint
+                    const contextResult = await client.getContext(params.topic, {
+                        file_patterns: params.file_patterns,
+                        limit: params.limit,
+                        min_confidence: params.min_confidence,
+                        visibility: params.visibility,
+                    });
+                    if (contextResult.learnings.length > 0) {
+                        const text = formatContextLearnings(params.topic, contextResult.learnings, contextResult.total_matched);
+                        return { content: [{ type: "text", text }] };
+                    }
+                    // 3. Fall back to raw event query
+                    const rawResult = await client.query({
+                        area: params.topic,
+                    });
+                    if (rawResult.results.length > 0) {
+                        const text = formatEvents(rawResult.results);
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `## Raw Events: ${params.topic}\n\n> No consolidated learnings yet. Showing ${rawResult.source_count} raw event(s).\n\n${text}`,
+                                },
+                            ],
+                        };
+                    }
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `No knowledge found for topic "${params.topic}". This area hasn't been explored yet.`,
+                            },
+                        ],
+                    };
                 }
-                if (l.suggested_action) {
-                    lines.push(`**Action:** ${l.suggested_action}`);
+                catch (error) {
+                    analytics.track("tool.error", {
+                        tool: "context",
+                        error: toSafeTelemetryMessage(error),
+                    });
+                    return {
+                        content: [{ type: "text", text: toUserMessage(error) }],
+                        isError: true,
+                    };
                 }
-                if (l.file_patterns?.length > 0) {
-                    lines.push(`**Files:** ${l.file_patterns.join(", ")}`);
+            },
+        }),
+        // ─── learnings ─────────────────────────────────────────────────
+        buildTool({
+            name: "learnings",
+            description: "Browse institutional knowledge. Filter by category, status, " +
+                "confidence, or repo. Returns consolidated learnings with evidence counts.",
+            inputSchema: {
+                category: z
+                    .enum([
+                    "architecture",
+                    "bug_pattern",
+                    "convention",
+                    "decision",
+                    "performance",
+                    "security",
+                    "workflow",
+                    "domain_knowledge",
+                ])
+                    .optional()
+                    .describe("Filter by learning category"),
+                status: z
+                    .enum(["active", "reinforced", "contradicted", "obsolete"])
+                    .optional()
+                    .describe("Filter by learning status"),
+                min_confidence: z
+                    .number()
+                    .optional()
+                    .describe("Minimum confidence (0.0-1.0)"),
+                limit: z.number().optional().default(30).describe("Max results"),
+                visibility: z
+                    .enum(["user_repo", "account_wide", "user_private"])
+                    .optional()
+                    .describe("Visibility scope: user_repo (default), account_wide (cross-repo), user_private"),
+            },
+            isReadOnly: true,
+            call: async (params) => {
+                analytics.track("tool.invoked", { tool: "learnings" });
+                try {
+                    const result = await client.getLearnings({
+                        category: params.category,
+                        status: params.status,
+                        min_confidence: params.min_confidence,
+                        limit: params.limit,
+                        visibility: params.visibility,
+                    });
+                    if (!result.learnings || result.learnings.length === 0) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: "No learnings found matching the filters. " +
+                                        "Learnings are generated when the consolidation engine processes reasoning events.",
+                                },
+                            ],
+                        };
+                    }
+                    const lines = [
+                        `## Learnings (${result.total} total, showing ${result.learnings.length})`,
+                        "",
+                    ];
+                    for (const l of result.learnings) {
+                        const confidence = ((l.confidence || 0) * 100).toFixed(0);
+                        lines.push(`### ${l.summary}`);
+                        lines.push(`**Confidence:** ${confidence}% | **Category:** ${l.category || "general"} | **Status:** ${l.status || "active"}`);
+                        if (l.evidence_count > 1) {
+                            lines.push(`**Evidence:** ${l.evidence_count} source(s)`);
+                        }
+                        if (l.suggested_action) {
+                            lines.push(`**Action:** ${l.suggested_action}`);
+                        }
+                        if (l.file_patterns?.length > 0) {
+                            lines.push(`**Files:** ${l.file_patterns.join(", ")}`);
+                        }
+                        lines.push("");
+                    }
+                    return {
+                        content: [{ type: "text", text: lines.join("\n") }],
+                    };
                 }
-                lines.push("");
-            }
-            return {
-                content: [{ type: "text", text: lines.join("\n") }],
-            };
-        }
-        catch (error) {
-            return {
-                content: [{ type: "text", text: `Error: ${error}` }],
-                isError: true,
-            };
-        }
-    });
-    // ─── decisions ─────────────────────────────────────────────────
-    server.tool("decisions", "Get the decision log, optionally filtered by module and timeframe", {
-        module: z.string().optional().describe("Filter by module/area"),
-        timeframe: z
-            .string()
-            .optional()
-            .describe("Time filter (e.g., '7d', '24h')"),
-    }, async (params) => {
-        const result = await client.query({
-            event_type: "decision",
-            module: params.module,
-            timeframe: params.timeframe,
-        });
-        const text = formatEvents(result.results);
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `## Decision log${params.module ? ` for "${params.module}"` : ""}\n\n${text}`,
-                },
-            ],
-        };
-    });
-    // ─── patterns ──────────────────────────────────────────────────
-    server.tool("patterns", "Get recurring insights and patterns identified across agent sessions", {}, async () => {
-        try {
-            const result = await client.getLearnings({
-                min_confidence: 0.5,
-                sort_by: "confidence",
-                sort_order: "desc",
-            });
-            const learnings = result.learnings || [];
-            if (learnings.length === 0) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: "No patterns identified yet. Patterns emerge after consolidation runs process reasoning events.",
-                        },
-                    ],
-                };
-            }
-            const text = learnings
-                .map((l) => `[confidence: ${(l.confidence ?? 0).toFixed(2)}] ${l.summary}\n  tags: ${(l.tags ?? []).join(", ") || "none"}\n  files: ${(l.file_patterns ?? []).join(", ") || "none"}`)
-                .join("\n\n");
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `## Patterns\n\n${text}`,
-                    },
-                ],
-            };
-        }
-        catch (error) {
-            return {
-                content: [{ type: "text", text: `Error: ${error}` }],
-                isError: true,
-            };
-        }
-    });
-    // ─── suggest ───────────────────────────────────────────────────
-    server.tool("suggest", "Get ranked task priorities based on accumulated reasoning", {
-        backlog: z
-            .preprocess((v) => (typeof v === "string" ? JSON.parse(v) : v), z.array(z.string()).min(1))
-            .describe("List of backlog items to prioritize"),
-    }, async (params) => {
-        try {
-            // Fetch learnings to rank backlog items by relevance to institutional knowledge
-            const learningsResult = await client.getLearnings({
-                sort_by: "confidence",
-                sort_order: "desc",
-            });
-            const learnings = learningsResult.learnings || [];
-            // Score each backlog item by how many learnings mention related terms
-            const scored = params.backlog.map((task) => {
-                const taskLower = task.toLowerCase();
-                const keywords = taskLower.split(/\s+/).filter((w) => w.length > 3);
-                let score = 0;
-                const reasons = [];
-                for (const l of learnings) {
-                    const summary = (l.summary || "").toLowerCase();
-                    const tags = (l.tags || []).join(" ").toLowerCase();
-                    const matched = keywords.filter((kw) => summary.includes(kw) || tags.includes(kw));
-                    if (matched.length > 0) {
-                        score += (l.confidence ?? 0.5) * matched.length;
-                        reasons.push(`${((l.confidence ?? 0) * 100).toFixed(0)}% confidence learning: "${(l.summary || "").slice(0, 80)}..."`);
+                catch (error) {
+                    analytics.track("tool.error", {
+                        tool: "learnings",
+                        error: toSafeTelemetryMessage(error),
+                    });
+                    return {
+                        content: [{ type: "text", text: toUserMessage(error) }],
+                        isError: true,
+                    };
+                }
+            },
+        }),
+        // ─── decisions ─────────────────────────────────────────────────
+        buildTool({
+            name: "decisions",
+            description: "Get the decision log, optionally filtered by module and timeframe",
+            inputSchema: {
+                module: z.string().optional().describe("Filter by module/area"),
+                timeframe: z
+                    .string()
+                    .optional()
+                    .describe("Time filter (e.g., '7d', '24h')"),
+            },
+            isReadOnly: true,
+            call: async (params) => {
+                analytics.track("tool.invoked", { tool: "decisions" });
+                try {
+                    if (params.module)
+                        validateInput(params.module, 1000);
+                    const result = await client.query({
+                        event_type: "decision",
+                        module: params.module,
+                        timeframe: params.timeframe,
+                    });
+                    const text = formatEvents(result.results);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `## Decision log${params.module ? ` for "${params.module}"` : ""}\n\n${text}`,
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    analytics.track("tool.error", {
+                        tool: "decisions",
+                        error: toSafeTelemetryMessage(error),
+                    });
+                    return {
+                        content: [{ type: "text", text: toUserMessage(error) }],
+                        isError: true,
+                    };
+                }
+            },
+        }),
+        // ─── patterns ──────────────────────────────────────────────────
+        buildTool({
+            name: "patterns",
+            description: "Get recurring insights and patterns identified across agent sessions",
+            inputSchema: {},
+            isReadOnly: true,
+            call: async () => {
+                analytics.track("tool.invoked", { tool: "patterns" });
+                try {
+                    const result = await client.getLearnings({
+                        min_confidence: 0.5,
+                        sort_by: "confidence",
+                        sort_order: "desc",
+                    });
+                    const learnings = result.learnings || [];
+                    if (learnings.length === 0) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: "No patterns identified yet. Patterns emerge after consolidation runs process reasoning events.",
+                                },
+                            ],
+                        };
                     }
+                    const text = learnings
+                        .map((l) => `[confidence: ${(l.confidence ?? 0).toFixed(2)}] ${l.summary}\n  tags: ${(l.tags ?? []).join(", ") || "none"}\n  files: ${(l.file_patterns ?? []).join(", ") || "none"}`)
+                        .join("\n\n");
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `## Patterns\n\n${text}`,
+                            },
+                        ],
+                    };
                 }
-                return { task, score: Math.round(score * 100) / 100, reasons };
-            });
-            scored.sort((a, b) => b.score - a.score);
-            const text = scored
-                .map((item, i) => `${i + 1}. **${item.task}** (evidence score: ${item.score})\n` +
-                (item.reasons.length > 0
-                    ? item.reasons
-                        .slice(0, 3)
-                        .map((r) => `   - ${r}`)
-                        .join("\n")
-                    : `   _No matching learnings yet_`))
-                .join("\n\n");
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `## Suggested priorities\n\n${text}`,
-                    },
-                ],
-            };
-        }
-        catch (error) {
-            return {
-                content: [{ type: "text", text: `Error: ${error}` }],
-                isError: true,
-            };
-        }
-    });
-    // ─── backlog ───────────────────────────────────────────────────
-    server.tool("backlog", "Get the auto-generated agentic product backlog. " +
-        "PBIs are generated by the consolidation engine from high-confidence learnings. " +
-        "Each PBI includes evidence summary, suggested approach, and full context.", {
-        status: z
-            .string()
-            .optional()
-            .describe("Filter by status: draft, approved, assigned, in_progress, done, rejected"),
-        priority: z
-            .string()
-            .optional()
-            .describe("Filter by priority: CRITICAL, HIGH, MEDIUM, LOW"),
-        tags: z.array(z.string()).optional().describe("Filter by tags"),
-        max_results: z.number().optional().default(20),
-    }, async (params) => {
-        try {
-            const backlog = await client.getBacklog({
-                status: params.status,
-                priority: params.priority,
-                tags: params.tags?.join(","),
-                limit: params.max_results,
-            });
-            if (!backlog || backlog.length === 0) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: "Backlog is empty. PBIs are auto-generated when the consolidation engine " +
-                                "runs and identifies actionable insights from reasoning events.",
-                        },
-                    ],
-                };
-            }
-            const lines = [
-                `## Agentic Product Backlog`,
-                ``,
-                `> ${backlog.length} item(s) | Auto-generated from consolidated learnings`,
-                ``,
-            ];
-            for (const item of backlog) {
-                lines.push(`### [${item.priority}] ${item.title}`);
-                lines.push(`**Status:** ${item.status} | **Scope:** ${item.scope}`);
-                if (item.description)
-                    lines.push(item.description);
-                if (item.evidence_summary)
-                    lines.push(`**Evidence:** ${item.evidence_summary}`);
-                if (item.suggested_approach)
-                    lines.push(`**Approach:** ${item.suggested_approach}`);
-                lines.push("");
-            }
-            return {
-                content: [{ type: "text", text: lines.join("\n") }],
-            };
-        }
-        catch (error) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Failed to retrieve backlog: ${error}`,
-                    },
-                ],
-                isError: true,
-            };
-        }
-    });
-    // ─── priorities ────────────────────────────────────────────────
-    server.tool("priorities", "Get evidence-ranked priorities for what to build next. " +
-        "Priorities are derived from consolidated learnings across agent sessions, " +
-        "code changes, meetings, tickets, and chat.", {
-        current_tasks: z
-            .array(z.string())
-            .optional()
-            .describe("Current task descriptions for context-aware ranking"),
-        max_results: z
-            .number()
-            .optional()
-            .default(10)
-            .describe("Maximum number of priorities to return"),
-    }, async (params) => {
-        try {
-            const backlog = await client.getBacklog({
-                status: "approved",
-                limit: params.max_results,
-            });
-            if (!backlog || backlog.length === 0) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: "No approved priorities in the backlog. " +
-                                "Run consolidation to generate PBIs from accumulated reasoning, " +
-                                "then have a PM approve them for work.",
-                        },
-                    ],
-                };
-            }
-            const lines = [
-                "## Evidence-Ranked Priorities",
-                "",
-                "> Derived from consolidated institutional knowledge, not guesswork.",
-                "",
-            ];
-            for (let i = 0; i < backlog.length; i++) {
-                const item = backlog[i];
-                lines.push(`${i + 1}. **[${item.priority}] ${item.title}**`);
-                lines.push(`   Status: ${item.status} | Scope: ${item.scope}`);
-                if (item.evidence_summary) {
-                    lines.push(`   Evidence: ${item.evidence_summary}`);
+                catch (error) {
+                    analytics.track("tool.error", {
+                        tool: "patterns",
+                        error: toSafeTelemetryMessage(error),
+                    });
+                    return {
+                        content: [{ type: "text", text: toUserMessage(error) }],
+                        isError: true,
+                    };
                 }
-                lines.push("");
-            }
-            return {
-                content: [{ type: "text", text: lines.join("\n") }],
-            };
-        }
-        catch (error) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Failed to retrieve priorities: ${error}`,
-                    },
-                ],
-                isError: true,
-            };
-        }
-    });
-    // ─── semantic_search ─────────────────────────────────────────
-    server.tool("semantic_search", "Search institutional knowledge using natural language. " +
-        "Uses vector embeddings for semantic similarity — finds learnings " +
-        "that are conceptually related to your query even if they don't share " +
-        "exact keywords. Requires the embedding provider to be configured.", {
-        query: z
-            .string()
-            .describe("Natural language query (e.g., 'authentication token refresh')"),
-        limit: z.number().optional().default(10).describe("Max results"),
-        min_similarity: z
-            .number()
-            .optional()
-            .default(0.4)
-            .describe("Minimum cosine similarity threshold (0.0–1.0)"),
-        visibility: z
-            .enum(["user_repo", "account_wide", "user_private"])
-            .optional()
-            .describe("Visibility scope: user_repo (default, repo-scoped), " +
-            "account_wide (cross-repo within account), " +
-            "user_private (personal learnings only)"),
-    }, async (params) => {
-        try {
-            // Try hybrid search first (BM25 + vector + RRF fusion)
-            const hybridResult = await client
-                .hybridSearch(params.query, {
-                limit: params.limit,
-                min_similarity: params.min_similarity,
-                visibility: params.visibility,
-            })
-                .catch(() => null);
-            if (hybridResult && hybridResult.results.length > 0) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: formatHybridResults(params.query, hybridResult.results, hybridResult.total_candidates, hybridResult.pipeline),
-                        },
-                    ],
-                };
-            }
-            // Fall back to legacy semantic search
-            const result = await client.semanticSearch(params.query, {
-                limit: params.limit,
-                min_similarity: params.min_similarity,
-                visibility: params.visibility,
-            });
-            if (result.results.length === 0) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: `No semantically similar learnings found for "${params.query}". ` +
-                                "The embedding provider may not be configured, or no learnings have been embedded yet.",
-                        },
-                    ],
-                };
-            }
-            const lines = [
-                `## Semantic Search: ${params.query}`,
-                "",
-                `> ${result.total} result(s) found.`,
-                "",
-            ];
-            for (const r of result.results) {
-                const sim = (r.similarity * 100).toFixed(0);
-                lines.push(`- **[${sim}%]** ${r.summary}`);
-                lines.push(`  *ID: ${r.id}*`);
-                lines.push("");
-            }
-            return {
-                content: [{ type: "text", text: lines.join("\n") }],
-            };
-        }
-        catch (error) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Semantic search failed: ${error}`,
-                    },
-                ],
-                isError: true,
-            };
-        }
-    });
-    // ─── consolidate ──────────────────────────────────────────────
-    server.tool("consolidate", "Trigger a consolidation run to process recent reasoning events " +
-        "and derive new learnings and backlog items. Use this when you want " +
-        "to refresh the institutional knowledge base.", {
-        max_events: z.number().optional().describe("Maximum events to process"),
-    }, async (params) => {
-        try {
-            const result = await client.triggerConsolidation({
-                repo: "",
-                trigger: "manual",
-                max_events: params.max_events,
-            });
-            const lines = [
-                "## Consolidation Complete",
-                "",
-                `**Run ID:** ${result.run_id}`,
-                `**Events processed:** ${result.events_processed}`,
-                `**New learnings:** ${result.new_learnings}`,
-                `**Reinforced:** ${result.reinforced}`,
-                `**Contradicted:** ${result.contradicted}`,
-                `**Backlog items generated:** ${result.backlog_items_generated}`,
-            ];
-            if (result.model_id) {
-                lines.push(`**Model:** ${result.model_id}`);
-            }
-            if (result.input_tokens) {
-                lines.push(`**Tokens:** ${result.input_tokens} in / ${result.output_tokens} out`);
-            }
-            return {
-                content: [{ type: "text", text: lines.join("\n") }],
-            };
-        }
-        catch (error) {
-            return {
-                content: [
-                    { type: "text", text: `Consolidation failed: ${error}` },
-                ],
-                isError: true,
-            };
-        }
-    });
+            },
+        }),
+        // ─── suggest ───────────────────────────────────────────────────
+        buildTool({
+            name: "suggest",
+            description: "Get ranked task priorities based on accumulated reasoning",
+            inputSchema: {
+                backlog: z
+                    .preprocess((v) => (typeof v === "string" ? JSON.parse(v) : v), z.array(z.string()).min(1))
+                    .describe("List of backlog items to prioritize"),
+            },
+            isReadOnly: true,
+            call: async (params) => {
+                analytics.track("tool.invoked", { tool: "suggest" });
+                try {
+                    for (const item of params.backlog) {
+                        validateInput(item, 10_000);
+                    }
+                    const learningsResult = await client.getLearnings({
+                        sort_by: "confidence",
+                        sort_order: "desc",
+                    });
+                    const learnings = learningsResult.learnings || [];
+                    const scored = params.backlog.map((task) => {
+                        const taskLower = task.toLowerCase();
+                        const keywords = taskLower
+                            .split(/\s+/)
+                            .filter((w) => w.length > 3);
+                        let score = 0;
+                        const reasons = [];
+                        for (const l of learnings) {
+                            const summary = (l.summary || "").toLowerCase();
+                            const tags = (l.tags || []).join(" ").toLowerCase();
+                            const matched = keywords.filter((kw) => summary.includes(kw) || tags.includes(kw));
+                            if (matched.length > 0) {
+                                score += (l.confidence ?? 0.5) * matched.length;
+                                reasons.push(`${((l.confidence ?? 0) * 100).toFixed(0)}% confidence learning: "${(l.summary || "").slice(0, 80)}..."`);
+                            }
+                        }
+                        return { task, score: Math.round(score * 100) / 100, reasons };
+                    });
+                    scored.sort((a, b) => b.score - a.score);
+                    const text = scored
+                        .map((item, i) => `${i + 1}. **${item.task}** (evidence score: ${item.score})\n` +
+                        (item.reasons.length > 0
+                            ? item.reasons
+                                .slice(0, 3)
+                                .map((r) => `   - ${r}`)
+                                .join("\n")
+                            : `   _No matching learnings yet_`))
+                        .join("\n\n");
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `## Suggested priorities\n\n${text}`,
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    analytics.track("tool.error", {
+                        tool: "suggest",
+                        error: toSafeTelemetryMessage(error),
+                    });
+                    return {
+                        content: [{ type: "text", text: toUserMessage(error) }],
+                        isError: true,
+                    };
+                }
+            },
+        }),
+        // ─── backlog ───────────────────────────────────────────────────
+        buildTool({
+            name: "backlog",
+            description: "Get the auto-generated agentic product backlog. " +
+                "PBIs are generated by the consolidation engine from high-confidence learnings. " +
+                "Each PBI includes evidence summary, suggested approach, and full context.",
+            inputSchema: {
+                status: z
+                    .string()
+                    .optional()
+                    .describe("Filter by status: draft, approved, assigned, in_progress, done, rejected"),
+                priority: z
+                    .string()
+                    .optional()
+                    .describe("Filter by priority: CRITICAL, HIGH, MEDIUM, LOW"),
+                tags: z.array(z.string()).optional().describe("Filter by tags"),
+                max_results: z.number().optional().default(20),
+            },
+            isReadOnly: true,
+            call: async (params) => {
+                analytics.track("tool.invoked", { tool: "backlog" });
+                try {
+                    const backlog = await client.getBacklog({
+                        status: params.status,
+                        priority: params.priority,
+                        tags: params.tags?.join(","),
+                        limit: params.max_results,
+                    });
+                    if (!backlog || backlog.length === 0) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: "Backlog is empty. PBIs are auto-generated when the consolidation engine " +
+                                        "runs and identifies actionable insights from reasoning events.",
+                                },
+                            ],
+                        };
+                    }
+                    const lines = [
+                        `## Agentic Product Backlog`,
+                        ``,
+                        `> ${backlog.length} item(s) | Auto-generated from consolidated learnings`,
+                        ``,
+                    ];
+                    for (const item of backlog) {
+                        lines.push(`### [${item.priority}] ${item.title}`);
+                        lines.push(`**Status:** ${item.status} | **Scope:** ${item.scope}`);
+                        if (item.description)
+                            lines.push(item.description);
+                        if (item.evidence_summary)
+                            lines.push(`**Evidence:** ${item.evidence_summary}`);
+                        if (item.suggested_approach)
+                            lines.push(`**Approach:** ${item.suggested_approach}`);
+                        lines.push("");
+                    }
+                    return {
+                        content: [{ type: "text", text: lines.join("\n") }],
+                    };
+                }
+                catch (error) {
+                    analytics.track("tool.error", {
+                        tool: "backlog",
+                        error: toSafeTelemetryMessage(error),
+                    });
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Failed to retrieve backlog: ${toUserMessage(error)}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            },
+        }),
+        // ─── priorities ────────────────────────────────────────────────
+        buildTool({
+            name: "priorities",
+            description: "Get evidence-ranked priorities for what to build next. " +
+                "Priorities are derived from consolidated learnings across agent sessions, " +
+                "code changes, meetings, tickets, and chat.",
+            inputSchema: {
+                current_tasks: z
+                    .array(z.string())
+                    .optional()
+                    .describe("Current task descriptions for context-aware ranking"),
+                max_results: z
+                    .number()
+                    .optional()
+                    .default(10)
+                    .describe("Maximum number of priorities to return"),
+            },
+            isReadOnly: true,
+            call: async (params) => {
+                analytics.track("tool.invoked", { tool: "priorities" });
+                try {
+                    if (params.current_tasks) {
+                        for (const task of params.current_tasks) {
+                            validateInput(task, 10_000);
+                        }
+                    }
+                    const backlog = await client.getBacklog({
+                        status: "approved",
+                        limit: params.max_results,
+                    });
+                    if (!backlog || backlog.length === 0) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: "No approved priorities in the backlog. " +
+                                        "Run consolidation to generate PBIs from accumulated reasoning, " +
+                                        "then have a PM approve them for work.",
+                                },
+                            ],
+                        };
+                    }
+                    const lines = [
+                        "## Evidence-Ranked Priorities",
+                        "",
+                        "> Derived from consolidated institutional knowledge, not guesswork.",
+                        "",
+                    ];
+                    for (let i = 0; i < backlog.length; i++) {
+                        const item = backlog[i];
+                        lines.push(`${i + 1}. **[${item.priority}] ${item.title}**`);
+                        lines.push(`   Status: ${item.status} | Scope: ${item.scope}`);
+                        if (item.evidence_summary) {
+                            lines.push(`   Evidence: ${item.evidence_summary}`);
+                        }
+                        lines.push("");
+                    }
+                    return {
+                        content: [{ type: "text", text: lines.join("\n") }],
+                    };
+                }
+                catch (error) {
+                    analytics.track("tool.error", {
+                        tool: "priorities",
+                        error: toSafeTelemetryMessage(error),
+                    });
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Failed to retrieve priorities: ${toUserMessage(error)}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            },
+        }),
+        // ─── semantic_search ─────────────────────────────────────────
+        buildTool({
+            name: "semantic_search",
+            description: "Search institutional knowledge using natural language. " +
+                "Uses vector embeddings for semantic similarity — finds learnings " +
+                "that are conceptually related to your query even if they don't share " +
+                "exact keywords. Requires the embedding provider to be configured.",
+            inputSchema: {
+                query: z
+                    .string()
+                    .describe("Natural language query (e.g., 'authentication token refresh')"),
+                limit: z.number().optional().default(10).describe("Max results"),
+                min_similarity: z
+                    .number()
+                    .optional()
+                    .default(0.4)
+                    .describe("Minimum cosine similarity threshold (0.0–1.0)"),
+                visibility: z
+                    .enum(["user_repo", "account_wide", "user_private"])
+                    .optional()
+                    .describe("Visibility scope: user_repo (default, repo-scoped), " +
+                    "account_wide (cross-repo within account), " +
+                    "user_private (personal learnings only)"),
+            },
+            isReadOnly: true,
+            call: async (params) => {
+                analytics.track("tool.invoked", { tool: "semantic_search" });
+                try {
+                    validateInput(params.query, 100_000);
+                    // Try hybrid search first (BM25 + vector + RRF fusion)
+                    const hybridResult = await client
+                        .hybridSearch(params.query, {
+                        limit: params.limit,
+                        min_similarity: params.min_similarity,
+                        visibility: params.visibility,
+                    })
+                        .catch(() => null);
+                    if (hybridResult && hybridResult.results.length > 0) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: formatHybridResults(params.query, hybridResult.results, hybridResult.total_candidates, hybridResult.pipeline),
+                                },
+                            ],
+                        };
+                    }
+                    // Fall back to legacy semantic search
+                    const result = await client.semanticSearch(params.query, {
+                        limit: params.limit,
+                        min_similarity: params.min_similarity,
+                        visibility: params.visibility,
+                    });
+                    if (result.results.length === 0) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `No semantically similar learnings found for "${params.query}". ` +
+                                        "The embedding provider may not be configured, or no learnings have been embedded yet.",
+                                },
+                            ],
+                        };
+                    }
+                    const lines = [
+                        `## Semantic Search: ${params.query}`,
+                        "",
+                        `> ${result.total} result(s) found.`,
+                        "",
+                    ];
+                    for (const r of result.results) {
+                        const sim = (r.similarity * 100).toFixed(0);
+                        lines.push(`- **[${sim}%]** ${r.summary}`);
+                        lines.push(`  *ID: ${r.id}*`);
+                        lines.push("");
+                    }
+                    return {
+                        content: [{ type: "text", text: lines.join("\n") }],
+                    };
+                }
+                catch (error) {
+                    analytics.track("tool.error", {
+                        tool: "semantic_search",
+                        error: toSafeTelemetryMessage(error),
+                    });
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Semantic search failed: ${toUserMessage(error)}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            },
+        }),
+        // ─── consolidate ──────────────────────────────────────────────
+        buildTool({
+            name: "consolidate",
+            description: "Trigger a consolidation run to process recent reasoning events " +
+                "and derive new learnings and backlog items. Use this when you want " +
+                "to refresh the institutional knowledge base.",
+            inputSchema: {
+                max_events: z.number().optional().describe("Maximum events to process"),
+            },
+            isReadOnly: false,
+            isConcurrencySafe: false,
+            call: async (params) => {
+                analytics.track("tool.invoked", { tool: "consolidate" });
+                try {
+                    const result = await client.triggerConsolidation({
+                        repo: "",
+                        trigger: "manual",
+                        max_events: params.max_events,
+                    });
+                    const lines = [
+                        "## Consolidation Complete",
+                        "",
+                        `**Run ID:** ${result.run_id}`,
+                        `**Events processed:** ${result.events_processed}`,
+                        `**New learnings:** ${result.new_learnings}`,
+                        `**Reinforced:** ${result.reinforced}`,
+                        `**Contradicted:** ${result.contradicted}`,
+                        `**Backlog items generated:** ${result.backlog_items_generated}`,
+                    ];
+                    if (result.model_id) {
+                        lines.push(`**Model:** ${result.model_id}`);
+                    }
+                    if (result.input_tokens) {
+                        lines.push(`**Tokens:** ${result.input_tokens} in / ${result.output_tokens} out`);
+                    }
+                    return {
+                        content: [{ type: "text", text: lines.join("\n") }],
+                    };
+                }
+                catch (error) {
+                    analytics.track("tool.error", {
+                        tool: "consolidate",
+                        error: toSafeTelemetryMessage(error),
+                    });
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Consolidation failed: ${toUserMessage(error)}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            },
+        }),
+    ];
+}
+// ─── Registration ─────────────────────────────────────────────────────
+/**
+ * Register read tools on the MCP server.
+ */
+export function registerReadTools(server, client) {
+    registerToolPool(buildReadTools(client), server);
 }