threadwire 0.1.24 → 0.1.26

package/src/mutation-snapshot.js

@@ -0,0 +1,307 @@
+// @ts-check
+
+import {spawn} from "node:child_process"
+import {createHash} from "node:crypto"
+import {createReadStream} from "node:fs"
+import {stat} from "node:fs/promises"
+import {join} from "node:path"
+
+const MAX_REFLOG_LINES = 256
+const MAX_STATUS_LINES = 10_000
+const MAX_REF_LINES = 10_000
+const MAX_REMOTE_REF_LINES = 1_000
+const MAX_OUTPUT_BYTES = 1_048_576
+const MAX_IDENTITY_BYTES = 1_048_576
+const SNAPSHOT_HASH_ALGORITHM = "sha256"
+
+/**
+ * @typedef {import("./mutation-policy.js").MutationPolicy} MutationPolicy
+ * @typedef {{head: {ref?: string, sha: string}, refs: Record<string, string>, status: string[], reflog: string[], remoteRefs: Record<string, string>, identities: Record<string, string>}} GitSnapshot
+ * @typedef {{worktreeEdit: boolean, commit: boolean, push: boolean, githubWrite: boolean}} ObservedMutations
+ * @typedef {{worktreeEdit: boolean, commit: boolean, push: boolean, githubWrite: boolean}} MutationClaim
+ */
+
+/**
+ * Capture a bounded, credential-free snapshot of a git repository's observable
+ * mutation surface. All subprocess output is capped and no config, remote URL,
+ * or identity secret is included in the returned snapshot.
+ * @param {string} repositoryRoot
+ * @param {{gitExecutable?: string, maxOutputBytes?: number, timeoutMs?: number}} [options]
+ * @returns {Promise<GitSnapshot>}
+ */
+export async function gitSnapshot(repositoryRoot, options = {}) {
+  const git = options.gitExecutable ?? "git"
+  const timeoutMs = options.timeoutMs ?? 10_000
+  const maxOutputBytes = options.maxOutputBytes ?? MAX_OUTPUT_BYTES
+  const [head, refs, status, reflog, remoteRefs] = await Promise.all([
+    readHead(git, repositoryRoot, timeoutMs, maxOutputBytes),
+    readRefs(git, repositoryRoot, timeoutMs, maxOutputBytes),
+    readStatus(git, repositoryRoot, timeoutMs, maxOutputBytes),
+    readReflog(git, repositoryRoot, timeoutMs, maxOutputBytes),
+    readRemoteRefs(git, repositoryRoot, timeoutMs, maxOutputBytes)
+  ])
+  const identities = await readIdentities(repositoryRoot, status)
+  return {head, refs, status, reflog, remoteRefs, identities}
+}
+
+/**
+ * Derive the observed mutation flags from two snapshots. Detection is
+ * conservative: any observable change in the corresponding git surface is
+ * treated as a mutation of that capability. GitHub writes are not observable
+ * through git and are always reported as false.
+ * @param {GitSnapshot} before
+ * @param {GitSnapshot} after
+ * @returns {ObservedMutations}
+ */
+export function snapshotMutations(before, after) {
+  return {
+    worktreeEdit: !arraysEqual(before.status, after.status)
+      || !recordsEqual(before.identities, after.identities),
+    commit: before.head.sha !== after.head.sha
+      || !recordsEqual(before.refs, after.refs)
+      || !arraysEqual(before.reflog, after.reflog),
+    push: !recordsEqual(before.remoteRefs, after.remoteRefs),
+    githubWrite: false
+  }
+}
+
+/**
+ * Reconcile observed mutations against the sealed per-run policy and an
+ * optional closed provider mutation claim. The provider claim contract is a
+ * `{type: "mutation_claim", mutations: {...}}` record; any claim that
+ * contradicts observations is a reconciliation failure.
+ * @param {{policy: MutationPolicy, observed: ObservedMutations, providerExitCode: number, providerClaim?: MutationClaim}} options
+ * @returns {{state: "completed" | "failed", exitCode: number, observedMutations: ObservedMutations, blocker?: string}}
+ */
+export function reconcileMutationResult(options) {
+  const {policy, observed, providerExitCode, providerClaim} = options
+  const denied = /** @type {(keyof MutationPolicy)[]} */ (Object.keys(policy)).filter((capability) => policy[capability] === false && observed[capability])
+  if (denied.length > 0) {
+    return {
+      state: "failed",
+      exitCode: 2,
+      observedMutations: observed,
+      blocker: `Denied mutation observed: ${denied.join(", ")}`
+    }
+  }
+  if (providerClaim !== undefined && !claimMatchesObservations(providerClaim, observed)) {
+    return {
+      state: "failed",
+      exitCode: 2,
+      observedMutations: observed,
+      blocker: "Provider mutation claim contradicts observed mutations"
+    }
+  }
+  return {
+    state: providerExitCode === 0 ? "completed" : "failed",
+    exitCode: providerExitCode,
+    observedMutations: observed
+  }
+}
+
+/**
+ * Hash a snapshot for identity comparison without exposing its content.
+ * @param {GitSnapshot} snapshot
+ * @returns {string}
+ */
+export function hashSnapshot(snapshot) {
+  const hash = createHash(SNAPSHOT_HASH_ALGORITHM)
+  hash.update(JSON.stringify({
+    head: snapshot.head,
+    refs: snapshot.refs,
+    status: snapshot.status,
+    reflog: snapshot.reflog,
+    remoteRefs: snapshot.remoteRefs,
+    identities: snapshot.identities
+  }))
+  return hash.digest("hex")
+}
+
+/**
+ * @param {MutationClaim} claim
+ * @param {ObservedMutations} observed
+ */
+function claimMatchesObservations(claim, observed) {
+  for (const capability of /** @type {(keyof MutationPolicy)[]} */ (Object.keys(observed))) {
+    if (claim[capability] !== observed[capability]) return false
+  }
+  return true
+}
+
+/** @param {string[]} first @param {string[]} second */
+function arraysEqual(first, second) {
+  if (first.length !== second.length) return false
+  for (let index = 0; index < first.length; index += 1) {
+    if (first[index] !== second[index]) return false
+  }
+  return true
+}
+
+/** @param {Record<string, string>} first @param {Record<string, string>} second */
+function recordsEqual(first, second) {
+  const firstKeys = Object.keys(first)
+  const secondKeys = Object.keys(second)
+  if (firstKeys.length !== secondKeys.length) return false
+  for (const key of firstKeys) {
+    if (first[key] !== second[key]) return false
+  }
+  return true
+}
+
+/** @param {string} git @param {string} repositoryRoot @param {number} timeoutMs @param {number} maxBytes */
+async function readHead(git, repositoryRoot, timeoutMs, maxBytes) {
+  const sha = (await runGit(git, repositoryRoot, ["rev-parse", "HEAD"], timeoutMs, maxBytes)).trim()
+  const ref = await runGit(git, repositoryRoot, ["symbolic-ref", "--quiet", "HEAD"], timeoutMs, maxBytes).then((text) => text.trim()).catch(() => undefined)
+  return {sha, ...(ref === undefined || ref.length === 0 ? {} : {ref})}
+}
+
+/** @param {string} git @param {string} repositoryRoot @param {number} timeoutMs @param {number} maxBytes */
+async function readRefs(git, repositoryRoot, timeoutMs, maxBytes) {
+  const text = await runGit(git, repositoryRoot, ["for-each-ref", "--format=%(refname) %(objectname)", "refs/heads", "refs/tags"], timeoutMs, maxBytes)
+  return parseRefLines(text, MAX_REF_LINES)
+}
+
+/** @param {string} git @param {string} repositoryRoot @param {number} timeoutMs @param {number} maxBytes */
+async function readStatus(git, repositoryRoot, timeoutMs, maxBytes) {
+  // Use commands that never refresh or rewrite the index so the snapshot works
+  // when .git is mounted read-only. `git status` would try to update the index
+  // and fail on a read-only git directory.
+  const [tracked, untracked] = await Promise.all([
+    runGit(git, repositoryRoot, ["diff", "--name-status", "--no-renames", "HEAD"], timeoutMs, maxBytes),
+    runGit(git, repositoryRoot, ["ls-files", "--others", "--exclude-standard"], timeoutMs, maxBytes)
+  ])
+  const lines = boundedLines(tracked, MAX_STATUS_LINES).map((line) => line.replace(/\t/u, " "))
+  for (const line of boundedLines(untracked, MAX_STATUS_LINES)) lines.push(`? ${line}`)
+  lines.sort()
+  if (lines.length > MAX_STATUS_LINES) return lines.slice(0, MAX_STATUS_LINES)
+  return lines
+}
+
+/** @param {string} git @param {string} repositoryRoot @param {number} timeoutMs @param {number} maxBytes */
+async function readReflog(git, repositoryRoot, timeoutMs, maxBytes) {
+  const text = await runGit(git, repositoryRoot, ["reflog", "--all"], timeoutMs, maxBytes)
+  return boundedLines(text, MAX_REFLOG_LINES)
+}
+
+/** @param {string} git @param {string} repositoryRoot @param {number} timeoutMs @param {number} maxBytes */
+async function readRemoteRefs(git, repositoryRoot, timeoutMs, maxBytes) {
+  const text = await runGit(git, repositoryRoot, ["for-each-ref", "--format=%(refname) %(objectname)", "refs/remotes"], timeoutMs, maxBytes)
+  return parseRefLines(text, MAX_REMOTE_REF_LINES)
+}
+
+/**
+ * Compute bounded content identities for dirty tracked and untracked files.
+ * Deleted files have no identity; identities are sorted by path and capped to
+ * the same line budget as status. The hash covers a bounded prefix of the file
+ * and its size so large files cannot exhaust memory or leak raw content.
+ * @param {string} repositoryRoot
+ * @param {string[]} statusLines
+ */
+async function readIdentities(repositoryRoot, statusLines) {
+  const limit = Math.min(statusLines.length, MAX_STATUS_LINES)
+  /** @type {[string, string][]} */
+  const entries = []
+  for (let index = 0; index < limit; index += 1) {
+    const line = statusLines[index]
+    if (!line || line.length < 2) continue
+    const status = line[0]
+    const path = line.slice(2)
+    if (status === "D" || path.length === 0) continue
+    try {
+      const identity = await hashWorktreeFile(join(repositoryRoot, path))
+      entries.push([path, identity])
+    } catch {
+      // Missing directories or unreadable files are omitted from the identity set.
+    }
+  }
+  entries.sort((a, b) => (a[0] < b[0] ? -1 : 1))
+  return Object.fromEntries(entries)
+}
+
+/** @param {string} absolutePath */
+async function hashWorktreeFile(absolutePath) {
+  const metadata = await stat(absolutePath)
+  if (!metadata.isFile()) throw new Error("Not a regular file")
+  const size = metadata.size
+  const hash = createHash(SNAPSHOT_HASH_ALGORITHM)
+  await new Promise((resolve, reject) => {
+    const stream = createReadStream(absolutePath, {start: 0, end: MAX_IDENTITY_BYTES - 1})
+    stream.on("data", (chunk) => { hash.update(chunk) })
+    stream.on("end", () => resolve(undefined))
+    stream.on("error", reject)
+  })
+  hash.update(`:${size}`)
+  return hash.digest("hex")
+}
+
+/** @param {string} text @param {number} limit @returns {Record<string, string>} */
+function parseRefLines(text, limit) {
+  const refs = /** @type {Record<string, string>} */ ({})
+  for (const line of boundedLines(text, limit)) {
+    const space = line.indexOf(" ")
+    if (space < 0) continue
+    refs[line.slice(0, space)] = line.slice(space + 1)
+  }
+  return refs
+}
+
+/** @param {string} text @param {number} limit */
+function boundedLines(text, limit) {
+  const all = text.split("\n")
+  const lines = all[all.length - 1] === "" ? all.slice(0, -1) : all
+  if (lines.length > limit) return [...lines.slice(0, limit), `... (${lines.length - limit} lines truncated)`]
+  return lines
+}
+
+/**
+ * Run git in a credential-free environment. The subprocess inherits PATH and
+ * HOME only; git-specific config/env variables are cleared so the snapshot
+ * cannot accidentally read credentials or remote URLs from the host.
+ * @param {string} git
+ * @param {string} repositoryRoot
+ * @param {string[]} args
+ * @param {number} timeoutMs
+ * @param {number} maxBytes
+ */
+function runGit(git, repositoryRoot, args, timeoutMs, maxBytes) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(git, ["--no-optional-locks", "-c", "safe.directory=*", "-C", repositoryRoot, ...args], {
+      env: {
+        PATH: process.env.PATH ?? "",
+        HOME: process.env.HOME ?? ""
+      },
+      stdio: ["ignore", "pipe", "pipe"]
+    })
+    let stdout = ""
+    let stderr = ""
+    let killed = false
+    const timer = setTimeout(() => {
+      killed = true
+      child.kill("SIGKILL")
+      reject(new Error("Git snapshot timeout"))
+    }, timeoutMs)
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString("utf8")
+      if (Buffer.byteLength(stdout, "utf8") > maxBytes && !killed) {
+        killed = true
+        child.kill("SIGKILL")
+        clearTimeout(timer)
+        reject(new Error("Git snapshot output exceeded capacity"))
+      }
+    })
+    child.stderr.on("data", (chunk) => { stderr += chunk.toString("utf8") })
+    child.on("error", (error) => {
+      clearTimeout(timer)
+      reject(error)
+    })
+    child.on("close", (code, signal) => {
+      clearTimeout(timer)
+      if (signal !== null && killed) return
+      if (code !== 0) {
+        reject(new Error(`Git snapshot failed: ${stderr.trim() || signal || code}`))
+        return
+      }
+      resolve(stdout)
+    })
+  })
+}

