opencode-starterkit 1.0.1

package/baseline/plugin/lib/memory-db.ts

@@ -0,0 +1,58 @@
+/**
+ * Memory Database Module v2 — 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".
+ *
+ * Sub-module structure:
+ *   db/types.ts        — Configuration, types, interfaces
+ *   db/schema.ts       — SQL schema, migrations, DB manager
+ *   db/observations.ts — Observation CRUD, search, timeline, stats
+ *   db/pipeline.ts     — Temporal messages, distillations, relevance scoring
+ *   db/maintenance.ts  — Memory files, FTS5, DB maintenance
+ */
+
+// Memory Files, FTS5, and Maintenance
+export {
+	archiveOldObservations,
+	checkFTS5Available,
+	checkpointWAL,
+	getDatabaseSizes,
+	getMarkdownFilesInSqlite,
+	getMemoryFile,
+	optimizeFTS5,
+	rebuildFTS5,
+	runFullMaintenance,
+	upsertMemoryFile,
+	vacuumDatabase,
+} from "./db/maintenance.js";
+// Observation Operations
+export {
+	getMostRecentObservation,
+	getObservationById,
+	getObservationStats,
+	getObservationsByIds,
+	getTimelineAroundObservation,
+	searchObservationsFTS,
+	storeObservation,
+} from "./db/observations.js";
+// Temporal Message & Distillation Operations
+export {
+	estimateTokens,
+	getCaptureStats,
+	getDistillationById,
+	getDistillationStats,
+	getRecentDistillations,
+	getRelevantKnowledge,
+	getUndistilledMessageCount,
+	getUndistilledMessages,
+	markMessagesDistilled,
+	purgeOldTemporalMessages,
+	searchDistillationsFTS,
+	storeDistillation,
+	storeTemporalMessage,
+} from "./db/pipeline.js";
+// Database Manager
+export { closeMemoryDB, getMemoryDB } from "./db/schema.js";
+// Types & Configuration
+export * from "./db/types.js";

package/baseline/plugin/lib/memory-helpers.ts

@@ -0,0 +1,111 @@
+/**
+ * Memory Plugin — Helpers
+ *
+ * Constants, tool formatting helpers, and file utilities.
+ * Pure functions — no plugin/closure dependencies.
+ */
+
+import { readFile } from "node:fs/promises";
+import type { ObservationType } from "./memory-db.js";
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+export const VALID_TYPES: ObservationType[] = [
+	"decision",
+	"bugfix",
+	"feature",
+	"pattern",
+	"discovery",
+	"learning",
+	"warning",
+];
+
+export const TYPE_ICONS: Record<string, string> = {
+	decision: "\u2696\uFE0F",
+	bugfix: "\uD83D\uDC1B",
+	feature: "\u2728",
+	pattern: "\uD83D\uDD04",
+	discovery: "\uD83D\uDD2D",
+	learning: "\uD83D\uDCDA",
+	warning: "\u26A0\uFE0F",
+};
+
+export const FILE_REF_PATTERNS = [
+	/(?:^|\s)(\S+\.(?:ts|tsx|js|jsx|json|md|yaml|yml|toml|sql|sh|py|rs|go)):(\d+)/g,
+	/`([^`]+\.(?:ts|tsx|js|jsx|json|md|yaml|yml|toml))`/g,
+	/(?:^|\s)(src\/\S+)/gm,
+	/(?:^|\s)(\.opencode\/\S+)/gm,
+];
+
+// ============================================================================
+// File Helpers
+// ============================================================================
+
+export async function safeReadFile(filePath: string): Promise<string> {
+	try {
+		return await readFile(filePath, "utf-8");
+	} catch {
+		return "";
+	}
+}
+
+// ============================================================================
+// Tool Helpers
+// ============================================================================
+
+export function autoDetectFiles(text: string): string[] {
+	const files = new Set<string>();
+	for (const pattern of FILE_REF_PATTERNS) {
+		const regex = new RegExp(pattern.source, pattern.flags);
+		let match: RegExpExecArray | null;
+		while ((match = regex.exec(text)) !== null) {
+			files.add(match[1]);
+		}
+	}
+	return [...files];
+}
+
+export function parseCSV(value: string | undefined): string[] | undefined {
+	if (!value) return undefined;
+	return value
+		.split(",")
+		.map((s) => s.trim())
+		.filter((s) => s.length > 0);
+}
+
+export function formatObservation(obs: {
+	id: number;
+	type: string;
+	title: string;
+	subtitle?: string | null;
+	confidence?: string | null;
+	concepts?: string | null;
+	files_read?: string | null;
+	files_modified?: string | null;
+	facts?: string | null;
+	narrative?: string | null;
+	bead_id?: string | null;
+	supersedes?: number | null;
+	superseded_by?: number | null;
+	source?: string | null;
+	created_at?: string | null;
+}): string {
+	const icon = TYPE_ICONS[obs.type] ?? "\uD83D\uDCCC";
+	const lines = [`${icon} **#${obs.id}** [${obs.type}] ${obs.title}`];
+	if (obs.subtitle) lines.push(`  _${obs.subtitle}_`);
+	if (obs.confidence) lines.push(`  Confidence: ${obs.confidence}`);
+	if (obs.source && obs.source !== "manual")
+		lines.push(`  Source: ${obs.source}`);
+	if (obs.concepts) lines.push(`  Concepts: ${obs.concepts}`);
+	if (obs.files_read) lines.push(`  Files read: ${obs.files_read}`);
+	if (obs.files_modified) lines.push(`  Files modified: ${obs.files_modified}`);
+	if (obs.facts) lines.push(`  Facts: ${obs.facts}`);
+	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.narrative) lines.push(`\n${obs.narrative}`);
+	if (obs.created_at) lines.push(`\n  _Created: ${obs.created_at}_`);
+	return lines.join("\n");
+}

