opencode-starterkit 1.0.1

package/baseline/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/baseline/plugin/lib/context.ts

@@ -0,0 +1,198 @@
+/**
+ * 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 = 500;
+
+	if (text.length <= maxChars) return text;
+
+	// For very large messages (>5000 chars), be more aggressive
+	const isLarge = text.length > 5000;
+	const effectiveMax = isLarge ? 300 : maxChars;
+
+	// 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, effectiveMax)}...`;
+	}
+
+	const first = sentences[0];
+	const last = sentences[sentences.length - 1];
+
+	const summary = `[compressed ${role}] ${first} [...${sentences.length - 2} sentences...] ${last}`;
+
+	return summary.length > effectiveMax
+		? `${summary.slice(0, effectiveMax)}...`
+		: 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/baseline/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;
+}