@ultrakit/ultrakit 0.0.0

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

@@ -0,0 +1,535 @@
+/**
+ * Memory Plugin — Core Tools
+ *
+ * observation, memory-search, memory-get, memory-read, memory-update, memory-timeline,
+ * memory-graph-add, memory-graph-query, memory-graph-invalidate, memory-compact
+ *
+ * Uses factory pattern: createCoreTools(deps) returns tool definitions
+ * that can be spread into plugin's tool:{} export.
+ */
+
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import { tool } from "@opencode-ai/plugin/tool";
+import {
+	addEntityTriple,
+	type ConfidenceLevel,
+	checkFTS5Available,
+	getMemoryDB,
+	getMemoryFile,
+	getObservationsByIds,
+	getTimelineAroundObservation,
+	invalidateTriple,
+	type ObservationSource,
+	type ObservationType,
+	queryEntity,
+	searchDistillationsFTS,
+	searchObservationsFTS,
+	storeObservation,
+	upsertMemoryFile,
+	type HallType,
+	VALID_HALLS,
+} from "./memory-db.js";
+import {
+	autoDetectFiles,
+	formatObservation,
+	parseCSV,
+	safeReadFile,
+	TYPE_ICONS,
+	VALID_TYPES,
+} from "./memory-helpers.js";
+import { validateObservation } from "./validate.js";
+import { compactObservations } from "./compact.js";
+
+/**
+ * Wrap a memory tool execute function with DB error handling.
+ * Returns a user-friendly error message instead of raw SQLite crashes.
+ */
+function withDBErrorHandling<T extends Record<string, unknown>>(
+	fn: (args: T) => Promise<string>,
+): (args: T) => Promise<string> {
+	return async (args: T) => {
+		try {
+			return await fn(args);
+		} catch (err) {
+			const message =
+				err instanceof Error ? err.message : String(err);
+			if (
+				message.includes("database disk image is malformed") ||
+				message.includes("SQLITE_CORRUPT") ||
+				message.includes("integrity check failed")
+			) {
+				return (
+					`Error: Memory database is corrupted. ` +
+					`Run \`memory-admin({ operation: "full" })\` to attempt repair, ` +
+					`or delete .opencode/memory.db to start fresh. Details: ${message}`
+				);
+			}
+			return `Error: Memory operation failed: ${message}`;
+		}
+	};
+}
+
+interface CoreToolDeps {
+	handoffDir: string;
+}
+
+export function createCoreTools(deps: CoreToolDeps) {
+	const { handoffDir } = deps;
+
+	return {
+		observation: tool({
+			description: `Create a structured observation for future reference.\n\t\n\tPurpose:\n\t- Capture decisions, bugs, features, patterns, discoveries, learnings, or warnings\n\t- Auto-detects file references from content (file:line, \`path\`, src/, .opencode/)\n\t- Stores in SQLite with FTS5 index for fast search\n\t- Supports enhanced schema: facts, subtitle, files_read/files_modified\n\t\n\tConfidence guidance:\n\t- high: verified by tests, logs, or direct inspection (default)\n\t- medium: likely, but not fully verified\n\t- low: uncertain or speculative\n\t\n\tType-specific examples:\n\tdecision\n\tobservation({\n\t  type: "decision",\n\t  title: "Use JWT for auth",\n\t  narrative: "Chose JWT for stateless auth across services.",\n\t  facts: "stateless, scalable",\n\t  concepts: "authentication, jwt",\n\t  confidence: "high"\n\t})\n\t\n\tbugfix\n\tobservation({\n\t  type: "bugfix",\n\t  title: "Fix null pointer on login",\n\t  narrative: "Guarded optional user in src/auth.ts:42 to prevent crash.",\n\t  files_modified: "src/auth.ts",\n\t  concepts: "auth, null-check",\n\t  confidence: "high"\n\t})\n\t\n\tfeature\n\tobservation({\n\t  type: "feature",\n\t  title: "Add CLI --dry-run",\n\t  narrative: "Introduce dry-run mode to show planned changes without writing.",\n\t  files_modified: "src/commands/init.ts",\n\t  concepts: "cli, ux",\n\t  confidence: "medium"\n\t})\n\t\n\tpattern\n\tobservation({\n\t  type: "pattern",\n\t  title: "Use zod for input validation",\n\t  narrative: "All command inputs validated with zod schemas before execute.",\n\t  concepts: "validation, zod",\n\t  confidence: "high"\n\t})\n\t\n\tdiscovery\n\tobservation({\n\t  type: "discovery",\n\t  title: "Build copies .opencode/ to dist/template/",\n\t  narrative: "Found rsync step in build.ts that bundles .opencode/.",\n\t  files_read: "build.ts",\n\t  confidence: "high"\n\t})\n\t\n\tlearning\n\tobservation({\n\t  type: "learning",\n\t  title: "Bun test respects --watch",\n\t  narrative: "Observed bun test --watch keeps runner active during edits.",\n\t  confidence: "medium"\n\t})\n\t\n\twarning\n\tobservation({\n\t  type: "warning",\n\t  title: "Do not edit dist/ directly",\n\t  narrative: "dist/ is built output and overwritten on build.",\n\t  concepts: "build, generated",\n\t  confidence: "high"\n\t})`,
+			args: {
+				type: tool.schema
+					.string()
+					.describe(
+						"Observation type: decision, bugfix, feature, pattern, discovery, learning, warning",
+					),
+				title: tool.schema.string().describe("Brief title"),
+				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 content"),
+				content: tool.schema
+					.string()
+					.optional()
+					.describe("DEPRECATED: Use 'narrative'"),
+				concepts: tool.schema
+					.string()
+					.optional()
+					.describe("Comma-separated concept tags"),
+				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("DEPRECATED: Use 'files_modified'"),
+				bead_id: tool.schema.string().optional().describe("Related bead ID"),
+				confidence: tool.schema
+					.string()
+					.optional()
+					.describe("high, medium, low"),
+				supersedes: tool.schema
+					.string()
+					.optional()
+					.describe("ID this supersedes"),
+				source: tool.schema
+					.string()
+					.optional()
+					.describe("manual, curator, imported"),
+				wing: tool.schema
+					.string()
+					.optional()
+					.describe("Navigation wing (project or person name)"),
+				hall: tool.schema
+					.string()
+					.optional()
+					.describe("Navigation hall: facts, events, discoveries, preferences, advice"),
+				room: tool.schema
+					.string()
+					.optional()
+					.describe("Navigation room (topic name, e.g. auth-migration)"),
+				raw_source: tool.schema
+					.string()
+					.optional()
+					.describe("Verbatim source text to preserve losslessly alongside narrative"),
+			},
+			execute: withDBErrorHandling(async (args) => {
+				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 filesModifiedRaw = args.files_modified ?? args.files;
+				const facts = parseCSV(args.facts);
+				const concepts = parseCSV(args.concepts);
+				let filesRead = parseCSV(args.files_read);
+				const filesModified = parseCSV(filesModifiedRaw);
+
+				if (narrative) {
+					const detected = autoDetectFiles(narrative);
+					if (detected.length > 0) {
+						const existing = new Set([
+							...(filesRead ?? []),
+							...(filesModified ?? []),
+						]);
+						const newRefs = detected.filter((f) => !existing.has(f));
+						if (newRefs.length > 0)
+							filesRead = [...(filesRead ?? []), ...newRefs];
+					}
+				}
+
+				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;
+				if (hall && !VALID_HALLS.includes(hall)) {
+					return `Error: Invalid hall "${args.hall}". Valid: ${VALID_HALLS.join(", ")}`;
+				}
+
+				// Validation gate: check for duplicates, contradictions, low quality
+				const validation = validateObservation({
+					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,
+					wing: args.wing,
+					hall,
+					room: args.room,
+				});
+
+				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,
+					raw_source: args.raw_source,
+					concepts,
+					files_read: filesRead,
+					files_modified: filesModified,
+					confidence,
+					bead_id: args.bead_id,
+					supersedes,
+					source,
+					wing: args.wing,
+					hall,
+					room: args.room,
+				});
+
+				const warnings = validation.issues.length > 0
+					? `\n⚠️ Warnings: ${validation.issues.map(i => i.message).join("; ")}`
+					: "";
+
+				return `${TYPE_ICONS[obsType] ?? "\uD83D\uDCCC"} Observation #${id} stored [${obsType}] "${args.title}" (confidence: ${confidence}, source: ${source})${warnings}`;
+			}),
+		}),
+
+		"memory-search": tool({
+			description: `Search memory across observations and markdown archives.\n\t\n\tPurpose:\n\t- Fast, ranked search across all observations in SQLite (when FTS5 is available)\n\t- Returns compact index (~50-100 tokens per result) for progressive disclosure\n\t- Use memory-get for full details after identifying relevant observations\n\t\n\tFTS5 availability:\n\t- Auto-detected at runtime; if unavailable, observation searches fall back to file scan\n\t\n\tSearch modes and hints:\n\t- "observations" (default): Best for decisions, bugs, learnings; uses FTS5 ranking when available\n\t- "handoffs": Use for past session handoffs and summaries\n\t- "research": Use for research notes and external findings\n\t- "templates": Use for memory templates and boilerplate references\n\t- "beads": Use for task artifacts in .beads/artifacts\n\t- "all": Use when you are unsure where info lives; searches SQLite + markdown + beads\n\t\n\tExample:\n\tmemory-search({ query: "authentication" })\n\tmemory-search({ query: "auth", type: "decision", limit: 5 })`,
+			args: {
+				query: tool.schema.string().describe("Search query"),
+				type: tool.schema
+					.string()
+					.optional()
+					.describe("Filter by type or scope"),
+				limit: tool.schema
+					.number()
+					.optional()
+					.describe("Max results (default: 10)"),
+			},
+			execute: withDBErrorHandling(async (args) => {
+				const query = args.query.trim();
+				if (!query) return "Error: Empty search query";
+				const limit = args.limit ?? 10;
+				const scope = args.type ?? "observations";
+				const lines: string[] = [];
+
+				if (
+					scope === "observations" ||
+					scope === "all" ||
+					VALID_TYPES.includes(scope as ObservationType)
+				) {
+					const typeFilter = VALID_TYPES.includes(scope as ObservationType)
+						? (scope as ObservationType)
+						: undefined;
+					if (checkFTS5Available()) {
+						const results = searchObservationsFTS(query, {
+							type: typeFilter,
+							limit,
+						});
+						if (results.length > 0) {
+							lines.push(`## Observations (${results.length} results)\n`);
+							lines.push("| ID | Type | Title | Date |");
+							lines.push("|---|---|---|---|");
+							for (const r of results)
+								lines.push(
+									`| ${r.id} | ${r.type} | ${r.title} | ${r.created_at.slice(0, 10)} |`,
+								);
+							lines.push("");
+							for (const r of results.slice(0, 3)) {
+								if (r.snippet) lines.push(`**#${r.id}**: ${r.snippet}`);
+							}
+							lines.push(
+								`\nUse \`memory-get({ ids: "${results
+									.slice(0, 3)
+									.map((r) => r.id)
+									.join(",")}" })\` for full details.`,
+							);
+						} else {
+							lines.push("No observation matches found.");
+						}
+					} else {
+						lines.push("FTS5 not available. Use memory-admin to check status.");
+					}
+				}
+
+				if (scope === "distillations" || scope === "all") {
+					const distResults = searchDistillationsFTS(query, limit);
+					if (distResults.length > 0) {
+						lines.push(`\n## Distillations (${distResults.length} results)\n`);
+						for (const d of distResults) {
+							lines.push(
+								`- **Session ${d.session_id.slice(0, 8)}** (${d.message_count} msgs): ${d.snippet}`,
+							);
+						}
+					}
+				}
+
+				if (scope === "handoffs" || scope === "all") {
+					try {
+						const handoffFiles = await readdir(handoffDir);
+						const matches: string[] = [];
+						for (const f of handoffFiles.filter((n) => n.endsWith(".md"))) {
+							const content = await safeReadFile(path.join(handoffDir, f));
+							if (content.toLowerCase().includes(query.toLowerCase()))
+								matches.push(f);
+						}
+						if (matches.length > 0) {
+							lines.push(`\n## Handoffs (${matches.length} matches)\n`);
+							for (const m of matches.slice(0, 5)) lines.push(`- ${m}`);
+						}
+					} catch {
+						/* No handoffs directory */
+					}
+				}
+
+				return lines.length > 0 ? lines.join("\n") : "No results found.";
+			}),
+		}),
+
+		"memory-get": tool({
+			description: `Get full observation details by ID.\n\t\n\tPurpose:\n\t- Progressive disclosure: fetch full details after identifying relevant observations via search\n\t- Get complete narrative, facts, and metadata\n\t- Supports multiple IDs for batch retrieval\n\t\n\tExample:\n\tmemory-get({ ids: "42" })           // Single observation\n\tmemory-get({ ids: "1,5,10" })       // Multiple observations`,
+			args: {
+				ids: tool.schema.string().describe("Comma-separated observation IDs"),
+			},
+			execute: withDBErrorHandling(async (args) => {
+				const idList = args.ids
+					.split(",")
+					.map((s) => Number.parseInt(s.trim(), 10))
+					.filter((n) => !Number.isNaN(n));
+				if (idList.length === 0) return "Error: No valid IDs provided";
+				const observations = getObservationsByIds(idList);
+				if (observations.length === 0)
+					return "No observations found for given IDs.";
+				return observations
+					.map((obs) => formatObservation(obs))
+					.join("\n\n---\n\n");
+			}),
+		}),
+
+		"memory-read": tool({
+			description: `Read memory files for persistent cross-session context.\n\t\n\tPurpose:\n\t- Retrieve project state, learnings, and active tasks\n\t- Reads from SQLite database\n\t- Supports subdirectories: handoffs/, research/\n\t\n\tExample:\n\tmemory-read({ file: "handoffs/2024-01-20-phase-1" })\n\tmemory-read({ file: "research/2024-01-topic" })`,
+			args: {
+				file: tool.schema.string().optional().describe("Memory file path"),
+			},
+			execute: withDBErrorHandling(async (args) => {
+				const filePath = (args.file ?? "").replace(/\.md$/, "");
+				if (!filePath) return "Error: No file path provided";
+				const row = getMemoryFile(filePath);
+				return row ? row.content : `Memory file "${filePath}" not found.`;
+			}),
+		}),
+
+		"memory-update": tool({
+			description: `Update memory files with new learnings, progress, or context.\n\t\n\tPurpose:\n\t- Write or append to project memory in SQLite\n\t- Supports subdirectories (e.g., 'research/2024-01-topic')\n\t- Two modes: 'replace' (overwrite) or 'append' (add to end)\n\t\n\tExample:\n\tmemory-update({ file: "research/session-findings", content: "..." })\n\tmemory-update({ file: "handoffs/phase-2", content: "...", mode: "append" })`,
+			args: {
+				file: tool.schema.string().describe("Memory file to update"),
+				content: tool.schema.string().describe("Content to write or append"),
+				mode: tool.schema
+					.string()
+					.optional()
+					.describe("replace (default) or append"),
+			},
+			execute: withDBErrorHandling(async (args) => {
+				const filePath = args.file.replace(/\.md$/, "");
+				const mode = (args.mode ?? "replace") as "replace" | "append";
+				let finalContent = args.content;
+				if (mode === "append") {
+					finalContent = `\n---\n_Updated: ${new Date().toISOString()}_\n\n${args.content}`;
+				}
+				upsertMemoryFile(filePath, finalContent, mode);
+				return `Memory file "${filePath}" updated (mode: ${mode}).`;
+			}),
+		}),
+
+		"memory-timeline": tool({
+			description: `Get chronological context around an observation.\n\t\n\tPurpose:\n\t- Progressive disclosure: see what was happening before/after a specific observation\n\t- Understand decision context over time\n\t- Navigate memory timeline\n\t\n\tExample:\n\tmemory-timeline({ anchor_id: 42, depth_before: 5, depth_after: 5 })`,
+			args: {
+				anchor_id: tool.schema.number().describe("ID of the observation"),
+				depth_before: tool.schema
+					.number()
+					.optional()
+					.describe("Earlier observations (default: 5)"),
+				depth_after: tool.schema
+					.number()
+					.optional()
+					.describe("Later observations (default: 5)"),
+			},
+			execute: withDBErrorHandling(async (args) => {
+				const { anchor, before, after } = getTimelineAroundObservation(
+					args.anchor_id,
+					args.depth_before ?? 5,
+					args.depth_after ?? 5,
+				);
+				if (!anchor) return `Observation #${args.anchor_id} not found.`;
+				const lines: string[] = [];
+				if (before.length > 0) {
+					lines.push("### Earlier");
+					for (const b of before)
+						lines.push(
+							`  ${b.id}: [${b.type}] ${b.title} (${b.created_at.slice(0, 10)})`,
+						);
+				}
+				lines.push(
+					`\n### ${TYPE_ICONS[anchor.type] ?? "\uD83D\uDCCC"} Current: #${anchor.id} [${anchor.type}] ${anchor.title}`,
+				);
+				if (anchor.narrative) lines.push(anchor.narrative.slice(0, 200));
+				if (after.length > 0) {
+					lines.push("\n### Later");
+					for (const a of after)
+						lines.push(
+							`  ${a.id}: [${a.type}] ${a.title} (${a.created_at.slice(0, 10)})`,
+						);
+				}
+				return lines.join("\n");
+			}),
+		}),
+
+		"memory-graph-add": tool({
+			description: `Add a triple to the entity knowledge graph.\n\nStores a subject-predicate-object relationship with optional temporal bounds and confidence.\nUse for structured facts like "project uses typescript" or "user prefers dark-mode".\n\nExample:\nmemory-graph-add({ subject: "project", predicate: "uses", object: "typescript" })\nmemory-graph-add({ subject: "auth", predicate: "depends-on", object: "jwt", confidence: 0.9, source_observation_id: 42 })`,
+			args: {
+				subject: tool.schema.string().describe("Entity subject"),
+				predicate: tool.schema.string().describe("Relationship type (e.g. uses, depends-on, prefers)"),
+				object: tool.schema.string().describe("Entity object"),
+				valid_from: tool.schema.string().optional().describe("Start date (ISO, default: today)"),
+				valid_to: tool.schema.string().optional().describe("End date (ISO, null = still active)"),
+				confidence: tool.schema.number().optional().describe("Confidence 0.0-1.0 (default: 1.0)"),
+				source_observation_id: tool.schema.number().optional().describe("Link to source observation"),
+			},
+			execute: withDBErrorHandling(async (args) => {
+				if (!args.subject?.trim() || !args.predicate?.trim() || !args.object?.trim()) {
+					return "Error: subject, predicate, and object are required.";
+				}
+				const id = addEntityTriple({
+					subject: args.subject,
+					predicate: args.predicate,
+					object: args.object,
+					valid_from: args.valid_from,
+					valid_to: args.valid_to,
+					confidence: args.confidence,
+					source_observation_id: args.source_observation_id,
+				});
+				return `Triple #${id} added: ${args.subject} —[${args.predicate}]→ ${args.object}`;
+			}),
+		}),
+
+		"memory-graph-query": tool({
+			description: `Query the entity knowledge graph.\n\nFind relationships for an entity with optional time and direction filters.\nReturns triples where the entity appears as subject, object, or both.\n\nExample:\nmemory-graph-query({ entity: "typescript" })\nmemory-graph-query({ entity: "auth", direction: "out", active_only: true })\nmemory-graph-query({ entity: "project", as_of: "2025-06-01" })`,
+			args: {
+				entity: tool.schema.string().describe("Entity to query"),
+				direction: tool.schema.string().optional().describe("out (subject), in (object), both (default)"),
+				predicate: tool.schema.string().optional().describe("Filter by predicate"),
+				as_of: tool.schema.string().optional().describe("ISO date for point-in-time query"),
+				active_only: tool.schema.boolean().optional().describe("Only active triples (default: false)"),
+				limit: tool.schema.number().optional().describe("Max results (default: 50)"),
+			},
+			execute: withDBErrorHandling(async (args) => {
+				if (!args.entity?.trim()) return "Error: entity is required.";
+				const results = queryEntity(args.entity, {
+					direction: args.direction as "out" | "in" | "both" | undefined,
+					predicate: args.predicate,
+					as_of: args.as_of,
+					activeOnly: args.active_only,
+					limit: args.limit,
+				});
+				if (results.length === 0) return `No triples found for entity "${args.entity}".`;
+				const lines: string[] = [
+					`## Entity Graph: ${args.entity} (${results.length} triples)\n`,
+					"| ID | Subject | Predicate | Object | Active | Confidence |",
+					"|---|---|---|---|---|---|",
+				];
+				for (const r of results) {
+					lines.push(`| ${r.id} | ${r.subject} | ${r.predicate} | ${r.object} | ${r.is_active ? "\u2705" : "\u274C"} | ${(r.confidence * 100).toFixed(0)}% |`);
+				}
+				return lines.join("\n");
+			}),
+		}),
+
+		"memory-graph-invalidate": tool({
+			description: `Invalidate (close) entity triples in the knowledge graph.\n\nMarks active triples matching subject+predicate+object as no longer valid by setting valid_to.\nUse when a fact is no longer true (e.g. project stopped using a library).\n\nExample:\nmemory-graph-invalidate({ subject: "project", predicate: "uses", object: "moment.js" })`,
+			args: {
+				subject: tool.schema.string().describe("Entity subject"),
+				predicate: tool.schema.string().describe("Relationship type"),
+				object: tool.schema.string().describe("Entity object"),
+				end_date: tool.schema.string().optional().describe("End date (ISO, default: today)"),
+			},
+			execute: withDBErrorHandling(async (args) => {
+				if (!args.subject?.trim() || !args.predicate?.trim() || !args.object?.trim()) {
+					return "Error: subject, predicate, and object are required.";
+				}
+				const count = invalidateTriple(args.subject, args.predicate, args.object, args.end_date);
+				return count > 0
+					? `Invalidated ${count} triple(s): ${args.subject} —[${args.predicate}]→ ${args.object}`
+					: `No active triples found matching ${args.subject} —[${args.predicate}]→ ${args.object}.`;
+			}),
+		}),
+
+		"memory-compact": tool({
+			description: `Compact observations into a dense, token-efficient format.\n\nUses AAAK-inspired pipe-separated compression achieving ~3-5x token reduction.\nUseful for injecting memory into prompts with minimal token cost.\n\nExample:\nmemory-compact({})\nmemory-compact({ limit: 20 })`,
+			args: {
+				limit: tool.schema.number().optional().describe("Max observations to compact (default: all)"),
+			},
+			execute: withDBErrorHandling(async (args) => {
+				const db = getMemoryDB();
+				const limitClause = args.limit ? `LIMIT ${Number(args.limit)}` : "";
+				const observations = db.query(
+					`SELECT id, type, title, narrative, concepts, wing, hall, room, confidence, created_at
+					 FROM observations
+					 WHERE superseded_by IS NULL
+					 ORDER BY created_at_epoch DESC ${limitClause}`
+				).all() as { id: number; type: string; title: string; narrative?: string | null; concepts?: string | null; wing?: string | null; hall?: string | null; room?: string | null; confidence?: string | null; created_at?: string | null }[];
+				if (observations.length === 0) return "No observations to compact.";
+				const result = compactObservations(observations);
+				if (!result.compressed) return "No observations to compact.";
+				const ratio = result.compression_ratio > 0 ? ` (${(result.compression_ratio * 100).toFixed(0)}% of original)` : "";
+				return `## Compact Memory (${observations.length} observations, ~${result.token_estimate} tokens${ratio})\n\n${result.compressed}`;
+			}),
+		}),
+	};
+}

