opencodekit 0.17.13 → 0.18.1

package/dist/template/.opencode/package.json

@@ -11,7 +11,7 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "1.2.10"
+    "@opencode-ai/plugin": "1.2.15"
   },
   "devDependencies": {
     "@types/node": "^25.3.0",

package/dist/template/.opencode/plugin/README.md

@@ -6,36 +6,48 @@ Plugins in this directory extend OpenCode with project-specific behavior and too
 
 ```text
 plugin/
-├── memory.ts           # Memory DB maintenance + observation toasts
-├── sessions.ts         # Session tools (list/read/search/summarize)
-├── compaction.ts       # Compaction-time context recovery injection
-├── swarm-enforcer.ts   # Beads workflow enforcement and reminders
-├── skill-mcp.ts        # Skill-scoped MCP bridge (skill_mcp tools)
+├── memory.ts           # 4-tier automated memory system (capture → distill → curate → inject)
+├── sessions.ts         # Session search tools (find/read)
 ├── copilot-auth.ts     # GitHub Copilot provider/auth integration
-├── lib/
-│   ├── memory-db.ts    # SQLite + FTS5 memory backend
-│   └── notify.ts       # Shared notification helpers
-└── sdk/                # Copilot SDK adaptation code
+├── skill-mcp.ts        # Skill-scoped MCP bridge (skill_mcp tools)
+└── lib/
+    ├── memory-tools.ts       # 6 core memory tools (observation, search, get, read, update, timeline)
+    ├── memory-admin-tools.ts # Admin tool (memory-admin: 9 operations)
+    ├── memory-hooks.ts       # All hooks (event, idle, transforms, compaction)
+    ├── memory-helpers.ts     # Constants, compaction utilities, formatting
+    ├── memory-db.ts          # Barrel re-export for db/ modules
+    ├── capture.ts            # message.part.updated → temporal_messages
+    ├── distill.ts            # TF-IDF extraction, key sentence selection
+    ├── curator.ts            # Pattern-based knowledge extraction
+    ├── context.ts            # Token budget enforcement via messages.transform
+    ├── inject.ts             # Relevance-scored LTM injection via system.transform
+    ├── notify.ts             # Cross-platform notification helpers
+    └── db/
+        ├── types.ts          # All types + MEMORY_CONFIG
+        ├── schema.ts         # SQL schema, migrations, DB singleton
+        ├── observations.ts   # Observation CRUD + FTS5 search
+        ├── pipeline.ts       # Temporal messages + distillations + relevance scoring
+        └── maintenance.ts    # Memory files, FTS5, archiving, vacuum
 ```
 
 ## Plugin Responsibilities
 
 - `memory.ts`
-  - Optimizes FTS5 index on idle sessions
-  - Checkpoints WAL when needed
-  - Shows toast feedback for observation saves and session errors
+  - 4-tier automated knowledge system: temporal_messages → distillations → observations → memory_files
+  - Captures messages automatically via `message.part.updated` events
+  - Distills sessions on idle (TF-IDF, key sentence extraction)
+  - Curates observations from distillations via pattern matching
+  - Injects relevant knowledge into system prompt (BM25 _ recency _ confidence scoring)
+  - Manages context window via messages.transform (token budget enforcement)
+  - Merges compaction logic (beads, handoffs, project memory, knowledge)
+  - Provides 7 tools: observation, memory-search, memory-get, memory-read, memory-update, memory-timeline, memory-admin
 
 - `sessions.ts`
-  - Provides custom tools: `list_sessions`, `read_session`, `search_session`, `summarize_session`
-
-- `compaction.ts`
-  - Injects session continuity context during compaction
-  - Pulls memory/project/handoff context and recovery instructions
-
-- `swarm-enforcer.ts`
-  - Injects bead state and stage labels into system context
-  - Warns when implementation starts without a properly started bead
-  - Reminds to close/sync in-progress work on session idle
+  - Provides tools: `find_sessions`, `read_session`
+  - Direct SQLite access to OpenCode's session DB
+  - Multi-word AND search with relevance ranking
+  - 180-day time-bounded search
+  - Agentic `nextStep` guidance in results
 
 - `skill-mcp.ts`
   - Loads MCP configs from skills
@@ -48,9 +60,9 @@ plugin/
 
 ## Notes
 
-- `notification.ts.bak` is a backup file and not part of the active plugin set.
-- Keep plugin documentation aligned with actual files in this directory.
-- Prefer shared helpers in `lib/` over duplicated utilities across plugins.
+- OpenCode auto-discovers every `.ts` file in `plugin/` as a plugin — keep helper modules in `lib/`
+- Keep plugin documentation aligned with actual files in this directory
+- Prefer shared helpers in `lib/` over duplicated utilities across plugins
 
 ## References
 

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

@@ -0,0 +1,177 @@
+/**
+ * Message Capture Module
+ *
+ * Handles message.part.updated events: extracts text content from parts,
+ * estimates tokens, and stores/updates temporal_messages for later distillation.
+ *
+ * Architecture note: OpenCode fires separate events for messages and parts.
+ * - message.updated → { info: Message } (metadata only, no text)
+ * - message.part.updated → { part: Part, delta?: string } (has text content)
+ *
+ * We capture from message.part.updated since that's where the text lives.
+ * Each part update upserts the message row, accumulating content.
+ */
+
+import type { Database } from "bun:sqlite";
+import {
+	estimateTokens,
+	getMemoryDB,
+	MEMORY_CONFIG,
+	type TemporalMessageInput,
+} from "./memory-db.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** Shape of properties from EventMessagePartUpdated */
+export interface PartEvent {
+	part?: {
+		id?: string;
+		sessionID?: string;
+		messageID?: string;
+		type?: string;
+		text?: string;
+	};
+	delta?: string;
+}
+
+/** Shape of properties from EventMessageUpdated (metadata only) */
+export interface MessageEvent {
+	info?: {
+		id?: string;
+		sessionID?: string;
+		role?: string;
+		time?: { created?: number };
+	};
+}
+
+// ============================================================================
+// Capture Handlers
+// ============================================================================
+
+/**
+ * Process a message.part.updated event.
+ * Upserts the temporal_messages row for this message, appending new text.
+ *
+ * Returns true if part was captured, false if skipped.
+ */
+export function captureMessagePart(props: PartEvent): boolean {
+	if (!MEMORY_CONFIG.capture.enabled) return false;
+
+	const part = props.part;
+	if (!part?.sessionID || !part.messageID) return false;
+
+	// Only capture text and reasoning parts
+	if (part.type !== "text" && part.type !== "reasoning") return false;
+
+	const text = part.text;
+	if (!text || text.trim().length === 0) return false;
+
+	// Cap content length
+	const cappedText = text.slice(0, MEMORY_CONFIG.capture.maxContentLength);
+
+	try {
+		const db = getMemoryDB();
+		upsertMessageContent(db, part.sessionID, part.messageID, cappedText);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Process a message.updated event to capture role metadata.
+ * Only stores role — content comes from message.part.updated.
+ *
+ * Returns true if metadata was captured.
+ */
+export function captureMessageMeta(props: MessageEvent): boolean {
+	if (!MEMORY_CONFIG.capture.enabled) return false;
+
+	const info = props.info;
+	if (!info?.id || !info.sessionID) return false;
+
+	const role = info.role ?? "unknown";
+	if (role !== "user" && role !== "assistant") return false;
+
+	try {
+		const db = getMemoryDB();
+		// Upsert with role but empty content — parts will fill it in
+		const existing = db
+			.query<{ content: string }, [string]>(
+				"SELECT content FROM temporal_messages WHERE message_id = ?",
+			)
+			.get(info.id);
+
+		if (!existing) {
+			// Insert placeholder that parts will update
+			const now = info.time?.created ?? Date.now();
+			db.run(
+				`INSERT OR IGNORE INTO temporal_messages
+				 (session_id, message_id, role, content, token_estimate, time_created)
+				 VALUES (?, ?, ?, '', 0, ?)`,
+				info.sessionID,
+				info.id,
+				role,
+				now,
+			);
+		}
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+// ============================================================================
+// Internal
+// ============================================================================
+
+/**
+ * Upsert a message row, replacing content with the latest part text.
+ * Since parts stream in incrementally, we replace (not append) with the
+ * latest full text from the part — OpenCode sends cumulative text.
+ */
+function upsertMessageContent(
+	db: Database,
+	sessionId: string,
+	messageId: string,
+	text: string,
+): void {
+	const tokenEstimate = estimateTokens(text);
+	const now = Date.now();
+
+	// Try update first (most common case — message.updated fires before parts)
+	const result = db.run(
+		`UPDATE temporal_messages
+		 SET content = ?, token_estimate = ?
+		 WHERE message_id = ?`,
+		text,
+		tokenEstimate,
+		messageId,
+	);
+
+	if (result.changes === 0) {
+		// No existing row — insert with unknown role (message.updated hasn't fired yet)
+		const input: TemporalMessageInput = {
+			session_id: sessionId,
+			message_id: messageId,
+			role: "assistant", // Parts without prior message.updated are typically assistant
+			content: text,
+			token_estimate: tokenEstimate,
+			time_created: now,
+		};
+
+		db.run(
+			`INSERT OR IGNORE INTO temporal_messages
+			 (session_id, message_id, role, content, token_estimate, time_created)
+			 VALUES (?, ?, ?, ?, ?, ?)`,
+			input.session_id,
+			input.message_id,
+			input.role,
+			input.content,
+			input.token_estimate,
+			input.time_created,
+		);
+	}
+}

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

@@ -0,0 +1,194 @@
+/**
+ * Context Window Management Module
+ *
+ * Implements messages.transform: estimates token usage across conversation
+ * messages and compresses oldest messages when approaching the budget limit.
+ *
+ * Protects the most recent N messages from compression.
+ */
+
+import { estimateTokens, MEMORY_CONFIG } from "./memory-db.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** Minimal message shape from messages.transform output */
+interface TransformMessage {
+	info: {
+		id?: string;
+		role?: string;
+		time?: {
+			created?: number;
+		};
+	};
+	parts: Array<{
+		type?: string;
+		text?: string;
+		data?: {
+			type?: string;
+			text?: string;
+		};
+	}>;
+}
+
+// ============================================================================
+// Token Estimation
+// ============================================================================
+
+/**
+ * Estimate total tokens in a message (all text parts).
+ */
+function estimateMessageTokens(msg: TransformMessage): number {
+	let total = 0;
+	for (const part of msg.parts) {
+		if (part.text) {
+			total += estimateTokens(part.text);
+		} else if (part.data?.text) {
+			total += estimateTokens(part.data.text);
+		}
+	}
+	// Add overhead for message framing (~10 tokens per message)
+	return total + 10;
+}
+
+/**
+ * Create a compressed summary of a message.
+ * Preserves non-text parts (tool calls, tool results, images) to maintain
+ * conversation coherence. Only compresses text parts.
+ */
+function compressMessage(msg: TransformMessage): TransformMessage {
+	const role = msg.info.role ?? "unknown";
+
+	// Separate text parts from non-text parts (tool calls, tool results, etc.)
+	const textParts: Array<(typeof msg.parts)[number]> = [];
+	const nonTextParts: Array<(typeof msg.parts)[number]> = [];
+
+	for (const part of msg.parts) {
+		const isTextPart =
+			part.type === "text" || (!part.type && (part.text || part.data?.text));
+		if (isTextPart) {
+			textParts.push(part);
+		} else {
+			nonTextParts.push(part);
+		}
+	}
+
+	// Extract text content for summarization
+	const texts: string[] = [];
+	for (const part of textParts) {
+		if (part.text) texts.push(part.text);
+		else if (part.data?.text) texts.push(part.data.text);
+	}
+
+	const fullText = texts.join("\n");
+
+	// Build compressed parts: summarized text + preserved non-text parts
+	const compressedParts: typeof msg.parts = [];
+
+	if (fullText.length > 0) {
+		compressedParts.push({
+			type: "text",
+			text: createSummary(fullText, role),
+		});
+	}
+
+	// Preserve tool calls, tool results, and other structural parts
+	compressedParts.push(...nonTextParts);
+
+	return {
+		info: msg.info,
+		parts:
+			compressedParts.length > 0
+				? compressedParts
+				: [{ type: "text", text: `[compressed ${role} message]` }],
+	};
+}
+
+/**
+ * Create a brief summary of message content.
+ * Keeps first and last sentence, truncates middle.
+ */
+function createSummary(text: string, role: string): string {
+	const maxChars = 200;
+
+	if (text.length <= maxChars) return text;
+
+	// Split into sentences
+	const sentences = text
+		.split(/(?<=[.!?])\s+|\n+/)
+		.map((s) => s.trim())
+		.filter((s) => s.length > 0);
+
+	if (sentences.length <= 2) {
+		return `${text.slice(0, maxChars)}...`;
+	}
+
+	const first = sentences[0];
+	const last = sentences[sentences.length - 1];
+
+	const summary = `[compressed ${role} message] ${first} [...${sentences.length - 2} more sentences...] ${last}`;
+
+	return summary.length > maxChars * 2
+		? `${summary.slice(0, maxChars * 2)}...`
+		: summary;
+}
+
+// ============================================================================
+// Context Manager
+// ============================================================================
+
+/**
+ * Process messages through context management.
+ *
+ * If total tokens exceed maxContextTokens, compresses oldest messages
+ * (excluding the most recent `protectedMessages` count).
+ *
+ * @param messages - Current conversation messages
+ * @returns Potentially compressed messages array
+ */
+export function manageContext(
+	messages: TransformMessage[],
+): TransformMessage[] {
+	if (!MEMORY_CONFIG.context.enabled) return messages;
+
+	const maxTokens = MEMORY_CONFIG.context.maxContextTokens;
+	const protectedCount = MEMORY_CONFIG.context.protectedMessages;
+
+	// Estimate total tokens
+	let totalTokens = 0;
+	const tokenCounts: number[] = [];
+
+	for (const msg of messages) {
+		const tokens = estimateMessageTokens(msg);
+		tokenCounts.push(tokens);
+		totalTokens += tokens;
+	}
+
+	// If under budget, return unchanged
+	if (totalTokens <= maxTokens) return messages;
+
+	// Calculate how many tokens to shed
+	const tokensToShed = totalTokens - maxTokens;
+
+	// Identify compressible messages (all except protected recent ones)
+	const compressibleEnd = Math.max(0, messages.length - protectedCount);
+	let shedSoFar = 0;
+
+	const result = [...messages];
+
+	// Compress from oldest to newest until we've shed enough
+	for (let i = 0; i < compressibleEnd && shedSoFar < tokensToShed; i++) {
+		const originalTokens = tokenCounts[i];
+		const compressed = compressMessage(messages[i]);
+		const compressedTokens = estimateMessageTokens(compressed);
+		const saved = originalTokens - compressedTokens;
+
+		if (saved > 0) {
+			result[i] = compressed;
+			shedSoFar += saved;
+		}
+	}
+
+	return result;
+}

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

@@ -0,0 +1,234 @@
+/**
+ * Curator Module
+ *
+ * Pattern-matches distillations to automatically create observations.
+ * Uses regex patterns to detect decisions, bugfixes, patterns, discoveries, warnings.
+ * All curated observations are created with source='curator'.
+ *
+ * No LLM dependency — pure heuristic pattern matching.
+ */
+
+import {
+	type DistillationRow,
+	getRecentDistillations,
+	MEMORY_CONFIG,
+	type ObservationInput,
+	type ObservationType,
+	storeObservation,
+} from "./memory-db.js";
+
+// ============================================================================
+// Pattern Definitions
+// ============================================================================
+
+/** Curator patterns — regex + type mapping.
+ *
+ * Each pattern requires multi-word phrases or contextual markers to reduce
+ * false positives. Single common words like "using", "found", "always" are
+ * NOT matched alone — they must appear in decision/discovery phrases.
+ */
+const CURATOR_PATTERNS: Array<{
+	type: ObservationType;
+	pattern: RegExp;
+	titleExtractor: (match: RegExpMatchArray, sentence: string) => string;
+}> = [
+	{
+		type: "decision",
+		pattern:
+			/\b(decided to|chose to|selected\s+\w+\s+(?:over|instead)|went with|opted for|switched to|migrated to|picked\s+\w+\s+(?:over|for))\b/i,
+		titleExtractor: (_match, sentence) => truncateSentence(sentence, 80),
+	},
+	{
+		type: "bugfix",
+		pattern:
+			/\b(fixed (?:a|the|an)\b|resolved (?:a|the|an)\b|patched (?:a|the|an)\b|corrected (?:a|the|an)\b|bug in\b|error in\b|crash in\b|regression in\b)\b/i,
+		titleExtractor: (_match, sentence) => truncateSentence(sentence, 80),
+	},
+	{
+		type: "pattern",
+		pattern:
+			/\b(pattern(?::|is| for)\b|convention(?::|is)\b|best practice\b|standard practice\b|workflow for\b|(?:we|I|the team) (?:always|never)\b)\b/i,
+		titleExtractor: (_match, sentence) => truncateSentence(sentence, 80),
+	},
+	{
+		type: "discovery",
+		pattern:
+			/\b(found that|discovered that|noticed that|learned that|turns out|realized that|it (?:seems|appears) that)\b/i,
+		titleExtractor: (_match, sentence) => truncateSentence(sentence, 80),
+	},
+	{
+		type: "warning",
+		pattern:
+			/\b(warning:|caution:|careful with|gotcha:|pitfall(?:s|:)?\b|don't use\b|avoid (?:using|calling|importing)\b|beware of\b|watch out for\b|never (?:use|call|import|commit|push)\b)\b/i,
+		titleExtractor: (_match, sentence) => truncateSentence(sentence, 80),
+	},
+];
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+/**
+ * Truncate a sentence to max length, preserving word boundaries.
+ */
+function truncateSentence(sentence: string, maxLen: number): string {
+	const clean = sentence.replace(/\s+/g, " ").trim();
+	if (clean.length <= maxLen) return clean;
+
+	const truncated = clean.slice(0, maxLen);
+	const lastSpace = truncated.lastIndexOf(" ");
+	return lastSpace > maxLen / 2
+		? `${truncated.slice(0, lastSpace)}...`
+		: `${truncated}...`;
+}
+
+/**
+ * Split distillation content into sentences.
+ */
+function splitSentences(content: string): string[] {
+	return content
+		.split(/(?<=[.!?])\s+|\n+/)
+		.map((s) => s.trim())
+		.filter((s) => s.length > 30); // Skip short fragments that lack enough context
+}
+
+/**
+ * Extract concept tags from a sentence (significant nouns/terms).
+ */
+function extractConcepts(sentence: string): string[] {
+	// Extract potential concept words (3+ chars, not common stop words)
+	const words = sentence
+		.toLowerCase()
+		.replace(/[^a-z0-9_\-/.]+/g, " ")
+		.split(/\s+/)
+		.filter((w) => w.length > 3);
+
+	// Return unique terms, limited to 5
+	return [...new Set(words)].slice(0, 5);
+}
+
+/**
+ * Deduplicate against existing observation titles (simple guard).
+ * Returns true if a similar title already exists.
+ */
+function isDuplicateTitle(title: string, existingTitles: Set<string>): boolean {
+	const normalized = title.toLowerCase().trim();
+	if (existingTitles.has(normalized)) return true;
+
+	// Also check prefix match (first 40 chars) for fuzzy dedup
+	const prefix = normalized.slice(0, 40);
+	for (const existing of existingTitles) {
+		if (
+			existing.startsWith(prefix) ||
+			prefix.startsWith(existing.slice(0, 40))
+		) {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+// ============================================================================
+// Curator Pipeline
+// ============================================================================
+
+interface CuratorResult {
+	created: number;
+	skipped: number;
+	patterns: Record<string, number>;
+}
+
+/**
+ * Run curator on recent distillations to extract observations.
+ *
+ * @param sessionId - If provided, only process distillations from this session
+ * @param limit - Max distillations to process (default: MEMORY_CONFIG.curator.minDistillations)
+ */
+export function curateFromDistillations(
+	sessionId?: string,
+	limit?: number,
+): CuratorResult {
+	if (!MEMORY_CONFIG.curator.enabled) {
+		return { created: 0, skipped: 0, patterns: {} };
+	}
+
+	const maxDistillations = limit ?? MEMORY_CONFIG.curator.minDistillations;
+	const distillations = getRecentDistillations(sessionId, maxDistillations);
+
+	if (distillations.length < MEMORY_CONFIG.curator.minDistillations) {
+		return { created: 0, skipped: 0, patterns: {} };
+	}
+
+	const result: CuratorResult = { created: 0, skipped: 0, patterns: {} };
+	const seenTitles = new Set<string>();
+
+	for (const distillation of distillations) {
+		const sentences = splitSentences(distillation.content);
+
+		for (const sentence of sentences) {
+			const observation = matchPatterns(sentence, distillation, seenTitles);
+
+			if (observation) {
+				try {
+					storeObservation(observation);
+					result.created++;
+					result.patterns[observation.type] =
+						(result.patterns[observation.type] ?? 0) + 1;
+					seenTitles.add(observation.title.toLowerCase().trim());
+				} catch {
+					result.skipped++;
+				}
+			}
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Match a sentence against curator patterns and return an observation input if matched.
+ */
+function matchPatterns(
+	sentence: string,
+	distillation: DistillationRow,
+	seenTitles: Set<string>,
+): ObservationInput | null {
+	for (const { type, pattern, titleExtractor } of CURATOR_PATTERNS) {
+		const match = sentence.match(pattern);
+		if (!match) continue;
+
+		const title = titleExtractor(match, sentence);
+
+		// Skip duplicates
+		if (isDuplicateTitle(title, seenTitles)) {
+			continue;
+		}
+
+		const concepts = extractConcepts(sentence);
+
+		// Parse distillation terms for additional concepts
+		let distTerms: string[] = [];
+		try {
+			distTerms = JSON.parse(distillation.terms);
+		} catch {
+			// Invalid JSON, skip
+		}
+
+		// Merge concepts from sentence + distillation terms (max 8)
+		const allConcepts = [
+			...new Set([...concepts, ...distTerms.slice(0, 3)]),
+		].slice(0, 8);
+
+		return {
+			type,
+			title,
+			narrative: sentence,
+			concepts: allConcepts,
+			confidence: MEMORY_CONFIG.curator.defaultConfidence,
+			source: "curator",
+		};
+	}
+
+	return null;
+}