opencodekit 0.21.10 → 0.22.0

package/dist/template/.opencode/plugin/{lib → memory}/capture.ts

@@ -18,7 +18,7 @@ import {
 	getMemoryDB,
 	MEMORY_CONFIG,
 	type TemporalMessageInput,
-} from "./memory-db.js";
+} from "./db.js";
 
 // ============================================================================
 // Types

package/dist/template/.opencode/plugin/{lib → memory}/compile.ts

@@ -17,8 +17,8 @@
 
 import { upsertMemoryFile } from "./db/maintenance.js";
 import type { ObservationRow } from "./db/types.js";
-import { getMemoryDB } from "./memory-db.js";
-import { TYPE_ICONS, parseConcepts } from "./memory-helpers.js";
+import { getMemoryDB } from "./db.js";
+import { TYPE_ICONS, parseConcepts } from "./helpers.js";
 import { appendOperationLog } from "./operation-log.js";
 
 // ============================================================================

package/dist/template/.opencode/plugin/{lib → memory}/context.ts

@@ -7,7 +7,7 @@
  * Protects the most recent N messages from compression.
  */
 
-import { estimateTokens, MEMORY_CONFIG } from "./memory-db.js";
+import { estimateTokens, MEMORY_CONFIG } from "./db.js";
 
 // ============================================================================
 // Types

package/dist/template/.opencode/plugin/{lib → memory}/curator.ts

@@ -15,7 +15,7 @@ import {
 	type ObservationInput,
 	type ObservationType,
 	storeObservation,
-} from "./memory-db.js";
+} from "./db.js";
 
 // ============================================================================
 // Pattern Definitions

package/dist/template/.opencode/plugin/{lib → memory}/db/observations.ts

