opencode-consistent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nguyen Phan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# opencode-consistent
+
+OpenCode rebuilds the system prompt on every turn. `Today's date`, cwd, git, AGENTS.md, MCP instructions, and the skill list all go back in from live disk. Prefix caches hash from token 0, so one changed byte after the tools block misses the whole session.
+
+This plugin snapshots that system prefix on the first real turn of a session and puts the same bytes back on every later turn. Time can land at session start. It does not move while you work.
+
+Measured on a homelab vLLM pair: a 186k OpenCode resume after 60 minutes idle came back with 1,792 cached tokens (the built-in tool schemas) and prefilling the rest. Sibling sessions on the same key were at 99.9%. The GPU still had the old prefix. OpenCode had sent a different one.
+
+Upstream knows. [#32622](https://github.com/anomalyco/opencode/issues/32622) (date in the cached prefix, closed not-planned), [#29672](https://github.com/anomalyco/opencode/issues/29672), [PR #29949](https://github.com/anomalyco/opencode/pull/29949) (move env to the tail, not default as of 1.18.27). `OPENCODE_EXPERIMENTAL_CACHE_STABILIZATION` did not ship in 1.18.x runtime flags.
+
+## Install
+
+Put it **last** in the plugin list so other plugins mutate first, then this freezes the result:
+
+```json
+{
+  "plugin": [
+    "opencode-consistent"
+  ]
+}
+```
+
+Restart OpenCode. Plugins load at process start.
+
+## What it freezes
+
+The joined system string OpenCode sends to the model (env + instructions + MCP instructions + skills). Per `sessionID`, in memory, for that process.
+
+Title-generation uses the same sessionID with no `<env>` block. Those calls are ignored so they cannot poison the snapshot.
+
+## What it does not freeze
+
+The MCP **tool list**. If a server appears or disappears mid-session, tool schemas after the built-in set can still break the hash. Env/date/AGENTS.md will not.
+
+A process restart drops the snapshot. The first turn after a relaunch writes a new prefix (one cold prefill), then it holds again.
+
+`/compact` still rewrites history. The system prefix stays; the conversation after it is a new hash.
+
+## Debug
+
+```bash
+OPENCODE_CONSISTENT_LOG=1 opencode
+```
+
+Writes `~/.local/state/opencode/opencode-consistent.log` with `snapshot` / `restore` and a 12-char sha of the frozen bytes. Same sha on restore means it held.
+
+## License
+
+MIT

package/freeze.js

@@ -0,0 +1,40 @@
+const MAX_SESSIONS = 32
+const snapshots = new Map()
+
+export function isEnvBearing(system) {
+  if (!Array.isArray(system) || system.length === 0) return false
+  const text = system.join("\n")
+  return text.includes("<env>") || text.includes("Today's date:")
+}
+
+function remember(sessionID, system) {
+  if (snapshots.has(sessionID)) snapshots.delete(sessionID)
+  snapshots.set(sessionID, system.slice())
+  while (snapshots.size > MAX_SESSIONS) {
+    const oldest = snapshots.keys().next().value
+    snapshots.delete(oldest)
+  }
+}
+
+/** @returns {"snapshot"|"restore"|"skip"} */
+export function freezeSessionSystem(sessionID, system) {
+  if (!sessionID || !Array.isArray(system) || !isEnvBearing(system)) return "skip"
+  const prev = snapshots.get(sessionID)
+  if (!prev) {
+    remember(sessionID, system)
+    return "snapshot"
+  }
+  system.length = 0
+  for (const part of prev) system.push(part)
+  snapshots.delete(sessionID)
+  snapshots.set(sessionID, prev)
+  return "restore"
+}
+
+export function forgetSession(sessionID) {
+  if (sessionID) snapshots.delete(sessionID)
+}
+
+export function resetSnapshots() {
+  snapshots.clear()
+}

package/index.js

@@ -0,0 +1,38 @@
+import { createHash } from "node:crypto"
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import { freezeSessionSystem, forgetSession } from "./freeze.js"
+
+function digest(system) {
+  return createHash("sha256").update(system.join("\n")).digest("hex").slice(0, 12)
+}
+
+function logLine(kind, sessionID, system) {
+  if (process.env.OPENCODE_CONSISTENT_LOG !== "1") return
+  try {
+    const dir = path.join(os.homedir(), ".local", "state", "opencode")
+    fs.mkdirSync(dir, { recursive: true })
+    const file = path.join(dir, "opencode-consistent.log")
+    const line = `${new Date().toISOString()} ${kind} session=${sessionID.slice(0, 12)} sha=${digest(system)} parts=${system.length} bytes=${system.join("\n").length}\n`
+    fs.appendFileSync(file, line)
+  } catch {
+    /* logging must never break a turn */
+  }
+}
+
+export const OpencodeConsistentPlugin = async () => ({
+  "experimental.chat.system.transform": async (input, output) => {
+    const sessionID = input?.sessionID
+    const system = output?.system
+    const kind = freezeSessionSystem(sessionID, system)
+    if (kind !== "skip") logLine(kind, sessionID, system)
+  },
+  event: async ({ event }) => {
+    const type = event?.type
+    const id = event?.properties?.sessionID ?? event?.properties?.info?.id
+    if (typeof id === "string" && type === "session.deleted") forgetSession(id)
+  },
+})
+
+export default OpencodeConsistentPlugin

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "opencode-consistent",
+  "version": "0.1.0",
+  "description": "Freeze OpenCode's system prefix after the first turn of a session so prefix caches (vLLM, Anthropic, OpenAI) actually hit.",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "freeze.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "opencode",
+    "plugin",
+    "prefix-cache",
+    "vllm",
+    "kv-cache",
+    "prompt-cache"
+  ],
+  "author": "Nguyen Phan <nguyen@nguyenphan.org>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NguyenPhan2810/opencode-consistent.git"
+  },
+  "bugs": {
+    "url": "https://github.com/NguyenPhan2810/opencode-consistent/issues"
+  },
+  "homepage": "https://github.com/NguyenPhan2810/opencode-consistent#readme",
+  "engines": {
+    "opencode": ">=1.18.0"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.18.0"
+  },
+  "peerDependenciesMeta": {
+    "@opencode-ai/plugin": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "test": "node freeze.test.js"
+  }
+}