import type { MeticulousClient } from "../types/client.types";
import type { ContainerEnvVariable, ProjectIdentifier } from "./project-deployments.api";
export interface RequestAgenticInstructionsUploadParams extends ProjectIdentifier {
    size: number;
}
export interface RequestAgenticInstructionsUploadResponse {
    uploadUrl: string;
    /** Server-minted id that ties the uploaded instructions to a later trigger. */
    instructionsId: string;
}
export interface AgenticContainerAppTarget {
    type: "container";
    uploadId: string;
    enableLocalMocks?: boolean | undefined;
    containerPort?: number | undefined;
    containerEnv?: ContainerEnvVariable[] | undefined;
    containerHealthCheckEndpoint?: string | undefined;
}
export interface AgenticAssetsBackend {
    url: string;
    username?: string | undefined;
    password?: string | undefined;
    proxyPaths?: string[] | undefined;
}
export interface AgenticAssetsAppTarget {
    type: "assets";
    assetsUploadId: string;
    backend?: AgenticAssetsBackend | undefined;
}
export type AgenticAppTarget = AgenticContainerAppTarget | AgenticAssetsAppTarget;
export interface CompleteAgenticSessionGenerationParams extends ProjectIdentifier {
    commitSha: string;
    /** Server-minted id of instructions uploaded for this trigger, if any. */
    instructionsId?: string;
    appTarget?: AgenticAppTarget | undefined;
    /** @deprecated Use appTarget.type = "container". */
    uploadId?: string | undefined;
    /** @deprecated Use appTarget.type = "container". */
    containerPort?: number | undefined;
    /** @deprecated Use appTarget.type = "container". */
    containerEnv?: ContainerEnvVariable[] | undefined;
    /** @deprecated Use appTarget.type = "container". */
    containerHealthCheckEndpoint?: string | undefined;
}
export interface CompleteAgenticSessionGenerationResponse {
    /** The id of the launched agentic session generation workflow run. */
    workflowRunId?: string;
    message?: string;
}
export declare const requestAgenticInstructionsUpload: ({ client, projectId, ...body }: RequestAgenticInstructionsUploadParams & {
    client: MeticulousClient;
}) => Promise<RequestAgenticInstructionsUploadResponse>;
export declare const completeAgenticSessionGeneration: ({ client, projectId, ...body }: CompleteAgenticSessionGenerationParams & {
    client: MeticulousClient;
}) => Promise<CompleteAgenticSessionGenerationResponse>;
export type AgenticRunResultCaseOutcome = "pass" | "fail" | "blocked" | "skipped";
export type AgenticRunResultCaseTag = "happy-path" | "edge-case" | "regression";
/**
 * Outcome of a single step. A case's outcome is derived from its steps'
 * outcomes: any failed step fails the case, otherwise any blocked step blocks
 * it, otherwise it passes.
 */
export type AgenticRunStepOutcome = Exclude<AgenticRunResultCaseOutcome, "skipped">;
export type AgenticRunStepKind = "navigate" | "click" | "input" | "assert" | "other";
/**
 * The region of a step's screenshot the reviewer should focus on, in CSS
 * pixels relative to the top-left of the viewport screenshot. Inferred by the
 * worker from a live DOM element's bounding box — never supplied as coordinates
 * by the model.
 */
export interface AgenticRunHighlightRegion {
    x: number;
    y: number;
    width: number;
    height: number;
}
/** A single step the agent took while running a case. */
export interface AgenticRunResultStep {
    /** What the step did, e.g. "Click the 'Schedule for later' switch". */
    description: string;
    kind?: AgenticRunStepKind;
    /** How the step went. Absent on blobs from older workers. */
    outcome?: AgenticRunStepOutcome;
    /** Extra detail, e.g. the selector used or the exact text asserted. */
    detail?: string;
    /**
     * Workdir-relative artifact path of a screenshot taken at this step (as
     * returned by the test facade's `page.screenshot`), e.g.
     * "artifacts/run-3/booked.png". Resolvable to a download URL via the run's
     * `artifactDownloadUrls` GraphQL field once the worker has uploaded it.
     */
    screenshotPath?: string;
    /** SHA-256 of the screenshot bytes, used to identify duplicate evidence. */
    screenshotContentHash?: string;
    /** Worker-measured element the reviewer should focus on, when available. */
    highlightRegion?: AgenticRunHighlightRegion;
    /**
     * Worker-captured viewport immediately before the action associated with this
     * step. Kept alongside `screenshotPath`, which shows the post-action state.
     */
    actionScreenshotPath?: string;
    /** SHA-256 of the pre-action screenshot bytes. */
    actionScreenshotContentHash?: string;
    /** Where the acted-on element was in `actionScreenshotPath`. */
    actionHighlightRegion?: AgenticRunHighlightRegion;
}
/**
 * A single user flow the agent exercised, with its outcome and the sessions it
 * recorded while running it. One agentic run produces many of these.
 */