@@ -7,6 +7,7 @@
 
 import { getMemoryDB } from "./schema.js";
 import type {
+	FeedbackEvent,
 	ObservationInput,
 	ObservationRow,
 	ObservationType,
@@ -19,8 +20,7 @@ import type {
 
 /**
  * Store a new observation in the database.
- */
-export function storeObservation(input: ObservationInput): number {
+ */	export function storeObservation(input: ObservationInput): number {
 	const db = getMemoryDB();
 	const now = new Date();
 
@@ -31,8 +31,10 @@ export function storeObservation(input: ObservationInput): number {
       type, title, subtitle, facts, narrative, raw_source, concepts,
       files_read, files_modified, confidence, bead_id,
       supersedes, markdown_file, source, wing, hall, room,
+      helpful_count, harmful_count, feedback_events, effective_score,
+      maturity, retrieval_count, last_retrieved,
       created_at, created_at_epoch
-    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `,
 		)
 		.run(
@@ -53,6 +55,13 @@ export function storeObservation(input: ObservationInput): number {
 			input.wing ?? null,
 			input.hall ?? null,
 			input.room ?? null,
+			0, // helpful_count
+			0, // harmful_count
+			null, // feedback_events
+			0.0, // effective_score
+			"candidate", // maturity
+			0, // retrieval_count
+			null, // last_retrieved
 			now.toISOString(),
 			now.getTime(),
 		);
@@ -302,3 +311,93 @@ export function getObservationStats(): Record<string, number> {
 	}
 	return stats;
 }
+
+// ============================================================================
+// Feedback & Tracking (aligned with pikit memory extension)
+// ============================================================================
+
+/**
+ * Record feedback (helpful/harmful) on an observation.
+ */
+export function recordFeedback(
+	observationId: number,
+	feedbackType: "helpful" | "harmful",
+	reason?: string,
+	sessionId?: string,
+): {
+	success: boolean;
+	helpfulCount: number;
+	harmfulCount: number;
+	error?: string;
+} {
+	const db = getMemoryDB();
+
+	const row = db
+		.query("SELECT * FROM observations WHERE id = ?")
+		.get(observationId) as ObservationRow | undefined;
+
+	if (!row) {
+		return {
+			success: false,
+			helpfulCount: 0,
+			harmfulCount: 0,
+			error: `Observation #${observationId} not found`,
+		};
+	}
+
+	// Parse existing feedback events
+	let events: FeedbackEvent[] = [];
+	try {
+		events = row.feedback_events ? JSON.parse(row.feedback_events) : [];
+	} catch {
+		events = [];
+	}
+
+	// Append new event
+	const newEvent: FeedbackEvent = {
+		type: feedbackType,
+		timestamp: Date.now(),
+		reason,
+		session_id: sessionId,
+	};
+	events.push(newEvent);
+
+	const helpfulCount =
+		feedbackType === "helpful" ? row.helpful_count + 1 : row.helpful_count;
+	const harmfulCount =
+		feedbackType === "harmful" ? row.harmful_count + 1 : row.harmful_count;
+
+	// Persist
+	db.run(
+		`UPDATE observations SET
+			helpful_count = ?,
+			harmful_count = ?,
+			feedback_events = ?,
+			updated_at = ?
+		WHERE id = ?`,
+		[
+			helpfulCount,
+			harmfulCount,
+			JSON.stringify(events),
+			new Date().toISOString(),
+			observationId,
+		],
+	);
+
+	return { success: true, helpfulCount, harmfulCount };
+}
+
+/**
+ * Increment retrieval_count and update last_retrieved for given observation IDs.
+ */
+export function markObservationsRetrieved(ids: number[]): void {
+	if (ids.length === 0) return;
+	const db = getMemoryDB();
+	const now = new Date().toISOString();
+	const stmt = db.query(
+		`UPDATE observations SET retrieval_count = retrieval_count + 1, last_retrieved = ? WHERE id = ?`,
+	);
+	for (const id of ids) {
+		stmt.run(now, id);
+	}
+}

package/dist/template/.opencode/plugin/{lib → memory}/db/schema.ts

@@ -126,7 +126,7 @@ function logRecovery(message: string): void {
 // Schema v3 (v2 + navigation, entity graph, raw source, chunk type)
 // ============================================================================
 
-const SCHEMA_VERSION = 3;
+const SCHEMA_VERSION = 4;
 
 const SCHEMA_SQL = `
 -- Schema versioning for migrations
@@ -158,6 +158,13 @@ CREATE TABLE IF NOT EXISTS observations (
   wing TEXT,
   hall TEXT CHECK(hall IS NULL OR hall IN ('facts','events','discoveries','preferences','advice')),
   room TEXT,
+  helpful_count INTEGER NOT NULL DEFAULT 0,
+  harmful_count INTEGER NOT NULL DEFAULT 0,
+  feedback_events TEXT,
+  effective_score REAL DEFAULT 0,
+  maturity TEXT DEFAULT 'active',
+  retrieval_count INTEGER DEFAULT 0,
+  last_retrieved TEXT,
   created_at TEXT NOT NULL,
   created_at_epoch INTEGER NOT NULL,
   updated_at TEXT,
@@ -610,6 +617,9 @@ function initializeSchema(db: Database): void {
 		if (currentVersion < 3) {
 			migrateV2ToV3(db);
 		}
+		if (currentVersion < 4) {
+			migrateV3ToV4(db);
+		}
 	}
 
 	// Record schema version
@@ -685,3 +695,35 @@ function migrateV2ToV3(db: Database): void {
 		}
 	}
 }
+
+// ============================================================================
+// Schema v4: Pikit alignment — feedback, scoring, and tracking columns
+// ============================================================================
+
+const MIGRATION_V3_TO_V4 = `
+ALTER TABLE observations ADD COLUMN helpful_count INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE observations ADD COLUMN harmful_count INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE observations ADD COLUMN feedback_events TEXT;
+ALTER TABLE observations ADD COLUMN effective_score REAL DEFAULT 0;
+ALTER TABLE observations ADD COLUMN maturity TEXT DEFAULT 'active';
+ALTER TABLE observations ADD COLUMN retrieval_count INTEGER DEFAULT 0;
+ALTER TABLE observations ADD COLUMN last_retrieved TEXT;
+`;
+
+/**
+ * Migrate from schema v3 to v4.
+ * Adds: helpful_count, harmful_count, feedback_events, effective_score,
+ *       maturity, retrieval_count, last_retrieved.
+ */
+function migrateV3ToV4(db: Database): void {
+	for (const stmt of MIGRATION_V3_TO_V4.split(";")) {
+		const trimmed = stmt.trim();
+		if (trimmed) {
+			try {
+				db.run(trimmed);
+			} catch {
+				// Statement may fail if already applied (e.g. column exists)
+			}
+		}
+	}
+}

package/dist/template/.opencode/plugin/{lib → memory}/db/types.ts

@@ -145,6 +145,13 @@ export interface ObservationRow {
 	wing: string | null; // v3: navigation wing (project/person)
 	hall: HallType | null; // v3: navigation hall (facts/events/...)
 	room: string | null; // v3: navigation room (topic)
+	helpful_count: number;
+	harmful_count: number;
+	feedback_events: string | null; // JSON array of FeedbackEvent
+	effective_score: number | null;
+	maturity: string | null;
+	retrieval_count: number | null;
+	last_retrieved: string | null;
 	created_at: string;
 	created_at_epoch: number;
 	updated_at: string | null;
@@ -282,3 +289,18 @@ export interface ArchiveOptions {
 	/** Dry run — don't actually archive, just count */
 	dryRun?: boolean;
 }
+
+// ============================================================================
+// Feedback & Scoring Types (aligned with pikit memory extension)
+// ============================================================================
+
+export type FeedbackType = "helpful" | "harmful";
+
+export interface FeedbackEvent {
+	type: FeedbackType;
+	timestamp: number; // Date.now()
+	reason?: string;
+	session_id?: string;
+}
+
+export type MaturityState = "candidate" | "active" | "stale" | "deprecated";

package/dist/template/.opencode/plugin/{lib/memory-db.ts → memory/db.ts}

@@ -2,7 +2,7 @@
  * Memory Database Module v3 — Barrel Export
  *
  * Re-exports all functions and types from sub-modules in ./db/.
- * This preserves backward compatibility for existing imports from "./lib/memory-db.js".
+ * This preserves backward compatibility for existing imports from "./db.js".
  *
  * Sub-module structure:
  *   db/types.ts        — Configuration, types, interfaces

package/dist/template/.opencode/plugin/{lib → memory}/distill.ts

@@ -16,7 +16,7 @@ import {
 	markMessagesDistilled,
 	storeDistillation,
 	type TemporalMessageRow,
-} from "./memory-db.js";
+} from "./db.js";
 
 // ============================================================================
 // TF-IDF Engine

package/dist/template/.opencode/plugin/{lib/memory-helpers.ts → memory/helpers.ts}

@@ -6,7 +6,7 @@
  */
 
 import { readFile } from "node:fs/promises";
-import type { ObservationType } from "./memory-db.js";
+import type { ObservationType } from "./db.js";
 
 // ============================================================================
 // Constants
@@ -120,6 +120,8 @@ export function formatObservation(obs: {
 	supersedes?: number | null;
 	superseded_by?: number | null;
 	source?: string | null;
+	helpful_count?: number | null;
+	harmful_count?: number | null;
 	created_at?: string | null;
 }): string {
 	const icon = TYPE_ICONS[obs.type] ?? "\uD83D\uDCCC";
@@ -135,6 +137,8 @@ export function formatObservation(obs: {
 	if (obs.bead_id) lines.push(`  Bead: ${obs.bead_id}`);
 	if (obs.supersedes) lines.push(`  Supersedes: #${obs.supersedes}`);
 	if (obs.superseded_by) lines.push(`  Superseded by: #${obs.superseded_by}`);
+	if ((obs.helpful_count ?? 0) > 0 || (obs.harmful_count ?? 0) > 0)
+		lines.push(`  Feedback: ${obs.helpful_count ?? 0}\uD83D\uDC4D / ${obs.harmful_count ?? 0}\uD83D\uDC4E`);
 	if (obs.narrative) lines.push(`\n${obs.narrative}`);
 	if (obs.created_at) lines.push(`\n  _Created: ${obs.created_at}_`);
 	return lines.join("\n");

package/dist/template/.opencode/plugin/{lib/memory-hooks.ts → memory/hooks.ts}

@@ -26,7 +26,7 @@ import {
 	checkpointWAL,
 	getDatabaseSizes,
 	optimizeFTS5,
-} from "./memory-db.js";
+} from "./db.js";
 
 interface HookDeps {
 	showToast: (

package/dist/template/.opencode/plugin/{lib → memory}/index-generator.ts

@@ -10,8 +10,8 @@
 
 import { upsertMemoryFile } from "./db/maintenance.js";
 import type { ObservationRow } from "./db/types.js";
-import { getMemoryDB } from "./memory-db.js";
-import { TYPE_ICONS, parseConcepts } from "./memory-helpers.js";
+import { getMemoryDB } from "./db.js";
+import { TYPE_ICONS, parseConcepts } from "./helpers.js";
 
 // ============================================================================
 // Types

package/dist/template/.opencode/plugin/{lib → memory}/inject.ts

@@ -13,7 +13,7 @@ import {
 	estimateTokens,
 	getRelevantKnowledge,
 	MEMORY_CONFIG,
-} from "./memory-db.js";
+} from "./db.js";
 
 // ============================================================================
 // Query Term Extraction

package/dist/template/.opencode/plugin/{lib → memory}/lint.ts

@@ -9,8 +9,8 @@
  */
 
 import type { ObservationRow } from "./db/types.js";
-import { getMemoryDB } from "./memory-db.js";
-import { hasWord, parseConcepts } from "./memory-helpers.js";
+import { getMemoryDB } from "./db.js";
+import { hasWord, parseConcepts } from "./helpers.js";
 
 // ============================================================================
 // Types

package/dist/template/.opencode/plugin/memory/tools.ts

@@ -0,0 +1,322 @@
+/**
+ * Core Memory Tools
+ *
+ * Two tools aligned with pikit memory extension:
+ * - observation: create observations OR give feedback on existing ones
+ * - memory-search: search observations by text OR read memory files by path
+ */
+
+import { tool, type ToolContext } from "@opencode-ai/plugin/tool";
+import {
+	type ConfidenceLevel,
+	type ObservationSource,
+	type ObservationType,
+	type HallType,
+	VALID_HALLS,
+} from "./db/types.js";
+import {
+	autoDetectFiles,
+	parseCSV,
+	formatObservation,
+	TYPE_ICONS,
+	VALID_TYPES,
+} from "./helpers.js";
+import { validateObservation } from "./validate.js";
+import {
+	storeObservation,
+	getObservationById,
+	searchObservationsFTS,
+	recordFeedback,
+	markObservationsRetrieved,
+} from "./db/observations.js";
+import { getMemoryFile } from "./db/maintenance.js";
+
+// ============================================================================
+// Error Handling Wrapper
+// ============================================================================
+
+function withDBErrorHandling<T extends Record<string, unknown>>(
+	handler: (args: T) => string | Promise<string>,
+): (args: T, context: ToolContext) => Promise<string> {
+	return async (args: T, _context: ToolContext) => {
+		try {
+			return await handler(args);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			return `Error: ${msg}`;
+		}
+	};
+}
+
+// ============================================================================
+// Tool Definitions
+// ============================================================================
+
+interface CoreToolDeps {
+	handoffDir: string;
+}
+
+export function createCoreTools(deps: CoreToolDeps) {
+	const { handoffDir } = deps;
+
+	return {
+		// --------------------------------------------------------------------
+		// observation: Create or give feedback
+		// --------------------------------------------------------------------
+		observation: tool({
+			description: `Create a durable observation for future retrieval, or mark an existing one as helpful/harmful.
+Pass id+feedback for feedback mode; pass type+title for create mode.
+
+Create mode captures decisions, bugs, features, patterns, discoveries, learnings, or warnings.
+Feedback mode lets you rate past observations.
+
+Create mode examples:
+  observation({ type: "decision", title: "Use JWT for auth", narrative: "Stateless across services.", confidence: "high" })
+  observation({ type: "bugfix", title: "Fix null pointer", files_modified: "src/auth.ts" })
+
+Feedback mode examples:
+  observation({ id: 42, feedback: "helpful" })
+  observation({ id: 42, feedback: "harmful", reason: "Outdated information" })`,
+			args: {
+				// --- Create mode params ---
+				type: tool.schema
+					.string()
+					.optional()
+					.describe(
+						"Observation type for create mode: decision, bugfix, feature, pattern, discovery, learning, warning",
+					),
+				title: tool.schema.string().optional().describe("Short title (create mode)"),
+				subtitle: tool.schema.string().optional().describe("Optional subtitle"),
+				facts: tool.schema
+					.string()
+					.optional()
+					.describe("Comma-separated key facts"),
+				narrative: tool.schema
+					.string()
+					.optional()
+					.describe("Detailed context"),
+				content: tool.schema
+					.string()
+					.optional()
+					.describe("Alias for narrative"),
+				concepts: tool.schema
+					.string()
+					.optional()
+					.describe("Comma-separated concepts"),
+				files_read: tool.schema
+					.string()
+					.optional()
+					.describe("Comma-separated files read"),
+				files_modified: tool.schema
+					.string()
+					.optional()
+					.describe("Comma-separated files modified"),
+				files: tool.schema
+					.string()
+					.optional()
+					.describe("Alias for files_modified"),
+				bead_id: tool.schema.string().optional().describe("Related bead ID"),
+				confidence: tool.schema
+					.string()
+					.optional()
+					.describe("high, medium, or low"),
+				supersedes: tool.schema
+					.string()
+					.optional()
+					.describe("Observation ID this supersedes"),
+				source: tool.schema
+					.string()
+					.optional()
+					.describe("manual, curator, or imported"),
+				hall: tool.schema
+					.string()
+					.optional()
+					.describe("Navigation hall: facts, events, discoveries, preferences, advice"),
+
+				// --- Feedback mode params ---
+				id: tool.schema
+					.number()
+					.optional()
+					.describe("Observation ID for feedback mode"),
+				feedback: tool.schema
+					.string()
+					.optional()
+					.describe('"helpful" or "harmful" (feedback mode)'),
+				reason: tool.schema
+					.string()
+					.optional()
+					.describe("Optional reason for feedback"),
+			},
+			execute: withDBErrorHandling(async (args) => {
+				// --- Feedback mode: observation #id marked helpful/harmful ---
+				if (args.id !== undefined && args.feedback !== undefined) {
+					const obsId = Number(args.id);
+					if (!Number.isInteger(obsId)) return "❌ id must be an integer.";
+					const fb = String(args.feedback);
+					if (fb !== "helpful" && fb !== "harmful") return '❌ feedback must be "helpful" or "harmful".';
+
+					const result = recordFeedback(obsId, fb, args.reason as string | undefined);
+					if (!result.success) return `❌ ${result.error ?? "Failed to record feedback."}`;
+
+					return [
+						`✅ Observation #${obsId} marked as ${fb}.`,
+						`- Feedback: ${result.helpfulCount} helpful / ${result.harmfulCount} harmful`,
+					].join("\n");
+				}
+
+				// --- Create mode: store a new observation ---
+				if (!args.type || !args.title) {
+					return "❌ Provide type+title to create an observation, or id+feedback to give feedback.";
+				}
+
+				const obsType = args.type as ObservationType;
+				if (!VALID_TYPES.includes(obsType)) {
+					return `Error: Invalid type "${args.type}". Valid: ${VALID_TYPES.join(", ")}`;
+				}
+
+				const confidence = (args.confidence ?? "high") as ConfidenceLevel;
+				if (!["high", "medium", "low"].includes(confidence)) {
+					return `Error: Invalid confidence "${args.confidence}". Valid: high, medium, low`;
+				}
+
+				const narrative = args.narrative ?? args.content;
+				const facts = parseCSV(args.facts);
+				const concepts = parseCSV(args.concepts);
+				let filesRead = parseCSV(args.files_read);
+				const filesModified = parseCSV(args.files_modified ?? args.files);
+
+				// Auto-detect files from narrative if not explicitly provided
+				if (!filesRead && narrative) {
+					const detected = autoDetectFiles(narrative);
+					if (detected.length > 0) filesRead = detected;
+				}
+
+				let supersedes: number | undefined;
+				if (args.supersedes) {
+					const parsed = Number.parseInt(args.supersedes, 10);
+					if (!Number.isNaN(parsed)) supersedes = parsed;
+				}
+
+				const source = (args.source ?? "manual") as ObservationSource;
+				const hall = args.hall as HallType | undefined;
+
+				// Validation gate: check for duplicates, contradictions, low quality
+				const validation = validateObservation({
+					type: obsType,
+					title: args.title,
+					facts,
+					narrative,
+					concepts,
+					confidence,
+				});
+
+				if (validation.verdict === "reject") {
+					const reasons = validation.issues.map(i => i.message).join("; ");
+					const dupHint = validation.duplicateOf
+						? ` Use \`observation({ supersedes: "${validation.duplicateOf}", ... })\` to update it.`
+						: "";
+					return `Rejected: ${reasons}.${dupHint}`;
+				}
+
+				const id = storeObservation({
+					type: obsType,
+					title: args.title,
+					subtitle: args.subtitle,
+					facts,
+					narrative,
+					concepts,
+					files_read: filesRead,
+					files_modified: filesModified,
+					confidence,
+					bead_id: args.bead_id,
+					supersedes,
+					source,
+					hall,
+				});
+
+				const warnings = validation.issues.length > 0
+					? `\n⚠️ Warnings: ${validation.issues.map(i => i.message).join("; ")}`
+					: "";
+
+				return `${TYPE_ICONS[obsType] ?? "📌"} Observation #${id} stored [${obsType}] "${args.title}" (confidence: ${confidence}, source: ${source})${warnings}`;
+			}),
+		}),
+
+		// --------------------------------------------------------------------
+		// memory-search: Search or read memory
+		// --------------------------------------------------------------------
+		"memory-search": tool({
+			description: `Search observations by text query / #id references, or read a memory file by path.
+Pass file=path to read a memory file; pass query=text to search observations.
+
+Search modes:
+- query only: Search observations using FTS5 (falls back to LIKE)
+- query + type: Filter observations by type (decision, bugfix, etc.)
+- file=path: Read a memory file (e.g. persona/default, scenes/<id>)
+- #id refs: Lookup observations by ID number`,
+			args: {
+				query: tool.schema
+					.string()
+					.optional()
+					.describe("Search query or #id references"),
+				type: tool.schema
+					.string()
+					.optional()
+					.describe("Optional observation type filter"),
+				limit: tool.schema
+					.number()
+					.optional()
+					.describe("Maximum results, default 10"),
+				file: tool.schema
+					.string()
+					.optional()
+					.describe("Memory file path (e.g. persona/default, scenes/<id>)"),
+			},
+			execute: withDBErrorHandling(async (args) => {
+				const limit = Math.min(args.limit ?? 10, 50);
+
+				// --- File mode: read a memory file by path ---
+				if (args.file) {
+					const filePath = String(args.file);
+					const row = getMemoryFile(filePath);
+					if (!row) return `Memory file not found: ${filePath}`;
+					return row.content;
+				}
+
+				// --- ID refs mode: resolve #N references ---
+				if (args.query) {
+					const query = String(args.query);
+					const idRefs = [...query.matchAll(/#(\d+)/g)].map(m => parseInt(m[1], 10));
+					if (idRefs.length > 0) {
+						const rows = idRefs
+							.map(id => getObservationById(id))
+							.filter((r): r is NonNullable<typeof r> => r !== null);
+						if (rows.length === 0) return "No observations found for the requested IDs.";
+						return rows.map(r => formatObservation(r)).join("\n\n---\n\n");
+					}
+				}
+
+				// --- Search mode ---
+				const query = args.query ? String(args.query).trim() : "";
+				const scope = (args.type ?? "observations") as string;
+				const typeFilter = VALID_TYPES.includes(scope as ObservationType)
+					? (scope as ObservationType)
+					: undefined;
+
+				let rows;
+				try {
+					rows = searchObservationsFTS(query, { type: typeFilter, limit });
+				} catch {
+					return "Search failed.";
+				}
+
+				if (rows.length === 0) return "No matching observations found.";
+
+				// Track retrieval
+				markObservationsRetrieved(rows.map(r => r.id));
+
+				return rows.map(r => formatObservation(r)).join("\n\n---\n\n");
+			}),
+		}),
+	};
+}