@vostride/agent-qa-runner-local 0.0.1 → 0.2.2

package/dist/index.d.ts

@@ -0,0 +1,311 @@
+import { ActionPlanCache, CachedPlanValue, StorageStatePort, StorageStateBlob, StorageStateReference, EventLogPort, HandoffStorePort, RunArtifactStorePort, EvidenceArtifactStorePort, PersistedRecording, ScreenshotCompressor, CompressedScreenshot, HookExecutorPort, HookDefinition, HookExecuteOptions, HookResult } from '@vostride/agent-qa-runner';
+export { ActionPlanCache, StorageStateBlob, StorageStatePort, StorageStateReference } from '@vostride/agent-qa-runner';
+import { CacheKey, RunEventEnvelope, CompletedRunHandoff, RunArtifactStageInput, RunArtifactFinalizeInput, ArtifactRef, EvidenceDocument } from '@vostride/agent-qa-schema';
+export { CacheKey, slugBranch } from '@vostride/agent-qa-schema';
+
+interface CachePolicy {
+    /** The branch the current run executes on (raw, un-slugged). */
+    currentBranch: string;
+    /** The repo's default branch (raw, un-slugged) — the read-fallback namespace. */
+    defaultBranch: string;
+    /** default branch ∪ any configured protected branches. */
+    protectedBranches: readonly string[];
+    /** Resolved in the CLI (reusing the CI vendor-var set), passed in here. */
+    isCI: boolean;
+    /** `--save-cache` — force writes even on a protected branch. */
+    saveCache: boolean;
+    /** `--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;
+interface FsActionCacheConfig {
+    /** Cache root (e.g. DEFAULT_AGENT_QA_CACHE_DIR = '.agent-qa/cache'). */
+    root: string;
+    /** Resolved branch context + write policy (branch + CI + flags). */
+    policy: CachePolicy;
+}
+declare class FsActionCache implements ActionPlanCache {
+    private readonly root;
+    private readonly policy;
+    constructor(config: FsActionCacheConfig);
+    get(key: CacheKey): Promise<CachedPlanValue | null>;
+    set(key: CacheKey, value: CachedPlanValue): Promise<void>;
+    invalidate(key: CacheKey): Promise<void>;
+    private branchDir;
+    private entryPath;
+    private readEntry;
+}
+
+/** Subdirectory under the runtime root holding the raw storage-state blobs. */
+declare const STORAGE_STATES_SUBDIR = "storage-states";
+interface FsStorageStateStoreConfig {
+    /** Runtime root (e.g. DEFAULT_AGENT_QA_DIR = '.agent-qa'). */
+    root: string;
+}
+declare class FsStorageStateStore implements StorageStatePort {
+    private readonly root;
+    constructor(config: FsStorageStateStoreConfig);
+    save(name: string, state: StorageStateBlob): Promise<StorageStateReference>;
+    load(name: string): Promise<StorageStateBlob | undefined>;
+    private storageStatesDir;
+    private entryPath;
+}
+
+interface ResolvedBranch {
+    /** The branch the run is on; falls back to defaultBranch when undetectable. */
+    currentBranch: string;
+    /** The remote default branch; falls back to the configured default -> main. */
+    defaultBranch: string;
+}
+interface BranchResolverOptions {
+    /** Directory to resolve git state from (default process.cwd()). */
+    cwd?: string;
+    /** Configured default branch, used when the remote default is undetectable. */
+    configuredDefault?: string;
+    /** Injected .git/HEAD reader — returns raw file content or null. */
+    readHead?: (cwd: string) => string | null;
+    /** Injected `git symbolic-ref refs/remotes/origin/HEAD` reader — raw or null. */
+    runSymbolicRef?: (cwd: string) => string | null;
+}
+/**
+ * Resolve the current + default branch names. Both are returned raw (un-slugged);
+ * the fs store slugs each before it becomes a path segment. Never throws.
+ */
+declare function resolveBranch(opts?: BranchResolverOptions): ResolvedBranch;
+
+/** Subdirectory under the runtime root holding per-run event logs. */
+declare const RUNS_SUBDIR = "runs";
+/** The single JSONL file name each run appends its event stream to. */
+declare const EVENTS_FILE = "events.jsonl";
+interface FsEventLogConfig {
+    /** Runtime root (e.g. DEFAULT_AGENT_QA_DIR = '.agent-qa'). */
+    root: string;
+    /** The run this log belongs to; slugged before it becomes a path segment. */
+    runId: string;
+}
+declare class FsEventLog implements EventLogPort {
+    private readonly dir;
+    private readonly file;
+    constructor(config: FsEventLogConfig);
+    append(envelope: RunEventEnvelope): void;
+    read(fromSeq: number): RunEventEnvelope[];
+}
+
+/** The single JSON document each run writes its completed-run handoff to. */
+declare const HANDOFF_FILE = "handoff.json";
+interface FsHandoffStoreConfig {
+    /** Runtime root (e.g. DEFAULT_AGENT_QA_DIR = '.agent-qa'). */
+    root: string;
+    /** The run this handoff belongs to; slugged before it becomes a path segment. */
+    runId: string;
+}
+declare class FsHandoffStore implements HandoffStorePort {
+    private readonly dir;
+    private readonly file;
+    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. */
+declare const ARTIFACT_FILE = "artifact.json";
+interface FsRunArtifactStoreConfig {
+    /** Runtime root (e.g. DEFAULT_AGENT_QA_DIR = '.agent-qa'). */
+    root: string;
+    /** The run this artifact belongs to; slugged before it becomes a path segment. */
+    runId: string;
+}
+declare class FsRunArtifactStore implements RunArtifactStorePort {
+    private readonly dir;
+    private readonly file;
+    constructor(config: FsRunArtifactStoreConfig);
+    stage(document: RunArtifactStageInput): void;
+    finalize(patch: RunArtifactFinalizeInput): void;
+    /** Shallow-merge a stage/finalize input onto the base, always dropping the top-level runtime. */
+    private merge;
+    private readExisting;
+    private write;
+}
+
+/** Subdirectory under each slugged run dir holding the content-addressed evidence blobs. */
+declare const RUN_EVIDENCE_BLOBS_SUBDIR = "blobs";
+interface FsEvidenceArtifactStoreConfig {
+    /** Runtime root (e.g. DEFAULT_AGENT_QA_DIR = '.agent-qa'). */
+    root: string;
+    /** The run these blobs belong to; slugged before it becomes a path segment. */
+    runId: string;
+}
+declare class FsEvidenceArtifactStore implements EvidenceArtifactStorePort {
+    private readonly dir;
+    private readonly durabilityRoot;
+    constructor(config: FsEvidenceArtifactStoreConfig);
+    persistDecisionScreenshot(bytes: Uint8Array): ArtifactRef;
+    persistEvidenceDocument(document: Exclude<EvidenceDocument, {
+        kind: 'variables';
+    }>): ArtifactRef;
+    private syncDirectories;
+    private syncPath;
+    hasBlob(sha: string): boolean;
+    persistRecording(stagingPath: string): PersistedRecording;
+    blobSize(sha: string): number | undefined;
+    readBlobRange(sha: string, start: number, end: number): Uint8Array | undefined;
+    discardRecording(stagingPath: string): void;
+    private assertRecordingStagingPath;
+    private unlinkRecordingStaging;
+    getBlob(sha: string): Uint8Array | undefined;
+}
+
+/** Minimal structural debug-logger seam (a core `ScopedLogger` satisfies it; no core dependency). */
+interface ScreenshotCompressorLogger {
+    debug(message: string, meta?: Record<string, unknown>): void;
+}
+interface CompressOptions {
+    effectiveResolution: number;
+    maxBytes?: number;
+    actionSpaceWidth: number;
+}
+interface CompressResult {
+    buffer: Buffer;
+    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);
+    compress(screenshot: Buffer, options: {
+        effectiveResolution: number;
+        maxBytes?: number;
+        actionSpaceWidth: number;
+    }): Promise<CompressedScreenshot>;
+    dimensions(screenshot: Buffer): Promise<{
+        width: number;
+        height: number;
+    }>;
+}
+interface AlignOptions {
+    width: number;
+    height: number;
+}
+/** Resize buffer to exact window dimensions. Used by mobile adapters for action-space alignment
+ *  (e.g., iOS physical pixels → logical points). */
+declare function alignToWindow(buffer: Buffer, opts: AlignOptions): Promise<Buffer>;
+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>;
+
+/** The project-local state file holding the per-product ordinal map. */
+declare const BUILD_ORDINALS_FILE = "build-ordinals.json";
+interface NextBuildOrdinalOptions {
+    /** Runtime root (e.g. DEFAULT_AGENT_QA_DIR = '.agent-qa'). */
+    root: string;
+    /** The product whose counter to advance. */
+    product: string;
+}
+interface BuildOrdinalReservation {
+    /** Canonical, sorted, duplicate-free product axes advanced by the reservation. */
+    products: readonly string[];
+    /** One ordinal strictly later than every affected product's current counter. */
+    ordinal: number;
+}
+type BuildOrdinalReservationErrorCode = 'invalid-state' | 'missing-counter' | 'invalid-counter' | 'counter-exhausted';
+/** Typed pre-persistence refusal for an unsafe maintenance ordinal reservation. */
+declare class BuildOrdinalReservationError extends Error {
+    readonly name = "BuildOrdinalReservationError";
+    readonly code: BuildOrdinalReservationErrorCode;
+    readonly product: string;
+    readonly value?: unknown;
+    constructor(code: BuildOrdinalReservationErrorCode, product: string, value?: unknown);
+}
+interface ReserveBuildOrdinalForProductsOptions {
+    /** Runtime root containing build-ordinals.json. */
+    root: string;
+    /** Product axes whose counters must advance together. Duplicates and order are ignored. */
+    products: Iterable<string>;
+    /**
+     * Synchronous authority fence invoked after the complete temp file is prepared and immediately
+     * before the atomic rename. Throwing refuses persistence and removes the temp file.
+     */
+    beforePersist?: (reservation: BuildOrdinalReservation) => void;
+}
+/** Undefined is the explicit no-op result for an empty affected-product set. */
+type ReserveBuildOrdinalForProductsResult = number | undefined;
+declare function nextBuildOrdinal(opts: NextBuildOrdinalOptions): Promise<number>;
+/**
+ * Reserve one strictly-later maintenance ordinal across every affected product axis.
+ *
+ * Unlike the best-effort run-start counter above, maintenance reservation is fail-closed: every
+ * required counter must already exist and be a non-negative safe integer. The complete map is
+ * persisted with one same-directory atomic replacement only after all validation succeeds.
+ */
+declare function reserveBuildOrdinalForProducts(opts: ReserveBuildOrdinalForProductsOptions): Promise<ReserveBuildOrdinalForProductsResult>;
+
+/** The project-local state file holding product -> tag -> first-seen ordinal. */
+declare const BUILD_TAGS_FILE = "build-tags.json";
+type BuildTagMap = Record<string, Record<string, number>>;
+declare function recordBuildTag(opts: {
+    root: string;
+    product: string;
+    tag: string;
+    ordinal: number;
+}): Promise<void>;
+declare function resolveBuildTag(opts: {
+    root: string;
+    product: string;
+    tag: string;
+}): number | undefined;
+/** Pure read of the current per-product ordinal; never advances build-ordinals.json. */
+declare function latestBuildOrdinal(opts: {
+    root: string;
+    product: string;
+}): number;
+/** Best-effort, sanitized read: missing, corrupt, and non-object state starts empty. */
+declare function readBuildTagMap(opts: {
+    root: string;
+}): BuildTagMap;
+
+interface DockerHookExecutorConfig {
+    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 dockerBin;
+    private readonly pullPolicy;
+    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.
+ */
+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 };