opencode-agent-skill 10.0.0 → 11.0.0

package/lib/evidence-store.mjs

@@ -0,0 +1,178 @@
+import { createHash } from "node:crypto"
+import { existsSync } from "node:fs"
+import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises"
+import path from "node:path"
+
+const STORE_VERSION = 1
+const REF_PREFIX = "evidence:sha256:"
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue)
+  if (!value || typeof value !== "object" || Buffer.isBuffer(value)) return value
+  return Object.fromEntries(
+    Object.keys(value).sort().map((key) => [key, stableValue(value[key])]),
+  )
+}
+
+function toBytes(value, options = {}) {
+  if (Buffer.isBuffer(value)) return { bytes: value, encoding: "binary", mediaType: options.mediaType || "application/octet-stream" }
+  if (typeof value === "string") return { bytes: Buffer.from(value, "utf8"), encoding: "utf8", mediaType: options.mediaType || "text/plain; charset=utf-8" }
+  const text = JSON.stringify(stableValue(value), null, options.pretty === false ? 0 : 2)
+  return { bytes: Buffer.from(text, "utf8"), encoding: "utf8", mediaType: options.mediaType || "application/json" }
+}
+
+function normalizeHash(ref) {
+  const value = String(ref || "").trim()
+  const hash = value.startsWith(REF_PREFIX) ? value.slice(REF_PREFIX.length) : value.replace(/^sha256:/, "")
+  if (!/^[a-f0-9]{64}$/i.test(hash)) throw new Error("Invalid evidence reference")
+  return hash.toLowerCase()
+}
+
+export function evidenceReference(hash) {
+  return REF_PREFIX + normalizeHash(hash)
+}
+
+export function evidenceStoreRoot(root = process.cwd()) {
+  return path.join(path.resolve(root), ".ues-cache", "evidence-v1")
+}
+
+function evidencePaths(root, hash) {
+  const normalized = normalizeHash(hash)
+  const dir = path.join(evidenceStoreRoot(root), normalized.slice(0, 2))
+  return {
+    dir,
+    meta: path.join(dir, normalized + ".json"),
+    data: path.join(dir, normalized + ".blob"),
+  }
+}
+
+export async function putEvidence(root, value, options = {}) {
+  root = path.resolve(root)
+  const encoded = toBytes(value, options)
+  const hash = createHash("sha256").update(encoded.bytes).digest("hex")
+  const target = evidencePaths(root, hash)
+  await mkdir(target.dir, { recursive: true })
+
+  const now = new Date().toISOString()
+  const existing = existsSync(target.meta)
+    ? JSON.parse(await readFile(target.meta, "utf8").catch(() => "{}"))
+    : null
+
+  if (!existsSync(target.data)) await writeFile(target.data, encoded.bytes)
+
+  const preview = encoded.encoding === "utf8"
+    ? encoded.bytes.toString("utf8", 0, Math.min(encoded.bytes.length, 600))
+    : null
+
+  const metadata = {
+    schemaVersion: STORE_VERSION,
+    ref: evidenceReference(hash),
+    sha256: hash,
+    bytes: encoded.bytes.length,
+    encoding: encoded.encoding,
+    mediaType: encoded.mediaType,
+    kind: options.kind || existing?.kind || "tool-output",
+    source: options.source || existing?.source || null,
+    summary: options.summary || existing?.summary || null,
+    createdAt: existing?.createdAt || now,
+    lastSeenAt: now,
+    preview,
+  }
+  await writeFile(target.meta, JSON.stringify(metadata, null, 2) + "\n", "utf8")
+  return metadata
+}
+
+export async function getEvidence(root, ref, options = {}) {
+  const hash = normalizeHash(ref)
+  const target = evidencePaths(root, hash)
+  const metadata = JSON.parse(await readFile(target.meta, "utf8"))
+  const bytes = await readFile(target.data)
+  const start = Math.max(0, Number(options.start || 0))
+  const maxBytes = Math.max(1, Number(options.maxBytes || options.maxChars || 24_000))
+  const slice = bytes.subarray(start, Math.min(bytes.length, start + maxBytes))
+  return {
+    ...metadata,
+    truncated: start + slice.length < bytes.length,
+    start,
+    returnedBytes: slice.length,
+    content: metadata.encoding === "utf8" ? slice.toString("utf8") : slice.toString("base64"),
+  }
+}
+
+async function metadataFiles(root) {
+  const base = evidenceStoreRoot(root)
+  const prefixes = await readdir(base, { withFileTypes: true }).catch(() => [])
+  const files = []
+  for (const prefix of prefixes) {
+    if (!prefix.isDirectory()) continue
+    const dir = path.join(base, prefix.name)
+    for (const entry of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
+      if (entry.isFile() && entry.name.endsWith(".json")) files.push(path.join(dir, entry.name))
+    }
+  }
+  return files
+}
+
+export async function evidenceStoreStatus(root = process.cwd()) {
+  const files = await metadataFiles(root)
+  let bytes = 0
+  let oldest = null
+  let newest = null
+  for (const file of files) {
+    const meta = JSON.parse(await readFile(file, "utf8").catch(() => "{}"))
+    bytes += Number(meta.bytes || 0)
+    if (meta.createdAt && (!oldest || meta.createdAt < oldest)) oldest = meta.createdAt
+    if (meta.lastSeenAt && (!newest || meta.lastSeenAt > newest)) newest = meta.lastSeenAt
+  }
+  return {
+    schemaVersion: STORE_VERSION,
+    root: evidenceStoreRoot(root),
+    entries: files.length,
+    bytes,
+    oldest,
+    newest,
+  }
+}
+
+export async function gcEvidenceStore(root = process.cwd(), options = {}) {
+  const files = await metadataFiles(root)
+  const maxEntries = Math.max(10, Number(options.maxEntries || 2_000))
+  const maxAgeMs = Math.max(0, Number(options.maxAgeDays ?? 30)) * 86_400_000
+  const now = Date.now()
+  const rows = []
+  for (const metaFile of files) {
+    const meta = JSON.parse(await readFile(metaFile, "utf8").catch(() => "{}"))
+    const time = Date.parse(meta.lastSeenAt || meta.createdAt || 0) || 0
+    rows.push({ metaFile, meta, time })
+  }
+  rows.sort((a, b) => b.time - a.time)
+
+  const removed = []
+  for (let index = 0; index < rows.length; index += 1) {
+    const row = rows[index]
+    const tooMany = index >= maxEntries
+    const tooOld = maxAgeMs > 0 && row.time > 0 && now - row.time > maxAgeMs
+    if (!tooMany && !tooOld) continue
+    const hash = row.meta.sha256 || path.basename(row.metaFile, ".json")
+    const target = evidencePaths(root, hash)
+    await rm(target.meta, { force: true })
+    await rm(target.data, { force: true })
+    removed.push(evidenceReference(hash))
+  }
+
+  return {
+    removed,
+    removedCount: removed.length,
+    status: await evidenceStoreStatus(root),
+  }
+}
+
+export async function evidenceExists(root, ref) {
+  try {
+    const target = evidencePaths(root, normalizeHash(ref))
+    const info = await stat(target.data)
+    return info.isFile()
+  } catch {
+    return false
+  }
+}

