@vostride/agent-qa-runner-local 0.2.3 → 0.2.4

package/dist/index.d.ts

@@ -17,15 +17,9 @@ interface CachePolicy {
     /** `--disable-cache` — short-circuit both reads and writes. */
     disableCache: boolean;
 }
-/**
- * Writes are skipped when the current branch is protected (default ∪ configured)
- * unless `--save-cache` or CI; `--disable-cache` forbids all writes. Reads are not
- * governed here (D-14).
- */
 declare function shouldWrite(policy: CachePolicy): boolean;
 
-/** Envelopes live under <root>/<branchSlug>/<key>.json; any other stamp reads as a miss. */
-declare const CACHE_SCHEMA_VERSION = 2;
+declare const CACHE_SCHEMA_VERSION = 3;
 interface FsActionCacheConfig {
     /** Cache root (e.g. DEFAULT_AGENT_QA_CACHE_DIR = '.agent-qa/cache'). */
     root: string;
@@ -35,14 +29,22 @@ interface FsActionCacheConfig {
 declare class FsActionCache implements ActionPlanCache {
     private readonly root;
     private readonly policy;
+    private readonly skipped;
     constructor(config: FsActionCacheConfig);
     get(key: CacheKey): Promise<CachedPlanValue | null>;
     set(key: CacheKey, value: CachedPlanValue): Promise<void>;
     invalidate(key: CacheKey): Promise<void>;
+    private writeEnvelope;
     private branchDir;
     private entryPath;
     private readEntry;
 }
+/**
+ * Removes every `<root>/<branch-slug>/<16-hex>.json` entry, and a branch directory only when that
+ * leaves it empty. Nothing else under `root` is touched, so a cache root that also holds other
+ * files keeps them. Returns the number of entries removed.
+ */
+declare function purgeActionCache(root: string): Promise<number>;
 
 /** Subdirectory under the runtime root holding the raw storage-state blobs. */
 declare const STORAGE_STATES_SUBDIR = "storage-states";
@@ -113,11 +115,6 @@ declare class FsHandoffStore implements HandoffStorePort {
     constructor(config: FsHandoffStoreConfig);
     save(handoff: CompletedRunHandoff): void;
 }
-/**
- * The fs read leg of the handoff version discipline (D-19): read the single document, parse it,
- * and delegate to the schema package's `guardCompletedRunHandoff`. A newer-than-known schemaVersion
- * surfaces the schema's typed `HandoffVersionError` — this leg re-implements no version rule.
- */
 declare function loadCompletedRunHandoff(filePath: string): CompletedRunHandoff;
 
 /** The single JSON document each run writes its run artifact to. */
@@ -182,12 +179,6 @@ interface CompressResult {
     imageWidth: number;
     imageHeight: number;
 }
-/**
- * The runner `ScreenshotCompressor` port impl (D-08 / Q10). `compress` covers the LLM-planner
- * compression call site; `dimensions` covers the action-space-width metadata fallback done inline
- * via `sharp(screenshot).metadata()` at v1 loop.ts. The loop applies `stampCaptureMode` itself
- * (runner-owned since 352), so this stays purely pixel-level and returns v1's CompressResult shape.
- */
 declare class SharpScreenshotCompressor implements ScreenshotCompressor {
     private readonly logger?;
     constructor(logger?: ScreenshotCompressorLogger | undefined);
@@ -212,8 +203,6 @@ interface ImageDimensions {
     width: number;
     height: number;
 }
-/** Read image buffer width/height without decoding pixels. Used by mobile adapters for
- *  action-space drift assertions (D-06/D-07). */
 declare function getImageDimensions(buffer: Buffer): Promise<ImageDimensions | undefined>;
 declare function flattenOntoWhite(buffer: Buffer): Promise<Buffer>;
 
@@ -288,24 +277,18 @@ declare function readBuildTagMap(opts: {
 }): BuildTagMap;
 
 interface DockerHookExecutorConfig {
+    version: string;
     dockerBin?: string;
     pullPolicy?: 'always' | 'if-not-present' | 'never';
 }
-/**
- * The D-06 hook-execution impl. Constructed once at the CLI composition root and threaded
- * into the runner `runHooks` orchestration behind the {@link HookExecutorPort}. A per-hook
- * timeout resolves a FAILED {@link HookResult} (exit-124-style error), never a throw.
- */
 declare class DockerHookExecutor implements HookExecutorPort {
+    private readonly version;
     private readonly dockerBin;
     private readonly pullPolicy;
-    constructor(config?: DockerHookExecutorConfig);
+    constructor(config: DockerHookExecutorConfig);
     execute(hook: HookDefinition, opts: HookExecuteOptions): Promise<HookResult>;
 }
-/**
- * Docker availability probe (re-homed from core/src/hooks/sandbox-runner.ts). The CLI
- * `doctor` command consumes this to report whether the hook sandbox can run.
- */
+/** Docker availability probe; `doctor` reports from it whether the hook sandbox can run. */
 declare function checkDockerAvailable(dockerBin?: string): Promise<boolean>;
 
-export { ARTIFACT_FILE, type AlignOptions, BUILD_ORDINALS_FILE, BUILD_TAGS_FILE, type BranchResolverOptions, type BuildOrdinalReservation, BuildOrdinalReservationError, type BuildOrdinalReservationErrorCode, type BuildTagMap, CACHE_SCHEMA_VERSION, type CachePolicy, type CompressOptions, type CompressResult, DockerHookExecutor, type DockerHookExecutorConfig, EVENTS_FILE, FsActionCache, type FsActionCacheConfig, FsEventLog, type FsEventLogConfig, FsEvidenceArtifactStore, type FsEvidenceArtifactStoreConfig, FsHandoffStore, type FsHandoffStoreConfig, FsRunArtifactStore, type FsRunArtifactStoreConfig, FsStorageStateStore, type FsStorageStateStoreConfig, HANDOFF_FILE, type ImageDimensions, type NextBuildOrdinalOptions, RUNS_SUBDIR, RUN_EVIDENCE_BLOBS_SUBDIR, type ReserveBuildOrdinalForProductsOptions, type ReserveBuildOrdinalForProductsResult, type ResolvedBranch, STORAGE_STATES_SUBDIR, type ScreenshotCompressorLogger, SharpScreenshotCompressor, alignToWindow, checkDockerAvailable, flattenOntoWhite, getImageDimensions, latestBuildOrdinal, loadCompletedRunHandoff, nextBuildOrdinal, readBuildTagMap, recordBuildTag, reserveBuildOrdinalForProducts, resolveBranch, resolveBuildTag, shouldWrite };
+export { ARTIFACT_FILE, type AlignOptions, BUILD_ORDINALS_FILE, BUILD_TAGS_FILE, type BranchResolverOptions, type BuildOrdinalReservation, BuildOrdinalReservationError, type BuildOrdinalReservationErrorCode, type BuildTagMap, CACHE_SCHEMA_VERSION, type CachePolicy, type CompressOptions, type CompressResult, DockerHookExecutor, type DockerHookExecutorConfig, EVENTS_FILE, FsActionCache, type FsActionCacheConfig, FsEventLog, type FsEventLogConfig, FsEvidenceArtifactStore, type FsEvidenceArtifactStoreConfig, FsHandoffStore, type FsHandoffStoreConfig, FsRunArtifactStore, type FsRunArtifactStoreConfig, FsStorageStateStore, type FsStorageStateStoreConfig, HANDOFF_FILE, type ImageDimensions, type NextBuildOrdinalOptions, RUNS_SUBDIR, RUN_EVIDENCE_BLOBS_SUBDIR, type ReserveBuildOrdinalForProductsOptions, type ReserveBuildOrdinalForProductsResult, type ResolvedBranch, STORAGE_STATES_SUBDIR, type ScreenshotCompressorLogger, SharpScreenshotCompressor, alignToWindow, checkDockerAvailable, flattenOntoWhite, getImageDimensions, latestBuildOrdinal, loadCompletedRunHandoff, nextBuildOrdinal, purgeActionCache, readBuildTagMap, recordBuildTag, reserveBuildOrdinalForProducts, resolveBranch, resolveBuildTag, shouldWrite };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/fs-action-cache.ts
-import { mkdir, readFile, unlink, writeFile } from "fs/promises";
+import { mkdir, readdir, readFile, rmdir, unlink, writeFile } from "fs/promises";
 import { join as join2 } from "path";
 
 // src/branch-resolver.ts
@@ -79,39 +79,56 @@ function shouldWrite(policy) {
 }
 
 // src/fs-action-cache.ts
-var CACHE_SCHEMA_VERSION = 2;
+var CACHE_SCHEMA_VERSION = 3;
+var CACHE_ENTRY_FILE_RE = /^[0-9a-f]{16}\.json$/;
 var FsActionCache = class {
   root;
   policy;
+  skipped = /* @__PURE__ */ new Set();
   constructor(config) {
     this.root = config.root;
     this.policy = config.policy;
   }
   async get(key) {
-    if (this.policy.disableCache) return null;
+    if (this.policy.disableCache || this.skipped.has(key)) return null;
     const onCurrent = await this.readEntry(this.policy.currentBranch, key);
-    if (onCurrent !== null) return onCurrent;
+    if (onCurrent?.kind === "suppressed") return null;
+    if (onCurrent?.kind === "value") return onCurrent.value;
     if (this.policy.currentBranch !== this.policy.defaultBranch) {
-      return this.readEntry(this.policy.defaultBranch, key);
+      const onDefault = await this.readEntry(this.policy.defaultBranch, key);
+      return onDefault?.kind === "value" ? onDefault.value : null;
     }
     return null;
   }
   async set(key, value) {
     if (!shouldWrite(this.policy)) return;
-    const dir = this.branchDir(this.policy.currentBranch);
-    await mkdir(dir, { recursive: true });
-    const envelope = { schemaVersion: CACHE_SCHEMA_VERSION, value };
-    await writeFile(this.entryPath(dir, key), `${JSON.stringify(envelope, null, 2)}
-`, "utf-8");
+    await this.writeEnvelope(key, { schemaVersion: CACHE_SCHEMA_VERSION, value });
   }
   async invalidate(key) {
-    const dir = this.branchDir(this.policy.currentBranch);
+    if (!shouldWrite(this.policy)) {
+      this.skipped.add(key);
+      return;
+    }
+    const { currentBranch, defaultBranch } = this.policy;
+    if (currentBranch !== defaultBranch) {
+      const onDefault = await this.readEntry(defaultBranch, key);
+      if (onDefault?.kind === "value") {
+        await this.writeEnvelope(key, { schemaVersion: CACHE_SCHEMA_VERSION, suppressed: true });
+        return;
+      }
+    }
     try {
-      await unlink(this.entryPath(dir, key));
+      await unlink(this.entryPath(this.branchDir(currentBranch), key));
     } catch (err) {
-      if (err.code !== "ENOENT") throw err;
+      if (!isMissing(err)) throw err;
     }
   }
+  async writeEnvelope(key, envelope) {
+    const dir = this.branchDir(this.policy.currentBranch);
+    await mkdir(dir, { recursive: true });
+    await writeFile(this.entryPath(dir, key), `${JSON.stringify(envelope, null, 2)}
+`, "utf-8");
+  }
   branchDir(branch) {
     return join2(this.root, slugBranch(branch));
   }
@@ -123,7 +140,7 @@ var FsActionCache = class {
     try {
       raw = await readFile(this.entryPath(this.branchDir(branch), key), "utf-8");
     } catch (err) {
-      if (err.code === "ENOENT") return null;
+      if (isMissing(err)) return null;
       throw err;
     }
     let envelope;
@@ -133,9 +150,44 @@ var FsActionCache = class {
       return null;
     }
     if (envelope?.schemaVersion !== CACHE_SCHEMA_VERSION) return null;
-    return envelope.value ?? null;
+    if (envelope.suppressed === true) return { kind: "suppressed" };
+    return envelope.value ? { kind: "value", value: envelope.value } : null;
   }
 };
+function isMissing(err) {
+  return err.code === "ENOENT";
+}
+async function purgeActionCache(root) {
+  let branches;
+  try {
+    branches = await readdir(root, { withFileTypes: true });
+  } catch (err) {
+    if (isMissing(err)) return 0;
+    throw err;
+  }
+  let purged = 0;
+  for (const branch of branches) {
+    if (!branch.isDirectory() || slugBranch(branch.name) !== branch.name) continue;
+    const dir = join2(root, branch.name);
+    const entries = await readdir(dir, { withFileTypes: true });
+    let removed = 0;
+    for (const entry of entries) {
+      if (!entry.isFile() || !CACHE_ENTRY_FILE_RE.test(entry.name)) continue;
+      try {
+        await unlink(join2(dir, entry.name));
+      } catch (err) {
+        if (!isMissing(err)) throw err;
+      }
+      removed++;
+    }
+    purged += removed;
+    if (removed > 0 && removed === entries.length) {
+      await rmdir(dir).catch(() => {
+      });
+    }
+  }
+  return purged;
+}
 
 // src/storage-state-store.ts
 import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
@@ -849,7 +901,7 @@ import { readFile as readFile3, mkdtemp, mkdir as mkdir3, rm, cp } from "fs/prom
 import { join as join10, basename } from "path";
 import { tmpdir } from "os";
 import {
-  RUNTIME_IMAGE_MAP,
+  hookRunnerImage,
   parseEnvFile,
   AUTH_STATE_HOOK_CONTAINER_STORAGE_STATE_PATH,
   AUTH_STATE_HOOK_STORAGE_STATE_FILENAME,
@@ -860,9 +912,11 @@ import {
 } from "@vostride/agent-qa-runner";
 var DEFAULT_DOCKER_BIN = "docker";
 var DockerHookExecutor = class {
+  version;
   dockerBin;
   pullPolicy;
-  constructor(config = {}) {
+  constructor(config) {
+    this.version = config.version;
     this.dockerBin = config.dockerBin ?? DEFAULT_DOCKER_BIN;
     this.pullPolicy = config.pullPolicy ?? "if-not-present";
   }
@@ -870,15 +924,15 @@ var DockerHookExecutor = class {
     const dockerBin = this.dockerBin;
     const pullPolicy = this.pullPolicy;
     const start = Date.now();
-    const image = RUNTIME_IMAGE_MAP[hook.runtime];
-    if (pullPolicy === "always" || pullPolicy === "if-not-present") {
-      const needsPull = pullPolicy === "always" || !await imageExists(dockerBin, image);
-      if (needsPull) {
-        await pullImage(dockerBin, image);
-      }
-    }
+    const image = hookRunnerImage(hook.runtime, this.version);
     let workDir;
     try {
+      if (pullPolicy === "always" || pullPolicy === "if-not-present") {
+        const needsPull = pullPolicy === "always" || !await imageExists(dockerBin, image);
+        if (needsPull) {
+          await pullImage(dockerBin, image);
+        }
+      }
       workDir = await mkdtemp(join10(tmpdir(), "agent-qa-hook-"));
       await mkdir3(join10(workDir, "tmp"), { recursive: true });
       await cp(hook.file, join10(workDir, basename(hook.file)));
@@ -1062,6 +1116,7 @@ export {
   latestBuildOrdinal,
   loadCompletedRunHandoff,
   nextBuildOrdinal,
+  purgeActionCache,
   readBuildTagMap,
   recordBuildTag,
   reserveBuildOrdinalForProducts,