export type AgenticCaseProvenance = "new" | "reused" | "repaired";
export interface AgenticRunResultCase {
    /** Short human-readable name of the flow, unique within this run. */
    title: string;
    /**
     * How this run came by the case: authored fresh, inherited and re-run
     * unchanged, or inherited and edited. Derived by the worker from the case
     * file's hash — never declared by the agent.
     */
    provenance?: AgenticCaseProvenance;
    /** The kind of flow this case exercises. */
    tag?: AgenticRunResultCaseTag;
    /** Short human-readable name shared by closely related cases. */
    group?: string;
    /** The steps the agent took, in order. */
    steps: AgenticRunResultStep[];
    outcome: AgenticRunResultCaseOutcome;
    /**
     * Concise user-visible account of what happened and, for a non-passing case,
     * the concrete reason. Optional for result blobs written by older workers.
     */
    outcomeSummary?: string;
    /** Sessions recorded while running this case. */
    sessionIds: string[];
    /** Why this case was worth testing, e.g. which changed code it targets. */
    rationale?: string;
    /**
     * @deprecated Legacy workers may have included free-form notes. New workers
     * report step outcomes instead.
     */
    notes?: string;
}
export interface AgenticRunSummaryTakeaway {
    /** Index into the run's `cases` array. */
    caseIndex: number;
    /** Short, agent-written finding grounded in that case's result. */
    text: string;
}
/** Agent-written summary of the completed run. */
export interface AgenticRunSummary {
    takeaways: AgenticRunSummaryTakeaway[];
}
/** Coarse metadata about how the agentic run itself executed. */
export interface AgenticRunMetadata {
    /** ISO timestamp the worker started the run. */
    startedAt?: string;
    /** ISO timestamp the worker finished driving and reported. */
    finishedAt?: string;
    /** The model the agent ran on. */
    model?: string;
    /** Number of runTest invocations across the run. */
    iterations?: number;
}
export type AgenticRunTraceEventKind = "system-prompt" | "user-prompt" | "assistant" | "tool-use" | "tool-result" | "result" | "error";
export interface AgenticRunTraceEvent {
    timestamp: string;
    kind: AgenticRunTraceEventKind;
    text: string;
    toolName?: string;
    toolUseId?: string;
    isError?: boolean;
}
export interface AgenticRunTraceUsage {
    status: "success" | "error" | "unknown";
    stopReason?: string;
    durationMs: number;
    numTurns: number;
    inputTokens: number;
    outputTokens: number;
    cacheReadInputTokens: number;
    cacheCreationInputTokens: number;
    totalCostUsd: number;
}
export interface AgenticRunTrace {
    events: AgenticRunTraceEvent[];
    truncated: boolean;
    /** Terminal status and model usage reported by this SDK query. */
    usage?: AgenticRunTraceUsage;
}
export interface AgenticRunCaseTrace extends AgenticRunTrace {
    caseIndex: number;
    caseTitle: string;
}
/** Transcript of the planning agent and each independently-run case agent. */
export interface AgenticRunTraces {
    planner: AgenticRunTrace;
    cases: AgenticRunCaseTrace[];
}
export interface AgenticRunCoverageFile {
    /** Repo-relative post-edit path. */
    path: string;
    /**
     * Edited lines the coverage tool could observe (this file's denominator), as
     * inclusive [start, end] line ranges.
     */
    executableEditedRanges: Array<[number, number]>;
    /**
     * Executable-edited lines the run covered (a subset of
     * `executableEditedRanges`), as inclusive [start, end] line ranges.
     */
    coveredEditedRanges: Array<[number, number]>;
}
/**
 * Edit-coverage for the run: how much of the PR's changed code the produced
 * sessions exercised. Omitted entirely when coverage could not be measured
 * (e.g. the app under test served no source maps).
 *
 * The canonical, non-redundant coverage shape (structurally the `EditCoverage`
 * produced by `@alwaysmeticulous/coverage-utils`): only the executable and
 * covered edited ranges are carried per file; aggregate counts, the fraction,
 * and residual-uncovered ranges are all DERIVED by consumers, never stored.
 */