package/baseline/plugin/lib/memory-hooks.ts

@@ -0,0 +1,195 @@
+/**
+ * Memory Plugin — Hooks
+ *
+ * All event handlers, transforms, and compaction logic.
+ * Uses factory pattern: createHooks(deps) returns hook definitions.
+ *
+ * Hook architecture (from @opencode-ai/plugin Hooks interface):
+ * - `event` — generic handler for ALL events (session.idle, message.updated, etc.)
+ * - Named hooks — separate handlers with (input, output) signature:
+ *   - "tool.execute.after", "chat.message", "experimental.chat.*", etc.
+ *
+ * Events NOT in the Hooks interface (handled via generic `event`):
+ * - session.idle, session.error, session.created, session.deleted
+ * - message.updated, message.removed, message.part.updated, message.part.removed
+ */
+
+import { captureMessageMeta, captureMessagePart } from "./capture.js";
+import { manageContext } from "./context.js";
+import { curateFromDistillations } from "./curator.js";
+import { distillSession } from "./distill.js";
+import { buildInjection } from "./inject.js";
+import {
+	checkFTS5Available,
+	checkpointWAL,
+	getDatabaseSizes,
+	optimizeFTS5,
+} from "./memory-db.js";
+
+interface HookDeps {
+	showToast: (
+		title: string,
+		message: string,
+		variant?: "info" | "warning",
+	) => Promise<void>;
+	log: (message: string, level?: "info" | "warn") => Promise<void>;
+}
+
+export function createHooks(deps: HookDeps) {
+	const { showToast, log } = deps;
+
+	return {
+		// ================================================================
+		// Generic event handler — ALL events route through here
+		// Receives: { event: { type, properties? } }
+		// ================================================================
+		event: async (input: unknown) => {
+			const { event } = input as {
+				event: {
+					type?: string;
+					properties?: Record<string, unknown>;
+				};
+			};
+			if (!event?.type) return;
+
+			// --- Message capture ---
+			if (event.type === "message.updated") {
+				try {
+					captureMessageMeta(
+						event.properties as Parameters<typeof captureMessageMeta>[0],
+					);
+				} catch {
+					/* Non-fatal */
+				}
+			}
+
+			if (event.type === "message.part.updated") {
+				try {
+					captureMessagePart(
+						event.properties as Parameters<typeof captureMessagePart>[0],
+					);
+				} catch {
+					/* Non-fatal */
+				}
+			}
+
+			// --- Session idle: distill + curate + optimize ---
+			if (event.type === "session.idle") {
+				const sessionId =
+					(event.properties as { sessionID?: string })?.sessionID ??
+					(event as unknown as { sessionID?: string })?.sessionID;
+				try {
+					if (sessionId) distillSession(sessionId);
+					curateFromDistillations(sessionId, 5);
+					if (checkFTS5Available()) optimizeFTS5();
+					const sizes = getDatabaseSizes();
+					if (sizes.wal > 1024 * 1024) checkpointWAL();
+				} catch (err) {
+					const msg = err instanceof Error ? err.message : String(err);
+					await log(`Idle maintenance failed: ${msg}`, "warn");
+				}
+			}
+
+			// --- Session error: show actual error details ---
+			if (event.type === "session.error") {
+				const props = event.properties as Record<string, unknown> | undefined;
+				const errorMsg = props?.error
+					? String(props.error).slice(0, 120)
+					: props?.message
+						? String(props.message).slice(0, 120)
+						: "Unknown error";
+
+				// Classify: match the specific AI SDK error pattern
+				const isTokenOverflow =
+					/token.{0,20}(exceed|limit)/i.test(errorMsg) ||
+					errorMsg.includes("context_length_exceeded");
+				const guidance = isTokenOverflow
+					? "Context too large — use /compact or start a new session"
+					: "Save important learnings with observation tool";
+
+				await showToast("Session Error", `${guidance} (${errorMsg})`, "warning");
+			}
+		},
+
+		// ================================================================
+		// Named hook: tool.execute.after
+		// Receives: (input: { tool, sessionID, callID, args }, output: { title, output, metadata })
+		// ================================================================
+		"tool.execute.after": async (input: {
+			tool?: string;
+			sessionID?: string;
+		}) => {
+			try {
+				if (input.tool === "observation" && typeof showToast === "function") {
+					await showToast("Saved", "Observation added to memory");
+				}
+			} catch {
+				/* Toast is cosmetic, never block tool execution */
+			}
+		},
+
+		// ================================================================
+		// LTM injection into system prompt
+		// ================================================================
+		"experimental.chat.system.transform": async (
+			_input: unknown,
+			output: { system: string[] },
+		) => {
+			try {
+				const injection = buildInjection(output.system);
+				if (injection) output.system.push(injection);
+			} catch {
+				/* Non-fatal */
+			}
+		},
+
+		// ================================================================
+		// Context window management
+		// ================================================================
+		"experimental.chat.messages.transform": async (
+			_input: unknown,
+			output: { messages: unknown[] },
+		) => {
+			try {
+				// eslint-disable-next-line @typescript-eslint/no-explicit-any
+				output.messages = manageContext(output.messages as any) as any;
+			} catch {
+				/* Non-fatal */
+			}
+		},
+
+		// ================================================================
+		// Compaction — inject session continuity context
+		// Receives: (input: { sessionID }, output: { context, prompt? })
+		// ================================================================
+		"experimental.session.compacting": async (
+			_input: { sessionID?: string },
+			output: { context: string[]; prompt?: string },
+		) => {
+			// No context injection here — the session is already at the
+			// model limit when compaction fires. Only append prompt guidance.
+			output.prompt = `${output.prompt ?? ""}
+
+<compaction_task>
+Summarize conversation state for reliable continuation after compaction.
+</compaction_task>
+
+<compaction_rules>
+- Preserve exact IDs, file paths, and unresolved constraints.
+- Distinguish completed work from current in-progress work.
+- Keep summary concise and execution-focused.
+- If critical context is missing, state uncertainty explicitly.
+</compaction_rules>
+
+<compaction_output>
+Include:
+- What was done
+- What is being worked on now
+- Files currently in play
+- Next actions
+- Persistent user constraints/preferences
+</compaction_output>
+`;
+		},
+	};
+}