opencodekit 0.21.10 → 0.23.0

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");
+			}),
+		}),
+	};
+}

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

@@ -14,8 +14,8 @@
  */
 
 import type { ObservationInput, ObservationRow } from "./db/types.js";
-import { getMemoryDB } from "./memory-db.js";
-import { hasWord } from "./memory-helpers.js";
+import { getMemoryDB } from "./db.js";
+import { hasWord } from "./helpers.js";
 import { appendOperationLog } from "./operation-log.js";
 
 // ============================================================================

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

@@ -10,29 +10,19 @@
  * 4. LTM Injection — system.transform → relevance-scored knowledge
  * 5. Context Management — messages.transform → token budget enforcement
  *
- * Tools: observation, memory-search, memory-get, memory-read,
- *        memory-update, memory-timeline, memory-graph-add, memory-graph-query,
- *        memory-graph-invalidate, memory-compact, memory-admin
+ * Tools: observation, memory-search, memory-admin
  *
  * Module structure:
  *   memory.ts              — Plugin entry (this file)
- *   lib/memory-helpers.ts  — Constants, compaction utilities, formatting
- *   lib/memory-tools.ts    — Core tools (observation, search, get, read, update, timeline)
- *   lib/memory-admin-tools.ts — Admin tools (memory-admin)
- *   lib/memory-hooks.ts    — Event hooks, transforms, compaction
- *   lib/memory-db.ts       — Database barrel (re-exports from lib/db/*.ts)
- *   lib/capture.ts         — Message capture module
- *   lib/distill.ts         — Heuristic distillation engine
- *   lib/curator.ts         — Pattern-based knowledge extraction
- *   lib/inject.ts          — LTM relevance scoring + injection
- *   lib/context.ts         — Context window management
- */
+ *   memory/tools.ts         — Core tools (observation, memory-search)
+ *   memory/admin.ts         — Admin tools (memory-admin)
+ *   memory/hooks.ts         — Event hooks, transforms, compaction */
 
 import path from "node:path";
 import type { Plugin } from "@opencode-ai/plugin";
-import { createAdminTools } from "./lib/memory-admin-tools.js";
-import { createHooks } from "./lib/memory-hooks.js";
-import { createCoreTools } from "./lib/memory-tools.js";
+import { createAdminTools } from "./memory/admin.js";
+import { createHooks } from "./memory/hooks.js";
+import { createCoreTools } from "./memory/tools.js";
 
 // ============================================================================
 // Plugin Export