export interface AgenticRunCoverage {
    perFile: AgenticRunCoverageFile[];
    /** Edited files with no coverage data at all (unmappable / not loaded). */
    unobservedFiles: string[];
}
/**
 * The `{ cases, coverage, runMetadata, traces, summary }` document stored in S3
 * for one run — everything about a run that is too big to belong on its row.
 * Uploaded by the worker straight to a presigned URL; read back by the webapp
 * via the run's `resultBlobUrl`, and by the backend for its coverage.
 */
export interface AgenticRunResultBlob {
    /**
     * Format version of this document, so a reader holding only the bytes can
     * tell whether it can parse them. `AGENTIC_RESULT_VERSION` in
     * `@alwaysmeticulous/common-utils` is the current value and documents when to
     * bump it; absent means the blob predates versioning and reads as version 1.
     */
    version: number;
    cases: AgenticRunResultCase[];
    /** Edit-coverage for the run; omitted when coverage could not be measured. */
    coverage?: AgenticRunCoverage;
    /** How the run itself executed (timing, model, iterations), when known. */
    runMetadata?: AgenticRunMetadata;
    /** Planner and per-case agent transcripts, when captured by the worker. */
    traces?: AgenticRunTraces;
    /** Agent-written takeaways grounded in completed cases. */
    summary?: AgenticRunSummary;
}
export interface ReportAgenticRunResultResponse {
    message?: string;
    /**
     * Whether the backend actually stored the result on a run record. False when
     * the report could not be correlated to a run or the run already had a
     * terminal result (the response is still a 200 so terminal reports never
     * fail the worker).
     */
    recorded?: boolean;
}
export interface RequestAgenticResultUploadParams extends ProjectIdentifier {
    /** The agentic run id the backend minted at launch (env `AGENTIC_RUN_ID`). */
    agenticRunId: string;
    /** Size in bytes of the blob about to be PUT, signed into the URL. */
    size: number;
}
export interface RequestAgenticResultUploadResponse {
    uploadUrl: string;
}
/**
 * Requests a presigned URL for the run's result blob, so the worker PUTs the
 * payload straight to S3 rather than sending it through the API. The key is
 * derived server-side from the run, so the caller never names its destination.
 * Followed by {@link completeAgenticRunResult} once the PUT succeeds.
 */
export declare const requestAgenticResultUpload: ({ client, projectId, ...body }: RequestAgenticResultUploadParams & {
    client: MeticulousClient;
}) => Promise<RequestAgenticResultUploadResponse>;
export interface CompleteAgenticRunResultParams extends ProjectIdentifier {
    /** The agentic run id the blob was keyed on when its upload was presigned. */
    agenticRunId: string;
    /** Every session produced across the run (the union of all cases' sessions). */
    sessionIds: string[];
}
/**
 * Points a run at the result blob the worker has already uploaded. Everything
 * else the run records — its commit and app URL — the backend wrote at launch.
 */
