opencode-agent-skill 13.0.0-beta.2 → 14.4.0

package/lib/verification-broker.mjs

@@ -0,0 +1,284 @@
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises"
+import path from "node:path"
+import { createHash, randomUUID } from "node:crypto"
+import { createVerificationReceipt, validateVerificationReceipt } from "./evidence-receipt.mjs"
+import { getEvidence, putEvidence } from "./evidence-store.mjs"
+import { runtimeWorkspaceFingerprint } from "./workspace-fingerprint.mjs"
+
+const CACHE_VERSION = 1
+const CACHE_FILE = "verification-broker-v1.json"
+
+const CACHE_WRITE_TAILS = new Map()
+const CACHE_LOCK_SUFFIX = ".lock"
+const CACHE_LOCK_STALE_MS = 5_000
+const CACHE_LOCK_WAIT_MS = 8_000
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+function cacheLockPath(root) {
+  return cachePath(root) + CACHE_LOCK_SUFFIX
+}
+
+async function withCrossProcessCacheLock(root, fn) {
+  const lockDir = cacheLockPath(root)
+  await mkdir(path.dirname(lockDir), { recursive: true })
+  const deadline = Date.now() + CACHE_LOCK_WAIT_MS
+  let delayMs = 8
+
+  while (true) {
+    try {
+      await mkdir(lockDir)
+      break
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error
+
+      const info = await stat(lockDir).catch(() => null)
+      if (info && Date.now() - info.mtimeMs > CACHE_LOCK_STALE_MS) {
+        const confirmed = await stat(lockDir).catch(() => null)
+        if (
+          confirmed &&
+          confirmed.ino === info.ino &&
+          confirmed.mtimeMs === info.mtimeMs
+        ) {
+          await rm(lockDir, { recursive: true, force: true }).catch(() => {})
+          continue
+        }
+      }
+      if (Date.now() >= deadline) {
+        throw new Error("Timed out waiting for verification broker cache lock")
+      }
+      await sleep(delayMs)
+      delayMs = Math.min(80, delayMs * 2)
+    }
+  }
+
+  try {
+    return await fn()
+  } finally {
+    await rm(lockDir, { recursive: true, force: true }).catch(() => {})
+  }
+}
+
+async function withCacheWriteLock(root, fn) {
+  const key = path.resolve(root)
+  const previous = CACHE_WRITE_TAILS.get(key) || Promise.resolve()
+  let release
+  const barrier = new Promise((resolve) => { release = resolve })
+  const tail = previous.catch(() => {}).then(() => barrier)
+  CACHE_WRITE_TAILS.set(key, tail)
+
+  await previous.catch(() => {})
+  try {
+    return await withCrossProcessCacheLock(root, fn)
+  } finally {
+    release()
+    if (CACHE_WRITE_TAILS.get(key) === tail) CACHE_WRITE_TAILS.delete(key)
+  }
+}
+
+function cachePath(root) {
+  return path.join(path.resolve(root), ".ues-cache", CACHE_FILE)
+}
+
+function keyFor(command, args = []) {
+  return createHash("sha256")
+    .update(JSON.stringify([String(command || ""), (args || []).map(String)]))
+    .digest("hex")
+}
+
+function receiptReusableAtFingerprint(receipt, fingerprint) {
+  if (!validateVerificationReceipt(receipt).valid) return false
+  if (receipt.exitCode !== 0 || receipt.passed !== true) return false
+  if (!Number.isFinite(Date.parse(receipt.startedAt || ""))) return false
+  if (!Number.isFinite(Date.parse(receipt.finishedAt || ""))) return false
+  return Boolean(
+    receipt.workspaceBefore &&
+    receipt.workspaceAfter &&
+    receipt.workspaceBefore === receipt.workspaceAfter &&
+    receipt.workspaceAfter === fingerprint
+  )
+}
+
+function entryMatchesKey(key, entry) {
+  const receipt = entry?.receipt
+  if (!receipt || !String(receipt.command || "").trim()) return false
+  if (!Array.isArray(receipt.args)) return false
+  return keyFor(receipt.command, receipt.args) === key
+}
+
+function finishedAtMs(entry) {
+  const value = Date.parse(entry?.finishedAt || entry?.receipt?.finishedAt || "")
+  return Number.isFinite(value) ? value : null
+}
+
+function freshEnough(entry, maxAgeMs, now = Date.now()) {
+  const finished = finishedAtMs(entry)
+  if (finished == null) return false
+  if (finished > now + 60_000) return false
+  if (!maxAgeMs) return true
+  return now - finished <= maxAgeMs
+}
+
+async function readCache(root) {
+  try {
+    const parsed = JSON.parse(await readFile(cachePath(root), "utf8"))
+    if (parsed?.schemaVersion !== CACHE_VERSION || typeof parsed.entries !== "object") return { schemaVersion: CACHE_VERSION, entries: {} }
+    return parsed
+  } catch {
+    return { schemaVersion: CACHE_VERSION, entries: {} }
+  }
+}
+
+async function writeCache(root, value) {
+  const file = cachePath(root)
+  await mkdir(path.dirname(file), { recursive: true })
+  const temp = file + "." + process.pid + "." + Date.now() + "." + randomUUID() + ".tmp"
+  await writeFile(temp, JSON.stringify(value, null, 2) + "\n", "utf8")
+  try {
+    await rename(temp, file)
+  } catch (error) {
+    await rm(temp, { force: true }).catch(() => {})
+    throw error
+  }
+}
+
+export async function findReusableVerification(root, command, args = [], options = {}) {
+  root = path.resolve(root)
+  const maxAgeMs = Math.max(0, Number(options.maxAgeMs ?? 20 * 60_000))
+  const cache = await readCache(root)
+  const key = keyFor(command, args)
+  const entry = cache.entries[key]
+  if (!entry || !entryMatchesKey(key, entry)) return null
+  if (!freshEnough(entry, maxAgeMs)) return null
+
+  const currentFingerprint = String(options.workspaceFingerprint || runtimeWorkspaceFingerprint(root))
+  if (!receiptReusableAtFingerprint(entry.receipt, currentFingerprint)) return null
+
+  const stdout = entry.stdoutRef
+    ? await getEvidence(root, entry.stdoutRef, { maxBytes: options.maxBytes || 16_000 }).catch(() => null)
+    : null
+  const stderr = entry.stderrRef
+    ? await getEvidence(root, entry.stderrRef, { maxBytes: options.maxBytes || 8_000 }).catch(() => null)
+    : null
+
+  return {
+    schemaVersion: 1,
+    reused: true,
+    key,
+    receipt: entry.receipt,
+    stdoutRef: entry.stdoutRef || null,
+    stderrRef: entry.stderrRef || null,
+    stdout: stdout?.content || "",
+    stderr: stderr?.content || "",
+    ageMs: Math.max(0, Date.now() - finishedAtMs(entry)),
+  }
+}
+
+export async function recordVerification(root, input = {}) {
+  root = path.resolve(root)
+  const stdout = String(input.stdout || "")
+  const stderr = String(input.stderr || "")
+  const stdoutEvidence = await putEvidence(root, stdout, {
+    kind: "verification-stdout",
+    source: input.command || "verification-broker",
+    summary: "Captured stdout preserved for reusable verification receipt",
+  })
+  const stderrEvidence = await putEvidence(root, stderr, {
+    kind: "verification-stderr",
+    source: input.command || "verification-broker",
+    summary: "Captured stderr preserved for reusable verification receipt",
+  })
+
+  const receipt = createVerificationReceipt({
+    task: input.task || null,
+    runId: input.runId || null,
+    command: input.command,
+    args: input.args || [],
+    cwd: root,
+    exitCode: input.exitCode,
+    startedAt: input.startedAt,
+    finishedAt: input.finishedAt,
+    durationMs: input.durationMs,
+    stdout,
+    stderr,
+    workspaceBefore: input.workspaceBefore || null,
+    workspaceAfter: input.workspaceAfter || runtimeWorkspaceFingerprint(root),
+  })
+
+  const key = keyFor(input.command, input.args || [])
+  await withCacheWriteLock(root, async () => {
+    const cache = await readCache(root)
+    cache.entries[key] = {
+      receipt,
+      stdoutRef: stdoutEvidence.ref,
+      stderrRef: stderrEvidence.ref,
+      finishedAt: receipt.finishedAt,
+    }
+
+    // Keep cache small and deterministic.
+    const rows = Object.entries(cache.entries)
+      .sort((a, b) => (finishedAtMs(b[1]) || 0) - (finishedAtMs(a[1]) || 0))
+      .slice(0, 200)
+    cache.entries = Object.fromEntries(rows)
+    await writeCache(root, cache)
+  })
+
+  return {
+    schemaVersion: 1,
+    reused: false,
+    key,
+    receipt,
+    stdoutRef: stdoutEvidence.ref,
+    stderrRef: stderrEvidence.ref,
+  }
+}
+
+export async function listReusableVerification(root, options = {}) {
+  root = path.resolve(root)
+  const currentFingerprint = String(options.workspaceFingerprint || runtimeWorkspaceFingerprint(root))
+  const maxAgeMs = Math.max(0, Number(options.maxAgeMs ?? 30 * 60_000))
+  const limit = Math.max(1, Math.min(50, Number(options.limit || 12)))
+  const now = Date.now()
+  const cache = await readCache(root)
+  const rows = []
+
+  for (const [key, entry] of Object.entries(cache.entries || {})) {
+    const receipt = entry?.receipt
+    if (!entryMatchesKey(key, entry)) continue
+    if (!receiptReusableAtFingerprint(receipt, currentFingerprint)) continue
+    const finished = finishedAtMs(entry)
+    if (!freshEnough(entry, maxAgeMs, now)) continue
+    rows.push({
+      key,
+      receipt,
+      stdoutRef: entry.stdoutRef || null,
+      stderrRef: entry.stderrRef || null,
+      finishedAt: entry.finishedAt || receipt.finishedAt || null,
+    })
+  }
+
+  rows.sort((a, b) => (Date.parse(b.finishedAt || "") || 0) - (Date.parse(a.finishedAt || "") || 0))
+  const selected = rows.slice(0, limit)
+  const output = []
+  for (const row of selected) {
+    const stdout = row.stdoutRef
+      ? await getEvidence(root, row.stdoutRef, { maxBytes: options.previewBytes || 2400 }).catch(() => null)
+      : null
+    const stderr = row.stderrRef
+      ? await getEvidence(root, row.stderrRef, { maxBytes: options.previewBytes || 1200 }).catch(() => null)
+      : null
+    output.push({
+      ...row,
+      stdoutPreview: stdout?.content || "",
+      stderrPreview: stderr?.content || "",
+    })
+  }
+  return {
+    schemaVersion: 1,
+    workspaceFingerprint: currentFingerprint,
+    count: output.length,
+    results: output,
+  }
+}