package/lib/hermes-bridge.mjs

@@ -1,11 +1,20 @@
 import { spawnSync } from "node:child_process"
+import { resolveWindowsCommand } from "./windows-shim.mjs"
+
+function runHermesVersion() {
+  if (process.platform !== "win32") return spawnSync("hermes", ["--version"], { encoding: "utf8" })
+  const resolved = resolveWindowsCommand("hermes")
+  if (!resolved) return { status: 127, stdout: "", stderr: "Hermes CLI not found" }
+  return spawnSync(resolved.executable, [...resolved.argsPrefix, "--version"], { encoding: "utf8" })
+}
 
 export function hermesStatus() {
-  const result = spawnSync("hermes", ["--version"], { encoding: "utf8", shell: process.platform === "win32" })
+  const result = runHermesVersion()
   return {
     available: result.status === 0,
     version: result.status === 0 ? String(result.stdout || result.stderr || "").trim() : null,
     error: result.status === 0 ? null : String(result.stderr || result.stdout || "Hermes CLI not found").trim(),
+    mode: "optional-sidecar",
   }
 }
 
@@ -15,11 +24,46 @@ export function buildHermesDelegationPrompt(contextPack) {
     "Implement exactly the approved task described below.",
     "Do not broaden scope, merge, push, publish, deploy, or alter durable UES state.",
     "Run the declared verification and return a concise structured report.",
+    "Large evidence is referenced by evidence:sha256 pointers; fetch only the slice required for the task.",
+    "",
+    JSON.stringify(contextPack, null, 2),
+  ].join("\n")
+}
+
+export function buildHermesWorkflowPrompt(contextPack, schedule) {
+  return [
+    "You are the optional Hermes sidecar for a UES V11 dynamic workflow.",
+    "Follow the supplied bounded wave schedule. Deterministic tasks are not delegated to LLM children.",
+    "Never exceed declared task ownership or concurrency. Persist outputs/evidence to files instead of conversational summaries.",
+    "Do not merge, push, publish, deploy, or mutate durable UES state except through explicitly supplied UES commands.",
+    "",
+    "SCHEDULE:",
+    JSON.stringify(schedule, null, 2),
     "",
+    "CONTEXT:",
     JSON.stringify(contextPack, null, 2),
   ].join("\n")
 }
 
