@mainahq/core 1.0.3 → 1.1.0

package/src/feedback/__tests__/signals.test.ts

@@ -0,0 +1,144 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { getFeedbackDb } from "../../db/index";
+import { recordFeedback } from "../collector";
+import { emitAcceptSignal, emitRejectSignal } from "../signals";
+
+let tmpDir: string;
+
+beforeEach(() => {
+	tmpDir = join(
+		import.meta.dir,
+		`tmp-signals-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+	);
+	mkdirSync(tmpDir, { recursive: true });
+});
+
+afterEach(() => {
+	try {
+		rmSync(tmpDir, { recursive: true, force: true });
+	} catch {
+		/* ignore */
+	}
+});
+
+/** Insert a feedback row and set its workflow_id. */
+function insertFeedback(
+	tool: string,
+	workflowId: string,
+	accepted: boolean,
+): void {
+	recordFeedback(tmpDir, {
+		promptHash: `${tool}-mcp`,
+		task: tool,
+		accepted,
+		timestamp: new Date().toISOString(),
+	});
+	const dbResult = getFeedbackDb(tmpDir);
+	if (!dbResult.ok) return;
+	const { db } = dbResult.value;
+	db.prepare(
+		`UPDATE feedback SET workflow_id = ?
+		 WHERE id = (SELECT id FROM feedback ORDER BY rowid DESC LIMIT 1)`,
+	).run(workflowId);
+}
+
+describe("emitAcceptSignal", () => {
+	test("marks recent review/verify entries as accepted", () => {
+		insertFeedback("reviewCode", "wf-1", false);
+		insertFeedback("verify", "wf-1", false);
+
+		emitAcceptSignal(tmpDir, "wf-1");
+
+		const dbResult = getFeedbackDb(tmpDir);
+		expect(dbResult.ok).toBe(true);
+		if (!dbResult.ok) return;
+		const { db } = dbResult.value;
+		const rows = db
+			.query("SELECT command, accepted FROM feedback WHERE workflow_id = ?")
+			.all("wf-1") as Array<{ command: string; accepted: number }>;
+		for (const row of rows) {
+			expect(row.accepted).toBe(1);
+		}
+	});
+
+	test("does not affect entries from a different workflow", () => {
+		insertFeedback("reviewCode", "wf-1", false);
+		insertFeedback("reviewCode", "wf-2", false);
+
+		emitAcceptSignal(tmpDir, "wf-1");
+
+		const dbResult = getFeedbackDb(tmpDir);
+		if (!dbResult.ok) return;
+		const { db } = dbResult.value;
+		const wf2 = db
+			.query("SELECT accepted FROM feedback WHERE workflow_id = ?")
+			.get("wf-2") as { accepted: number } | null;
+		expect(wf2?.accepted).toBe(0);
+	});
+
+	test("accepts custom tool list", () => {
+		insertFeedback("reviewCode", "wf-1", false);
+		insertFeedback("verify", "wf-1", false);
+
+		emitAcceptSignal(tmpDir, "wf-1", ["reviewCode"]);
+
+		const dbResult = getFeedbackDb(tmpDir);
+		if (!dbResult.ok) return;
+		const { db } = dbResult.value;
+		const review = db
+			.query(
+				"SELECT accepted FROM feedback WHERE command = ? AND workflow_id = ?",
+			)
+			.get("reviewCode", "wf-1") as { accepted: number } | null;
+		expect(review?.accepted).toBe(1);
+		const verify = db
+			.query(
+				"SELECT accepted FROM feedback WHERE command = ? AND workflow_id = ?",
+			)
+			.get("verify", "wf-1") as { accepted: number } | null;
+		expect(verify?.accepted).toBe(0);
+	});
+});
+
+describe("emitRejectSignal", () => {
+	test("marks the most recent entry for a tool+workflow as rejected", () => {
+		insertFeedback("reviewCode", "wf-1", true);
+		emitRejectSignal(tmpDir, "reviewCode", "wf-1");
+
+		const dbResult = getFeedbackDb(tmpDir);
+		if (!dbResult.ok) return;
+		const { db } = dbResult.value;
+		const row = db
+			.query(
+				"SELECT accepted FROM feedback WHERE command = ? AND workflow_id = ? ORDER BY created_at DESC LIMIT 1",
+			)
+			.get("reviewCode", "wf-1") as { accepted: number } | null;
+		expect(row?.accepted).toBe(0);
+	});
+
+	test("only rejects the most recent entry, not older ones", () => {
+		insertFeedback("reviewCode", "wf-1", true);
+		insertFeedback("reviewCode", "wf-1", true);
+		emitRejectSignal(tmpDir, "reviewCode", "wf-1");
+
+		const dbResult = getFeedbackDb(tmpDir);
+		if (!dbResult.ok) return;
+		const { db } = dbResult.value;
+		const rows = db
+			.query(
+				"SELECT accepted FROM feedback WHERE command = ? AND workflow_id = ? ORDER BY created_at ASC",
+			)
+			.all("reviewCode", "wf-1") as Array<{ accepted: number }>;
+		expect(rows).toHaveLength(2);
+		expect(rows[0]?.accepted).toBe(1);
+		expect(rows[1]?.accepted).toBe(0);
+	});
+
+	test("does not throw when no matching entries exist", () => {
+		expect(() => {
+			emitRejectSignal(tmpDir, "reviewCode", "nonexistent");
+		}).not.toThrow();
+	});
+});

package/src/feedback/capture.ts

@@ -0,0 +1,102 @@
+/**
+ * MCP result capture — connects tool outputs to cache, feedback, and stats.
+ * This is the core of the round-trip flywheel.
+ */
+
+import { hashContent } from "../cache/keys";
+import { createCacheManager } from "../cache/manager";
+import { trackToolUsage } from "../stats/tracker";
+import { recordFeedback } from "./collector";
+import { emitRejectSignal } from "./signals";
+
+export interface CaptureInput {
+	tool: string;
+	input: Record<string, unknown>;
+	output: string;
+	promptHash?: string;
+	durationMs: number;
+	mainaDir: string;
+	workflowId?: string;
+}
+
+export function buildToolCacheKey(
+	tool: string,
+	input: Record<string, unknown>,
+): string {
+	const inputHash = hashContent(JSON.stringify(input));
+	return hashContent(`mcp:${tool}:${inputHash}`);
+}
+
+export function getCachedResult(
+	tool: string,
+	input: Record<string, unknown>,
+	mainaDir: string,
+): string | null {
+	try {
+		const cache = createCacheManager(mainaDir);
+		const key = buildToolCacheKey(tool, input);
+		const entry = cache.get(key);
+		if (entry !== null) {
+			const inputHash = hashContent(JSON.stringify(input));
+			trackToolUsage(mainaDir, {
+				tool,
+				inputHash,
+				durationMs: 0,
+				cacheHit: true,
+			});
+			return entry.value;
+		}
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+export function captureResult(input: CaptureInput): void {
+	const inputHash = hashContent(JSON.stringify(input.input));
+
+	// 1. Cache (synchronous — fast SQLite write)
+	try {
+		const cache = createCacheManager(input.mainaDir);
+		const key = buildToolCacheKey(input.tool, input.input);
+		cache.set(key, input.output, { ttl: 0 });
+	} catch {
+		// Cache failure is non-fatal
+	}
+
+	// 2. Reject previous result for same tool+workflow (re-run implies rejection)
+	if (input.workflowId) {
+		try {
+			emitRejectSignal(input.mainaDir, input.tool, input.workflowId);
+		} catch {
+			// Reject failure is non-fatal
+		}
+	}
+
+	// 3. Feedback (fire-and-forget via microtask)
+	queueMicrotask(() => {
+		try {
+			recordFeedback(input.mainaDir, {
+				promptHash: input.promptHash ?? `${input.tool}-mcp`,
+				task: input.tool,
+				accepted: true,
+				timestamp: new Date().toISOString(),
+			});
+		} catch {
+			// Never throw from background feedback
+		}
+	});
+
+	// 4. Stats (synchronous — fast SQLite write)
+	try {
+		trackToolUsage(input.mainaDir, {
+			tool: input.tool,
+			inputHash,
+			durationMs: input.durationMs,
+			cacheHit: false,
+			workflowId: input.workflowId,
+		});
+	} catch {
+		// Stats failure is non-fatal
+	}
+}

package/src/feedback/signals.ts

@@ -0,0 +1,68 @@
+/**
+ * Implicit accept/reject signals for the RL flywheel.
+ * Infers outcomes from downstream user behavior instead of requiring explicit action.
+ */
+
+import { join } from "node:path";
+import { getFeedbackDb } from "../db/index";
+import { recordWikiUsage } from "../wiki/signals";
+
+const DEFAULT_ACCEPT_TOOLS = ["reviewCode", "verify", "checkSlop"];
+
+export function emitAcceptSignal(
+	mainaDir: string,
+	workflowId: string,
+	tools?: string[],
+	wikiArticles?: string[],
+): void {
+	try {
+		const dbResult = getFeedbackDb(mainaDir);
+		if (!dbResult.ok) return;
+		const { db } = dbResult.value;
+		const targetTools = tools ?? DEFAULT_ACCEPT_TOOLS;
+		const placeholders = targetTools.map(() => "?").join(",");
+		db.prepare(
+			`UPDATE feedback SET accepted = 1
+			 WHERE workflow_id = ?
+			 AND command IN (${placeholders})`,
+		).run(workflowId, ...targetTools);
+
+		// Record wiki effectiveness signal for loaded articles
+		if (wikiArticles && wikiArticles.length > 0) {
+			const wikiDir = join(mainaDir, "wiki");
+			recordWikiUsage(wikiDir, wikiArticles, "accept", true);
+		}
+	} catch {
+		// Never throw from signals
+	}
+}
+
+export function emitRejectSignal(
+	mainaDir: string,
+	tool: string,
+	workflowId: string,
+	wikiArticles?: string[],
+): void {
+	try {
+		const dbResult = getFeedbackDb(mainaDir);
+		if (!dbResult.ok) return;
+		const { db } = dbResult.value;
+		db.prepare(
+			`UPDATE feedback SET accepted = 0
+			 WHERE command = ? AND workflow_id = ?
+			 AND id = (
+				 SELECT id FROM feedback
+				 WHERE command = ? AND workflow_id = ?
+				 ORDER BY created_at DESC, rowid DESC LIMIT 1
+			 )`,
+		).run(tool, workflowId, tool, workflowId);
+
+		// Record wiki effectiveness signal for loaded articles
+		if (wikiArticles && wikiArticles.length > 0) {
+			const wikiDir = join(mainaDir, "wiki");
+			recordWikiUsage(wikiDir, wikiArticles, tool, false);
+		}
+	} catch {
+		// Never throw from signals
+	}
+}

package/src/index.ts

@@ -154,6 +154,12 @@ export type {
 	TraceDeps,
 } from "./features/traceability";
 export { traceFeature } from "./features/traceability";
+export {
+	buildToolCacheKey,
+	type CaptureInput,
+	captureResult,
+	getCachedResult,
+} from "./feedback/capture";
 // Feedback
 export {
 	type FeedbackRecord,
@@ -176,6 +182,7 @@ export {
 	type RulePreference,
 	savePreferences,
 } from "./feedback/preferences";
+export { emitAcceptSignal, emitRejectSignal } from "./feedback/signals";
 export {
 	exportEpisodicForCloud,
 	exportFeedbackForCloud,
@@ -287,12 +294,16 @@ export {
 	getLatest,
 	getSkipRate,
 	getStats,
+	getToolUsageStats,
 	getTrends,
 	recordSnapshot,
 	type SnapshotInput,
 	type StatsReport,
+	type ToolUsageInput,
+	type ToolUsageStats,
 	type TrendDirection,
 	type TrendsReport,
+	trackToolUsage,
 } from "./stats/tracker";
 // Ticket
 export {
@@ -427,8 +438,101 @@ export {
 	type ZapOptions,
 	type ZapResult,
 } from "./verify/zap";
+// Wiki — Compiler
+export {
+	type CompilationResult as WikiCompilationResult,
+	type CompileOptions as WikiCompileOptions,
+	compile as compileWiki,
+} from "./wiki/compiler";
+export { type CodeEntity, extractCodeEntities } from "./wiki/extractors/code";
+export {
+	extractDecisions,
+	extractSingleDecision,
+} from "./wiki/extractors/decision";
+export {
+	extractFeatures,
+	extractSingleFeature,
+} from "./wiki/extractors/feature";
+export { extractWorkflowTrace } from "./wiki/extractors/workflow";
+// Wiki — Graph
+export {
+	buildKnowledgeGraph,
+	computePageRank,
+	type GraphEdge,
+	type GraphNode,
+	type KnowledgeGraph,
+	mapToArticles,
+} from "./wiki/graph";
+// Wiki — Indexer
+export { generateIndex } from "./wiki/indexer";
+// Wiki — Linker
+export { generateLinks, type LinkResult } from "./wiki/linker";
+// Wiki — Louvain
+export {
+	detectCommunities,
+	type LouvainNode,
+	type LouvainResult,
+} from "./wiki/louvain";
+// Wiki — Query
+export {
+	queryWiki,
+	type WikiQueryOptions,
+	type WikiQueryResult,
+} from "./wiki/query";
+export {
+	DEFAULT_SCHEMA,
+	getArticleMaxLength,
+	getLinkSyntax,
+	validateArticleStructure,
+	type WikiSchema,
+} from "./wiki/schema";
+// Wiki — Signals
+export {
+	type ArticleLoadSignal,
+	type CompilationPromptSignal,
+	calculateEbbinghausScore,
+	getPromptEffectiveness,
+	getWikiEffectivenessReport,
+	recordArticlesLoaded,
+	recordWikiUsage,
+	type WikiEffectivenessReport,
+	type WikiEffectivenessSignal,
+} from "./wiki/signals";
+export {
+	createEmptyState,
+	getChangedFiles as getWikiChangedFiles,
+	hashContent,
+	hashFile,
+	loadState as loadWikiState,
+	saveState as saveWikiState,
+} from "./wiki/state";
+// Wiki — Tracking
+export {
+	trackWikiRefsRead,
+	trackWikiRefsWritten,
+} from "./wiki/tracking";
+// Wiki
+export type {
+	ArticleType,
+	DecisionStatus,
+	EdgeType,
+	ExtractedDecision,
+	ExtractedFeature,
+	ExtractedWorkflowTrace,
+	RLSignal,
+	TaskItem,
+	WikiArticle,
+	WikiLink,
+	WikiLintCheck,
+	WikiLintFinding,
+	WikiLintResult,
+	WikiState,
+	WorkflowStep as WikiWorkflowStep,
+} from "./wiki/types";
+export { DECAY_HALF_LIVES } from "./wiki/types";
 // Workflow
 export {
+	appendWikiRefs,
 	appendWorkflowStep,
 	loadWorkflowContext,
 	resetWorkflowContext,