package/src/provider-capacity-kimi.js

@@ -1,7 +1,7 @@
 // @ts-check
 
 import {isAbsolute, join} from "node:path"
-import {readResponseCapped} from "./absolute-deadline.js"
+import {readResponseCapped, ResponseCapacityError} from "./absolute-deadline.js"
 import {openKimiOAuthStore} from "./kimi-oauth-store.js"
 import {CapacityProbeError, DEFAULT_CAPACITY_TIMEOUT_MS, normalizeKimiUsages} from "./provider-capacity.js"
 
@@ -64,13 +64,22 @@ export async function probeKimiCapacity(options) {
   if (contentType === null || !contentType.toLowerCase().includes("application/json")) {
     throw new CapacityProbeError("protocol", "Kimi usages response has an unexpected content type")
   }
+  /** @type {Buffer} */
+  let bytes
+  try {
+    bytes = await readResponseCapped(response, MAX_USAGES_BYTES, signal)
+  } catch (error) {
+    if (error instanceof ResponseCapacityError) {
+      throw new CapacityProbeError("protocol", "Kimi usages response body exceeded the size bound")
+    }
+    throw new CapacityProbeError("unavailable", "Kimi usages response body is unavailable")
+  }
   /** @type {unknown} */
   let parsed
   try {
-    const bytes = await readResponseCapped(response, MAX_USAGES_BYTES, signal)
     parsed = JSON.parse(bytes.toString("utf8"))
   } catch {
-    throw new CapacityProbeError("protocol", "Kimi usages response is not valid bounded JSON")
+    throw new CapacityProbeError("protocol", "Kimi usages response is not valid JSON")
   }
   return normalizeKimiUsages(parsed)
 }

