opencodekit 0.23.0 → 0.23.2

package/dist/template/.opencode/plugin/session-summary.ts

@@ -0,0 +1,542 @@
+/**
+ * Session Summary Plugin — Structured Persistent Context
+ *
+ * Maintains a structured, incrementally-updated session summary that survives
+ * DCP compression cycles ("anchored iterative summarization" — inspired by
+ * Factory.ai's approach). Tracks:
+ *
+ * 1. File artifact trail — which files were read, modified, or created
+ * 2. Decisions — what was decided and why (rationale + alternatives)
+ * 3. Session intent and state — what we're doing and where we are
+ * 4. Continuation — next steps to resume work without re-fetching
+ *
+ * On each system.transform, the summary is injected into context.
+ * On compaction, the summary is persisted to disk so it survives the cycle.
+ * The anchored design means we merge new information incrementally rather
+ * than regenerating from scratch (avoiding semantic drift per Factory's research).
+ *
+ * Persistence: .opencode/state/session-summary.md
+ * Hooks: tool.execute.before, experimental.chat.system.transform, experimental.session.compacting
+ *
+ * Inspired by: https://factory.ai/news/evaluating-compression
+ */
+import fs from "node:fs";
+import path from "node:path";
+import type { Plugin } from "@opencode-ai/plugin";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface Decision {
+  what: string;
+  rationale: string;
+}
+
+interface SessionSummaryData {
+  intent: string;
+  state: "exploring" | "implementing" | "verifying" | "done" | "unknown";
+  files: {
+    modified: Map<string, string>; // path → what changed
+    created: Set<string>; // paths
+    read: Map<string, string>; // path → why examined / key finding
+  };
+  decisions: Decision[];
+  nextSteps: string[];
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** Max artifact entries before we start evicting oldest reads */
+const MAX_READS = 30;
+const MAX_MODIFIED = 20;
+const MAX_CREATED = 10;
+const MAX_DECISIONS = 10;
+const MAX_NEXT_STEPS = 8;
+/** Target summary size in chars (~400 tokens * ~4 chars/token) */
+const MAX_SUMMARY_CHARS = 1600;
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Extract a short change description from edit tool args.
+ */
+function extractEditDetail(args: Record<string, unknown>): string {
+  const oldStr = String(args.oldString ?? "").trim();
+  const newStr = String(args.newString ?? "").trim();
+  if (!oldStr || !newStr) return "Modified";
+
+  // If old is much longer than new, it's a deletion/truncation
+  if (oldStr.length > newStr.length * 3) return "Truncated/reduced content";
+  // If new is much longer than old, it's an addition
+  if (newStr.length > oldStr.length * 3) return "Expanded content";
+  // Single-line change: show the first line
+  const oldLine = oldStr.split("\n")[0]?.trim() ?? "";
+  const newLine = newStr.split("\n")[0]?.trim() ?? "";
+  if (oldLine && newLine && oldLine !== newLine) {
+    const maxLen = 60;
+    const shortOld = oldLine.length > maxLen ? `${oldLine.slice(0, maxLen)}…` : oldLine;
+    const shortNew = newLine.length > maxLen ? `${newLine.slice(0, maxLen)}…` : newLine;
+    return `"${shortOld}" → "${shortNew}"`;
+  }
+  return "Modified";
+}
+
+/**
+ * Normalize file path: strip leading ./ and cwd prefix.
+ */
+function normalizePath(filePath: string, cwd: string): string {
+  let normalized = filePath.startsWith("./") ? filePath.slice(2) : filePath;
+
+  // Strip path:line or path:start-end suffix (from srcwalk_read path:line format).
+  // e.g., "src/app.ts:44-89" → "src/app.ts"
+  normalized = normalized.replace(/:\d+(-\d+)?$/, "");
+
+  // If it's an absolute path, try to make it relative to cwd
+  if (path.isAbsolute(normalized)) {
+    const relative = path.relative(cwd, normalized);
+    // If relative doesn't start with .., it's inside cwd
+    if (!relative.startsWith("..")) return relative;
+    // Otherwise keep absolute but shortened
+    return normalized;
+  }
+  return normalized;
+}
+
+/**
+ * Format the summary for context injection (compact markdown).
+ * Uses XML-like block for easy delimiting in system prompt.
+ */
+function formatSummary(s: SessionSummaryData): string {
+  const lines: string[] = [`intent: ${s.intent}`, `state: ${s.state}`, ""];
+
+  // Files section
+  const fileParts: string[] = [];
+
+  if (s.files.created.size > 0) {
+    fileParts.push(`created: ${[...s.files.created].map((p) => `\`${p}\``).join(", ")}`);
+  }
+
+  if (s.files.modified.size > 0) {
+    for (const [p, detail] of s.files.modified) {
+      fileParts.push(`modified: \`${p}\` — ${detail}`);
+    }
+  }
+
+  if (s.files.read.size > 0) {
+    // Only include reads that have a reason, plus a summary count
+    const readsWithReason = [...s.files.read.entries()].filter(([, r]) => r.length > 0);
+    if (readsWithReason.length > 0) {
+      for (const [p, reason] of readsWithReason) {
+        fileParts.push(`read: \`${p}\` — ${reason}`);
+      }
+    }
+    // Always note total read count
+    const extraReads = s.files.read.size - readsWithReason.length;
+    if (extraReads > 0) {
+      fileParts.push(`read: ${extraReads} more files (no specific notes)`);
+    }
+  }
+
+  if (fileParts.length > 0) {
+    lines.push("== files ==");
+    lines.push(...fileParts);
+    lines.push("");
+  }
+
+  // Decisions section
+  if (s.decisions.length > 0) {
+    lines.push("== decisions ==");
+    for (const d of s.decisions) {
+      const maxWhat = 120;
+      const what = d.what.length > maxWhat ? `${d.what.slice(0, maxWhat)}…` : d.what;
+      const maxRat = 200;
+      const rationale =
+        d.rationale.length > maxRat ? `${d.rationale.slice(0, maxRat)}…` : d.rationale;
+      lines.push(`- ${what} | ${rationale}`);
+    }
+    lines.push("");
+  }
+
+  // Next steps
+  if (s.nextSteps.length > 0) {
+    lines.push("== next ==");
+    for (const step of s.nextSteps) {
+      lines.push(`- ${step}`);
+    }
+    lines.push("");
+  }
+
+  let result = lines.join("\n").trim();
+
+  // Trim to max chars at line boundary
+  if (result.length > MAX_SUMMARY_CHARS) {
+    result = result.slice(0, MAX_SUMMARY_CHARS);
+    const lastNewline = result.lastIndexOf("\n");
+    if (lastNewline > 0) result = result.slice(0, lastNewline);
+    result += "\n… (summary truncated)";
+  }
+
+  return result;
+}
+
+/**
+ * Serialize summary to compact line-based format for disk persistence.
+ * Each section uses a single-letter prefix for parseability.
+ */
+function serializeSummary(s: SessionSummaryData): string {
+  const lines: string[] = [];
+  lines.push(`I: ${s.intent}`);
+  lines.push(`S: ${s.state}`);
+
+  for (const p of s.files.created) {
+    lines.push(`C: ${p}`);
+  }
+  for (const [p, d] of s.files.modified) {
+    const detail = d.replace(/\n/g, " ");
+    if (detail) {
+      lines.push(`M: ${p} | ${detail}`);
+    } else {
+      lines.push(`M: ${p}`);
+    }
+  }
+  for (const [p, r] of s.files.read) {
+    const reason = r.replace(/\n/g, " ");
+    if (reason) {
+      lines.push(`R: ${p} | ${reason}`);
+    } else {
+      lines.push(`R: ${p}`);
+    }
+  }
+  for (const d of s.decisions) {
+    const what = d.what.replace(/\n/g, " ");
+    const rat = d.rationale.replace(/\n/g, " ");
+    if (rat) {
+      lines.push(`D: ${what} | ${rat}`);
+    } else {
+      lines.push(`D: ${what}`);
+    }
+  }
+  for (const step of s.nextSteps) {
+    lines.push(`N: ${step}`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Parse the serialized format back into a SessionSummaryData.
+ */
+function deserializeSummary(text: string): SessionSummaryData {
+  const summary: SessionSummaryData = {
+    intent: "",
+    state: "unknown",
+    files: {
+      modified: new Map(),
+      created: new Set(),
+      read: new Map(),
+    },
+    decisions: [],
+    nextSteps: [],
+  };
+
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.length < 3) continue;
+
+    const prefix = trimmed[0];
+    const content = trimmed.slice(2).trim();
+
+    if (!content) continue;
+
+    switch (prefix) {
+      case "I":
+        summary.intent = content;
+        break;
+      case "S":
+        if (["exploring", "implementing", "verifying", "done", "unknown"].includes(content)) {
+          summary.state = content as SessionSummaryData["state"];
+        }
+        break;
+      case "C":
+        summary.files.created.add(content);
+        break;
+      case "M": {
+        const pipeIdx = content.indexOf(" | ");
+        if (pipeIdx > 0) {
+          summary.files.modified.set(content.slice(0, pipeIdx), content.slice(pipeIdx + 3).trim());
+        } else {
+          summary.files.modified.set(content, "Modified");
+        }
+        break;
+      }
+      case "R": {
+        const pipeIdx = content.indexOf(" | ");
+        if (pipeIdx > 0) {
+          summary.files.read.set(content.slice(0, pipeIdx), content.slice(pipeIdx + 3).trim());
+        } else {
+          summary.files.read.set(content, "");
+        }
+        break;
+      }
+      case "D": {
+        const pipeIdx = content.indexOf(" | ");
+        if (pipeIdx > 0) {
+          summary.decisions.push({
+            what: content.slice(0, pipeIdx),
+            rationale: content.slice(pipeIdx + 3).trim(),
+          });
+        } else {
+          summary.decisions.push({ what: content, rationale: "" });
+        }
+        break;
+      }
+      case "N":
+        summary.nextSteps.push(content);
+        break;
+    }
+  }
+
+  return summary;
+}
+
+// ============================================================================
+// Enforce max sizes — evict oldest entries
+// ============================================================================
+
+function enforceLimits(summary: SessionSummaryData): void {
+  // Reads: keep newest (Map preserves insertion order)
+  if (summary.files.read.size > MAX_READS) {
+    const entries = [...summary.files.read.entries()];
+    summary.files.read = new Map(entries.slice(entries.length - MAX_READS));
+  }
+  if (summary.files.modified.size > MAX_MODIFIED) {
+    const entries = [...summary.files.modified.entries()];
+    summary.files.modified = new Map(entries.slice(entries.length - MAX_MODIFIED));
+  }
+  if (summary.files.created.size > MAX_CREATED) {
+    summary.files.created = new Set([...summary.files.created].slice(-MAX_CREATED));
+  }
+  if (summary.decisions.length > MAX_DECISIONS) {
+    summary.decisions = summary.decisions.slice(-MAX_DECISIONS);
+  }
+  if (summary.nextSteps.length > MAX_NEXT_STEPS) {
+    summary.nextSteps = summary.nextSteps.slice(-MAX_NEXT_STEPS);
+  }
+}
+
+// ============================================================================
+// Helper: addRead with dedup and reason preservation
+// ============================================================================
+
+function addRead(summary: SessionSummaryData, filePath: string, reason = ""): void {
+  // If already tracked as read, update reason only if new one is non-empty
+  if (summary.files.read.has(filePath) && !reason) return;
+  // Re-insert to update insertion order (move to "newest")
+  summary.files.read.delete(filePath);
+  summary.files.read.set(filePath, reason);
+}
+
+function addModified(summary: SessionSummaryData, filePath: string, detail: string): void {
+  summary.files.modified.set(filePath, detail);
+  // Remove from created if it was tracked as created
+  summary.files.created.delete(filePath);
+}
+
+function addDecision(summary: SessionSummaryData, what: string, rationale: string): void {
+  summary.decisions.push({ what, rationale });
+}
+
+function addCreated(summary: SessionSummaryData, filePath: string): void {
+  summary.files.created.add(filePath);
+}
+
+// ============================================================================
+// Persistence
+// ============================================================================
+
+function ensureDir(dir: string): void {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function loadSummary(filePath: string): SessionSummaryData {
+  try {
+    if (fs.existsSync(filePath)) {
+      const text = fs.readFileSync(filePath, "utf-8").trim();
+      if (text) return deserializeSummary(text);
+    }
+  } catch {
+    /* Corrupted or missing — start fresh */
+  }
+  return {
+    intent: "",
+    state: "unknown",
+    files: { modified: new Map(), created: new Set(), read: new Map() },
+    decisions: [],
+    nextSteps: [],
+  };
+}
+
+function saveSummary(filePath: string, summary: SessionSummaryData): void {
+  try {
+    ensureDir(path.dirname(filePath));
+    fs.writeFileSync(filePath, serializeSummary(summary), "utf-8");
+  } catch {
+    /* Non-fatal — summary is best-effort */
+  }
+}
+
+// ============================================================================
+// Plugin Export
+// ============================================================================
+
+export const SessionSummaryPlugin: Plugin = async ({ client, directory }) => {
+  const cwd = process.cwd();
+  const stateDir = path.join(directory, ".opencode", "state");
+  const summaryPath = path.join(stateDir, "session-summary.md");
+
+  // Load persisted summary (survives compaction)
+  const summary = loadSummary(summaryPath);
+
+  // Helper to log
+  const log = async (message: string, level: "info" | "warn" = "info") => {
+    try {
+      await client.app.log({
+        body: { service: "session-summary", level, message },
+      });
+    } catch {
+      /* Best-effort */
+    }
+  };
+
+  // Attempt to guess intent from the first user message we see
+  let intentGuessed = summary.intent.length > 0;
+
+  return {
+    // ================================================================
+    // File-Artifact Instrumentation
+    // Intercept tool calls before execution to track file operations.
+    // ================================================================
+    "tool.execute.before": async (input, output) => {
+      const tool = input.tool?.toLowerCase() ?? "";
+      const args = (output.args as Record<string, unknown>) ?? {};
+      const filePath = String(args.filePath ?? args.path ?? "").trim();
+
+      if (!filePath) return;
+
+      const normalized = normalizePath(filePath, cwd);
+
+      switch (tool) {
+        case "read":
+          addRead(summary, normalized);
+          break;
+        case "edit":
+          addModified(summary, normalized, extractEditDetail(args));
+          break;
+        case "write": {
+          // Distinguish create from overwrite
+          const absolutePath = path.isAbsolute(normalized)
+            ? normalized
+            : path.join(cwd, normalized);
+          if (!fs.existsSync(absolutePath)) {
+            addCreated(summary, normalized);
+          }
+          addModified(summary, normalized, "Written/created");
+          break;
+        }
+        case "srcwalk_read":
+          addRead(summary, normalized, "Code navigation");
+          break;
+        case "grep":
+        case "srcwalk_search":
+        case "glob":
+        case "srcwalk_files":
+          // Search tools — not tracking individual files
+          break;
+      }
+    },
+
+    // ================================================================
+    // Context Injection
+    // Inject the structured summary into the system prompt on every
+    // system.transform cycle, so it's always available after DCP
+    // compression clears older conversation spans.
+    // ================================================================
+    "experimental.chat.system.transform": async (_input, output) => {
+      // If summary is empty, don't waste tokens
+      const hasContent =
+        summary.intent ||
+        summary.files.modified.size > 0 ||
+        summary.files.created.size > 0 ||
+        summary.decisions.length > 0;
+
+      if (!hasContent) return;
+
+      const formatted = formatSummary(summary);
+      output.system.push(`\n<session_summary>\n${formatted}\n</session_summary>`);
+    },
+
+    // ================================================================
+    // Compaction Anchor
+    // Before DCP compression fires:
+    // 1. Persist the summary to disk (so it survives the compression)
+    // 2. Instruct the summarizer to preserve the summary's data
+    // ================================================================
+    "experimental.session.compacting": async (_input, output) => {
+      // Persist current summary state
+      enforceLimits(summary);
+      saveSummary(summaryPath, summary);
+      await log("Session summary persisted for compaction");
+
+      // Add instructions to the compaction prompt
+      const existingPrompt = output.prompt ?? "";
+      output.prompt = `${existingPrompt}
+
+<session_summary_anchor>
+The session artifact trail is tracked in .opencode/state/session-summary.md.
+Preserve all file paths, decisions, and next steps noted there.
+Include the updated summary in your compression output.
+</session_summary_anchor>`;
+    },
+
+    // ================================================================
+    // Generic Event Handler
+    // Capture session intent from first user message.
+    // Also hook observation(type:decision) to auto-track decisions.
+    // ================================================================
+    event: async (input: unknown) => {
+      const ev = (input as { event?: { type?: string; properties?: Record<string, unknown> } })
+        ?.event;
+      if (!ev?.type) return;
+
+      // Capture session intent from first substantive user message
+      if (!intentGuessed && ev.type === "message.updated") {
+        const props = ev.properties as Record<string, unknown> | undefined;
+        const content = props?.content as string | undefined;
+        if (content && content.length > 10 && content.length < 500) {
+          summary.intent = content.slice(0, 200);
+          intentGuessed = true;
+        }
+      }
+
+      // Track decisions from observation tool
+      if (ev.type === "tool.execute.after") {
+        const props = ev.properties as Record<string, unknown> | undefined;
+        if (props?.tool === "observation") {
+          const args = props?.args as Record<string, unknown> | undefined;
+          if (args?.type === "decision" && args?.title) {
+            addDecision(summary, String(args.title), String(args.narrative ?? args.content ?? ""));
+          }
+        }
+      }
+    },
+  };
+};
+
+export default SessionSummaryPlugin;