package/dist/template/.opencode/plugin/lib/notify.ts

@@ -0,0 +1,89 @@
+/**
+ * Shared notification utilities for OpenCode plugins
+ * Uses Bun's shell API ($) as recommended by official docs
+ */
+
+// Cache WSL detection result
+let _isWSL: boolean | null = null;
+
+/**
+ * Check if running in WSL (cached)
+ */
+export function isWSL(): boolean {
+  if (_isWSL !== null) return _isWSL;
+  try {
+    const fs = require("node:fs");
+    const release = fs.readFileSync("/proc/version", "utf8").toLowerCase();
+    _isWSL = release.includes("microsoft") || release.includes("wsl");
+  } catch {
+    _isWSL = false;
+  }
+  return _isWSL ?? false;
+}
+
+/**
+ * Send native notification using Bun shell API
+ * @param $ - Bun shell from plugin context
+ * @param title - Notification title
+ * @param message - Notification body
+ */
+export async function notify($: any, title: string, message: string): Promise<void> {
+  const platform = process.platform;
+
+  try {
+    if (platform === "darwin") {
+      // Escape backslashes and double quotes for AppleScript string literals
+      const escapeAS = (s: string) => (s || "").replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+      const safeTitle = escapeAS(title || "OpenCode");
+      const safeMessage = escapeAS(message || "");
+      await $`osascript -e ${`display notification "${safeMessage}" with title "${safeTitle}"`}`;
+    } else if (platform === "linux") {
+      const safeTitle = title || "OpenCode";
+      const safeMessage = message || "";
+      if (isWSL()) {
+        // WSL: try notify-send, fail silently
+        await $`notify-send ${safeTitle} ${safeMessage}`.catch(() => {});
+      } else {
+        await $`notify-send ${safeTitle} ${safeMessage}`;
+      }
+    } else if (platform === "win32") {
+      // Escape single quotes for PowerShell string literals
+      const escapePS = (s: string) => (s || "").replace(/'/g, "''");
+      const safeTitle = escapePS(title || "OpenCode");
+      const safeMessage = escapePS(message || "");
+      // Windows: PowerShell toast (fire and forget)
+      await $`powershell -Command "Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.MessageBox]::Show('${safeMessage}', '${safeTitle}')"`.catch(
+        () => {},
+      );
+    }
+  } catch {
+    // Notifications are best-effort, never throw
+  }
+}
+
+/**
+ * Threshold configuration for context monitoring
+ */
+export const THRESHOLDS = {
+  MODERATE: 70,
+  URGENT: 85,
+  CRITICAL: 95,
+} as const;
+
+/**
+ * Token statistics from session events
+ */
+export interface TokenStats {
+  used: number;
+  limit: number;
+  percentage?: number;
+}
+
+/**
+ * Calculate context percentage from token stats
+ */
+export function getContextPercentage(stats: TokenStats): number {
+  if (stats.percentage) return stats.percentage;
+  if (stats.limit > 0) return Math.round((stats.used / stats.limit) * 100);
+  return 0;
+}