opencode-consistent 0.1.0 → 0.4.0

package/README.md

@@ -1,16 +1,21 @@
 # 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.
+OpenCode rebuilds the system prompt on every turn. In 1.18.27 the `<env>` block is cwd, worktree, git yes/no, platform, and `Today's date: ${new Date().toDateString()}`. Prefix caches hash from token 0, so when the calendar rolls the whole session misses.
 
-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.
+AGENTS.md, MCP instructions, and the skill list are re-read from disk. If you did not edit them, a restart already sends the same bytes. This plugin does **not** freeze those, so a mid-session edit still reaches the model (and correctly misses the old prefix).
 
-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.
+The other restart miss is MCP **tools**, which are not in the system string. They sit after the built-in tool schemas. If those servers are still connecting, vLLM hashes builtins only (1,792 tokens = 7×256 blocks) and prefills the rest.
 
-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.
+This plugin:
+
+1. **Pins `Today's date`** on the first real turn of a `sessionID` and rewrites just that field later, including after quit/reopen.
+2. **Waits** in `chat.message` until the same MCP servers are `connected` (or have finished failing) so `SessionTools.resolve` includes the same tool block.
+
+Upstream: [#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).
 
 ## Install
 
-Put it **last** in the plugin list so other plugins mutate first, then this freezes the result:
+Put it **last** in the plugin list:
 
 ```json
 {
@@ -20,21 +25,33 @@ Put it **last** in the plugin list so other plugins mutate first, then this free
 }
 ```
 
-Restart OpenCode. Plugins load at process start.
+Optional wait budget (milliseconds). Default `15000`. `0` polls once and does not block.
+
+```json
+{
+  "plugin": [
+    ["opencode-consistent", { "mcpWaitMs": 20000 }]
+  ]
+}
+```
+
+Same value via `OPENCODE_CONSISTENT_MCP_WAIT_MS`. 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.
+`Today's date` per `sessionID`, on disk under `~/.local/state/opencode/consistent/`.
+
+The list of MCP server names that were `connected` when that date was first pinned. Later turns wait until those names are `connected` again.
 
-Title-generation uses the same sessionID with no `<env>` block. Those calls are ignored so they cannot poison the snapshot.
+Title-generation has no date line. Those calls are ignored.
 
 ## 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.
+AGENTS.md, cwd, skills, MCP instruction prose. Change them and the next turn is live — and a new prefix hash.
 
-A process restart drops the snapshot. The first turn after a relaunch writes a new prefix (one cold prefill), then it holds again.
+Tool JSON schemas. The plugin cannot inject a missing MCP tool. If a server is still down after `mcpWaitMs`, or it advertises different tools, the hash still misses after the built-in set.
 
-`/compact` still rewrites history. The system prefix stays; the conversation after it is a new hash.
+`/compact` still rewrites history.
 
 ## Debug
 
@@ -42,7 +59,7 @@ A process restart drops the snapshot. The first turn after a relaunch writes a n
 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.
+Writes `~/.local/state/opencode/opencode-consistent.log` with `wait ok|timeout` and `snapshot` / `restore date=…`. Restore keeps the first-turn date; `sha=` of the full system string is allowed to move when AGENTS.md or skills change.
 
 ## License
 

package/freeze.js

@@ -1,38 +1,135 @@
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+
 const MAX_SESSIONS = 32
+/** JS Date#toDateString: "Thu Sep 03 2026" */
+export const DATE_LINE = /Today's date:\s+[A-Za-z]{3} [A-Za-z]{3} +\d{1,2} \d{4}/
+const DATE_VALUE = /Today's date:\s+([A-Za-z]{3} [A-Za-z]{3} +\d{1,2} \d{4})/
+
+/** @type {Map<string, { date: string, mcp: { connected: string[] } | null, savedAt?: number }>} */
 const snapshots = new Map()
 
+export function extractDate(system) {
+  const text = Array.isArray(system) ? system.join("\n") : typeof system === "string" ? system : ""
+  const match = text.match(DATE_VALUE)
+  return match ? match[1] : null
+}
+
+export function applyDate(system, date) {
+  if (!date || !Array.isArray(system)) return false
+  let hit = false
+  for (let i = 0; i < system.length; i++) {
+    if (DATE_LINE.test(system[i])) {
+      system[i] = system[i].replace(DATE_LINE, `Today's date: ${date}`)
+      hit = true
+    }
+  }
+  return hit
+}
+
 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:")
+  return extractDate(system) != null
 }
 