package/src/provider-capacity.js

@@ -213,7 +213,7 @@ function kimiQuotaWindow(value, windowDurationSeconds) {
   const used = quotaValue(value.used)
   const remaining = quotaValue(value.remaining)
   if (limit < 1 || used + remaining !== limit) throw kimiProtocolError()
-  const remainingPercent = Math.floor((remaining / limit) * 100)
+  const remainingPercent = Number((BigInt(remaining) * 100n) / BigInt(limit))
   return {
     usedPercent: 100 - remainingPercent,
     remainingPercent,

package/src/providers/kimi.js

@@ -1,5 +1,7 @@
 // @ts-check
 
+import {exactKeys, isRecord} from "../record-helpers.js"
+
 const EXECUTABLE = "kimi"
 const ALIAS_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,63}$/u
 const SESSION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,511}$/u
@@ -212,14 +214,6 @@ function withStarted(events, state) {
 }
 /** @returns {KimiRecognition} */
 function emptyRecognition() { return {trusted: false, sessionId: undefined, events: []} }
-/** @param {unknown} value @returns {value is Record<string, unknown>} */
-function isRecord(value) { return typeof value === "object" && value !== null && !Array.isArray(value) }
-/** @param {Record<string, unknown>} value @param {readonly string[]} expected @returns {boolean} */
-function exactKeys(value, expected) {
-  const actual = Object.keys(value).sort()
-  const wanted = [...expected].sort()
-  return actual.length === wanted.length && actual.every((key, index) => key === wanted[index])
-}
 /** @param {Record<string, unknown>} value @param {readonly string[]} required @param {readonly string[]} optional @returns {boolean} */
 function exactOptionalKeys(value, required, optional) {
   const actual = Object.keys(value)

package/src/record-helpers.js

@@ -0,0 +1,11 @@
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+export function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+/** @param {Record<string, unknown>} value @param {readonly string[]} expected */
+export function exactKeys(value, expected) {
+  const actual = Object.keys(value).sort()
+  const wanted = [...expected].sort()
+  return actual.length === wanted.length && actual.every((key, index) => key === wanted[index])
+}