@oka-core/reason 0.2.0

package/dist/tools/read.js

@@ -0,0 +1,578 @@
+import { z } from "zod";
+// ─── Formatters ────────────────────────────────────────────────────
+function formatEvents(events) {
+    if (events.length === 0)
+        return "No prior reasoning found for this area.";
+    return events
+        .map((e) => `[${e.event_type}] ${e.timestamp}\n${JSON.stringify(e.payload, null, 2)}`)
+        .join("\n\n---\n\n");
+}
+function formatContextLearnings(topic, learnings, totalMatched) {
+    if (learnings.length === 0) {
+        return `No consolidated knowledge found for topic "${topic}". This area may not have enough reasoning events yet.`;
+    }
+    const lines = [
+        `## Institutional Knowledge: ${topic}`,
+        ``,
+        `> ${totalMatched} learning(s) matched, showing top ${learnings.length}.`,
+        ``,
+    ];
+    for (const l of learnings) {
+        const confidence = ((l.confidence ?? 0) * 100).toFixed(0);
+        const relevance = ((l.relevance_score ?? 0) * 100).toFixed(0);
+        lines.push(`### ${l.summary}`);
+        lines.push(`**Relevance:** ${relevance}% | **Confidence:** ${confidence}% | **Category:** ${l.category}`);
+        if (l.evidence_count > 1) {
+            lines.push(`**Evidence:** ${l.evidence_count} source(s)`);
+        }
+        if (l.detailed_description) {
+            lines.push(`\n${l.detailed_description}`);
+        }
+        if (l.suggested_action) {
+            lines.push(`\n**Suggested action:** ${l.suggested_action}`);
+        }
+        if (l.file_patterns?.length > 0) {
+            lines.push(`**Related files:** ${l.file_patterns.join(", ")}`);
+        }
+        if (l.tags?.length > 0) {
+            lines.push(`**Tags:** ${l.tags.join(", ")}`);
+        }
+        lines.push(`*Matched by: ${l.metadata.matching_strategy}*`);
+        lines.push("");
+    }
+    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')"),
+        repo: z.string().optional().describe("Repository identifier"),
+        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 {
+            // Try the new context endpoint first
+            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 }] };
+            }
+            // Fall back to raw event query if no learnings exist
+            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.", {
+        repo: z.string().optional().describe("Repository to filter by"),
+        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({
+                repo: params.repo,
+                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") }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `Error: ${error}` }],
+                isError: true,
+            };
+        }
+    });
+    // ─── decisions ─────────────────────────────────────────────────
+    server.tool("decisions", "Get the decision log for a repo, optionally filtered by module and timeframe", {
+        repo: z.string().describe("Repository identifier"),
+        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", {
+        repo: z.string().describe("Repository identifier"),
+    }, async (params) => {
+        try {
+            const result = await client.getLearnings({
+                repo: params.repo,
+                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 for ${params.repo}\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", {
+        repo: z.string().describe("Repository identifier"),
+        backlog: 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({
+                repo: params.repo,
+                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)}..."`);
+                    }
+                }
+                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.", {
+        repo: z.string().optional().describe("Repository to scope to"),
+        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({
+                repo: params.repo,
+                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.", {
+        repo: z.string().optional().describe("Repository to scope priorities to"),
+        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({
+                repo: params.repo,
+                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) {
+            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')"),
+        repo: z
+            .string()
+            .optional()
+            .describe("Repository identifier. Optional for account_wide (cross-repo) search."),
+        limit: z.number().optional().default(10).describe("Max results"),
+        min_similarity: z
+            .number()
+            .optional()
+            .default(0.7)
+            .describe("Minimum cosine similarity (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 {
+            const result = await client.semanticSearch(params.query, {
+                repo: params.repo,
+                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.", {
+        repo: z.string().describe("Repository to run consolidation for"),
+        max_events: z.number().optional().describe("Maximum events to process"),
+    }, async (params) => {
+        try {
+            const result = await client.triggerConsolidation({
+                repo: params.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,
+            };
+        }
+    });
+}

package/dist/tools/read_enhanced.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { OkaClient } from "../client.js";
+export declare function registerEnhancedReadTools(server: McpServer, client: OkaClient): void;
+//# sourceMappingURL=read_enhanced.d.ts.map

package/dist/tools/read_enhanced.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read_enhanced.d.ts","sourceRoot":"","sources":["../../src/tools/read_enhanced.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAoE9C,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,SAAS,GAChB,IAAI,CAqPN"}