-function remember(sessionID, system) {
+export function stateDir() {
+  return process.env.OPENCODE_CONSISTENT_DIR || path.join(os.homedir(), ".local", "state", "opencode", "consistent")
+}
+
+function fileFor(sessionID) {
+  const safe = String(sessionID).replace(/[^A-Za-z0-9._-]/g, "_")
+  return path.join(stateDir(), `${safe}.json`)
+}
+
+function cloneRecord(rec) {
+  return {
+    date: rec.date,
+    mcp: rec.mcp && Array.isArray(rec.mcp.connected) ? { connected: rec.mcp.connected.slice() } : null,
+    savedAt: rec.savedAt,
+  }
+}
+
+export function loadRecord(sessionID) {
+  if (!sessionID) return null
+  try {
+    const raw = fs.readFileSync(fileFor(sessionID), "utf8")
+    const parsed = JSON.parse(raw)
+    let date = typeof parsed.date === "string" ? parsed.date : null
+    if (!date && Array.isArray(parsed.system)) date = extractDate(parsed.system)
+    if (!date) return null
+    const mcp =
+      parsed.mcp && Array.isArray(parsed.mcp.connected) ? { connected: parsed.mcp.connected.map(String) } : null
+    return { date, mcp, savedAt: parsed.savedAt }
+  } catch {
+    return null
+  }
+}
+
+export function saveRecord(sessionID, rec) {
+  if (!sessionID || !rec?.date) return
+  fs.mkdirSync(stateDir(), { recursive: true })
+  const body = { date: rec.date, savedAt: rec.savedAt ?? Date.now() }
+  if (rec.mcp && Array.isArray(rec.mcp.connected)) {
+    body.mcp = { connected: rec.mcp.connected.slice() }
+  }
+  fs.writeFileSync(fileFor(sessionID), JSON.stringify(body))
+}
+
+export function forgetDisk(sessionID) {
+  if (!sessionID) return
+  try {
+    fs.unlinkSync(fileFor(sessionID))
+  } catch {
+    /* missing is fine */
+  }
+}
+
+function remember(sessionID, rec) {
   if (snapshots.has(sessionID)) snapshots.delete(sessionID)
-  snapshots.set(sessionID, system.slice())
+  snapshots.set(sessionID, cloneRecord(rec))
   while (snapshots.size > MAX_SESSIONS) {
     const oldest = snapshots.keys().next().value
     snapshots.delete(oldest)
   }
 }
 
+export function peekRecord(sessionID) {
+  if (!sessionID) return null
+  const live = snapshots.get(sessionID)
+  if (live) return cloneRecord(live)
+  const disk = loadRecord(sessionID)
+  return disk ? cloneRecord(disk) : null
+}
+
 /** @returns {"snapshot"|"restore"|"skip"} */
 export function freezeSessionSystem(sessionID, system) {
-  if (!sessionID || !Array.isArray(system) || !isEnvBearing(system)) return "skip"
-  const prev = snapshots.get(sessionID)
+  if (!sessionID || !Array.isArray(system)) return "skip"
+  const date = extractDate(system)
+  if (!date) return "skip"
+  const prev = snapshots.get(sessionID) || loadRecord(sessionID)
   if (!prev) {
-    remember(sessionID, system)
+    const rec = { date, mcp: null, savedAt: Date.now() }
+    remember(sessionID, rec)
+    saveRecord(sessionID, rec)
     return "snapshot"
   }
-  system.length = 0
-  for (const part of prev) system.push(part)
-  snapshots.delete(sessionID)
-  snapshots.set(sessionID, prev)
+  applyDate(system, prev.date)
+  remember(sessionID, prev)
   return "restore"
 }
 
+export function setMcpConnected(sessionID, connected) {
+  const rec = snapshots.get(sessionID) || loadRecord(sessionID)
+  if (!rec) return
+  rec.mcp = { connected: [...new Set((connected ?? []).map(String))].sort() }
+  remember(sessionID, rec)
+  saveRecord(sessionID, rec)
+}
+
 export function forgetSession(sessionID) {
-  if (sessionID) snapshots.delete(sessionID)
+  if (!sessionID) return
+  snapshots.delete(sessionID)
+  forgetDisk(sessionID)
 }
 
 export function resetSnapshots() {

package/index.js

@@ -2,37 +2,134 @@ 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"
+import { freezeSessionSystem, forgetSession, peekRecord, setMcpConnected } from "./freeze.js"
+import { connectedNames, hasConnected, isSettled, waitMsFrom, waitUntil, wantedServers } from "./wait.js"
 
 function digest(system) {
   return createHash("sha256").update(system.join("\n")).digest("hex").slice(0, 12)
 }
 
-function logLine(kind, sessionID, system) {
+function logPath() {
+  return path.join(os.homedir(), ".local", "state", "opencode", "opencode-consistent.log")
+}
+
+function logRaw(line) {
   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)
+    fs.mkdirSync(path.dirname(logPath()), { recursive: true })
+    fs.appendFileSync(logPath(), `${new Date().toISOString()} ${line}\n`)
   } 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)
-  },
-})
+function logSystem(kind, sessionID, system) {
+  const rec = peekRecord(sessionID)
+  const date = rec?.date ?? "none"
+  logRaw(
+    `${kind} session=${sessionID.slice(0, 12)} date=${date.replaceAll(" ", "_")} sha=${digest(system)} parts=${system.length} bytes=${system.join("\n").length}`,
+  )
+}
+
+export async function readStatus(client) {
+  if (!client?.mcp?.status) return {}
+  try {
+    const result = await client.mcp.status()
+    const data = result?.data
+    if (data && typeof data === "object" && !Array.isArray(data)) return data
+    return {}
+  } catch {
+    return {}
+  }
+}
+
+async function readWanted(client) {
+  if (!client?.config?.get) return []
+  try {
+    const result = await client.config.get()
+    const cfg = result?.data ?? result
+    return wantedServers(cfg?.mcp)
+  } catch {
+    return []
+  }
+}
+
+export const OpencodeConsistentPlugin = async (ctx = {}, options = {}) => {
+  const client = ctx.client
+  let wanted = []
+  /** @type {Map<string, Record<string, { status: string }>>} */
+  const lastWait = new Map()
+  const timeoutMs = waitMsFrom(options.mcpWaitMs)
+  const intervalMs =
+    options.mcpWaitIntervalMs !== undefined && Number.isFinite(Number(options.mcpWaitIntervalMs))
+      ? Math.max(0, Number(options.mcpWaitIntervalMs))
+      : undefined
+
+  return {
+    config: async (cfg) => {
+      wanted = wantedServers(cfg?.mcp)
+    },
+    "chat.message": async (input) => {
+      const sessionID = input?.sessionID
+      if (!sessionID) return
+      try {
+        if (wanted.length === 0) wanted = await readWanted(client)
+        const rec = peekRecord(sessionID)
+        const required = rec?.mcp?.connected
+        let mode
+        let predicate
+        if (Array.isArray(required)) {
+          if (required.length === 0) {
+            logRaw(`wait skip session=${sessionID.slice(0, 12)} reason=no-mcp`)
+            lastWait.set(sessionID, {})
+            return
+          }
+          mode = "restore"
+          predicate = (status) => hasConnected(status, required)
+        } else {
+          if (wanted.length === 0) {
+            logRaw(`wait skip session=${sessionID.slice(0, 12)} reason=no-wanted`)
+            lastWait.set(sessionID, {})
+            return
+          }
+          mode = rec ? "upgrade" : "first"
+          predicate = (status) => isSettled(status, wanted)
+        }
+        const result = await waitUntil({
+          poll: () => readStatus(client),
+          ok: predicate,
+          timeoutMs,
+          intervalMs,
+        })
+        lastWait.set(sessionID, result.last ?? {})
+        const connected = connectedNames(result.last).join(",") || "-"
+        logRaw(
+          `wait ${result.ok ? "ok" : "timeout"} mode=${mode} session=${sessionID.slice(0, 12)} elapsed=${result.elapsed} connected=${connected}`,
+        )
+      } catch (err) {
+        logRaw(`wait error session=${sessionID.slice(0, 12)} ${err?.message ?? err}`)
+      }
+    },
+    "experimental.chat.system.transform": async (input, output) => {
+      const sessionID = input?.sessionID
+      const system = output?.system
+      const kind = freezeSessionSystem(sessionID, system)
+      if (kind === "skip") return
+      const rec = peekRecord(sessionID)
+      const waited = lastWait.get(sessionID)
+      const shouldCapture = waited !== undefined && (kind === "snapshot" || rec?.mcp == null)
+      if (shouldCapture) setMcpConnected(sessionID, connectedNames(waited))
+      logSystem(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") {
+        lastWait.delete(id)
+        forgetSession(id)
+      }
+    },
+  }
+}
 
 export default OpencodeConsistentPlugin

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.",
+  "version": "0.4.0",
+  "description": "Pin Today's date in OpenCode sessions and wait for the same MCP servers so prefix caches actually hit.",
   "type": "module",
   "main": "./index.js",
   "exports": {
@@ -10,6 +10,7 @@
   "files": [
     "index.js",
     "freeze.js",
+    "wait.js",
     "README.md",
     "LICENSE"
   ],
@@ -19,7 +20,8 @@
     "prefix-cache",
     "vllm",
     "kv-cache",
-    "prompt-cache"
+    "prompt-cache",
+    "mcp"
   ],
   "author": "Nguyen Phan <nguyen@nguyenphan.org>",
   "license": "MIT",
