|
| 1 | +/** |
| 2 | + * In-memory + on-disk cache of converted Kiro images, keyed per conversation |
| 3 | + * (workspace + fingerprint). See AGENTS.md §3 "Image carry-forward" for the |
| 4 | + * design rationale and the OpenCode-strip behaviour this works around. |
| 5 | + * |
| 6 | + * Bounded by 24h TTL, 20-conversation memory LRU, and the per-entry |
| 7 | + * MAX_KIRO_IMAGES / MAX_KIRO_IMAGE_BYTES caps. Disk persistence uses |
| 8 | + * write-temp-rename so a partial write can't corrupt the cache file. |
| 9 | + */ |
| 10 | +import { Buffer } from 'node:buffer' |
| 11 | +import { createHash } from 'node:crypto' |
| 12 | +import { |
| 13 | + existsSync, |
| 14 | + mkdirSync, |
| 15 | + readFileSync, |
| 16 | + readdirSync, |
| 17 | + renameSync, |
| 18 | + statSync, |
| 19 | + unlinkSync, |
| 20 | + writeFileSync |
| 21 | +} from 'node:fs' |
| 22 | +import { homedir } from 'node:os' |
| 23 | +import { join } from 'node:path' |
| 24 | + |
| 25 | +import { MAX_KIRO_IMAGES, MAX_KIRO_IMAGE_BYTES, type KiroImage } from './image-handler.js' |
| 26 | + |
| 27 | +// Content fingerprint for dedup — format + byte length + first/last 16 bytes |
| 28 | +// is unique enough in practice; matching head AND tail for two distinct |
| 29 | +// screenshots of identical size is vanishingly rare. No crypto needed. |
| 30 | +function dedupKey(img: KiroImage): string { |
| 31 | + const b = img.source.bytes |
| 32 | + const n = b.byteLength |
| 33 | + if (n === 0) return `${img.format}:empty` |
| 34 | + const hex = (start: number, end: number): string => |
| 35 | + Array.from(b.subarray(start, end), (v) => v.toString(16).padStart(2, '0')).join('') |
| 36 | + return `${img.format}:${n}:${hex(0, Math.min(16, n))}:${hex(Math.max(0, n - 16), n)}` |
| 37 | +} |
| 38 | + |
| 39 | +// Mirrors the layout of logger.ts and kiro.json so everything sits under one |
| 40 | +// base folder. Internal — only the module-level singleton uses this. |
| 41 | +function defaultCacheDir(): string { |
| 42 | + const platform = process.platform |
| 43 | + const base = |
| 44 | + platform === 'win32' |
| 45 | + ? join(process.env.APPDATA || join(homedir(), 'AppData', 'Roaming'), 'opencode') |
| 46 | + : join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'opencode') |
| 47 | + return join(base, 'kiro-images') |
| 48 | +} |
| 49 | + |
| 50 | +function diskFileFor(cacheDir: string, workspace: string, fingerprint: string): string { |
| 51 | + // Hash the composite key so the filename has no path separators or other |
| 52 | + // shell-unsafe characters from the workspace path. |
| 53 | + const id = createHash('sha256') |
| 54 | + .update(workspace + '\0' + fingerprint) |
| 55 | + .digest('hex') |
| 56 | + .slice(0, 32) |
| 57 | + return join(cacheDir, `${id}.json`) |
| 58 | +} |
| 59 | + |
| 60 | +interface CacheEntry { |
| 61 | + images: KiroImage[] |
| 62 | + totalBytes: number |
| 63 | + lastAccess: number |
| 64 | + // True once this conversation has ever contained an image-bearing turn. |
| 65 | + // Lets callers skip the history scan entirely on long sessions where no |
| 66 | + // images were ever attached. |
| 67 | + everHadImages: boolean |
| 68 | +} |
| 69 | + |
| 70 | +export interface ImageCacheOptions { |
| 71 | + ttlMs?: number |
| 72 | + maxEntries?: number |
| 73 | + // Injectable clock for deterministic tests. |
| 74 | + now?: () => number |
| 75 | + // Filesystem persistence directory. Omit (or pass null) to keep the cache |
| 76 | + // memory-only — tests rely on this default. |
| 77 | + cacheDir?: string | null |
| 78 | +} |
| 79 | + |
| 80 | +const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000 |
| 81 | +const DEFAULT_MAX_ENTRIES = 20 |
| 82 | + |
| 83 | +export class ImageCache { |
| 84 | + private cache = new Map<string, CacheEntry>() |
| 85 | + private ttlMs: number |
| 86 | + private maxEntries: number |
| 87 | + private now: () => number |
| 88 | + private cacheDir: string | null |
| 89 | + |
| 90 | + constructor(opts: ImageCacheOptions = {}) { |
| 91 | + this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS |
| 92 | + this.maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES |
| 93 | + this.now = opts.now ?? (() => Date.now()) |
| 94 | + this.cacheDir = opts.cacheDir ?? null |
| 95 | + if (this.cacheDir) this.sweepDiskExpired() |
| 96 | + } |
| 97 | + |
| 98 | + private k(workspace: string, fingerprint: string): string { |
| 99 | + return `${workspace}\0${fingerprint}` |
| 100 | + } |
| 101 | + |
| 102 | + set(workspace: string, fingerprint: string, images: KiroImage[]): void { |
| 103 | + if (images.length === 0) return |
| 104 | + const totalBytes = images.reduce((n, im) => n + im.source.bytes.byteLength, 0) |
| 105 | + const key = this.k(workspace, fingerprint) |
| 106 | + const entry: CacheEntry = { |
| 107 | + images, |
| 108 | + totalBytes, |
| 109 | + lastAccess: this.now(), |
| 110 | + everHadImages: true |
| 111 | + } |
| 112 | + // delete-then-set so the entry moves to the tail of the Map's insertion |
| 113 | + // order — that's what makes the eviction sweep pick the truly oldest. |
| 114 | + this.cache.delete(key) |
| 115 | + this.cache.set(key, entry) |
| 116 | + this.writeEntryToDisk(workspace, fingerprint, entry) |
| 117 | + this.evict() |
| 118 | + } |
| 119 | + |
| 120 | + /** |
| 121 | + * Merge new images with the existing cache for this conversation. |
| 122 | + * New images go to the front (most recent), then existing fills in. |
| 123 | + * Duplicates (same content fingerprint) collapse. |
| 124 | + * Result is capped at MAX_KIRO_IMAGES and MAX_KIRO_IMAGE_BYTES; |
| 125 | + * when over budget, the OLDEST entries drop first (FIFO). |
| 126 | + * |
| 127 | + * Returns the final image count for diagnostics. |
| 128 | + */ |
| 129 | + upsert(workspace: string, fingerprint: string, newImages: KiroImage[]): number { |
| 130 | + const key = this.k(workspace, fingerprint) |
| 131 | + // Try in-memory first; fall back to disk so cross-restart upserts merge |
| 132 | + // with what we already persisted instead of overwriting it. |
| 133 | + let existing = this.cache.get(key)?.images |
| 134 | + if (!existing && this.cacheDir) { |
| 135 | + existing = this.loadEntryFromDisk(workspace, fingerprint)?.images |
| 136 | + } |
| 137 | + existing ??= [] |
| 138 | + |
| 139 | + if (newImages.length === 0 && existing.length === 0) return 0 |
| 140 | + |
| 141 | + const seen = new Set<string>() |
| 142 | + const merged: KiroImage[] = [] |
| 143 | + const add = (img: KiroImage): void => { |
| 144 | + if (merged.length >= MAX_KIRO_IMAGES) return |
| 145 | + const k = dedupKey(img) |
| 146 | + if (seen.has(k)) return |
| 147 | + seen.add(k) |
| 148 | + merged.push(img) |
| 149 | + } |
| 150 | + for (const img of newImages) add(img) |
| 151 | + for (const img of existing) add(img) |
| 152 | + |
| 153 | + // Enforce byte budget by dropping the oldest entries (tail) until in cap. |
| 154 | + let total = merged.reduce((n, im) => n + im.source.bytes.byteLength, 0) |
| 155 | + while (total > MAX_KIRO_IMAGE_BYTES && merged.length > 0) { |
| 156 | + total -= merged.pop()!.source.bytes.byteLength |
| 157 | + } |
| 158 | + |
| 159 | + if (merged.length === 0) { |
| 160 | + this.cache.delete(key) |
| 161 | + this.deleteFromDisk(workspace, fingerprint) |
| 162 | + return 0 |
| 163 | + } |
| 164 | + |
| 165 | + const entry: CacheEntry = { |
| 166 | + images: merged, |
| 167 | + totalBytes: total, |
| 168 | + lastAccess: this.now(), |
| 169 | + everHadImages: true |
| 170 | + } |
| 171 | + this.cache.delete(key) |
| 172 | + this.cache.set(key, entry) |
| 173 | + this.writeEntryToDisk(workspace, fingerprint, entry) |
| 174 | + this.evict() |
| 175 | + return merged.length |
| 176 | + } |
| 177 | + |
| 178 | + get(workspace: string, fingerprint: string): KiroImage[] | null { |
| 179 | + const key = this.k(workspace, fingerprint) |
| 180 | + let entry = this.cache.get(key) |
| 181 | + |
| 182 | + // Lazy-load from disk if we don't have it in memory (e.g. fresh plugin |
| 183 | + // process resuming a prior conversation). |
| 184 | + if (!entry && this.cacheDir) { |
| 185 | + const loaded = this.loadEntryFromDisk(workspace, fingerprint) |
| 186 | + if (loaded) { |
| 187 | + entry = loaded |
| 188 | + this.cache.set(key, entry) |
| 189 | + this.evict() |
| 190 | + } |
| 191 | + } |
| 192 | + |
| 193 | + if (!entry) return null |
| 194 | + |
| 195 | + if (this.now() - entry.lastAccess > this.ttlMs) { |
| 196 | + this.cache.delete(key) |
| 197 | + this.deleteFromDisk(workspace, fingerprint) |
| 198 | + return null |
| 199 | + } |
| 200 | + // Refresh LRU position. |
| 201 | + entry.lastAccess = this.now() |
| 202 | + this.cache.delete(key) |
| 203 | + this.cache.set(key, entry) |
| 204 | + return entry.images |
| 205 | + } |
| 206 | + |
| 207 | + delete(workspace: string, fingerprint: string): void { |
| 208 | + this.cache.delete(this.k(workspace, fingerprint)) |
| 209 | + this.deleteFromDisk(workspace, fingerprint) |
| 210 | + } |
| 211 | + |
| 212 | + // True if this conversation has ever carried images. Lets callers skip |
| 213 | + // the history scan entirely on long text-only sessions. |
| 214 | + hasEverHadImages(workspace: string, fingerprint: string): boolean { |
| 215 | + const entry = this.cache.get(this.k(workspace, fingerprint)) |
| 216 | + if (entry) return entry.everHadImages |
| 217 | + if (this.cacheDir) { |
| 218 | + try { |
| 219 | + return existsSync(diskFileFor(this.cacheDir, workspace, fingerprint)) |
| 220 | + } catch { |
| 221 | + return false |
| 222 | + } |
| 223 | + } |
| 224 | + return false |
| 225 | + } |
| 226 | + |
| 227 | + // Memory-only clear; disk files survive and may be re-loaded by later get(). |
| 228 | + clear(): void { |
| 229 | + this.cache.clear() |
| 230 | + } |
| 231 | + |
| 232 | + size(): number { |
| 233 | + return this.cache.size |
| 234 | + } |
| 235 | + |
| 236 | + private evict(): void { |
| 237 | + const t = this.now() |
| 238 | + for (const [key, e] of this.cache) { |
| 239 | + if (t - e.lastAccess > this.ttlMs) this.cache.delete(key) |
| 240 | + } |
| 241 | + while (this.cache.size > this.maxEntries) { |
| 242 | + const first = this.cache.keys().next().value |
| 243 | + if (first === undefined) break |
| 244 | + this.cache.delete(first) |
| 245 | + } |
| 246 | + } |
| 247 | + |
| 248 | + // ── Disk persistence (no-ops when cacheDir is null) ──────────────────────── |
| 249 | + |
| 250 | + private writeEntryToDisk(workspace: string, fingerprint: string, entry: CacheEntry): void { |
| 251 | + if (!this.cacheDir) return |
| 252 | + try { |
| 253 | + mkdirSync(this.cacheDir, { recursive: true }) |
| 254 | + const file = diskFileFor(this.cacheDir, workspace, fingerprint) |
| 255 | + const tmp = `${file}.tmp` |
| 256 | + const payload = { |
| 257 | + workspace, |
| 258 | + fingerprint, |
| 259 | + updatedAt: entry.lastAccess, |
| 260 | + images: entry.images.map((im) => ({ |
| 261 | + format: im.format, |
| 262 | + b64: Buffer.from(im.source.bytes).toString('base64') |
| 263 | + })) |
| 264 | + } |
| 265 | + writeFileSync(tmp, JSON.stringify(payload)) |
| 266 | + renameSync(tmp, file) |
| 267 | + } catch { |
| 268 | + // Disk failures must never break the request — in-memory cache still works. |
| 269 | + } |
| 270 | + } |
| 271 | + |
| 272 | + private loadEntryFromDisk(workspace: string, fingerprint: string): CacheEntry | null { |
| 273 | + if (!this.cacheDir) return null |
| 274 | + try { |
| 275 | + const file = diskFileFor(this.cacheDir, workspace, fingerprint) |
| 276 | + if (!existsSync(file)) return null |
| 277 | + const stat = statSync(file) |
| 278 | + // mtime acts as "last access" — if older than TTL, treat as expired |
| 279 | + // and clean up. |
| 280 | + if (this.now() - stat.mtimeMs > this.ttlMs) { |
| 281 | + try { |
| 282 | + unlinkSync(file) |
| 283 | + } catch {} |
| 284 | + return null |
| 285 | + } |
| 286 | + const raw = readFileSync(file, 'utf-8') |
| 287 | + const data = JSON.parse(raw) |
| 288 | + if (!data || !Array.isArray(data.images)) return null |
| 289 | + const images: KiroImage[] = [] |
| 290 | + for (const im of data.images) { |
| 291 | + if (!im || typeof im.format !== 'string' || typeof im.b64 !== 'string') continue |
| 292 | + const bytes = new Uint8Array(Buffer.from(im.b64, 'base64')) |
| 293 | + images.push({ format: im.format, source: { bytes } }) |
| 294 | + } |
| 295 | + if (images.length === 0) return null |
| 296 | + const totalBytes = images.reduce((n, im) => n + im.source.bytes.byteLength, 0) |
| 297 | + return { images, totalBytes, lastAccess: stat.mtimeMs, everHadImages: true } |
| 298 | + } catch { |
| 299 | + return null |
| 300 | + } |
| 301 | + } |
| 302 | + |
| 303 | + private deleteFromDisk(workspace: string, fingerprint: string): void { |
| 304 | + if (!this.cacheDir) return |
| 305 | + try { |
| 306 | + const file = diskFileFor(this.cacheDir, workspace, fingerprint) |
| 307 | + if (existsSync(file)) unlinkSync(file) |
| 308 | + } catch {} |
| 309 | + } |
| 310 | + |
| 311 | + /** |
| 312 | + * Remove expired files from the cache dir. Runs once at construction so |
| 313 | + * a long-lived dir doesn't grow unbounded with stale conversations. |
| 314 | + */ |
| 315 | + private sweepDiskExpired(): void { |
| 316 | + if (!this.cacheDir) return |
| 317 | + try { |
| 318 | + if (!existsSync(this.cacheDir)) return |
| 319 | + const cutoff = this.now() - this.ttlMs |
| 320 | + for (const name of readdirSync(this.cacheDir)) { |
| 321 | + if (!name.endsWith('.json') && !name.endsWith('.tmp')) continue |
| 322 | + const file = join(this.cacheDir, name) |
| 323 | + try { |
| 324 | + const stat = statSync(file) |
| 325 | + if (stat.mtimeMs < cutoff) unlinkSync(file) |
| 326 | + } catch {} |
| 327 | + } |
| 328 | + } catch {} |
| 329 | + } |
| 330 | +} |
| 331 | + |
| 332 | +// Shared instance for the plugin runtime — persisted to ~/.config/opencode/kiro-images/ |
| 333 | +// (or %APPDATA%/opencode/kiro-images/ on Windows). Tests construct their own |
| 334 | +// ImageCache with a tmpdir or no cacheDir at all. |
| 335 | +export const imageCache = new ImageCache({ cacheDir: defaultCacheDir() }) |
0 commit comments