@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/plugin/lib/operation-log.ts

@@ -0,0 +1,110 @@
+/**
+ * Memory Operation Log — Append-Only Audit Trail
+ *
+ * Inspired by Karpathy's LLM Wiki log.md:
+ * chronological record of all memory operations for provenance tracking.
+ *
+ * Stored in memory_files as "log" — append-only, never overwritten.
+ */
+
+import { getMemoryFile, upsertMemoryFile } from "./db/maintenance.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type OperationType =
+	| "observation-created"
+	| "observation-superseded"
+	| "observation-validated"
+	| "observation-duplicate-warning"
+	| "observation-rejected"
+	| "index-generated"
+	| "lint-run"
+	| "compile-run"
+	| "maintenance-run"
+	| "distillation-created"
+	| "curation-run";
+
+export interface LogEntry {
+	timestamp: string;
+	operation: OperationType;
+	targets: string[];
+	summary: string;
+}
+
+// ============================================================================
+// Log Operations
+// ============================================================================
+
+/**
+ * Append an entry to the operation log.
+ * The log is append-only and stored in memory_files.
+ */
+export function appendOperationLog(entry: Omit<LogEntry, "timestamp">): void {
+	const timestamp = new Date().toISOString().slice(0, 19);
+	const targets = entry.targets.length > 0 ? entry.targets.join(", ") : "-";
+	const line = `[${timestamp}] ${entry.operation} | ${targets} | ${entry.summary}`;
+
+	// Check if log exists
+	const existing = getMemoryFile("log");
+	if (existing) {
+		// Append with newline
+		upsertMemoryFile("log", line, "append");
+	} else {
+		// Create with header
+		const header = [
+			"# Memory Operation Log",
+			"",
+			"> Append-only chronological record of all memory operations.",
+			"> Format: [timestamp] operation | targets | summary",
+			"",
+			"---",
+			"",
+			line,
+		].join("\n");
+		upsertMemoryFile("log", header, "replace");
+	}
+}
+
+/**
+ * Get recent log entries (parsed from the log file).
+ */
+export function getRecentLogEntries(limit = 20): LogEntry[] {
+	const existing = getMemoryFile("log");
+	if (!existing) return [];
+
+	const lines = existing.content
+		.split("\n")
+		.filter((line) => line.startsWith("["))
+		.slice(-limit);
+
+	return lines.map((line) => {
+		const match = line.match(/^\[(.+?)\] (.+?) \| (.+?) \| (.+)$/);
+		if (!match) {
+			return {
+				timestamp: "",
+				operation: "observation-created" as OperationType,
+				targets: [],
+				summary: line,
+			};
+		}
+		return {
+			timestamp: match[1],
+			operation: match[2] as OperationType,
+			targets: match[3].split(",").map((t) => t.trim()),
+			summary: match[4],
+		};
+	});
+}
+
+/**
+ * Get the full log content as a string.
+ */
+export function getLogContent(): string {
+	const existing = getMemoryFile("log");
+	return (
+		existing?.content ??
+		"No operation log found. Run a memory operation to start logging."
+	);
+}

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