@@ -43,6 +45,6 @@
     }
   },
   "scripts": {
-    "test": "node freeze.test.js"
+    "test": "node freeze.test.js && node wait.test.js && node plugin.test.js"
   }
 }

package/wait.js

@@ -0,0 +1,69 @@
+export const DEFAULT_WAIT_MS = 15_000
+export const DEFAULT_INTERVAL_MS = 200
+
+const TERMINAL = new Set(["connected", "failed", "needs_auth", "needs_client_registration"])
+
+export function waitMsFrom(option) {
+  if (option !== undefined && option !== null && Number.isFinite(Number(option))) {
+    return Math.max(0, Number(option))
+  }
+  const env = process.env.OPENCODE_CONSISTENT_MCP_WAIT_MS
+  if (env !== undefined && env !== "" && Number.isFinite(Number(env))) {
+    return Math.max(0, Number(env))
+  }
+  return DEFAULT_WAIT_MS
+}
+
+/** MCP names that OpenCode will try to connect (enabled !== false). */
+export function wantedServers(mcpConfig) {
+  if (!mcpConfig || typeof mcpConfig !== "object") return []
+  return Object.entries(mcpConfig)
+    .filter(([, value]) => value && typeof value === "object" && value.enabled !== false)
+    .map(([name]) => name)
+    .sort()
+}
+
+export function connectedNames(status) {
+  if (!status || typeof status !== "object") return []
+  return Object.entries(status)
+    .filter(([, value]) => value && value.status === "connected")
+    .map(([name]) => name)
+    .sort()
+}
+
+/**
+ * Connecting servers report as "disabled" on GET /mcp until they finish.
+ * Treat disabled/missing as in-flight for names that are configured and enabled.
+ */
+export function isSettled(status, wanted) {
+  if (!Array.isArray(wanted) || wanted.length === 0) return true
+  return wanted.every((name) => TERMINAL.has(status?.[name]?.status))
+}
+
+export function hasConnected(status, required) {
+  if (!Array.isArray(required) || required.length === 0) return true
+  return required.every((name) => status?.[name]?.status === "connected")
+}
+
+/**
+ * Poll until `ok(last)` or timeout. First poll is immediate.
+ * @returns {{ ok: boolean, elapsed: number, last: any, timedOut: boolean }}
+ */
+export async function waitUntil({ poll, ok, timeoutMs, intervalMs, sleep, now }) {
+  const t0 = (now ?? Date.now)()
+  const timeout = timeoutMs ?? DEFAULT_WAIT_MS
+  const step = intervalMs ?? DEFAULT_INTERVAL_MS
+  const nap = sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)))
+  const clock = now ?? Date.now
+
+  let last = await poll()
+  if (ok(last)) return { ok: true, elapsed: clock() - t0, last, timedOut: false }
+  if (timeout <= 0) return { ok: false, elapsed: clock() - t0, last, timedOut: true }
+
+  while (clock() - t0 < timeout) {
+    await nap(step)
+    last = await poll()
+    if (ok(last)) return { ok: true, elapsed: clock() - t0, last, timedOut: false }
+  }
+  return { ok: false, elapsed: clock() - t0, last, timedOut: true }
+}