+export function hermesSidecarPlan(input = {}) {
+  return {
+    schemaVersion: 2,
+    adapter: "hermes",
+    optional: true,
+    mode: input.mode || "one-shot",
+    maxConcurrent: Math.max(1, Math.min(16, Number(input.maxConcurrent || 4))),
+    durableStateOwner: "ues",
+    evidenceTransport: "content-addressed-pointers",
+    allowNestedDelegation: input.allowNestedDelegation === true,
+    safety: {
+      merge: false,
+      push: false,
+      publish: false,
+      deploy: false,
+      destructiveGit: false,
+    },
+  }
+}
 
 export function hermesOneShotArgs(prompt) {
   const text = String(prompt || "").trim()

package/lib/model-config.mjs

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs"
 import { mkdir, readFile, writeFile } from "node:fs/promises"
 import path from "node:path"
 import { defaultModelPolicy, resolveModel } from "./model-policy.mjs"
+import { normalizeCapabilityProfile } from "./capability-registry.mjs"
 
 const TIERS = new Set(["light", "standard", "heavy"])
 
@@ -23,14 +24,20 @@ function normalize(policy) {
     if (TIERS.has(tier)) roleTiers[role] = tier
   }
 
+  const capabilities = {}
+  for (const [model, profile] of Object.entries(input.capabilities || {})) {
+    if (validModelID(model)) capabilities[model] = normalizeCapabilityProfile(profile)
+  }
+
   return {
-    schemaVersion: 1,
+    schemaVersion: 2,
     enabled: input.enabled === true,
     maxEscalations: Number.isInteger(input.maxEscalations)
       ? Math.max(0, Math.min(input.maxEscalations, 2))
       : base.maxEscalations,
     tiers,
     roleTiers,
+    capabilities,
   }
 }
 
@@ -56,6 +63,7 @@ export async function writeModelPolicy(configDir, patch = {}) {
     ...patch,
     tiers: { ...current.tiers, ...(patch.tiers || {}) },
     roleTiers: { ...current.roleTiers, ...(patch.roleTiers || {}) },
+    capabilities: { ...(current.capabilities || {}), ...(patch.capabilities || {}) },
   })
   const file = modelPolicyFile(configDir)
   await mkdir(path.dirname(file), { recursive: true })

package/lib/model-policy.mjs

@@ -1,3 +1,5 @@
+import { inferTaskCapabilities, modelCandidatesFromPolicy, selectCapabilityCandidate } from "./capability-registry.mjs"
+
 const ROLE_TIERS = {
   "codebase-mapper": "standard",
   architect: "heavy",
@@ -9,6 +11,8 @@ const ROLE_TIERS = {
   critic: "heavy",
   verifier: "standard",
   "integration-verifier": "heavy",
+  "visual-verifier": "standard",
+  "merge-arbiter": "heavy",
 }
 
 const ORDER = ["light", "standard", "heavy"]
@@ -41,11 +45,12 @@ export function resolveModel(role, attempt, config = {}) {
 
 export function defaultModelPolicy() {
   return {
-    schemaVersion: 1,
+    schemaVersion: 2,
     enabled: false,
     maxEscalations: 2,
     tiers: { light: null, standard: null, heavy: null },
     roleTiers: { ...ROLE_TIERS },
+    capabilities: {},
   }
 }
 
@@ -75,3 +80,49 @@ export function resolveAdaptiveModel(role, attempt, taskPolicy = {}, config = {}
     },
   }
 }