package/lib/verification-command.mjs

@@ -0,0 +1,111 @@
+export const VERIFICATION_COMMAND_RE =
+  /(?:^|\s|&&|;|\|)(?:pnpm|npm|yarn|bun|npx|node|python|pytest|go|cargo|dotnet|mvn|gradle|\.\/gradlew|gradlew\.bat)[^\n]*(?:test|jest|vitest|pytest|typecheck|tsc|lint|eslint|ruff|mypy|check|build|compile)/i
+
+export function looksLikeVerificationCommand(command = "") {
+  return VERIFICATION_COMMAND_RE.test(String(command || ""))
+}
+
+export function hasMaskedShellExitRisk(command = "") {
+  const value = String(command || "")
+  // Receipt reuse is an optimization, so ambiguity fails closed. Quoted shell
+  // metacharacters may cause a false negative here, which only means rerunning
+  // the check; it can never create a false PASS receipt.
+  if (value.includes("||") || value.includes(";") || value.includes("|") || /\r|\n/.test(value)) {
+    return true
+  }
+  // Reject a single/background '&' while allowing '&&'.
+  const withoutAndAnd = value.replaceAll("&&", "")
+  if (withoutAndAnd.includes("&")) return true
+  return false
+}
+
+export function canRecordReusableVerification(command = "") {
+  const value = String(command || "").trim()
+  return Boolean(value) &&
+    looksLikeVerificationCommand(value) &&
+    !hasMaskedShellExitRisk(value)
+}
+
+function tokenizeSimpleShell(command) {
+  const value = String(command || "").trim()
+  if (!value || hasMaskedShellExitRisk(value)) return null
+  // Exact executable+args reuse is stricter than generic receipt eligibility:
+  // a compound chain has one aggregate exit status but no single argv identity.
+  if (/&&|\|\||;|\||\r|\n/.test(value)) return null
+  // Fail closed on expansion, redirection, globs and backslash-sensitive
+  // shell syntax. Receipt reuse is only an optimization, so false negatives
+  // here cost latency rather than correctness.
+  if (/[<>\\]/.test(value) || value.includes("\u0060") || /\$\(|\$\{|\$[A-Za-z_]|%[A-Za-z_][A-Za-z0-9_]*%|\*|\?|\[|\]/.test(value)) return null
+
+  const tokens = []
+  let current = ""
+  let quote = null
+  let escaped = false
+
+  const push = () => {
+    if (!current) return
+    tokens.push(current)
+    current = ""
+  }
+
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index]
+    if (escaped) {
+      current += char
+      escaped = false
+      continue
+    }
+    if (char === "\\" && quote !== "'") {
+      escaped = true
+      continue
+    }
+    if (quote) {
+      if (char === quote) quote = null
+      else current += char
+      continue
+    }
+    if (char === "'" || char === '"') {
+      quote = char
+      continue
+    }
+    if (/\s/.test(char)) {
+      push()
+      continue
+    }
+    current += char
+  }
+
+  if (escaped || quote) return null
+  push()
+  return tokens.length ? tokens : null
+}
+
+export function canonicalVerificationCommand(command = "") {
+  const value = String(command || "").trim()
+  if (!canRecordReusableVerification(value)) return null
+
+  const tokens = tokenizeSimpleShell(value)
+  if (!tokens?.length) return null
+
+  const firstRaw = String(tokens[0] || "")
+  const first = firstRaw.toLowerCase()
+  if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(firstRaw) || firstRaw.startsWith("~")) {
+    return null
+  }
+  if ((first === "cmd" || first === "cmd.exe") && /^\/c$/i.test(tokens[1] || "")) {
+    if (tokens.length < 3 || /\s/.test(tokens[2])) return null
+    return { command: tokens[2], args: tokens.slice(3), raw: value }
+  }
+
+  // PowerShell -Command is intentionally not canonicalized: quoting and command
+  // parsing semantics are too rich for a safe exact-reuse key.
+  if (first === "powershell" || first === "powershell.exe" || first === "pwsh" || first === "pwsh.exe") {
+    return null
+  }
+
+  return {
+    command: tokens[0],
+    args: tokens.slice(1),
+    raw: value,
+  }
+}

