opencode-blackhole 0.0.0-stage → 0.1.0

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./dist/server.js"

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "opencode-blackhole",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Deterministic compaction + observational memory for OpenCode. Replaces the native LLM summarizer with a zero-cost structural summary, and keeps durable session memory across compactions.",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/server.js",
+  "module": "./dist/server.js",
+  "exports": {
+    "./server": {
+      "import": "./dist/server.js"
+    },
+    ".": {
+      "import": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "index.ts",
+    "README.md",
+    "LICENSE",
+    "LICENSE.vendor"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "compaction",
+    "context",
+    "memory",
+    "observational-memory"
+  ],
+  "engines": {
+    "opencode": ">=2.0.28"
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outfile dist/server.js --target node --format esm --external @opencode/plugin",
+    "dev": "bun build src/index.ts --outfile dist/server.js --target node --format esm --external @opencode/plugin --watch",
+    "test": "bun test ./tests",
+    "typecheck": "tsc --noEmit",
+    "check": "bun run typecheck && bun test ./tests && bun run build",
+    "bench": "bun run scripts/bench-capture.ts",
+    "prepublishOnly": "bun run check"
+  },
+  "dependencies": {
+    "@opencode/plugin": "^2.0.32"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "bun-types": "^1.4.3",
+    "typescript": "^5.6.0"
+  },
+  "peerDependencies": {
+    "@opencode/plugin": ">=2.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/adapter/opencode-messages.ts

@@ -0,0 +1,270 @@
+/**
+ * OpenCode → vcc message adapter.
+ *
+ * OpenCode's model-request messages are AI-SDK style: `{ role, content: Part[] }`
+ * where a part is `text`, `reasoning`, `tool-call` or `tool-result`. The vcc
+ * core expects Pi's shape: `{ role, content: string | Part[] }` with
+ * `toolCall` parts, a `toolResult` role and a `bashExecution` role that
+ * carries a command and its output together.
+ *
+ * This adapter is the only place that knows about OpenCode's message format.
+ */
+import type { ContentPart, Message, ToolCall } from "../vcc/pi-types"
+
+interface OpenCodePart {
+  type: string
+  text?: string
+  id?: string
+  name?: string
+  input?: unknown
+  output?: unknown
+  toolCallId?: string
+  mimeType?: string
+  state?: { status?: string; output?: unknown; content?: unknown }
+}
+
+interface OpenCodeMessage {
+  id?: string
+  role: string
+  content?: unknown
+}
+
+/** A tool call, kept so a later tool result can be paired with its call. */
+export interface ToolCallInfo {
+  name: string
+  input: Record<string, unknown>
+}
+
+export interface AdaptedMessages {
+  messages: Message[]
+  /**
+   * Session-global index per adapted message, parallel to `messages`.
+   * `undefined` means the message has no stable index yet.
+   */
+  sourceIndices: Array<number | undefined>
+  /** The previous compaction's summary, when the request starts with a checkpoint. */
+  previousSummary?: string
+  /** The previous compaction's verbatim tail, when present. */
+  previousRecent?: string
+  /** The tool calls known after this batch — pass the map in, get it back. */
+  calls: Map<string, ToolCallInfo>
+}
+
+export interface AdaptOptions {
+  /**
+   * Tool calls already known for the session.
+   *
+   * The adapter is called with only the *new* messages of a request, so a
+   * tool result whose call was captured in an earlier request needs the call
+   * to be supplied from here.
+   */
+  calls?: Map<string, ToolCallInfo>
+  /** Resolve the session-global index of a message id. */
+  resolveIndex?: (id: string) => number | undefined
+}
+
+/**
+ * OpenCode tool names → Pi tool names the vcc core knows about.
+ *
+ * The core matches on Pi's vocabulary (`bash` for shell execution,
+ * `apply_patch` for multi-file edits) to decide what is a file read, a file
+ * write, or a shell command worth ranking.
+ */
+const TOOL_NAME_MAP: Record<string, string> = {
+  shell: "bash",
+  bash: "bash",
+  patch: "apply_patch",
+  apply_patch: "apply_patch",
+  multiedit: "multiedit",
+  write: "write",
+  edit: "edit",
+  read: "read",
+  view: "read",
+  glob: "glob",
+  grep: "grep",
+  list: "list",
+  todowrite: "todowrite",
+  webfetch: "webfetch",
+  websearch: "websearch",
+}
+
+const mapToolName = (name: string): string => TOOL_NAME_MAP[name.toLowerCase()] ?? name
+
+const textOf = (content: unknown): string => {
+  if (typeof content === "string") return content
+  if (!Array.isArray(content)) return ""
+  return content
+    .map((part) => {
+      const p = part as OpenCodePart
+      if (p?.type === "text" && typeof p.text === "string") return p.text
+      return ""
+    })
+    .filter(Boolean)
+    .join("\n")
+}
+
+const partsOf = (message: OpenCodeMessage): OpenCodePart[] => {
+  const raw = message.content
+  if (typeof raw === "string") return [{ type: "text", text: raw }]
+  if (!Array.isArray(raw)) return []
+  return raw as OpenCodePart[]
+}
+
+/** Tool result payloads arrive as a string or as `{ content, metadata }`. */
+const toolResultText = (part: OpenCodePart): string => {
+  const output = part.output ?? part.state?.output ?? part.state?.content
+  if (typeof output === "string") return output
+  if (output && typeof output === "object") {
+    const content = (output as { content?: unknown }).content
+    if (typeof content === "string") return content
+    if (Array.isArray(content)) {
+      return content
+        .map((item) => {
+          if (typeof item === "string") return item
+          if (item && typeof item === "object") {
+            const text = (item as { text?: unknown }).text
+            if (typeof text === "string") return text
+          }
+          return ""
+        })
+        .filter(Boolean)
+        .join("\n")
+    }
+    try {
+      return JSON.stringify(output)
+    } catch {
+      return ""
+    }
+  }
+  return textOf(part.output)
+}
+
+const exitCodeOf = (part: OpenCodePart): number | undefined => {
+  const output = part.output ?? part.state?.output
+  if (output && typeof output === "object") {
+    const metadata = (output as { metadata?: { exit?: number } }).metadata
+    if (typeof metadata?.exit === "number") return metadata.exit
+  }
+  return undefined
+}
+
+const CHECKPOINT_OPEN = "<conversation-checkpoint>"
+const CHECKPOINT_CLOSE = "</conversation-checkpoint>"
+
+/** Parse OpenCode's checkpoint wrapper (a completed compaction message). */
+const parseCheckpoint = (text: string): { summary?: string; recent?: string } | undefined => {
+  if (!text.includes(CHECKPOINT_OPEN) || !text.includes(CHECKPOINT_CLOSE)) return undefined
+  const summary = /<summary>\n?([\s\S]*?)\n?<\/summary>/.exec(text)?.[1]
+  const recent = /<recent-context>\n?([\s\S]*?)\n?<\/recent-context>/.exec(text)?.[1]
+  return { summary, recent }
+}
+
+/**
+ * Convert OpenCode messages into the vcc core's message shape.
+ *
+ * Shell executions are folded back into Pi's `bashExecution` role so the core's
+ * shell-aware ranking, commit extraction and tracked-command extraction all
+ * keep working.
+ */
+export const adaptMessages = (
+  messages: readonly OpenCodeMessage[],
+  options: AdaptOptions = {},
+): AdaptedMessages => {
+  const resolveIndex = options.resolveIndex
+  // The call map persists across requests, so a result can be paired with a
+  // call that was captured earlier in the session.
+  const calls = options.calls ?? new Map<string, ToolCallInfo>()
+
+  // Pass 1: index tool calls so results can be paired with their call.
+  for (const message of messages) {
+    if (message.role !== "assistant") continue
+    for (const part of partsOf(message)) {
+      if (part.type !== "tool-call" || !part.id) continue
+      if (calls.has(part.id)) continue
+      calls.set(part.id, {
+        name: mapToolName(part.name ?? "tool"),
+        input:
+          part.input && typeof part.input === "object"
+            ? (part.input as Record<string, unknown>)
+            : {},
+      })
+    }
+  }
+
+  const out: Message[] = []
+  const sourceIndices: Array<number | undefined> = []
+  let previousSummary: string | undefined
+  let previousRecent: string | undefined
+
+  const push = (message: Message, id?: string) => {
+    out.push(id ? { ...message, id } : message)
+    sourceIndices.push(id && resolveIndex ? resolveIndex(id) : undefined)
+  }
+  for (const message of messages) {
+    const parts = partsOf(message)
+
+    if (message.role === "user") {
+      const text = textOf(message.content)
+      const checkpoint = parseCheckpoint(text)
+      if (checkpoint) {
+        previousSummary = checkpoint.summary
+        previousRecent = checkpoint.recent
+        continue
+      }
+      const content: ContentPart[] = []
+      for (const part of parts) {
+        if (part.type === "text" && part.text) content.push({ type: "text", text: part.text })
+      }
+      if (content.length > 0) push({ role: "user", content }, message.id)
+      continue
+    }
+
+    if (message.role === "assistant") {
+      const content: ContentPart[] = []
+      for (const part of parts) {
+        if (part.type === "text" && part.text) content.push({ type: "text", text: part.text })
+        else if (part.type === "tool-call") {
+          const call = calls.get(part.id ?? "")
+          content.push({
+            type: "toolCall",
+            id: part.id ?? "",
+            name: call?.name ?? mapToolName(part.name ?? "tool"),
+            arguments: call?.input ?? {},
+          })
+        }
+      }
+      if (content.length > 0) push({ role: "assistant", content }, message.id)
+      continue
+    }
+
+    if (message.role === "tool") {
+      let seen = 0
+      for (const part of parts) {
+        if (part.type !== "tool-result") continue
+        const call = calls.get(part.toolCallId ?? "")
+        const name = call?.name ?? mapToolName(part.name ?? "tool")
+        const text = toolResultText(part)
+        // One OpenCode tool message can carry several results; keep a stable
+        // id per result so the transcript store can index them separately.
+        const id = seen === 0 ? message.id : `${message.id}~${part.toolCallId ?? seen}`
+        seen++
+        if (name === "bash") {
+          push(
+            {
+              role: "bashExecution",
+              command: typeof call?.input.command === "string" ? (call.input.command as string) : "",
+              output: text,
+              exitCode: exitCodeOf(part),
+            },
+            id,
+          )
+        } else {
+          push({ role: "toolResult", toolName: name, content: text }, id)
+        }
+      }
+      continue
+    }
+  }
+
+  return { messages: out, sourceIndices, previousSummary, previousRecent, calls }
+}

package/src/compaction/build.ts

@@ -0,0 +1,264 @@
+/**
+ * Deterministic summary construction for OpenCode's compaction hook.
+ *
+ * The vcc core produces the summary; this module adapts OpenCode's messages,
+ * sizes the brief transcript against a token budget, and enforces the safety
+ * valve: if the extraction yields nothing useful, we return no result at all
+ * so OpenCode falls back to its own summarizer.
+ */
+import { adaptMessages } from "../adapter/opencode-messages"
+import { stripHandoff } from "./handoff"
+import { compileRanked } from "../vcc/core/summarize"
+import {
+  calibrateCharsPerToken,
+  DEFAULT_CHARS_PER_TOKEN,
+  estimateTokensFromChars,
+} from "../vcc/core/token-estimate"
+import type { FileOps } from "../vcc/types"
+
+export interface BuildSummaryInput {
+  /** The compaction hook's request messages. */
+  messages: readonly unknown[]
+  /** Session-global index resolver, keyed by OpenCode message id. */
+  resolveIndex?: (id: string) => number | undefined
+  /**
+   * Authoritative file activity for the whole session. OpenCode keeps the
+   * newest exchange out of the summarization request (it is retained
+   * verbatim), so files touched there are only known from the transcript.
+   */
+  fileOps?: FileOps
+  /** Token budget for the brief transcript. */
+  briefTokens: number
+  /** Hard cap for the whole summary. */
+  maxSummaryTokens: number
+  /** Extra note appended to the summary (project conventions, etc.). */
+  extraNote?: string
+}
+
+export interface BuildSummaryResult {
+  summary?: string
+  /** Estimated size of the summary, in tokens. */
+  tokens?: number
+  /** The previous checkpoint's summary, when the request started with one. */
+  previousSummary?: string
+  /** True when the previous checkpoint was reused because nothing new was in the window. */
+  carried?: boolean
+  /** Why the summary was rejected, when it was. */
+  rejected?: string
+}
+
+const SECTION_MARKERS = ["[Session Goal]", "[Files And Changes]", "[Commits]", "[Outstanding Context]"]
+const SEPARATOR = "\n\n---\n\n"
+
+/**
+ * The vcc core ends every summary with a recall hint naming Pi's `vcc_recall`
+ * tool. We keep the vendored core pristine so upstream stays mergeable, and
+ * rewrite the hint here to name OpenCode's tool.
+ */
+const RECALL_TOOL = "blackhole_recall"
+const rewriteRecallNote = (summary: string): string => summary.replace(/`vcc_recall`/g, "`" + RECALL_TOOL + "`")
+
+/**
+ * Split a compiled summary into three parts: the section headers, the brief
+ * transcript and the trailing recall note.
+ *
+ * The vcc format is `sections --- brief --- note`, and the separator appears
+ * once or twice depending on whether there were sections.
+ */
+const splitSummary = (summary: string): { head: string; brief: string; note: string } => {
+  let body = summary
+  let note = ""
+
+  const noteIndex = body.lastIndexOf(SEPARATOR)
+  if (noteIndex >= 0) {
+    const tail = body.slice(noteIndex + SEPARATOR.length)
+    if (tail.includes("recall")) {
+      note = tail.trim()
+      body = body.slice(0, noteIndex).trim()
+    }
+  }
+
+  const index = body.indexOf(SEPARATOR)
+  if (index < 0) {
+    const startsWithSection = SECTION_MARKERS.some((marker) => body.trimStart().startsWith(marker))
+    return startsWithSection ? { head: body.trim(), brief: "", note } : { head: "", brief: body.trim(), note }
+  }
+  return {
+    head: body.slice(0, index).trim(),
+    brief: body.slice(index + SEPARATOR.length).trim(),
+    note,
+  }
+}
+
+/**
+ * Trim a section's bullet list to fit a character budget, dropping the
+ * oldest lines first (the brief transcript is the only part that can grow
+ * without bound).
+ */
+const trimToChars = (text: string, maxChars: number): string => {
+  if (text.length <= maxChars) return text
+  const lines = text.split("\n")
+  const kept: string[] = []
+  let size = 0
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i]
+    if (size + line.length + 1 > maxChars) break
+    kept.unshift(line)
+    size += line.length + 1
+  }
+  if (kept.length > 0) return kept.join("\n")
+  // The last line alone is over budget: cut it instead of dropping it.
+  const last = lines[lines.length - 1] ?? ""
+  return last.slice(0, Math.max(0, maxChars))
+}
+
+/**
+ * Trim a summary's header sections to fit a character budget.
+ *
+ * Section headers are kept (they carry the structure); the bullet lists under
+ * them give way first, oldest lines first, so the most recent facts survive.
+ */
+const trimSections = (head: string, maxChars: number): string => {
+  if (head.length <= maxChars) return head
+  const lines = head.split("\n")
+  const kept: string[] = []
+  let size = 0
+  for (const line of lines) {
+    const isHeader = line.startsWith("[")
+    const cost = line.length + 1
+    if (!isHeader && size + cost > maxChars) continue
+    if (isHeader && size + cost > maxChars) break
+    kept.push(line)
+    size += cost
+  }
+  return kept.join("\n").trim()
+}
+
+export const buildSummary = (input: BuildSummaryInput): BuildSummaryResult => {
+  const { messages, resolveIndex, fileOps, briefTokens, maxSummaryTokens, extraNote } = input
+  if (!Array.isArray(messages) || messages.length === 0) return { rejected: "no messages" }
+
+  const adapted = adaptMessages(messages as any[], { resolveIndex })
+  // A compaction request can carry the previous checkpoint and nothing else:
+  // the window since the last compaction held no new text. That is not an
+  // empty conversation - the checkpoint *is* the conversation now. Upstream
+  // merges the checkpoint's sections in this case; declining it hands the
+  // compaction back to OpenCode's own summarizer, which is the one thing
+  // this plugin exists to prevent.
+  const previous = adapted.previousSummary?.trim()
+  if (adapted.messages.length === 0 && !previous) return { rejected: "no conversation content" }
+
+  // Chars-per-token: heuristic unless the caller can calibrate. OpenCode does
+  // not expose the last request's token usage to plugins, so we use the
+  // conservative default and let the token cap do the real work.
+  const charsPerToken = DEFAULT_CHARS_PER_TOKEN
+
+  // A request that carries only the previous checkpoint has nothing new to
+  // summarise. Rebuilding it from its own sections was both wasteful and the
+  // source of the stacked handoff blocks: the rebuilt checkpoint looked like
+  // "fresh" content, so the hook appended another block every time.
+  if (adapted.messages.length === 0 && previous) {
+    const carried = rewriteRecallNote(previous)
+    return {
+      summary: carried,
+      tokens: estimateTokensFromChars(carried.length, charsPerToken),
+      previousSummary: adapted.previousSummary,
+      carried: true,
+    }
+  }
+  // 0 (or less) means no brief at all: do not pay for a floor the caller
+  // explicitly turned off.
+  const briefChars = briefTokens <= 0 ? 0 : Math.max(400, Math.round(briefTokens * charsPerToken))
+
+  let summary = compileRanked({
+    messages: adapted.messages,
+    sourceIndices: adapted.sourceIndices,
+    // The handoff block is not a section: strip it before merging so a
+    // section that has no fresh counterpart cannot carry the whole block
+    // forward verbatim. The raw checkpoint still goes to the handoff prompt.
+    previousSummary: previous ? stripHandoff(previous) : undefined,
+    fileOps,
+    ranking: {
+      maxBriefChars: briefChars,
+      maxBriefCharsCeiling: Math.round(briefChars * 1.5),
+      briefCharsPerBlock: Math.round(15 * charsPerToken),
+      maxBlocks: 64,
+      // Upstream keeps the newest 16 blocks whatever their score
+      // (rank.ts: `options.preserveRecentBlocks ?? DEFAULT_RECENT_BLOCKS`).
+      // A smaller value lets older, higher-scoring blocks - bug reports and
+      // diffs - crowd out the turns the brief exists to preserve.
+      preserveRecentBlocks: 16,
+    },
+  })
+
+  let { head, brief, note } = splitSummary(summary)
+  if (briefTokens <= 0) brief = ""
+
+  // Enforce the hard cap: the brief transcript is trimmed first, then the
+  // section bullets, and only then is the summary rejected outright.
+  const maxChars = Math.max(600, Math.round(maxSummaryTokens * charsPerToken))
+  if (brief.length > 0) {
+    const room = maxChars - head.length
+    if (room <= 200) {
+      brief = ""
+    } else {
+      brief = trimToChars(brief, room)
+    }
+  }
+
+  const hasSections = SECTION_MARKERS.some((marker) => head.includes(marker))
+  if (!hasSections && brief.length === 0) {
+    // Nothing new to extract. The previous checkpoint still summarises the
+    // conversation, so it is carried forward rather than paying a model to
+    // rewrite it.
+    if (previous) {
+      const carried = rewriteRecallNote(previous)
+      return {
+        summary: carried,
+        tokens: estimateTokensFromChars(carried.length, charsPerToken),
+        previousSummary: adapted.previousSummary,
+        carried: true,
+      }
+    }
+    return { rejected: "extraction produced no usable content", previousSummary: adapted.previousSummary }
+  }
+
+  const assemble = (parts: string[]) => parts.filter((part) => part.length > 0).join(SEPARATOR)
+  const withNote = (h: string, b: string) => rewriteRecallNote(assemble([h, b, note]))
+
+  summary = withNote(head, brief)
+  if (extraNote && extraNote.trim()) {
+    summary = `${summary}\n\n${extraNote.trim()}`
+  }
+
+  let tokens = estimateTokensFromChars(summary.length, charsPerToken)
+  if (tokens > maxSummaryTokens) {
+    // Drop the recall note first, then the brief, then trim the section
+    // bullets — the summary is only rejected when nothing usable is left.
+    summary = rewriteRecallNote(assemble([head, brief]))
+    tokens = estimateTokensFromChars(summary.length, charsPerToken)
+    if (tokens > maxSummaryTokens && brief.length > 0) {
+      summary = rewriteRecallNote(head)
+      tokens = estimateTokensFromChars(summary.length, charsPerToken)
+    }
+    if (tokens > maxSummaryTokens) {
+      const headerOnly = trimSections(head, maxChars)
+      const headerTokens = estimateTokensFromChars(headerOnly.length, charsPerToken)
+      if (headerTokens > maxSummaryTokens) {
+        return { rejected: "summary exceeded the token cap", previousSummary: adapted.previousSummary }
+      }
+      summary = headerOnly
+    }
+    if (extraNote && extraNote.trim()) {
+      summary = `${summary}\n\n${extraNote.trim()}`
+    }
+  }
+
+  return {
+    summary,
+    tokens: estimateTokensFromChars(summary.length, charsPerToken),
+    previousSummary: adapted.previousSummary,
+  }
+}
+
+export { calibrateCharsPerToken }