+
+
+export function resolveCapabilityModel(role, attempt, taskText = "", taskPolicy = {}, config = {}, facts = {}) {
+  const base = resolveAdaptiveModel(role, attempt, taskPolicy, config)
+  const requirements = inferTaskCapabilities(taskText, {
+    ...facts,
+    ...(role === "visual-verifier" && facts.coding === undefined ? { coding: false } : {}),
+  })
+  const candidates = modelCandidatesFromPolicy(config)
+    .filter((candidate) => tierIndex(candidate.tier) >= tierIndex(base.tier))
+  const selection = selectCapabilityCandidate(requirements, candidates, {
+    role,
+    preferredTier: base.tier,
+  })
+  const capabilityEnforced = config.enabled === true && candidates.length > 0
+  if (capabilityEnforced && !selection.selected) {
+    return {
+      ...base,
+      model: null,
+      capabilityRequirements: requirements,
+      capabilitySelection: selection,
+      capabilityFallback: true,
+      capabilityBlocked: true,
+      capabilityBlockReason: "no-configured-model-satisfies-required-capabilities",
+    }
+  }
+  if (!config.enabled || !selection.selected) {
+    return {
+      ...base,
+      capabilityRequirements: requirements,
+      capabilitySelection: selection,
+      capabilityFallback: selection.fallbackNeeded,
+      capabilityBlocked: false,
+    }
+  }
+  const selected = selection.selected
+  return {
+    ...base,
+    tier: selected.tier || base.tier,
+    model: selected.id,
+    capabilityRequirements: requirements,
+    capabilitySelection: selection,
+    capabilityFallback: false,
+    capabilityBlocked: false,
+  }
+}

package/lib/orchestrator-policy.mjs

@@ -1,4 +1,4 @@
-const HIGH_RISK = /(auth|security|permission|payment|migration|schema|database|production|deploy|public api|breaking|secret|credential|phân quyền|bảo mật|thanh toán|cơ sở dữ liệu|triển khai|migrate|migration)/i
+const HIGH_RISK = /(\bauth\b|authorization|authentication|security|permission|payment|migration|schema|database|production|deploy|public api|breaking|secret|credential|phân quyền|bảo mật|thanh toán|cơ sở dữ liệu|triển khai|migrate|migration)/i
 const LONG = /(whole repo|whole repository|whole project|entire repo|entire project|large refactor|major refactor|long[- ](?:running|horizon)|durable state|dependency graph|integration verification|resume|migration|refactor all|toàn bộ repo|toàn bộ repository|toàn bộ dự án|toàn bộ project|refactor lớn|tác vụ dài|nhiều file|nhiều module|tiếp tục công việc|refactor toàn bộ|xác minh tích hợp|kiểm tra tích hợp|chia (?:công việc|task|tác vụ).*(?:dependency|phụ thuộc))/i
 const DEBUG = /(fix|bug|debug|crash|regression|failure|error|broken|sửa lỗi|lỗi|điều tra lỗi|không chạy)/i
 const CONTRACT = /(public api|api contract|openapi|response schema|request schema|breaking api|hợp đồng api|api công khai)/i

package/lib/png-diff.mjs