@@ -0,0 +1,243 @@
+/**
+ * Observation Validation Gate
+ *
+ * Inspired by jumperz's Secondmate Hermes validation:
+ * checks for duplicates and contradictions BEFORE storing an observation.
+ *
+ * Unlike Secondmate's approach (separate LLM model), this uses
+ * FTS5 similarity search + heuristic contradiction detection.
+ *
+ * Returns a validation result that can:
+ * - PASS: store normally
+ * - WARN: store but flag issues
+ * - REJECT: don't store, return reason
+ */
+
+import type { ObservationInput, ObservationRow } from "./db/types.js";
+import { getMemoryDB } from "./memory-db.js";
+import { hasWord } from "./memory-helpers.js";
+import { appendOperationLog } from "./operation-log.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type ValidationVerdict = "pass" | "warn" | "reject";
+
+export interface ValidationResult {
+	verdict: ValidationVerdict;
+	issues: ValidationIssue[];
+	/** If a near-duplicate was found, its ID */
+	duplicateOf?: number;
+}
+
+export interface ValidationIssue {
+	type: "duplicate" | "near-duplicate" | "contradiction" | "low-quality";
+	severity: "high" | "medium" | "low";
+	message: string;
+	relatedId?: number;
+}
+
+// ============================================================================
+// Validation
+// ============================================================================
+
+/**
+ * Validate an observation before storing.
+ * Returns verdict (pass/warn/reject) with issues.
+ */
+export function validateObservation(input: ObservationInput): ValidationResult {
+	const issues: ValidationIssue[] = [];
+
+	// Check 1: Exact title duplicate
+	const exactDup = findExactDuplicate(input);
+	if (exactDup) {
+		// If it's explicitly superseding, that's fine
+		if (input.supersedes === exactDup.id) {
+			// Intentional supersede — pass
+		} else {
+			issues.push({
+				type: "duplicate",
+				severity: "high",
+				message: `Exact duplicate of #${exactDup.id}: "${exactDup.title}"`,
+				relatedId: exactDup.id,
+			});
+
+			appendOperationLog({
+				operation: "observation-duplicate-warning",
+				targets: [`#${exactDup.id}`],
+				summary: `Duplicate warning: "${input.title}" (matches #${exactDup.id})`,
+			});
+
+			return {
+				verdict: "warn",
+				issues,
+				duplicateOf: exactDup.id,
+			};
+		}
+	}
+
+	// Check 2: Near-duplicate via FTS5
+	const nearDup = findNearDuplicate(input);
+	if (nearDup) {
+		issues.push({
+			type: "near-duplicate",
+			severity: "medium",
+			message: `Similar to #${nearDup.id}: "${nearDup.title}" (consider superseding)`,
+			relatedId: nearDup.id,
+		});
+	}
+
+	// Check 3: Contradiction with existing decisions
+	if (input.type === "decision") {
+		const contradiction = findContradiction(input);
+		if (contradiction) {
+			issues.push({
+				type: "contradiction",
+				severity: "medium",
+				message: `May contradict #${contradiction.id}: "${contradiction.title}"`,
+				relatedId: contradiction.id,
+			});
+		}
+	}
+
+	// Check 4: Low quality (no narrative, no concepts)
+	if (!input.narrative && !input.concepts) {
+		issues.push({
+			type: "low-quality",
+			severity: "low",
+			message:
+				"Observation has no narrative and no concepts — low knowledge value",
+		});
+	}
+
+	// Determine verdict
+	const hasHigh = issues.some((i) => i.severity === "high");
+	const verdict: ValidationVerdict = hasHigh
+		? "reject"
+		: issues.length > 0
+			? "warn"
+			: "pass";
+
+	if (verdict === "pass" || verdict === "warn") {
+		appendOperationLog({
+			operation: "observation-validated",
+			targets: [input.title],
+			summary: `Validated [${input.type}] "${input.title}" — ${verdict}${issues.length > 0 ? ` (${issues.length} issues)` : ""}`,
+		});
+	}
+
+	return { verdict, issues };
+}
+
+// ============================================================================
+// Internal Checks
+// ============================================================================
+
+/**
+ * Check for exact title match (same type, active).
+ */
+function findExactDuplicate(input: ObservationInput): ObservationRow | null {
+	const db = getMemoryDB();
+	return db
+		.query(
+			`SELECT * FROM observations
+			 WHERE type = ? AND LOWER(title) = LOWER(?) AND superseded_by IS NULL
+			 LIMIT 1`,
+		)
+		.get(input.type, input.title) as ObservationRow | null;
+}
+
+/**
+ * Check for near-duplicate via FTS5 title search.
+ */
+function findNearDuplicate(input: ObservationInput): ObservationRow | null {
+	const db = getMemoryDB();
+
+	// Build FTS query from title words
+	// Strip FTS5 special operators and characters to prevent query syntax errors
+	const FTS5_OPERATORS = /\b(AND|OR|NOT|NEAR)\b/gi;
+	const words = input.title
+		.replace(FTS5_OPERATORS, "")
+		.replace(/['"*^+(){}]/g, "")
+		.split(/\s+/)
+		.filter((w) => w.length > 2)
+		.map((w) => `"${w}"*`)
+		.join(" AND ");
+
+	if (!words) return null;
+
+	try {
+		const result = db
+			.query(
+				`SELECT o.* FROM observations o
+				 JOIN observations_fts fts ON fts.rowid = o.id
+				 WHERE observations_fts MATCH ?
+				   AND o.type = ?
+				   AND o.superseded_by IS NULL
+				   AND o.id != COALESCE(?, -1)
+				 ORDER BY bm25(observations_fts) LIMIT 1`,
+			)
+			.get(
+				words,
+				input.type,
+				input.supersedes ?? null,
+			) as ObservationRow | null;
+
+		return result;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Check for contradictions with existing decisions.
+ */
+function findContradiction(input: ObservationInput): ObservationRow | null {
+	if (!input.concepts || input.concepts.length === 0) return null;
+
+	const db = getMemoryDB();
+
+	// Search for decisions with overlapping concepts
+	const conceptQuery = input.concepts.map((c) => `"${c}"*`).join(" OR ");
+
+	try {
+		const candidates = db
+			.query(
+				`SELECT o.* FROM observations o
+				 JOIN observations_fts fts ON fts.rowid = o.id
+				 WHERE observations_fts MATCH ?
+				   AND o.type = 'decision'
+				   AND o.superseded_by IS NULL
+				 ORDER BY bm25(observations_fts) LIMIT 5`,
+			)
+			.all(conceptQuery) as ObservationRow[];
+
+		// Check for opposing signals
+		const inputText = `${input.title} ${input.narrative ?? ""}`.toLowerCase();
+		const contradictionPairs = [
+			["use", "don't use"],
+			["enable", "disable"],
+			["add", "remove"],
+			["prefer", "avoid"],
+			["always", "never"],
+		];
+
+		for (const candidate of candidates) {
+			const candidateText =
+				`${candidate.title} ${candidate.narrative ?? ""}`.toLowerCase();
+			for (const [wordA, wordB] of contradictionPairs) {
+				if (
+					(hasWord(inputText, wordA) && hasWord(candidateText, wordB)) ||
+					(hasWord(inputText, wordB) && hasWord(candidateText, wordA))
+				) {
+					return candidate;
+				}
+			}
+		}
+	} catch {
+		// FTS5 query failed
+	}
+
+	return null;
+}

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

@@ -0,0 +1,90 @@
+/**
+ * Unified Memory Plugin v2
+ *
+ * Consolidates all memory tools + hooks + compaction into a single plugin.
+ *
+ * Systems:
+ * 1. Capture — message.updated → temporal_messages
+ * 2. Distillation — session.idle → TF-IDF compression
+ * 3. Curator — session.idle → pattern-matched observations
+ * 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
+ *
+ * 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
+ */
+
+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";
+
+// ============================================================================
+// Plugin Export
+// ============================================================================
+
+export const MemoryPlugin: Plugin = async ({ client, directory }) => {
+	const memoryDir = path.join(directory, ".opencode", "memory");
+	const handoffDir = path.join(memoryDir, "handoffs");
+
+	// Logging + toast helpers
+	const log = async (message: string, level: "info" | "warn" = "info") => {
+		await client.app
+			.log({ body: { service: "memory", level, message } })
+			.catch(() => {});
+	};
+
+	const showToast = async (
+		title: string,
+		message: string,
+		variant: "info" | "warning" = "info",
+	) => {
+		try {
+			await client.tui.showToast({
+				body: {
+					title: `Memory: ${title}`,
+					message,
+					variant,
+					duration: variant === "warning" ? 8000 : 5000,
+				},
+			});
+		} catch {
+			/* Toast API unavailable */
+		}
+	};
+
+	// Assemble tools
+	const coreTools = createCoreTools({ handoffDir });
+	const adminTools = createAdminTools({ directory });
+
+	// Assemble hooks
+	const hooks = createHooks({
+		showToast,
+		log,
+	});
+
+	return {
+		tool: {
+			...coreTools,
+			...adminTools,
+		},
+		...hooks,
+	};
+};
+
+export default MemoryPlugin;

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

@@ -0,0 +1,7 @@
+{
+  "name": "opencode-plugins",
+  "type": "module",
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.1.13"
+  }
+}

package/dist/template/.opencode/plugin/prompt-leverage.ts

@@ -0,0 +1,191 @@
+/**
+ * Prompt Leverage Plugin
+ *
+ * Automatically upgrades every user prompt with the seven-block framework before the AI processes it.
+ * Uses chat.message hook — safely inspects input structure before accessing properties.
+ */
+
+import type { Plugin } from "@opencode-ai/plugin";
+
+const TASK_KEYWORDS: Record<string, string[]> = {
+  coding: [
+    "code",
+    "bug",
+    "repo",
+    "refactor",
+    "test",
+    "implement",
+    "fix",
+    "function",
+    "api",
+    "add",
+    "update",
+    "remove",
+  ],
+  research: [
+    "research",
+    "compare",
+    "find",
+    "latest",
+    "sources",
+    "analyze",
+    "look up",
+  ],
+  writing: [
+    "write",
+    "rewrite",
+    "draft",
+    "email",
+    "memo",
+    "blog",
+    "copy",
+    "tone",
+  ],
+  review: ["review", "audit", "critique", "inspect", "evaluate", "assess"],
+  planning: ["plan", "roadmap", "strategy", "framework", "outline"],
+  analysis: ["analyze", "explain", "break down", "diagnose", "root cause"],
+};
+
+function detectTask(prompt: string): string {
+  const lowered = prompt.toLowerCase();
+  const scores: Record<string, number> = {};
+  for (const [task, keywords] of Object.entries(TASK_KEYWORDS)) {
+    scores[task] = keywords.filter((k) => lowered.includes(k)).length;
+  }
+  const best = Object.entries(scores).sort((a, b) => b[1] - a[1]);
+  return best[0]?.[1] ? best[0][0] : "analysis";
+}
+
+function inferIntensity(prompt: string, task: string): string {
+  const lowered = prompt.toLowerCase();
+  if (
+    ["careful", "deep", "thorough", "critical", "production"].some((t) =>
+      lowered.includes(t),
+    )
+  ) {
+    return "Deep";
+  }
+  if (task === "coding" || task === "research" || task === "review") {
+    return "Standard";
+  }
+  return "Light";
+}
+
+function buildToolRules(task: string): string {
+  const rules: Record<string, string> = {
+    coding:
+      "Inspect the relevant files and dependencies first. Validate the final change with the narrowest useful checks before broadening scope.",
+    research:
+      "Retrieve evidence from reliable sources before concluding. Do not guess facts that can be checked.",
+    review:
+      "Read enough surrounding context to understand intent before critiquing. Distinguish confirmed issues from plausible risks.",
+  };
+  return (
+    rules[task] ||
+    "Use tools or extra context only when they materially improve correctness or completeness."
+  );
+}
+
+function buildOutputContract(task: string): string {
+  const contracts: Record<string, string> = {
+    coding:
+      "Return the result in a practical execution format: concise summary, concrete changes or code, validation notes, and any remaining risks.",
+    research:
+      "Return a structured synthesis with key findings, supporting evidence, uncertainty where relevant, and a concise bottom line.",
+    writing:
+      "Return polished final copy in the requested tone and format. If useful, include a short rationale for major editorial choices.",
+    review:
+      "Return findings grouped by severity or importance, explain why each matters, and suggest the smallest credible next step.",
+  };
+  return (
+    contracts[task] ||
+    "Return a clear, well-structured response matched to the task, with no unnecessary verbosity."
+  );
+}
+
+function upgradePrompt(userPrompt: string): string {
+  const normalized = userPrompt.trim().replace(/\s+/g, " ");
+  const task = detectTask(normalized);
+  const intensity = inferIntensity(normalized, task);
+  const toolRules = buildToolRules(task);
+  const outputContract = buildOutputContract(task);
+
+  if (normalized.includes("Objective:") && normalized.includes("Context:")) {
+    return userPrompt;
+  }
+  if (normalized.length < 15 || normalized.split(" ").length < 3) {
+    return userPrompt;
+  }
+
+  return `Objective:
+- Complete this task: ${normalized}
+- Optimize for a correct, useful result rather than a merely plausible one.
+
+Context:
+- Preserve the user's original intent and constraints.
+- Surface any key assumptions if required information is missing.
+
+Work Style:
+- Task type: ${task}
+- Effort level: ${intensity}
+- Understand the problem broadly enough to avoid narrow mistakes, then go deep where the risk or complexity is highest.
+- Use first-principles reasoning before proposing changes.
+- For non-trivial work, review the result once with fresh eyes before finalizing.
+
+Tool Rules:
+- ${toolRules}
+
+Output Contract:
+- ${outputContract}
+
+Verification:
+- Check correctness, completeness, and edge cases.
+- Improve obvious weaknesses if a better approach is available within scope.
+
+Done Criteria:
+- Stop only when the response satisfies the task, matches the requested format, and passes the verification step.`;
+}
+
+export const PromptLeverage: Plugin = async ({ client }) => {
+  const showToast = async (message: string) => {
+    try {
+      await client.tui.showToast({
+        body: {
+          title: "PromptLeverage",
+          message,
+          variant: "info",
+          duration: 3000,
+        },
+      });
+    } catch {
+      /* Toast API unavailable */
+    }
+  };
+
+  return {
+    "experimental.chat.messages.transform": async (input: any, output: any) => {
+      try {
+        const msgs = output.messages || input.messages || [];
+
+        // Find the last message with parts (user message)
+        for (let i = msgs.length - 1; i >= 0; i--) {
+          const msg = msgs[i];
+          if (msg?.parts) {
+            for (const part of msg.parts) {
+              if (part.type === "text" && part.text) {
+                const upgraded = upgradePrompt(part.text);
+                if (upgraded !== part.text) {
+                  part.text = upgraded;
+                  showToast("Upgraded prompt!");
+                }
+              }
+            }
+            break; // Only upgrade the most recent message
+          }
+        }
+      } catch (e: any) {
+        showToast(`Error: ${e.message}`);
+      }
+    },
+  };
+};

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

@@ -0,0 +1,43 @@
+import type { Plugin } from "@opencode-ai/plugin";
+
+// RTK OpenCode plugin — rewrites commands to use rtk for token savings.
+// Requires: rtk >= 0.23.0 in PATH.
+//
+// This is a thin delegating plugin: all rewrite logic lives in `rtk rewrite`,
+// which is the single source of truth (src/discover/registry.rs).
+// To add or change rewrite rules, edit the Rust registry — not this file.
+
+export const RtkOpenCodePlugin: Plugin = async ({ $ }) => {
+	try {
+		await $`which rtk`.quiet();
+	} catch {
+		console.warn("[rtk] rtk binary not found in PATH — plugin disabled");
+		return {};
+	}
+
+	return {
+		"tool.execute.before": async (input, output) => {
+			const tool = String(input?.tool ?? "").toLowerCase();
+			if (tool !== "bash" && tool !== "shell") return;
+			const args = output?.args;
+			if (!args || typeof args !== "object") return;
+
+			const command = (args as Record<string, unknown>).command;
+			if (typeof command !== "string" || !command) return;
+			// This config is symlinked as both global and project OpenCode config.
+			// OpenCode may load this plugin twice in that layout, so avoid rewriting
+			// commands that have already been routed through rtk.
+			if (/^\s*(?:RTK_[A-Z_]+=\S+\s+)*rtk\b/.test(command)) return;
+
+			try {
+				const result = await $`rtk rewrite ${command}`.quiet().nothrow();
+				const rewritten = String(result.stdout).trim();
+				if (rewritten && rewritten !== command) {
+					(args as Record<string, unknown>).command = rewritten;
+				}
+			} catch {
+				// rtk rewrite failed — pass through unchanged
+			}
+		},
+	};
+};