export declare const completeAgenticRunResult: ({ client, projectId, ...body }: CompleteAgenticRunResultParams & {
    client: MeticulousClient;
}) => Promise<ReportAgenticRunResultResponse>;
export interface IsAgenticRunCancelledParams extends ProjectIdentifier {
    /** The agentic run id the backend minted at launch (env `AGENTIC_RUN_ID`). */
    agenticRunId: string;
}
export interface IsAgenticRunCancelledResponse {
    /**
     * `true` once the run has been cancelled (e.g. superseded by a newer run for
     * the same PR).
     */
    cancelled: boolean;
}
/**
 * Returns whether the run has been cancelled — a point-in-time query the worker
 * polls throughout its run. On the first `true` the worker aborts its agent and
 * exits without reporting a result; the run's terminal `cancelled` status was
 * already set by whoever requested the cancellation.
 */
export declare const isAgenticRunCancelled: ({ client, projectId, agenticRunId, }: IsAgenticRunCancelledParams & {
    client: MeticulousClient;
}) => Promise<IsAgenticRunCancelledResponse>;
export interface RequestAgenticTestcasesUploadParams extends ProjectIdentifier {
    /** The agentic run id the backend minted at launch (env `AGENTIC_RUN_ID`). */
    agenticRunId: string;
    /** Bundle size in bytes. */
    size: number;
}
export interface RequestAgenticTestcasesUploadResponse {
    uploadUrl: string;
}
/**
 * Requests a presigned upload URL for the run's testcase bundle — the verbatim
 * code of every testcase, which the next run on the same PR inherits as
 * its baseline. Deliberately takes no path: there is exactly one bundle per run
 * and the backend derives its key, so no part of the destination is
 * caller-controlled.
 */
export declare const requestAgenticTestcasesUpload: ({ client, projectId, ...body }: RequestAgenticTestcasesUploadParams & {
    client: MeticulousClient;
}) => Promise<RequestAgenticTestcasesUploadResponse>;
export interface AgenticArtifactUploadFile {
    /**
     * Workdir-relative artifact path, e.g. "artifacts/run-3/booked.png". Must
     * stay inside the artifacts directory (no ".." segments).
     */
    path: string;
    /** File size in bytes. */
    size: number;
}
export interface RequestAgenticArtifactUploadsParams extends ProjectIdentifier {
    /** The agentic run id the backend minted at launch (env `AGENTIC_RUN_ID`). */
    agenticRunId: string;
    files: AgenticArtifactUploadFile[];
}
export interface RequestAgenticArtifactUploadsResponse {
    uploads: Array<{
        path: string;
        uploadUrl: string;
    }>;
}
/**
 * Requests presigned upload URLs for run artifacts (the screenshots the agent
 * took while driving), stored next to the run's result blob. The worker calls
 * this just before reporting the result, so the report's `screenshotPath`
 * references resolve for readers.
 */
export declare const requestAgenticArtifactUploads: ({ client, projectId, ...body }: RequestAgenticArtifactUploadsParams & {
    client: MeticulousClient;
}) => Promise<RequestAgenticArtifactUploadsResponse>;
export interface GetAgenticRunCoverageParams extends ProjectIdentifier {
    /** The agentic run id the backend minted at launch. */
    agenticRunId: string;
}
export interface GetAgenticRunCoverageResponse {
    /**
     * The run's edit-coverage, read out of its result blob. `null` when the run has
     * no result yet or measured no coverage at all (e.g. the app under test served
     * no source maps) — distinct from a measured-but-empty `perFile`, which must
     * not be read as "the agent covered nothing".
     */
    coverage: AgenticRunCoverage | null;
}
/**
 * Reads one agentic run's edit-coverage. The counterpart to
 * `GET /api/agent/test-runs/:id/js-coverage` for the normal test run, so the two
 * can be compared over a shared denominator without either caller touching S3.
 *
 * Gated on source-code access like the other coverage reads: per-file ranges name
 * the project's changed source paths.
 */