@@ -0,0 +1,229 @@
+import { inflateSync, deflateSync } from "node:zlib"
+import { readFile, writeFile } from "node:fs/promises"
+
+const SIGNATURE = Buffer.from([137,80,78,71,13,10,26,10])
+
+function paeth(a, b, c) {
+  const p = a + b - c
+  const pa = Math.abs(p - a)
+  const pb = Math.abs(p - b)
+  const pc = Math.abs(p - c)
+  return pa <= pb && pa <= pc ? a : pb <= pc ? b : c
+}
+
+function bytesPerPixel(colorType) {
+  if (colorType === 0 || colorType === 3) return 1
+  if (colorType === 2) return 3
+  if (colorType === 4) return 2
+  if (colorType === 6) return 4
+  throw new Error("Unsupported PNG color type: " + colorType)
+}
+
+function parseChunks(buffer) {
+  if (buffer.length < 8 || !buffer.subarray(0, 8).equals(SIGNATURE)) throw new Error("Invalid PNG signature")
+  const chunks = []
+  let offset = 8
+  while (offset + 12 <= buffer.length) {
+    const length = buffer.readUInt32BE(offset)
+    const type = buffer.toString("ascii", offset + 4, offset + 8)
+    const dataStart = offset + 8
+    const dataEnd = dataStart + length
+    if (dataEnd + 4 > buffer.length) throw new Error("Truncated PNG chunk")
+    chunks.push({ type, data: buffer.subarray(dataStart, dataEnd) })
+    offset = dataEnd + 4
+    if (type === "IEND") break
+  }
+  return chunks
+}
+
+export function decodePng(buffer) {
+  const chunks = parseChunks(buffer)
+  const ihdr = chunks.find((chunk) => chunk.type === "IHDR")?.data
+  if (!ihdr || ihdr.length < 13) throw new Error("PNG missing IHDR")
+  const width = ihdr.readUInt32BE(0)
+  const height = ihdr.readUInt32BE(4)
+  const bitDepth = ihdr[8]
+  const colorType = ihdr[9]
+  const interlace = ihdr[12]
+  if (bitDepth !== 8) throw new Error("Only 8-bit PNG is supported")
+  if (interlace !== 0) throw new Error("Interlaced PNG is not supported")
+
+  const paletteChunk = chunks.find((chunk) => chunk.type === "PLTE")?.data || null
+  const transparency = chunks.find((chunk) => chunk.type === "tRNS")?.data || null
+  const idat = Buffer.concat(chunks.filter((chunk) => chunk.type === "IDAT").map((chunk) => chunk.data))
+  const bpp = bytesPerPixel(colorType)
+  const pixelsCount = width * height
+  if (!Number.isSafeInteger(pixelsCount) || pixelsCount <= 0 || pixelsCount > 50_000_000) {
+    throw new Error("PNG dimensions exceed the V11 visual safety budget")
+  }
+  const stride = width * bpp
+  const expectedRawBytes = height * (1 + stride)
+  if (!Number.isSafeInteger(expectedRawBytes) || expectedRawBytes > 256 * 1024 * 1024) {
+    throw new Error("PNG decompressed payload exceeds the V11 visual safety budget")
+  }
+  const raw = inflateSync(idat, { maxOutputLength: expectedRawBytes })
+  if (raw.length !== expectedRawBytes) throw new Error("PNG decompressed payload length does not match IHDR")
+  const pixels = Buffer.alloc(stride * height)
+  let input = 0
+
+  for (let y = 0; y < height; y += 1) {
+    const filter = raw[input++]
+    const row = y * stride
+    for (let x = 0; x < stride; x += 1) {
+      const byte = raw[input++]
+      const left = x >= bpp ? pixels[row + x - bpp] : 0
+      const up = y > 0 ? pixels[row - stride + x] : 0
+      const upLeft = y > 0 && x >= bpp ? pixels[row - stride + x - bpp] : 0
+      let value
+      if (filter === 0) value = byte
+      else if (filter === 1) value = (byte + left) & 255
+      else if (filter === 2) value = (byte + up) & 255
+      else if (filter === 3) value = (byte + Math.floor((left + up) / 2)) & 255
+      else if (filter === 4) value = (byte + paeth(left, up, upLeft)) & 255
+      else throw new Error("Unsupported PNG filter: " + filter)
+      pixels[row + x] = value
+    }
+  }
+
+  const rgba = Buffer.alloc(width * height * 4)
+  for (let i = 0, p = 0; i < pixels.length; i += bpp, p += 4) {
+    if (colorType === 6) {
+      rgba[p] = pixels[i]; rgba[p+1] = pixels[i+1]; rgba[p+2] = pixels[i+2]; rgba[p+3] = pixels[i+3]
+    } else if (colorType === 2) {
+      rgba[p] = pixels[i]; rgba[p+1] = pixels[i+1]; rgba[p+2] = pixels[i+2]; rgba[p+3] = 255
+    } else if (colorType === 0) {
+      rgba[p] = pixels[i]; rgba[p+1] = pixels[i]; rgba[p+2] = pixels[i]; rgba[p+3] = 255
+    } else if (colorType === 4) {
+      rgba[p] = pixels[i]; rgba[p+1] = pixels[i]; rgba[p+2] = pixels[i]; rgba[p+3] = pixels[i+1]
+    } else if (colorType === 3) {
+      if (!paletteChunk) throw new Error("Indexed PNG missing PLTE")
+      const index = pixels[i]
+      rgba[p] = paletteChunk[index * 3] ?? 0
+      rgba[p+1] = paletteChunk[index * 3 + 1] ?? 0
+      rgba[p+2] = paletteChunk[index * 3 + 2] ?? 0
+      rgba[p+3] = transparency?.[index] ?? 255
+    }
+  }
+  return { width, height, rgba }
+}
+
+let crcTable = null
+function crc32(buffer) {
+  if (!crcTable) {
+    crcTable = Array.from({ length: 256 }, (_, n) => {
+      let c = n
+      for (let k = 0; k < 8; k += 1) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1
+      return c >>> 0
+    })
+  }
+  let crc = 0xffffffff
+  for (const byte of buffer) crc = crcTable[(crc ^ byte) & 0xff] ^ (crc >>> 8)
+  return (crc ^ 0xffffffff) >>> 0
+}
+
+function chunk(type, data) {
+  const typeBytes = Buffer.from(type, "ascii")
+  const length = Buffer.alloc(4)
+  length.writeUInt32BE(data.length)
+  const crc = Buffer.alloc(4)
+  crc.writeUInt32BE(crc32(Buffer.concat([typeBytes, data])))
+  return Buffer.concat([length, typeBytes, data, crc])
+}
+
+export function encodeRgbaPng({ width, height, rgba }) {
+  if (!Number.isInteger(width) || !Number.isInteger(height) || width < 1 || height < 1) throw new Error("Invalid PNG dimensions")
+  if (!Buffer.isBuffer(rgba) || rgba.length !== width * height * 4) throw new Error("Invalid RGBA buffer")
+  const ihdr = Buffer.alloc(13)
+  ihdr.writeUInt32BE(width, 0)
+  ihdr.writeUInt32BE(height, 4)
+  ihdr[8] = 8
+  ihdr[9] = 6
+  const scan = Buffer.alloc(height * (1 + width * 4))
+  for (let y = 0; y < height; y += 1) {
+    const row = y * (1 + width * 4)
+    scan[row] = 0
+    rgba.copy(scan, row + 1, y * width * 4, (y + 1) * width * 4)
+  }
+  return Buffer.concat([SIGNATURE, chunk("IHDR", ihdr), chunk("IDAT", deflateSync(scan)), chunk("IEND", Buffer.alloc(0))])
+}
+
+export function comparePngBuffers(expectedBuffer, actualBuffer, options = {}) {
+  const expected = decodePng(expectedBuffer)
+  const actual = decodePng(actualBuffer)
+  if (expected.width !== actual.width || expected.height !== actual.height) {
+    return {
+      schemaVersion: 1,
+      verdict: "FAIL",
+      reason: "dimension-mismatch",
+      expected: { width: expected.width, height: expected.height },
+      actual: { width: actual.width, height: actual.height },
+      differentPixels: expected.width * expected.height,
+      differentRatio: 1,
+      bounds: { x: 0, y: 0, width: Math.max(expected.width, actual.width), height: Math.max(expected.height, actual.height) },
+    }
+  }
+
+  const threshold = Math.max(0, Math.min(255, Number(options.threshold ?? 16)))
+  const allowedRatio = Math.max(0, Math.min(1, Number(options.maxDiffRatio ?? 0)))
+  let differentPixels = 0
+  let minX = expected.width
+  let minY = expected.height
+  let maxX = -1
+  let maxY = -1
+
+  for (let pixel = 0; pixel < expected.width * expected.height; pixel += 1) {
+    const offset = pixel * 4
+    let delta = 0
+    for (let channel = 0; channel < 4; channel += 1) {
+      delta = Math.max(delta, Math.abs(expected.rgba[offset + channel] - actual.rgba[offset + channel]))
+    }
+    if (delta <= threshold) continue
+    differentPixels += 1
+    const x = pixel % expected.width
+    const y = Math.floor(pixel / expected.width)
+    minX = Math.min(minX, x); maxX = Math.max(maxX, x)
+    minY = Math.min(minY, y); maxY = Math.max(maxY, y)
+  }
+
+  const totalPixels = expected.width * expected.height
+  const differentRatio = totalPixels ? differentPixels / totalPixels : 0
+  const bounds = differentPixels
+    ? { x: minX, y: minY, width: maxX - minX + 1, height: maxY - minY + 1 }
+    : null
+
+  return {
+    schemaVersion: 1,
+    verdict: differentRatio <= allowedRatio ? "PASS" : "FAIL",
+    width: expected.width,
+    height: expected.height,
+    differentPixels,
+    differentRatio,
+    threshold,
+    maxDiffRatio: allowedRatio,
+    bounds,
+  }
+}
+
+export async function comparePngFiles(expectedFile, actualFile, options = {}) {
+  return comparePngBuffers(await readFile(expectedFile), await readFile(actualFile), options)
+}
+
+export function cropDecodedPng(decoded, bounds) {
+  const x = Math.max(0, Math.floor(Number(bounds?.x || 0)))
+  const y = Math.max(0, Math.floor(Number(bounds?.y || 0)))
+  const width = Math.max(1, Math.min(decoded.width - x, Math.floor(Number(bounds?.width || decoded.width))))
+  const height = Math.max(1, Math.min(decoded.height - y, Math.floor(Number(bounds?.height || decoded.height))))
+  const rgba = Buffer.alloc(width * height * 4)
+  for (let row = 0; row < height; row += 1) {
+    const sourceStart = ((y + row) * decoded.width + x) * 4
+    decoded.rgba.copy(rgba, row * width * 4, sourceStart, sourceStart + width * 4)
+  }
+  return { width, height, rgba }
+}
+
+export async function cropPngFile(inputFile, outputFile, bounds) {
+  const decoded = decodePng(await readFile(inputFile))
+  const cropped = cropDecodedPng(decoded, bounds)
+  await writeFile(outputFile, encodeRgbaPng(cropped))
+  return { file: outputFile, width: cropped.width, height: cropped.height }
+}