package/lib/windows-shim.mjs

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs"
 import path from "node:path"
+import os from "node:os"
 import { spawnSync } from "node:child_process"
 
 function within(base, candidate) {
@@ -219,6 +220,40 @@ export function resolveWindowsCommand(name) {
   return resolveWindowsCommandCandidates(candidates)
 }
 
+export function resolveManagedPiCommand(homeDir = os.homedir()) {
+  const releasesDir = path.join(homeDir, ".pi", "agent", "install", "releases")
+  let releases = []
+  try {
+    releases = readdirSync(releasesDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort((a, b) => b.localeCompare(a, undefined, { numeric: true, sensitivity: "base" }))
+  } catch {
+    return null
+  }
+
+  for (const release of releases) {
+    const packageDir = path.join(
+      releasesDir,
+      release,
+      "node_modules",
+      "@earendil-works",
+      "pi-coding-agent",
+    )
+    const target = packageBinTarget(packageDir, "pi")
+    if (!target) continue
+    const resolved = executionForTarget(target)
+    if (resolved) {
+      return {
+        ...resolved,
+        source: target,
+        managedRelease: release,
+      }
+    }
+  }
+  return null
+}
+
 function spawnWhere(name) {
   // Lazy import avoidance is unnecessary here; child_process is builtin and this
   // module is Node-only. Kept as one helper so tests can cover candidate selection

package/lib/workspace-fingerprint.mjs

@@ -0,0 +1,198 @@
+import { createHash } from "node:crypto"
+import { lstatSync, readFileSync, readlinkSync } from "node:fs"
+import { spawnSync } from "node:child_process"
+import path from "node:path"
+
+const RUNTIME_DIRS = [
+  ".ues-cache",
+  ".ues-traces",
+  ".ues-work",
+  ".ues-learning",
+  ".ues-dashboard",
+  ".ues-sandboxes",
+  ".ues-memory",
+  ".ues-evals",
+]
+const RUNTIME_PATHSPECS = [
+  ".",
+  ...RUNTIME_DIRS.map((dir) => `:(exclude)${dir}/**`),
+]
+
+let nonGitNonce = 0
+
+function git(root, args) {
+  return spawnSync("git", args, {
+    cwd: root,
+    encoding: "utf8",
+    maxBuffer: 16 * 1024 * 1024,
+  })
+}
+
+function normalizePath(value) {
+  return String(value || "").replaceAll("\\", "/").replace(/^\.\//, "")
+}
+
+function porcelainEntries(statusOutput) {
+  const records = String(statusOutput || "").split("\0").filter(Boolean)
+  const entries = []
+  let renameCode = null
+
+  for (const record of records) {
+    if (record.length >= 3 && record[2] === " ") {
+      const code = record.slice(0, 2)
+      const file = normalizePath(record.slice(3))
+      if (file) entries.push({ code, file })
+      renameCode = /[RC]/.test(code) ? code : null
+      continue
+    }
+    if (renameCode) {
+      const file = normalizePath(record)
+      if (file) entries.push({ code: renameCode, file, renameSource: true })
+      renameCode = null
+    }
+  }
+  return entries
+}
+
+function porcelainChangedFiles(statusOutput) {
+  return [...new Set(porcelainEntries(statusOutput).map((entry) => entry.file))].sort()
+}
+
+function untrackedContentDigest(root, statusOutput, options = {}) {
+  const limit = Math.max(1024 * 1024, Number(options.maxUntrackedBytes || 32 * 1024 * 1024))
+  const totalLimit = Math.max(limit, Number(options.maxUntrackedTotalBytes || 64 * 1024 * 1024))
+  const files = porcelainEntries(statusOutput)
+    .filter((entry) => entry.code === "??")
+    .map((entry) => entry.file)
+    .sort()
+  const hash = createHash("sha256")
+  let totalBytes = 0
+
+  for (const relative of files) {
+    const full = path.resolve(root, relative)
+    if (full !== root && !full.startsWith(root + path.sep)) {
+      return { cacheable: false, reason: "untracked-path-escape", files }
+    }
+    try {
+      const info = lstatSync(full)
+      hash.update(relative)
+      hash.update("\0")
+      if (info.isSymbolicLink()) {
+        hash.update("symlink:")
+        hash.update(readlinkSync(full))
+        hash.update("\0")
+        continue
+      }
+      if (!info.isFile()) {
+        return { cacheable: false, reason: "untracked-non-file", files }
+      }
+      if (info.size > limit) {
+        return {
+          cacheable: false,
+          reason: "untracked-file-too-large",
+          files,
+          file: relative,
+          bytes: info.size,
+        }
+      }
+      totalBytes += info.size
+      if (totalBytes > totalLimit) {
+        return {
+          cacheable: false,
+          reason: "untracked-total-too-large",
+          files,
+          bytes: totalBytes,
+        }
+      }
+      hash.update(readFileSync(full))
+      hash.update("\0")
+    } catch {
+      return { cacheable: false, reason: "untracked-read-failed", files, file: relative }
+    }
+  }
+  return { cacheable: true, digest: hash.digest("hex"), files }
+}
+
+function nonGitSnapshot(root) {
+  nonGitNonce += 1
+  return {
+    schemaVersion: 1,
+    root,
+    git: false,
+    cacheable: false,
+    fingerprint: createHash("sha256")
+      .update(
+        "non-git-no-reuse:" +
+        root +
+        ":" +
+        process.pid +
+        ":" +
+        nonGitNonce,
+      )
+      .digest("hex"),
+    changedFiles: [],
+    head: null,
+  }
+}
+
+export function runtimeWorkspaceSnapshot(root = process.cwd()) {
+  root = path.resolve(root)
+  const inside = git(root, ["rev-parse", "--is-inside-work-tree"])
+  if (inside.status !== 0 || String(inside.stdout || "").trim() !== "true") {
+    return nonGitSnapshot(root)
+  }
+
+  const head = git(root, ["rev-parse", "HEAD"])
+  const status = git(root, [
+    "status",
+    "--porcelain=v1",
+    "-z",
+    "--untracked-files=all",
+    "--",
+    ...RUNTIME_PATHSPECS,
+  ])
+  const diff = git(root, ["diff", "--binary", "--no-ext-diff", "--", ...RUNTIME_PATHSPECS])
+  const cached = git(root, ["diff", "--cached", "--binary", "--no-ext-diff", "--", ...RUNTIME_PATHSPECS])
+
+  const commands = [head, status, diff, cached]
+  const commandComplete = commands.every((result) => result.status === 0)
+  const untracked = status.status === 0
+    ? untrackedContentDigest(root, status.stdout)
+    : { cacheable: false, reason: "status-unavailable", files: [] }
+  const cacheable = commandComplete && untracked.cacheable === true
+  if (!cacheable) {
+    // A partial Git snapshot or unhashable untracked file must never be reused
+    // as if it proved repository identity. Return a nonce fingerprint so
+    // callers fail closed while still exposing changed-file hints.
+    return {
+      ...nonGitSnapshot(root),
+      git: true,
+      head: head.status === 0 ? String(head.stdout || "").trim() || null : null,
+      changedFiles: status.status === 0 ? porcelainChangedFiles(status.stdout) : [],
+      reason: commandComplete ? untracked.reason : "git-snapshot-incomplete",
+    }
+  }
+
+  const parts = [
+    String(head.stdout || ""),
+    String(status.stdout || ""),
+    String(diff.stdout || ""),
+    String(cached.stdout || ""),
+    "untracked:" + String(untracked.digest || ""),
+  ]
+  return {
+    schemaVersion: 1,
+    root,
+    git: true,
+    cacheable: true,
+    fingerprint: createHash("sha256")
+      .update(parts.join("\n---UES-RUNTIME-FP---\n"))
+      .digest("hex"),
+    changedFiles: porcelainChangedFiles(status.stdout),
+    head: String(head.stdout || "").trim() || null,
+  }
+}
+
+export function runtimeWorkspaceFingerprint(root = process.cwd()) {
+  return runtimeWorkspaceSnapshot(root).fingerprint
+}