export declare const getAgenticRunCoverage: ({ client, projectId, agenticRunId, }: GetAgenticRunCoverageParams & {
    client: MeticulousClient;
}) => Promise<GetAgenticRunCoverageResponse>;
export interface GetAgenticChangedFilesParams extends ProjectIdentifier, AgenticRepoLeaseRef {
    commitSha: string;
}
export interface AgenticChangedFile {
    filename: string;
    status?: string;
}
export interface GetAgenticChangedFilesResponse {
    /** `null` when no PR/diff is available or source access is disabled. */
    files: AgenticChangedFile[] | null;
    /**
     * The resolved PR base sha, or `null` under the same conditions `files` is
     * `null`. Lets a caller that only has the head commit sha (e.g. the agentic
     * session generation worker) call `getRelevantSessions`, which requires a
     * `baseCommitSha`.
     */
    baseSha: string | null;
}
/**
 * Lists the files the PR under test touched. Served cap-free off the project's
 * repo-server mirror where possible, falling back to the hosting provider. When
 * `runId` is supplied the mirror read borrows the worker's durable run lease (a
 * warm pod) instead of acquiring a fresh short-lived one; a missing/stale lease
 * falls back to the leaseless path server-side.
 */
export declare const getAgenticChangedFiles: ({ client, projectId, commitSha, runId, }: GetAgenticChangedFilesParams & {
    client: MeticulousClient;
}) => Promise<GetAgenticChangedFilesResponse>;
/**
 * The agentic run id (workflow run id) a read carries so the backend borrows the
 * worker's durable repo-server lease — discovered by this id — instead of
 * acquiring a fresh short-lived lease per read. Optional: absent (or a lease
 * that's since gone) falls back to the leaseless per-read path server-side.
 */
export interface AgenticRepoLeaseRef {
    runId?: string;
}
export interface GetAgenticRepoFileParams extends ProjectIdentifier, AgenticRepoLeaseRef {
    commitSha: string;
    path: string;
    /** Hard cap on the returned file size in bytes. */
    maxBytes?: number;
}
export interface GetAgenticRepoFileResponse {
    kind: "found" | "missing";
    /** UTF-8 decoded file contents; present only when `kind === "found"`. */
    content?: string;
    /** `true` when the file exceeded `maxBytes` and `content` is partial. */
    truncated?: boolean;
    /** Total file size in bytes before any truncation. */
    sizeBytes?: number;
}
/** Reads a single source file from the project's repo at `commitSha`. */
export declare const getAgenticRepoFile: ({ client, projectId, ...body }: GetAgenticRepoFileParams & {
    client: MeticulousClient;
}) => Promise<GetAgenticRepoFileResponse>;
export interface SearchAgenticRepoCodeParams extends ProjectIdentifier, AgenticRepoLeaseRef {
    commitSha: string;
    pattern: string;
    /** Restrict the search to these path prefixes. */
    paths?: string[];
    caseInsensitive?: boolean;
    /** Lines of context to return around each match. */
    contextLines?: number;
    /** Hard cap on the number of matches returned. */
    maxMatches?: number;
}
export interface AgenticRepoSearchMatch {
    path: string;
    lineNumber: number;
    line: string;
    before: string[];
    after: string[];
}
export interface SearchAgenticRepoCodeResponse {
    matches: AgenticRepoSearchMatch[];
    /** `true` when `maxMatches` was reached and trailing matches were dropped. */
    truncated: boolean;
}
/** Searches the project's repo (ripgrep) at `commitSha`. */
export declare const searchAgenticRepoCode: ({ client, projectId, ...body }: SearchAgenticRepoCodeParams & {
    client: MeticulousClient;
}) => Promise<SearchAgenticRepoCodeResponse>;
export interface GetAgenticFileChangesParams extends ProjectIdentifier, AgenticRepoLeaseRef {
    commitSha: string;
    /** Repo-relative path of the file whose changes to return. */
    path: string;
}
export interface GetAgenticFileChangesResponse {
    /**
     * The file's unified diff (base..head) as raw patch text, or `null` when no
     * PR/diff is available or source access is disabled. Empty string when the
     * file is unchanged.
     */
    diff: string | null;
}
/**
 * Returns how a single file changed in the PR under test (unified-diff hunks).
 * The worker uses this to compute edit-coverage; the agent uses it to see what
 * changed in a file it is about to exercise.
 */