package/lib/prompt-cache.mjs

@@ -0,0 +1,60 @@
+import { createHash } from "node:crypto"
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical)
+  if (!value || typeof value !== "object") return value
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])]))
+}
+
+function stringify(value) {
+  return typeof value === "string" ? value : JSON.stringify(canonical(value))
+}
+
+function digest(value) {
+  return createHash("sha256").update(stringify(value)).digest("hex")
+}
+
+function chars(value) {
+  return stringify(value ?? "").length
+}
+
+export function buildPromptEnvelope(input = {}) {
+  const stable = {
+    invariants: input.invariants || "",
+    role: input.role || "",
+    skills: input.skills || [],
+    projectFacts: input.projectFacts || {},
+    toolPolicy: input.toolPolicy || {},
+  }
+  const dynamic = {
+    task: input.task || {},
+    evidence: input.evidence || [],
+    recentFailure: input.recentFailure || null,
+    nextAction: input.nextAction || null,
+    recentMessages: input.recentMessages || [],
+  }
+  const stableChars = chars(stable)
+  const dynamicChars = chars(dynamic)
+  return {
+    schemaVersion: 1,
+    stable,
+    dynamic,
+    stablePrefixHash: digest(stable),
+    dynamicHash: digest(dynamic),
+    stableChars,
+    dynamicChars,
+    cacheableRatio: stableChars + dynamicChars ? stableChars / (stableChars + dynamicChars) : 0,
+  }
+}
+
+export function comparePromptEnvelopes(previous, current) {
+  const stableReused = Boolean(previous?.stablePrefixHash && previous.stablePrefixHash === current?.stablePrefixHash)
+  const repeatedStableChars = stableReused ? Number(current?.stableChars || 0) : 0
+  return {
+    schemaVersion: 1,
+    stableReused,
+    repeatedStableChars,
+    avoidableRepeatedChars: stableReused ? 0 : Math.min(Number(previous?.stableChars || 0), Number(current?.stableChars || 0)),
+    currentCacheableRatio: Number(current?.cacheableRatio || 0),
+  }
+}