@kortix/sandbox 0.4.1

package/opencode/plugin/memory.ts

@@ -0,0 +1,306 @@
+/**
+ * Kortix Memory Plugin
+ *
+ * Implements OpenClaw-style memory system integration for OpenCode:
+ *
+ * 1. System Prompt Injection — Automatically loads MEMORY.md + daily logs
+ *    into the system prompt at session start (no tool call needed).
+ *
+ * 2. Pre-Compaction Memory Flush — Before context compaction, triggers a
+ *    silent agentic turn that nudges the model to write durable memories
+ *    to disk, preventing memory loss.
+ *
+ * 3. Session Event Tracking — Listens to session events for memory lifecycle.
+ *
+ * Mirrors OpenClaw's memory architecture:
+ * - src/agents/system-prompt.ts (MEMORY.md injection)
+ * - compaction.memoryFlush (pre-compaction flush)
+ */
+
+import { readFile, access, mkdir } from "node:fs/promises"
+import * as path from "node:path"
+import type { Plugin } from "@opencode-ai/plugin"
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+interface MemoryConfig {
+  enabled: boolean
+  basePath: string
+  corePath: string
+  memoryDir: string
+  flush: {
+    enabled: boolean
+    softThresholdTokens: number
+    systemPrompt: string
+    prompt: string
+  }
+  inject: {
+    coreMemory: boolean
+    dailyLogs: boolean
+    dailyLogDays: number
+  }
+}
+
+const DEFAULT_CONFIG: MemoryConfig = {
+  enabled: true,
+  basePath: "/workspace/.kortix",
+  corePath: "MEMORY.md",
+  memoryDir: "memory",
+  flush: {
+    enabled: true,
+    softThresholdTokens: 4000,
+    systemPrompt:
+      "Session is nearing context compaction. Before context is lost, write any durable memories that should persist across sessions.",
+    prompt: [
+      "Review what you have learned in this session.",
+      `Write any lasting notes, decisions, lessons, or user preferences to workspace/.kortix/memory/${formatDate(new Date())}.md.`,
+      "Update workspace/.kortix/MEMORY.md Scratchpad with current state and pending items.",
+      "Reply with NO_REPLY if there is nothing worth remembering.",
+    ].join(" "),
+  },
+  inject: {
+    coreMemory: true,
+    dailyLogs: true,
+    dailyLogDays: 2,
+  },
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function formatDate(d: Date): string {
+  return d.toISOString().slice(0, 10)
+}
+
+function getDayOffset(offset: number): Date {
+  const d = new Date()
+  d.setDate(d.getDate() + offset)
+  return d
+}
+
+async function readFileSafe(filePath: string): Promise<string | null> {
+  try {
+    await access(filePath)
+    return await readFile(filePath, "utf-8")
+  } catch {
+    return null
+  }
+}
+
+async function loadConfig(directory: string): Promise<MemoryConfig> {
+  const configPath = path.join(directory, ".opencode", "memory.json")
+  try {
+    const raw = await readFile(configPath, "utf-8")
+    const parsed = JSON.parse(raw)
+    return {
+      ...DEFAULT_CONFIG,
+      ...parsed,
+      flush: { ...DEFAULT_CONFIG.flush, ...parsed.flush },
+      inject: { ...DEFAULT_CONFIG.inject, ...parsed.inject },
+    }
+  } catch {
+    // Also try sandbox-local config
+    const sandboxConfigPath = path.resolve(directory, "memory.json")
+    try {
+      const raw = await readFile(sandboxConfigPath, "utf-8")
+      const parsed = JSON.parse(raw)
+      return {
+        ...DEFAULT_CONFIG,
+        ...parsed,
+        flush: { ...DEFAULT_CONFIG.flush, ...parsed.flush },
+        inject: { ...DEFAULT_CONFIG.inject, ...parsed.inject },
+      }
+    } catch {
+      return DEFAULT_CONFIG
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Memory Content Loading
+// ---------------------------------------------------------------------------
+
+async function loadCoreMemory(basePath: string): Promise<string | null> {
+  const memoryPath = path.join(basePath, "MEMORY.md")
+  return readFileSafe(memoryPath)
+}
+
+async function loadDailyLogs(
+  basePath: string,
+  days: number,
+): Promise<{ date: string; content: string }[]> {
+  const logs: { date: string; content: string }[] = []
+  for (let i = 0; i < days; i++) {
+    const date = formatDate(getDayOffset(-i))
+    const logPath = path.join(basePath, "memory", `${date}.md`)
+    const content = await readFileSafe(logPath)
+    if (content && content.trim().length > 0) {
+      logs.push({ date, content })
+    }
+  }
+  return logs
+}
+
+function buildMemorySystemPrompt(
+  coreMemory: string | null,
+  dailyLogs: { date: string; content: string }[],
+): string {
+  const sections: string[] = []
+
+  sections.push("# Agent Memory (auto-loaded)")
+  sections.push("")
+
+  if (coreMemory && coreMemory.trim()) {
+    sections.push("## Core Memory (MEMORY.md)")
+    sections.push("")
+    sections.push(coreMemory.trim())
+    sections.push("")
+  }
+
+  if (dailyLogs.length > 0) {
+    sections.push("## Recent Daily Logs")
+    sections.push("")
+    for (const log of dailyLogs) {
+      sections.push(`### ${log.date}`)
+      sections.push("")
+      sections.push(log.content.trim())
+      sections.push("")
+    }
+  }
+
+  if (!coreMemory && dailyLogs.length === 0) {
+    sections.push(
+      "No memory found. Memory system is active but MEMORY.md has not been created yet.",
+    )
+    sections.push(
+      "Create it at workspace/.kortix/MEMORY.md or run /memory-init.",
+    )
+    sections.push("")
+  }
+
+  sections.push("---")
+  sections.push(
+    "Memory is auto-loaded. Update MEMORY.md and memory/*.md files to persist knowledge across sessions.",
+  )
+  sections.push(
+    "Use delta-only updates (never rewrite the whole file). Write daily entries to memory/YYYY-MM-DD.md.",
+  )
+
+  return sections.join("\n")
+}
+
+// ---------------------------------------------------------------------------
+// Track flush state per session to prevent multiple flushes
+// ---------------------------------------------------------------------------
+
+const flushedSessions = new Set<string>()
+
+// ---------------------------------------------------------------------------
+// Plugin Export
+// ---------------------------------------------------------------------------
+
+export const MemoryPlugin: Plugin = async (ctx) => {
+  const config = await loadConfig(ctx.directory)
+
+  if (!config.enabled) {
+    return {}
+  }
+
+  // Ensure base directories exist
+  const basePath = config.basePath
+  try {
+    await mkdir(path.join(basePath, "memory"), { recursive: true })
+    await mkdir(path.join(basePath, "journal"), { recursive: true })
+    await mkdir(path.join(basePath, "knowledge"), { recursive: true })
+    await mkdir(path.join(basePath, "sessions"), { recursive: true })
+  } catch {
+    // Directories may not be writable in all environments
+  }
+
+  return {
+    // -----------------------------------------------------------------
+    // Hook 1: System Prompt Injection
+    //
+    // Automatically load MEMORY.md + daily logs into the system prompt
+    // so the agent starts every turn with full memory context.
+    // Mirrors OpenClaw's src/agents/system-prompt.ts behavior.
+    // -----------------------------------------------------------------
+    "experimental.chat.system.transform": async (_input, output) => {
+      if (!config.inject.coreMemory && !config.inject.dailyLogs) return
+
+      const coreMemory = config.inject.coreMemory
+        ? await loadCoreMemory(basePath)
+        : null
+
+      const dailyLogs = config.inject.dailyLogs
+        ? await loadDailyLogs(basePath, config.inject.dailyLogDays)
+        : []
+
+      // Only inject if there's something to inject
+      if (coreMemory || dailyLogs.length > 0) {
+        const memoryPrompt = buildMemorySystemPrompt(coreMemory, dailyLogs)
+        output.system.push(memoryPrompt)
+      }
+    },
+
+    // -----------------------------------------------------------------
+    // Hook 2: Pre-Compaction Memory Flush
+    //
+    // Before context is compacted, inject instructions for the agent to
+    // write durable memories to disk. This prevents memory loss when the
+    // context window fills up.
+    // Mirrors OpenClaw's compaction.memoryFlush behavior.
+    // -----------------------------------------------------------------
+    "experimental.session.compacting": async (input, output) => {
+      if (!config.flush.enabled) return
+
+      const sessionID = input.sessionID
+
+      // One flush per compaction cycle per session
+      if (flushedSessions.has(sessionID)) return
+      flushedSessions.add(sessionID)
+
+      // Inject memory flush context into the compaction
+      const today = formatDate(new Date())
+      const flushContext = [
+        "--- MEMORY FLUSH ---",
+        config.flush.systemPrompt,
+        "",
+        `Write durable memories to: workspace/.kortix/memory/${today}.md`,
+        "Update MEMORY.md Scratchpad with: current state, pending items, handoff notes.",
+        "Format daily log entries with timestamps: ## HH:MM — [Topic]",
+        "Only write what's worth remembering. Skip if nothing notable happened.",
+        "--- END MEMORY FLUSH ---",
+      ].join("\n")
+
+      output.context.push(flushContext)
+    },
+
+    // -----------------------------------------------------------------
+    // Hook 3: Session Event Tracking
+    //
+    // Clean up flush tracking when sessions end.
+    // Listen for session events to manage memory lifecycle.
+    // -----------------------------------------------------------------
+    event: async ({ event }) => {
+      // Clean up flush tracking for completed sessions
+      if (event.type === "session.deleted") {
+        const data = event.properties as { id?: string }
+        if (data.id) flushedSessions.delete(data.id)
+      }
+
+      // Reset flush flag when a new compaction cycle might start
+      // (session becomes idle, meaning the previous turn finished)
+      if (event.type === "session.idle") {
+        // Allow future compaction cycles to flush again
+        // This is intentionally NOT clearing the flag here —
+        // it should only be cleared on session delete or new session
+      }
+    },
+  }
+}
+
+export default MemoryPlugin

package/opencode/plugin/worktree/state.ts

@@ -0,0 +1,412 @@
+/**
+ * SQLite State Module for Worktree Plugin
+ *
+ * Provides atomic, crash-safe persistence for worktree sessions and pending operations.
+ * Uses bun:sqlite for zero external dependencies.
+ *
+ * Database location: ~/.local/share/opencode/plugins/worktree/{project-id}.sqlite
+ * Project ID is the first git root commit SHA (40-char hex), with SHA-256 path hash fallback (16-char).
+ */
+
+import { Database } from "bun:sqlite"
+import { mkdirSync } from "node:fs"
+import * as os from "node:os"
+import * as path from "node:path"
+import { z } from "zod"
+import type { OpencodeClient } from "../kdco-primitives"
+import { getProjectId, logWarn } from "../kdco-primitives"
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/** Represents an active worktree session */
+export interface Session {
+	id: string
+	branch: string
+	path: string
+	createdAt: string
+}
+
+/** Pending spawn operation to be processed on session.idle */
+export interface PendingSpawn {
+	branch: string
+	path: string
+	sessionId: string
+}
+
+/** Pending delete operation to be processed on session.idle */
+export interface PendingDelete {
+	branch: string
+	path: string
+}
+
+// =============================================================================
+// SCHEMAS (Boundary Validation)
+// =============================================================================
+
+const sessionSchema = z.object({
+	id: z.string().min(1),
+	branch: z.string().min(1),
+	path: z.string().min(1),
+	createdAt: z.string().min(1),
+})
+
+const pendingSpawnSchema = z.object({
+	branch: z.string().min(1),
+	path: z.string().min(1),
+	sessionId: z.string().min(1),
+})
+
+const pendingDeleteSchema = z.object({
+	branch: z.string().min(1),
+	path: z.string().min(1),
+})
+
+// =============================================================================
+// DATABASE UTILITIES
+// =============================================================================
+
+/**
+ * Get the worktree path for a given project and branch.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param branch - Branch name for the worktree
+ * @returns Absolute path to the worktree directory
+ */
+export async function getWorktreePath(projectRoot: string, branch: string): Promise<string> {
+	if (!branch || typeof branch !== "string") {
+		throw new Error("branch is required")
+	}
+	const projectId = await getProjectId(projectRoot)
+	return path.join(os.homedir(), ".local", "share", "opencode", "worktree", projectId, branch)
+}
+
+/**
+ * Get the database directory path.
+ * Location: ~/.local/share/opencode/plugins/worktree/
+ */
+function getDbDirectory(): string {
+	const home = os.homedir()
+	return path.join(home, ".local", "share", "opencode", "plugins", "worktree")
+}
+
+/**
+ * Get the full database file path for a project.
+ * @param projectRoot - Absolute path to the project root
+ */
+async function getDbPath(projectRoot: string): Promise<string> {
+	const projectId = await getProjectId(projectRoot)
+	return path.join(getDbDirectory(), `${projectId}.sqlite`)
+}
+
+/**
+ * Initialize the SQLite database for worktree state.
+ * Creates the database file and schema if they don't exist.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @returns Configured Database instance
+ *
+ * @example
+ * ```ts
+ * const db = await initStateDb("/home/user/my-project")
+ * const sessions = getAllSessions(db)
+ * db.close()
+ * ```
+ */
+export async function initStateDb(projectRoot: string): Promise<Database> {
+	// Guard: validate project root
+	if (!projectRoot || typeof projectRoot !== "string") {
+		throw new Error("initStateDb requires a valid project root path")
+	}
+
+	const dbPath = await getDbPath(projectRoot)
+	const dbDir = path.dirname(dbPath)
+
+	// Create directory synchronously (required before opening DB)
+	mkdirSync(dbDir, { recursive: true })
+
+	// Open database (creates if doesn't exist)
+	const db = new Database(dbPath)
+
+	// Configure SQLite for concurrent access
+	db.exec("PRAGMA journal_mode=WAL")
+	db.exec("PRAGMA busy_timeout=5000")
+
+	// Create tables with schema
+	db.exec(`
+		CREATE TABLE IF NOT EXISTS sessions (
+			id TEXT PRIMARY KEY,
+			branch TEXT NOT NULL,
+			path TEXT NOT NULL,
+			created_at TEXT NOT NULL
+		)
+	`)
+
+	db.exec(`
+		CREATE TABLE IF NOT EXISTS pending_operations (
+			id INTEGER PRIMARY KEY CHECK (id = 1),
+			type TEXT NOT NULL,
+			branch TEXT NOT NULL,
+			path TEXT NOT NULL,
+			session_id TEXT
+		)
+	`)
+
+	return db
+}
+
+// =============================================================================
+// SESSION CRUD
+// =============================================================================
+
+/**
+ * Add a new session to the database.
+ * Uses atomic INSERT OR REPLACE for idempotency.
+ *
+ * @param db - Database instance from initStateDb
+ * @param session - Session data to persist
+ */
+export function addSession(db: Database, session: Session): void {
+	// Parse at boundary for type safety
+	const parsed = sessionSchema.parse(session)
+
+	const stmt = db.prepare(`
+		INSERT OR REPLACE INTO sessions (id, branch, path, created_at)
+		VALUES ($id, $branch, $path, $createdAt)
+	`)
+
+	stmt.run({
+		$id: parsed.id,
+		$branch: parsed.branch,
+		$path: parsed.path,
+		$createdAt: parsed.createdAt,
+	})
+}
+
+/**
+ * Get a session by ID.
+ *
+ * @param db - Database instance from initStateDb
+ * @param sessionId - Session ID to look up
+ * @returns Session if found, null otherwise
+ */
+export function getSession(db: Database, sessionId: string): Session | null {
+	// Guard: empty session ID
+	if (!sessionId) return null
+
+	const stmt = db.prepare(`
+		SELECT id, branch, path, created_at as createdAt
+		FROM sessions
+		WHERE id = $id
+	`)
+
+	const row = stmt.get({ $id: sessionId }) as Record<string, string> | null
+	if (!row) return null
+
+	return {
+		id: row.id,
+		branch: row.branch,
+		path: row.path,
+		createdAt: row.createdAt,
+	}
+}
+
+/**
+ * Remove a session by branch name.
+ * Deletes all sessions matching the branch.
+ *
+ * @param db - Database instance from initStateDb
+ * @param branch - Branch name to remove
+ */
+export function removeSession(db: Database, branch: string): void {
+	// Guard: empty branch
+	if (!branch) return
+
+	const stmt = db.prepare(`DELETE FROM sessions WHERE branch = $branch`)
+	stmt.run({ $branch: branch })
+}
+
+/**
+ * Get all active sessions.
+ *
+ * @param db - Database instance from initStateDb
+ * @returns Array of all sessions, empty if none
+ */
+export function getAllSessions(db: Database): Session[] {
+	const stmt = db.prepare(`
+		SELECT id, branch, path, created_at as createdAt
+		FROM sessions
+		ORDER BY created_at ASC
+	`)
+
+	const rows = stmt.all() as Array<Record<string, string>>
+	return rows.map((row) => ({
+		id: row.id,
+		branch: row.branch,
+		path: row.path,
+		createdAt: row.createdAt,
+	}))
+}
+
+// =============================================================================
+// PENDING SPAWN OPERATIONS
+// =============================================================================
+
+/**
+ * Set a pending spawn operation. Uses singleton pattern (last-write-wins).
+ *
+ * If a pending spawn already exists, it will be REPLACED and a warning logged.
+ * This is intentional: only the most recent spawn request should be processed.
+ *
+ * @param db - Database instance from initStateDb
+ * @param spawn - Spawn operation data
+ */
+export function setPendingSpawn(db: Database, spawn: PendingSpawn, client?: OpencodeClient): void {
+	// Parse at boundary for type safety
+	const parsed = pendingSpawnSchema.parse(spawn)
+
+	// Check for existing operations and warn about replacement
+	const existingSpawn = getPendingSpawn(db)
+	const existingDelete = getPendingDelete(db)
+
+	if (existingSpawn) {
+		logWarn(
+			client,
+			"worktree",
+			`Replacing pending spawn: "${existingSpawn.branch}" → "${parsed.branch}"`,
+		)
+	} else if (existingDelete) {
+		logWarn(
+			client,
+			"worktree",
+			`Pending spawn replacing pending delete for: "${existingDelete.branch}"`,
+		)
+	}
+
+	// Atomic: replace any existing pending operation
+	const stmt = db.prepare(`
+		INSERT OR REPLACE INTO pending_operations (id, type, branch, path, session_id)
+		VALUES (1, 'spawn', $branch, $path, $sessionId)
+	`)
+
+	stmt.run({
+		$branch: parsed.branch,
+		$path: parsed.path,
+		$sessionId: parsed.sessionId,
+	})
+}
+
+/**
+ * Get the pending spawn operation if one exists.
+ *
+ * @param db - Database instance from initStateDb
+ * @returns PendingSpawn if exists and type is 'spawn', null otherwise
+ */
+export function getPendingSpawn(db: Database): PendingSpawn | null {
+	const stmt = db.prepare(`
+		SELECT type, branch, path, session_id as sessionId
+		FROM pending_operations
+		WHERE id = 1 AND type = 'spawn'
+	`)
+
+	const row = stmt.get() as Record<string, string> | null
+	if (!row) return null
+
+	return {
+		branch: row.branch,
+		path: row.path,
+		sessionId: row.sessionId,
+	}
+}
+
+/**
+ * Clear any pending spawn operation.
+ * Removes the row if it's a spawn type, leaves deletes untouched.
+ *
+ * @param db - Database instance from initStateDb
+ */
+export function clearPendingSpawn(db: Database): void {
+	const stmt = db.prepare(`DELETE FROM pending_operations WHERE id = 1 AND type = 'spawn'`)
+	stmt.run()
+}
+
+// =============================================================================
+// PENDING DELETE OPERATIONS
+// =============================================================================
+
+/**
+ * Set a pending delete operation. Uses singleton pattern (last-write-wins).
+ *
+ * If a pending delete already exists, it will be REPLACED and a warning logged.
+ * This is intentional: only the most recent delete request should be processed.
+ *
+ * @param db - Database instance from initStateDb
+ * @param del - Delete operation data
+ */
+export function setPendingDelete(db: Database, del: PendingDelete, client?: OpencodeClient): void {
+	// Parse at boundary for type safety
+	const parsed = pendingDeleteSchema.parse(del)
+
+	// Check for existing operations and warn about replacement
+	const existingDelete = getPendingDelete(db)
+	const existingSpawn = getPendingSpawn(db)
+
+	if (existingDelete) {
+		logWarn(
+			client,
+			"worktree",
+			`Replacing pending delete: "${existingDelete.branch}" → "${parsed.branch}"`,
+		)
+	} else if (existingSpawn) {
+		logWarn(
+			client,
+			"worktree",
+			`Pending delete replacing pending spawn for: "${existingSpawn.branch}"`,
+		)
+	}
+
+	// Atomic: replace any existing pending operation
+	const stmt = db.prepare(`
+		INSERT OR REPLACE INTO pending_operations (id, type, branch, path, session_id)
+		VALUES (1, 'delete', $branch, $path, NULL)
+	`)
+
+	stmt.run({
+		$branch: parsed.branch,
+		$path: parsed.path,
+	})
+}
+
+/**
+ * Get the pending delete operation if one exists.
+ *
+ * @param db - Database instance from initStateDb
+ * @returns PendingDelete if exists and type is 'delete', null otherwise
+ */
+export function getPendingDelete(db: Database): PendingDelete | null {
+	const stmt = db.prepare(`
+		SELECT type, branch, path
+		FROM pending_operations
+		WHERE id = 1 AND type = 'delete'
+	`)
+
+	const row = stmt.get() as Record<string, string> | null
+	if (!row) return null
+
+	return {
+		branch: row.branch,
+		path: row.path,
+	}
+}
+
+/**
+ * Clear any pending delete operation.
+ * Removes the row if it's a delete type, leaves spawns untouched.
+ *
+ * @param db - Database instance from initStateDb
+ */
+export function clearPendingDelete(db: Database): void {
+	const stmt = db.prepare(`DELETE FROM pending_operations WHERE id = 1 AND type = 'delete'`)
+	stmt.run()
+}