export declare const getAgenticFileChanges: ({ client, projectId, ...body }: GetAgenticFileChangesParams & {
    client: MeticulousClient;
}) => Promise<GetAgenticFileChangesResponse>;
export interface ListAgenticRepoTreeParams extends ProjectIdentifier, AgenticRepoLeaseRef {
    commitSha: string;
    /** Tree path inside the commit. Defaults to the repo root. */
    path?: string;
    /** When true, walks descendants recursively. */
    recursive?: boolean;
    /** Hard cap on the number of entries returned. */
    maxEntries?: number;
}
export interface AgenticRepoTreeEntry {
    type: "blob" | "tree" | "commit";
    path: string;
    /** Blob size in bytes; `null` for trees/submodules and blobless-mirror blobs. */
    sizeBytes: number | null;
}
export interface ListAgenticRepoTreeResponse {
    entries: AgenticRepoTreeEntry[];
    /** `true` when `maxEntries` was reached and trailing entries were dropped. */
    truncated: boolean;
}
/** Lists a tree in the project's repo at `commitSha`. */
export declare const listAgenticRepoTree: ({ client, projectId, ...body }: ListAgenticRepoTreeParams & {
    client: MeticulousClient;
}) => Promise<ListAgenticRepoTreeResponse>;
export interface AcquireAgenticRepoLeaseParams extends ProjectIdentifier {
    /** The agentic run id (workflow run id) the lease is keyed on. */
    runId: string;
}
export interface AcquireAgenticRepoLeaseResponse {
    leaseId: string;
    podInstanceId?: string;
    recommendedHeartbeatIntervalMs: number;
    heartbeatTtlMs: number;
}
/**
 * Acquires a durable repo-server lease for the whole agentic run and kicks off
 * the mirror clone. Blocks only on the bounded pod-boot step; poll
 * {@link getAgenticRepoLeaseStatus} for the clone. The caller must heartbeat
 * (see {@link heartbeatAgenticRepoLease}) and release it
 * ({@link releaseAgenticRepoLease}). Source access is a hard requirement, so this
 * rejects (403) rather than returning an "unavailable" result when the
 * `ALLOW_CODE_ACCESS` kill switch is off, the project disables source access, or
 * the project isn't enrolled.
 */
export declare const acquireAgenticRepoLease: ({ client, projectId, ...body }: AcquireAgenticRepoLeaseParams & {
    client: MeticulousClient;
}) => Promise<AcquireAgenticRepoLeaseResponse>;
export interface GetAgenticRepoLeaseStatusParams extends ProjectIdentifier {
    /** Instance id of the lease-holding pod (from acquire), if any. */
    podInstanceId?: string;
}
export interface AgenticRepoLeaseStatusResponse {
    /** `true` when the pod is up and its git mirror has finished cloning. */
    ready: boolean;
}
/**
 * Returns whether the held lease's pod + git mirror are ready right now — a
 * single point-in-time status query, not a wait. The caller drives its own poll
 * loop (source reads simply retry a mirror that's still cloning).
 */
export declare const getAgenticRepoLeaseStatus: ({ client, projectId, podInstanceId, }: GetAgenticRepoLeaseStatusParams & {
    client: MeticulousClient;
}) => Promise<AgenticRepoLeaseStatusResponse>;
export interface HeartbeatAgenticRepoLeaseParams extends ProjectIdentifier {
    leaseId: string;
    podInstanceId?: string;
}
export interface HeartbeatAgenticRepoLeaseResponse {
    ok: boolean;
    expiresAt?: string;
}
/** Heartbeats the held lease to keep it alive for the run's lifetime. */
export declare const heartbeatAgenticRepoLease: ({ client, projectId, ...body }: HeartbeatAgenticRepoLeaseParams & {
    client: MeticulousClient;
}) => Promise<HeartbeatAgenticRepoLeaseResponse>;
export interface ReleaseAgenticRepoLeaseParams extends ProjectIdentifier {
    leaseId: string;
    podInstanceId?: string;
}
export interface ReleaseAgenticRepoLeaseResponse {
    released: boolean;
}
/** Releases the held lease at the end of the run (best-effort). */
export declare const releaseAgenticRepoLease: ({ client, projectId, ...body }: ReleaseAgenticRepoLeaseParams & {
    client: MeticulousClient;
}) => Promise<ReleaseAgenticRepoLeaseResponse>;
//# sourceMappingURL=agentic-session-generation.api.d.ts.map