@oka-core/reason 0.2.0

package/dist/tools/read_enhanced.js

@@ -0,0 +1,304 @@
+import { z } from "zod";
+/**
+ * Enhanced read tools that prefer consolidated Learnings over raw events.
+ *
+ * These are drop-in replacements for the basic read tools in read.ts.
+ * They query the enhanced learnings API first, falling back to raw events
+ * if the enhanced endpoint isn't available.
+ */
+const GetContextInputEnhanced = z.object({
+    repo: z.string().describe("Repository identifier"),
+    area: z
+        .string()
+        .describe("Area to get context for (e.g., 'auth', 'billing')"),
+    include_raw_events: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("Also include raw recent events alongside consolidated learnings"),
+    min_confidence: z
+        .number()
+        .optional()
+        .default(0.5)
+        .describe("Minimum confidence for included learnings"),
+});
+const GetDecisionsInputEnhanced = z.object({
+    repo: z.string(),
+    module: z.string().optional().describe("Module to filter by"),
+    timeframe: z.string().optional().describe("Timeframe: '7d', '30d', '24h'"),
+    include_rationale: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe("Include full rationale and alternatives considered"),
+});
+const GetPatternsInputEnhanced = z.object({
+    repo: z.string(),
+    category: z
+        .string()
+        .optional()
+        .describe("Filter by: architecture, bug_pattern, convention, decision, performance, security, workflow"),
+    min_evidence: z
+        .number()
+        .optional()
+        .default(2)
+        .describe("Minimum number of corroborating sources"),
+});
+const SuggestPrioritiesEnhanced = z.object({
+    repo: z.string(),
+    backlog: z
+        .array(z.string())
+        .optional()
+        .describe("Current backlog items for context-aware ranking"),
+    include_auto_generated: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe("Include auto-generated PBIs from consolidation"),
+});
+export function registerEnhancedReadTools(server, client) {
+    server.tool("get_context_enhanced", "Get consolidated institutional knowledge about an area. " +
+        "Unlike basic get_context, this returns Learnings derived from cross-source " +
+        "consolidation (agent reasoning + code + docs + meetings + tickets + chat). " +
+        "Each learning has a confidence score and evidence count.", GetContextInputEnhanced.shape, async (params) => {
+        try {
+            // Try enhanced endpoint first
+            const enhancedResult = await fetchEnhancedLearnings(client, {
+                repo: params.repo,
+                area: params.area,
+                minConfidence: params.min_confidence,
+            });
+            if (enhancedResult && enhancedResult.length > 0) {
+                let text = formatEnhancedContext(params.area, enhancedResult);
+                // Optionally include raw events for full picture
+                if (params.include_raw_events) {
+                    const rawResult = await client.query({
+                        area: params.area,
+                    });
+                    if (rawResult?.results?.length > 0) {
+                        text += "\n\n---\n\n## Recent Raw Events\n\n";
+                        text += rawResult.results
+                            .slice(0, 10)
+                            .map((r) => {
+                            const rec = r;
+                            const payload = rec["payload"];
+                            const desc = payload?.["description"] ||
+                                payload?.["area"] ||
+                                JSON.stringify(payload).slice(0, 200);
+                            return `- [${rec["event_type"]}] ${desc}`;
+                        })
+                            .join("\n");
+                    }
+                }
+                return { content: [{ type: "text", text }] };
+            }
+            // Fall back to raw events
+            const rawResult = await client.query({
+                area: params.area,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: rawResult?.results?.length > 0
+                            ? formatRawFallback(params.area, rawResult.results)
+                            : `No knowledge found for area "${params.area}". This area hasn't been explored yet.`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `Error: ${error}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("get_decisions_enhanced", "Get the decision log with full rationale and alternatives. " +
+        "Shows what was decided, why, and what was rejected.", GetDecisionsInputEnhanced.shape, async (params) => {
+        try {
+            const result = await client.query({
+                event_type: "decision",
+                module: params.module,
+                timeframe: params.timeframe,
+            });
+            if (!result?.results?.length) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "No decisions recorded for this scope.",
+                        },
+                    ],
+                };
+            }
+            const formatted = result.results
+                .map((r) => {
+                const record = r;
+                const p = record["payload"] || {};
+                let entry = `### ${p["description"] || "Decision"}\n`;
+                if (params.include_rationale && p["rationale"]) {
+                    entry += `**Rationale:** ${p["rationale"]}\n`;
+                }
+                const alts = p["alternatives_considered"];
+                if (alts && alts.length > 0) {
+                    entry += `**Rejected alternatives:** ${alts.join(", ")}\n`;
+                }
+                if (p["confidence"]) {
+                    entry += `**Confidence:** ${((p["confidence"] ?? 0) * 100).toFixed(0)}%\n`;
+                }
+                entry += `*Agent: ${record["agent_id"]} | Session: ${record["session_id"]}*\n`;
+                return entry;
+            })
+                .join("\n---\n\n");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `## Decision Log\n\n${formatted}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `Error: ${error}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("get_patterns_enhanced", "Get recurring patterns with evidence counts and confidence. " +
+        "Only shows patterns corroborated by multiple sources.", GetPatternsInputEnhanced.shape, async (params) => {
+        try {
+            const learnings = await fetchEnhancedLearnings(client, {
+                repo: params.repo,
+                category: params.category,
+                minConfidence: 0.5,
+            });
+            const patterns = (learnings || []).filter((l) => (l.evidence_count ?? 1) >= (params.min_evidence ?? 2));
+            if (patterns.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "No recurring patterns identified yet. Patterns emerge after multiple " +
+                                "sessions observe the same conventions, bugs, or architectural decisions.",
+                        },
+                    ],
+                };
+            }
+            const formatted = patterns
+                .map((p) => `### ${p.summary}\n` +
+                `**Confidence:** ${((p.confidence ?? 0) * 100).toFixed(0)}% | ` +
+                `**Evidence:** ${p.evidence_count} source(s) | ` +
+                `**Category:** ${p.category || "general"}\n` +
+                (p.suggested_action
+                    ? `**Action:** ${p.suggested_action}\n`
+                    : "") +
+                (p.file_patterns?.length
+                    ? `**Files:** ${p.file_patterns.join(", ")}\n`
+                    : ""))
+                .join("\n---\n\n");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `## Recurring Patterns\n\n${formatted}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `Error: ${error}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("suggest_priorities_enhanced", "Suggest evidence-ranked priorities combining human backlog with " +
+        "auto-generated PBIs from consolidation.", SuggestPrioritiesEnhanced.shape, async (params) => {
+        try {
+            // Get high-confidence learnings that suggest action
+            const learnings = await fetchEnhancedLearnings(client, {
+                repo: params.repo,
+                minConfidence: 0.7,
+            });
+            const actionable = (learnings || [])
+                .filter((l) => l.suggested_action)
+                .sort((a, b) => (b.confidence ?? 0) - (a.confidence ?? 0));
+            let text = "## Suggested Priorities\n\n";
+            text += "> Ranked by evidence weight across all knowledge sources.\n\n";
+            if (actionable.length === 0) {
+                text +=
+                    "No high-confidence actionable learnings yet. " +
+                        "Continue capturing reasoning events to build the evidence base.";
+            }
+            else {
+                actionable.forEach((l, i) => {
+                    text += `${i + 1}. **${l.summary}**\n`;
+                    text += `   Confidence: ${((l.confidence ?? 0) * 100).toFixed(0)}% | `;
+                    text += `Evidence: ${l.evidence_count ?? 1} source(s)\n`;
+                    text += `   Action: ${l.suggested_action}\n\n`;
+                });
+            }
+            return { content: [{ type: "text", text }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `Error: ${error}` }],
+                isError: true,
+            };
+        }
+    });
+}
+// --- Helpers ---
+async function fetchEnhancedLearnings(client, options) {
+    try {
+        // Try the enhanced learnings endpoint via the client's query method
+        // with a special type parameter that the API can recognize
+        const result = await client.query({
+            type: "learnings_enhanced",
+            area: options.area,
+            category: options.category,
+            min_confidence: options.minConfidence
+                ? String(options.minConfidence)
+                : undefined,
+            sort_by: "confidence",
+            sort_order: "desc",
+            limit: "30",
+        });
+        return result?.results ?? [];
+    }
+    catch {
+        return [];
+    }
+}
+function formatEnhancedContext(area, learnings) {
+    let text = `## Institutional Knowledge: ${area}\n\n`;
+    text += `> ${learnings.length} consolidated learning(s) from cross-source analysis.\n\n`;
+    for (const l of learnings) {
+        text += `### ${l.summary}\n`;
+        text += `**Confidence:** ${((l.confidence ?? 0) * 100).toFixed(0)}%`;
+        if (l.evidence_count > 1)
+            text += ` (${l.evidence_count} sources)`;
+        text += ` | **Category:** ${l.category || "general"}\n`;
+        if (l.detailed_description)
+            text += `\n${l.detailed_description}\n`;
+        if (l.suggested_action)
+            text += `\n**Suggested action:** ${l.suggested_action}\n`;
+        if (l.file_patterns?.length)
+            text += `**Related files:** ${l.file_patterns.join(", ")}\n`;
+        text += "\n";
+    }
+    return text;
+}
+function formatRawFallback(area, events) {
+    let text = `## Raw Events: ${area}\n\n`;
+    text += `> No consolidated learnings yet. Showing ${events.length} raw event(s).\n\n`;
+    for (const e of events) {
+        const payload = e["payload"];
+        const desc = payload?.["description"] || JSON.stringify(payload).slice(0, 200);
+        text += `- [${e["event_type"]}] ${desc}\n`;
+    }
+    return text;
+}

package/dist/tools/write.d.ts

@@ -0,0 +1,8 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { OkaClient } from "../client.js";
+/**
+ * Register the 4 write tools on the MCP server.
+ * Each tool validates input, creates a reasoning event, and fires it to the API.
+ */
+export declare function registerWriteTools(server: McpServer, client: OkaClient): void;
+//# sourceMappingURL=write.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/tools/write.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAgJ7E"}

package/dist/tools/write.js

@@ -0,0 +1,120 @@
+import { z } from "zod";
+/**
+ * Register the 4 write tools on the MCP server.
+ * Each tool validates input, creates a reasoning event, and fires it to the API.
+ */
+export function registerWriteTools(server, client) {
+    server.tool("decision", "Record an agent decision with rationale and alternatives considered", {
+        description: z.string().describe("What was decided"),
+        rationale: z.string().describe("Why this choice was made"),
+        alternatives_considered: z
+            .array(z.string())
+            .default([])
+            .describe("Other options that were evaluated"),
+        confidence: z
+            .number()
+            .min(0)
+            .max(1)
+            .describe("Confidence in the decision (0-1)"),
+    }, async (params) => {
+        await client.ingest({ event_type: "decision", payload: params });
+        return {
+            content: [{ type: "text", text: "Decision recorded." }],
+        };
+    });
+    server.tool("explore", "Record an area the agent explored and what was found", {
+        area: z.string().describe("The area or module explored"),
+        findings: z.string().describe("What was discovered"),
+        relevance_score: z
+            .number()
+            .min(0)
+            .max(1)
+            .describe("How relevant to the current task (0-1)"),
+    }, async (params) => {
+        await client.ingest({ event_type: "exploration", payload: params });
+        return {
+            content: [{ type: "text", text: "Exploration recorded." }],
+        };
+    });
+    server.tool("deviation", "Record when the agent deviated from the original plan", {
+        planned_action: z.string().describe("What was originally planned"),
+        actual_action: z.string().describe("What was actually done"),
+        reason: z.string().describe("Why the deviation occurred"),
+    }, async (params) => {
+        await client.ingest({ event_type: "deviation", payload: params });
+        return {
+            content: [{ type: "text", text: "Deviation recorded." }],
+        };
+    });
+    server.tool("done", "Record task completion with outcome and quality signals", {
+        task_id: z.string().describe("Identifier for the completed task"),
+        outcome: z
+            .enum(["success", "partial", "failed"])
+            .describe("Task outcome"),
+        artifacts: z
+            .array(z.string())
+            .default([])
+            .describe("Files or PRs produced"),
+        quality_signals: z
+            .record(z.string(), z.number())
+            .default({})
+            .describe("Quality metrics (e.g., test_coverage: 0.92)"),
+    }, async (params) => {
+        await client.ingest({ event_type: "completion", payload: params });
+        return {
+            content: [{ type: "text", text: "Completion recorded." }],
+        };
+    });
+    // ─── observe (general-purpose) ─────────────────────────────────
+    server.tool("observe", "Record a general observation that doesn't fit decision/explore/deviation/done. " +
+        "Use this for architectural insights, code quality notes, dependency observations, " +
+        "performance findings, or any other knowledge worth preserving.", {
+        category: z
+            .enum([
+            "architecture",
+            "bug_pattern",
+            "convention",
+            "performance",
+            "security",
+            "workflow",
+            "dependency",
+            "code_quality",
+            "other",
+        ])
+            .describe("Category of the observation"),
+        summary: z.string().describe("Brief summary of the observation"),
+        details: z.string().optional().describe("Detailed description"),
+        confidence: z
+            .number()
+            .min(0)
+            .max(1)
+            .default(0.7)
+            .describe("Confidence in this observation (0-1)"),
+        file_patterns: z
+            .array(z.string())
+            .default([])
+            .describe("Related file patterns (e.g., 'src/auth/**')"),
+        tags: z.array(z.string()).default([]).describe("Tags for categorization"),
+    }, async (params) => {
+        await client.ingest({
+            event_type: "exploration",
+            payload: {
+                area: params.category,
+                findings: params.summary,
+                details: params.details,
+                relevance_score: params.confidence,
+                observation_category: params.category,
+                file_patterns: params.file_patterns,
+                tags: params.tags,
+            },
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Observation recorded: [${params.category}] ${params.summary}`,
+                },
+            ],
+        };
+    });
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@oka-core/reason",
+  "version": "0.2.0",
+  "description": "MCP server for Oka Reason — institutional knowledge, semantic search, and consolidation",
+  "private": false,
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "type": "module",
+  "bin": {
+    "oka-reason": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./client": {
+      "import": "./dist/client.js",
+      "types": "./dist/client.d.ts"
+    },
+    "./auth": {
+      "import": "./dist/auth.js",
+      "types": "./dist/auth.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "check-types": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "echo 'lint ok'",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "mcp",
+    "reasoning",
+    "semantic-search",
+    "knowledge-management",
+    "oka"
+  ],
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/datacircuits/agentic.git",
+    "directory": "packages/reason"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0",
+    "@oka/typescript-config": "workspace:*"
+  }
+}