infraweaver 0.1.0

package/dist/mcp/modules.d.ts

@@ -0,0 +1,198 @@
+import type { LocalToolContext } from "#app/mcp/localContext";
+/**
+ * Terraform module support (module catalogue). Two related capabilities:
+ *
+ *  - **Module catalogue** — an operator-curated list of approved modules (a
+ *    registry module like `terraform-aws-modules/vpc/aws`, or one of the org's
+ *    own/house modules at a local path) that a fix/generation should PREFER over
+ *    hand-rolling raw resources. Surfaced by `list_modules`.
+ *  - **Module-source-aware fixes** — parse the repo's `module "x" { source = … }`
+ *    blocks into a call-graph so a concern inside a *local* module is fixed at
+ *    its SOURCE once (not patched at every call site), while a concern that would
+ *    require editing a *registry/remote* module is flagged as out-of-repo.
+ *    Surfaced by `terraform_module_graph`.
+ *
+ * The parsing is pure (no subprocess) and unit-tested; the tools just read files.
+ */
+export interface ModuleCatalogueEntry {
+    /** the local name to use in a `module "<name>"` block. */
+    name: string;
+    /** the `source` value, e.g. `terraform-aws-modules/vpc/aws` or `./modules/vpc`. */
+    source: string;
+    /** optional version constraint for a registry module. */
+    version: string | null;
+    /** classification of the source (registry / local / git / remote). */
+    kind: ModuleSourceKind;
+}
+export type ModuleSourceKind = "local" | "registry" | "git" | "remote" | "unknown" | "dynamic";
+export interface ParsedModuleSource {
+    /** the full original source string. */
+    raw: string;
+    /** the source with the `//subdir` selector and `?query` stripped. */
+    base: string;
+    /** the `//subdir` path within the module repo/package, or null. */
+    subdir: string | null;
+    /** the `?ref=` revision (git tag/branch/commit), or null. This is how git
+     * modules PIN a version — Terraform has no `version` attribute for them. */
+    ref: string | null;
+    kind: ModuleSourceKind;
+}
+/**
+ * Split a Terraform module `source` into its base, `//subdir` selector, and
+ * `?ref=` revision — the three parts Terraform's go-getter syntax composes
+ * (`git::https://host/repo.git//subdir?ref=v1`,
+ * `terraform-aws-modules/cloudwatch/aws//modules/log-group`). The `//` separator
+ * is the one NOT part of a `://` scheme. Pure; underpins classification + the
+ * version a git module is pinned at.
+ */
+export declare function splitModuleSource(raw: string): ParsedModuleSource;
+/**
+ * Classify a Terraform module `source` string (the full value, including any
+ * `//subdir` / `?ref=`). Mirrors Terraform's own source resolution: a
+ * `./`/`../`/absolute path is LOCAL; a `git::`/`github.com`/`.git`/`bitbucket.org`
+ * source is GIT; an `s3::`/`gcs::`/`http(s)` archive is REMOTE; a bare
+ * `namespace/name/provider` (optionally host-prefixed, optionally with a
+ * `//submodule` path) is a REGISTRY ref.
+ */
+export declare function classifyModuleSource(source: string): ModuleSourceKind;
+/**
+ * Parse the operator's `module_catalogue` input into structured entries. Accepts
+ * newline- and/or comma-separated entries, each:
+ *   `[name=]<source>[ <version>]`
+ * e.g. `vpc=terraform-aws-modules/vpc/aws ~> 5.0`, `terraform-aws-modules/s3-bucket/aws`,
+ * `./modules/networking`. Name is optional (derived from the source when absent);
+ * version applies to registry sources.
+ */
+export declare function parseModuleCatalogue(raw: string | undefined): ModuleCatalogueEntry[];
+export interface ModuleBlock {
+    /** the local name in `module "<name>" { … }`. */
+    name: string;
+    source: string;
+    /** the pinned version — the `version` attribute (registry) or the git `?ref=`
+     * (git), whichever is present; null when unpinned. */
+    version: string | null;
+    /** the `//subdir` selector within the module package, or null. */
+    subdir: string | null;
+    kind: ModuleSourceKind;
+    /** the file the `module` block was declared in (repo-relative). */
+    declaredIn: string;
+}
+/**
+ * Parse every `module "<name>" { … }` block in some HCL into its name, source,
+ * pinned version, and subdir. Brace-matched so nested blocks (e.g. a
+ * `providers = { … }` map inside the module block) don't confuse it. The version
+ * comes from the `version` attribute (registry modules) OR the source's `?ref=`
+ * (git modules), so a git-pinned module isn't reported as unpinned. `declaredIn`
+ * is filled by the caller; here it's "".
+ */
+export declare function parseModuleBlocks(hcl: string): ModuleBlock[];
+export interface ModuleGraph {
+    /** every `module` block found, with its classified source. */
+    modules: ModuleBlock[];
+    /** local module source dirs (repo-relative), each with the caller files that
+     * reference it — fix a concern in one of these dirs ONCE at the source. */
+    localModuleDirs: {
+        dir: string;
+        callers: string[];
+    }[];
+    /** count of registry/git/remote module references — concerns that live inside
+     * one of these are NOT editable in this repo (open an issue instead). */
+    externalCount: number;
+}
+export declare const MAX_TF_FILE_BYTES: number;
+export declare const MAX_TF_TOTAL_BYTES: number;
+/** read a text file, returning null for unreadable OR oversize (> cap bytes)
+ * files — the byte-cap complement of the walk's "unreadable ⇒ skip". */
+export declare function readTextCapped(path: string, cap?: number): string | null;
+/**
+ * Recursively list `*.tf` files under `cwd`, repo-relative (POSIX), skipping
+ * cache/VCS/dep dirs. Bounded by depth and a file cap so a huge monorepo can't
+ * stall the walk. Real Terraform repos (e.g. hepcare) keep their root config in
+ * a subdir (`terraform/`) with house modules in `terraform/modules/` and even a
+ * second root (`terraform/core/`) — a single-level read misses all of that, so
+ * we walk the tree.
+ */
+export declare function walkTfFiles(cwd: string, maxDepth?: number, cap?: number): string[];
+/**
+ * The same bounded walk for any file suffix. `.tfquery.hcl` (Terraform 1.14
+ * query files) lives outside `*.tf` deliberately — it is discovery input, not
+ * managed configuration — so it needs its own walk rather than a widened `.tf`
+ * one, which would sweep query files into every path that assumes "`.tf` ⇒
+ * remediable".
+ */
+export declare function walkFilesBySuffix(cwd: string, suffix: string, maxDepth?: number, cap?: number): string[];
+/**
+ * Walk `cwd` recursively and build the module call-graph across every Terraform
+ * file (root + subdir roots + nested modules). A local module's dir is resolved
+ * RELATIVE TO THE DECLARING FILE (`./modules/x` in `core/main.tf` → `core/modules/x`),
+ * not to `cwd`, so the graph is correct for multi-root repos.
+ */
+export declare function collectModuleGraph(cwd: string): ModuleGraph;
+/**
+ * dependency-aware fix ordering. Order the repo's LOCAL module dirs so a
+ * module that others depend on is fixed BEFORE its dependents — sequencing
+ * remediation PRs so they don't conflict (a fix at a shared module source
+ * propagates to callers; fixing the caller first would be redundant or clash).
+ *
+ * Builds edges among local module dirs: a `module` block declared inside local
+ * dir A whose source resolves to local dir B means "A depends on B", so B must
+ * come first. Returns a stable topological order (Kahn's algorithm, ties broken
+ * by path) of the local module dirs; cycle-safe (any leftover nodes are appended
+ * in sorted order). Pure. The remaining non-module (root) files are fixed after
+ * every local module they call — the caller dirs are in each entry's `callers`.
+ */
+export declare function dependencyOrderedModuleDirs(graph: ModuleGraph): string[];
+/** true when `file` sits under one of the graph's local module dirs — i.e. a
+ * concern there should be fixed at the module SOURCE (it propagates to callers). */
+export declare function isInLocalModule(file: string, graph: ModuleGraph): {
+    dir: string;
+    callers: string[];
+} | null;
+export interface ModuleVariable {
+    name: string;
+    /** the `type` expression as written (`string`, `list(string)`, …), or null. */
+    type: string | null;
+    description: string | null;
+    /** true when the variable has NO `default` (the caller must set it). */
+    required: boolean;
+}
+export interface ModuleOutput {
+    name: string;
+    description: string | null;
+}
+export interface ModuleInterface {
+    variables: ModuleVariable[];
+    outputs: ModuleOutput[];
+}
+/**
+ * Parse a module's `variable`/`output` blocks into its public interface — the
+ * real names, types, descriptions, and which variables are REQUIRED (no
+ * `default`). Used so a generated `module` block (or a Terratest/example
+ * fixture) sets the module's ACTUAL variables instead of guessed ones. Pure;
+ * brace-matched so a nested `type = object({…})` or `validation {…}` doesn't
+ * confuse it.
+ */
+export declare function parseModuleInterface(hcl: string): ModuleInterface;
+/** read a module DIR's `*.tf` (non-recursive — a module is a single dir) and
+ * parse its interface. */
+export declare function collectModuleInterface(cwd: string, moduleDir: string): ModuleInterface;
+export declare const ListModulesParams: import("arktype/internal/variants/object.ts").ObjectType<object, {}>;
+export declare function ListModulesTool(ctx: LocalToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<object, object>> & {
+    mutates?: boolean;
+};
+export declare const TerraformModuleGraphParams: import("arktype/internal/variants/object.ts").ObjectType<object, {}>;
+export declare function TerraformModuleGraphTool(ctx: LocalToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<object, object>> & {
+    mutates?: boolean;
+};
+export declare const TerraformModuleInterfaceParams: import("arktype/internal/variants/object.ts").ObjectType<{
+    module_dir: string;
+}, {}>;
+export declare function TerraformModuleInterfaceTool(ctx: LocalToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    module_dir: string;
+}, {
+    module_dir: string;
+}>> & {
+    mutates?: boolean;
+};
+/** best-effort existence check used by tests/tools — exported for reuse. */
+export declare function moduleDirExists(cwd: string, dir: string): boolean;

package/dist/mcp/output.d.ts

@@ -0,0 +1,16 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { ToolContext } from "#app/mcp/server";
+export declare const SetOutputParams: import("arktype/internal/variants/object.ts").ObjectType<{
+    value: string;
+}, {}>;
+type JsonSchema = Record<string, unknown>;
+export declare function SetOutputTool(ctx: ToolContext, outputSchema?: JsonSchema): (import("fastmcp").Tool<any, StandardSchemaV1<any, any>> & {
+    mutates?: boolean;
+}) | (import("fastmcp").Tool<any, StandardSchemaV1<{
+    value: string;
+}, {
+    value: string;
+}>> & {
+    mutates?: boolean;
+});
+export {};

package/dist/mcp/pathSafety.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Resolve an agent-supplied path against `cwd` and confine it to that workspace.
+ *
+ * Returns the absolute path when it stays inside `cwd`; throws otherwise. Blocks
+ * both `..` traversal and absolute paths that point outside `cwd` (including a
+ * different drive on Windows, where `relative` returns an absolute path).
+ *
+ * Infraweaver treats the agent as semi-trusted (attacker-controlled PR content can
+ * prompt-inject it), so any tool that reads or writes a file path the agent
+ * controls — read_findings, terraform_emit_sarif, terraform_module_interface —
+ * must confine that path to the workspace. Without it the agent has an arbitrary
+ * file read (findings) or write (SARIF) primitive on the runner.
+ */
+export declare function resolveWithinCwd(cwd: string, userPath: string): string;

package/dist/mcp/policy.d.ts

@@ -0,0 +1,50 @@
+import type { LocalToolContext } from "#app/mcp/localContext";
+/**
+ * Policy-as-code gate (OPA/Conftest). An optional, opt-in tool that runs
+ * the operator's own Rego policies against the Terraform plan JSON (or the HCL),
+ * so an org's policy-as-code can gate a remediation/generation the same way the
+ * deterministic scanners do — pairs with prevent recurrence. Infraweaver is
+ * an ORCHESTRATOR here, never a redistributor: it invokes the external
+ * `conftest` (OPA) binary as a separate process and consumes its normalized
+ * output. Degrades green — when conftest isn't installed or no policy dir
+ * exists, it returns `ok: false` with a `code` and never fails the run.
+ *
+ * The parsing is pure + unit-tested; the tool just shells out and parses.
+ */
+export interface PolicyFailure {
+    /** the policy rule message (the human-readable violation). */
+    msg: string;
+    /** the file conftest evaluated (repo-relative when conftest reported it). */
+    file: string;
+    /** "failure" (a deny) or "warning" (a warn). */
+    level: "failure" | "warning";
+}
+export interface PolicyResult {
+    /** true when there were zero failures (warnings don't fail the gate). */
+    passed: boolean;
+    failures: PolicyFailure[];
+    warnings: PolicyFailure[];
+    /** total tests conftest ran (across files), for a confidence signal. */
+    tested: number;
+}
+/**
+ * Parse `conftest test --output json` output into a normalized PolicyResult.
+ * Conftest emits an array of per-file result objects, each with `failures` /
+ * `warnings` / `successes`. Pure; tolerant of malformed/empty input (returns a
+ * clean pass). A non-empty `failures` anywhere means the gate did NOT pass;
+ * warnings are surfaced but don't fail it.
+ */
+export declare function parseConftestOutput(stdout: string): PolicyResult;
+export declare const PolicyCheckParams: import("arktype/internal/variants/object.ts").ObjectType<{
+    target?: string;
+    policy_dir?: string;
+}, {}>;
+export declare function PolicyCheckTool(ctx: LocalToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    target?: string;
+    policy_dir?: string;
+}, {
+    target?: string;
+    policy_dir?: string;
+}>> & {
+    mutates?: boolean;
+};

package/dist/mcp/pr.d.ts

@@ -0,0 +1,64 @@
+import type { GitHubWriteToolContext } from "#app/mcp/capabilityContext";
+import type { ResolvedPayload } from "#app/utils/payload";
+import type { RunContextData } from "#app/utils/runContextData";
+/**
+ * The slice `resolveBaseBranch` reads: the declared base-branch input and the
+ * repository's default branch. Shared with `terraform_change_summary`, which
+ * resolves the same base without needing the rest of the GitHub surface.
+ */
+export interface BaseBranchContext {
+    payload: ResolvedPayload;
+    repo: RunContextData["repo"];
+}
+export declare const PullRequest: import("arktype/internal/variants/object.ts").ObjectType<{
+    title: string;
+    body: string;
+    base?: string;
+    draft?: boolean;
+}, {}>;
+/**
+ * Pure base-branch picker. Precedence: an explicit `base_branch` declaration
+ * always wins; otherwise the repository's default branch (GitHub reports it —
+ * normally `main`, sometimes `master`); otherwise prefer `main`, then `master`;
+ * final fallback `main`. Split out from git/ctx so it's exhaustively testable.
+ */
+export declare function pickBaseBranch(opts: {
+    declared?: string | undefined;
+    defaultBranch?: string | undefined;
+    mainExists: boolean;
+    masterExists: boolean;
+}): string;
+/**
+ * Deterministically resolve the branch a PR targets, so the base is never left
+ * to the agent's guess. Resolves to the repository's default branch (`main`, or
+ * `master`), overridable by the `base_branch` input. Git is only probed for
+ * main/master in the last-resort case where neither an explicit declaration nor
+ * a GitHub default branch is available (essentially never).
+ */
+export declare function resolveBaseBranch(ctx: BaseBranchContext): string;
+export declare const UpdatePullRequestBody: import("arktype/internal/variants/object.ts").ObjectType<{
+    pull_number: number;
+    body: string;
+}, {}>;
+export declare function UpdatePullRequestBodyTool(ctx: GitHubWriteToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    pull_number: number;
+    body: string;
+}, {
+    pull_number: number;
+    body: string;
+}>> & {
+    mutates?: boolean;
+};
+export declare function CreatePullRequestTool(ctx: GitHubWriteToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    title: string;
+    body: string;
+    base?: string;
+    draft?: boolean;
+}, {
+    title: string;
+    body: string;
+    base?: string;
+    draft?: boolean;
+}>> & {
+    mutates?: boolean;
+};

package/dist/mcp/prInfo.d.ts

@@ -0,0 +1,11 @@
+import type { GitHubToolContext } from "#app/mcp/capabilityContext";
+export declare const PullRequestInfo: import("arktype/internal/variants/object.ts").ObjectType<{
+    pull_number: number;
+}, {}>;
+export declare function PullRequestInfoTool(ctx: GitHubToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    pull_number: number;
+}, {
+    pull_number: number;
+}>> & {
+    mutates?: boolean;
+};

package/dist/mcp/providerSchema.d.ts

@@ -0,0 +1,52 @@
+import type { LocalToolContext } from "#app/mcp/localContext";
+/**
+ * Provider-schema awareness. A "correct" fix for the wrong provider
+ * major just breaks `plan` — argument names and nested blocks differ across
+ * majors. After `terraform init`, the installed provider's exact schema is
+ * available via `terraform providers schema -json`; this parses it so a fix can
+ * be checked against the REAL attributes/blocks for the version in use, not the
+ * model's memory of the provider.
+ *
+ * The schema fetch is cached per `cwd` for the process (schemas don't change
+ * within a run) and degrades green (returns `ok: false`) when terraform isn't
+ * installed or the dir isn't initialised.
+ */
+export interface ResourceSchema {
+    attributes: Set<string>;
+    blocks: Set<string>;
+}
+/** resourceType → its attribute + nested-block names, across all providers. */
+export type ProvidersSchema = Map<string, ResourceSchema>;
+/**
+ * Parse `terraform providers schema -json` into a resource-type → {attributes,
+ * blocks} map. Merges every provider's `resource_schemas`. Pure; tolerant of a
+ * missing/empty schema.
+ */
+export declare function parseProvidersSchema(json: string): ProvidersSchema;
+/**
+ * Given a resource type and the argument names a fix introduces, return the ones
+ * that are NOT valid attributes or nested blocks for that resource in the
+ * installed provider — i.e. names that would break `plan`. Returns `null` for
+ * `unknownResourceType` when the schema has no entry for the type (can't judge).
+ */
+export declare function unknownArgsForResource(schema: ProvidersSchema, resourceType: string, args: string[]): {
+    unknownResourceType: boolean;
+    unknown: string[];
+};
+/** fetch + cache the providers schema for `cwd`. null when unavailable. */
+export declare function loadProvidersSchema(cwd: string): ProvidersSchema | null;
+/** test-only: clear the per-process schema cache. */
+export declare function _clearProviderSchemaCache(): void;
+export declare const TerraformProviderSchemaParams: import("arktype/internal/variants/object.ts").ObjectType<{
+    resource_type: string;
+    args?: string[];
+}, {}>;
+export declare function TerraformProviderSchemaTool(ctx: LocalToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    resource_type: string;
+    args?: string[];
+}, {
+    resource_type: string;
+    args?: string[];
+}>> & {
+    mutates?: boolean;
+};

package/dist/mcp/review.d.ts

@@ -0,0 +1,212 @@
+import type { RestEndpointMethodTypes } from "@octokit/rest";
+import type { GitHubWriteToolContext } from "#app/mcp/capabilityContext";
+import type { CommentableLines } from "#app/toolState";
+export type { CommentableLines };
+/**
+ * detect GitHub's generic server-side 422 ("An internal error occurred,
+ * please try again.") that sometimes fires on `POST /pulls/{n}/reviews`.
+ *
+ * the body is stable across occurrences and distinct from every other 422
+ * cause we care about (anchor validation, body length, malformed suggestion
+ * blocks) — those all cite the specific problem. treating this as a
+ * transient server error unlocks bounded in-tool retry instead of surfacing
+ * it to the agent with the generic "likely causes (1)(2)(3)" prompt, which
+ * induces whack-a-mole comment dropping on content that was never the issue.
+ */
+export declare function isTransientReviewError(err: unknown): boolean;
+export declare const TRANSIENT_REVIEW_RETRY_DELAYS_MS: number[];
+/**
+ * parse a PR file's patch to determine which line numbers on each side are
+ * valid anchors for inline comments. GitHub only accepts comments on lines
+ * inside a diff hunk: added/context lines on RIGHT, removed/context lines
+ * on LEFT.
+ */
+export declare function commentableLinesForFile(patch: string | undefined): CommentableLines;
+export declare function buildCommentableMap(ctx: GitHubWriteToolContext, pullNumber: number): Promise<Map<string, CommentableLines>>;
+export type ReviewCommentInput = NonNullable<RestEndpointMethodTypes["pulls"]["createReview"]["parameters"]["comments"]>[number];
+export interface DroppedComment {
+    path: string;
+    line: number;
+    startLine?: number | undefined;
+    side: "LEFT" | "RIGHT";
+    reason: string;
+}
+export declare function validateInlineComments(comments: ReviewCommentInput[], map: Map<string, CommentableLines>): {
+    valid: ReviewCommentInput[];
+    dropped: DroppedComment[];
+};
+export declare const MAX_DROPPED_COMMENT_LINES = 50;
+/**
+ * reason a create_pull_request_review call should be skipped without hitting
+ * GitHub. returned by reviewSkipDecision; null means submit normally.
+ */
+export type ReviewSkipDecision = {
+    kind: "no-issues";
+    reason: string;
+} | {
+    kind: "empty-downgraded-approve";
+    reason: string;
+} | {
+    kind: "empty-request-changes";
+    reason: string;
+};
+/**
+ * decision returned by duplicateReviewDecision when a session has already
+ * submitted a review and the current call would be a duplicate.
+ */
+export type DuplicateReviewDecision = {
+    kind: "already-submitted";
+    reviewId: number;
+    reason: string;
+};
+/**
+ * decide whether a second create_pull_request_review call in the same session
+ * is a duplicate of an earlier submission.
+ *
+ * the agent is instructed to call create_pull_request_review exactly once per
+ * Review-mode session (see src/modes/review.ts), but in practice it sometimes
+ * submits twice — once with substantive feedback, then again with the
+ * canonical "No new issues found." body when the prompt's branch logic
+ * re-classifies non-blocking observations. the second submission is
+ * always redundant: the first review is the record, and the duplicate just
+ * adds noise to the PR.
+ *
+ * legitimate follow-up reviews after new commits ARE allowed: when the agent
+ * re-runs checkout_pr to fetch the new commits, checkoutSha advances past the
+ * previously reviewed sha, so any call where checkoutSha has moved past the
+ * prior reviewedSha is a real follow-up and goes through. anything else — same
+ * sha (including an immediate re-submit that skipped checkout_pr), or no
+ * checkoutSha to compare against — is a duplicate.
+ */
+export declare function duplicateReviewDecision(params: {
+    existing: {
+        id: number;
+        reviewedSha: string | undefined;
+    } | undefined;
+    currentCheckoutSha: string | undefined;
+}): DuplicateReviewDecision | null;
+/**
+ * decide whether to skip a review submission before any network call.
+ *
+ * GitHub rejects `event: "COMMENT"` reviews with no body and no inline comments
+ * with HTTP 422 "Unprocessable Entity". two paths produce that shape:
+ *
+ *   1. `!approved` + empty body/comments: agent's "no issues found" result.
+ *      skipping preserves the agent's intent (nothing to post is a fine
+ *      outcome for a review run) without a spurious 422.
+ *   2. `approved` + `!prApproveEnabled` + empty body/comments: the runtime
+ *      downgrades APPROVE to COMMENT when prApproveEnabled is off, and the
+ *      resulting empty-COMMENT is exactly the shape GitHub 422s. skipping
+ *      here surfaces the cause (downgrade + nothing to say) instead of an
+ *      opaque 422 the agent can't recover from.
+ *
+ * legitimate bare approvals (`approved` + `prApproveEnabled`, no body/comments)
+ * are never skipped — GitHub accepts empty APPROVE reviews and the approval
+ * stamp itself is the review's content.
+ *
+ * a contentless `request_changes` is always skipped: a blocking verdict with no
+ * body and no inline comments tells the author nothing about what must change,
+ * and (when downgraded to COMMENT) is the empty-COMMENT shape GitHub 422s.
+ */
+export declare function reviewSkipDecision(params: {
+    approved: boolean;
+    requestChanges?: boolean;
+    body: string | null | undefined;
+    hasComments: boolean;
+    prApproveEnabled: boolean;
+}): ReviewSkipDecision | null;
+export declare function formatDroppedCommentsNote(dropped: DroppedComment[]): string;
+export declare const CreatePullRequestReview: import("arktype/internal/variants/object.ts").ObjectType<{
+    pull_number: number;
+    body?: string;
+    approved?: boolean;
+    request_changes?: boolean;
+    commit_id?: string;
+    comments?: {
+        path: string;
+        line: number;
+        side?: "LEFT" | "RIGHT";
+        body?: string;
+        suggestion?: string;
+        start_line?: number;
+    }[];
+}, {}>;
+export declare function CreatePullRequestReviewTool(ctx: GitHubWriteToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    pull_number: number;
+    body?: string;
+    approved?: boolean;
+    request_changes?: boolean;
+    commit_id?: string;
+    comments?: {
+        path: string;
+        line: number;
+        side?: "LEFT" | "RIGHT";
+        body?: string;
+        suggestion?: string;
+        start_line?: number;
+    }[];
+}, {
+    pull_number: number;
+    body?: string;
+    approved?: boolean;
+    request_changes?: boolean;
+    commit_id?: string;
+    comments?: {
+        path: string;
+        line: number;
+        side?: "LEFT" | "RIGHT";
+        body?: string;
+        suggestion?: string;
+        start_line?: number;
+    }[];
+}>> & {
+    mutates?: boolean;
+};
+/**
+ * clear a pending review draft stranded on the PR by a prior hard-killed run
+ * (workflow timeout, OOM) so the next createReview can succeed.
+ *
+ * GitHub enforces one-pending-review-per-user-per-PR. if the previous process
+ * died between createReview(PENDING) and submitReview, the draft remains and
+ * the next run's createReview 422s with "already has a pending review".
+ * listReviews only exposes PENDING reviews to their author, so filtering on
+ * state === "PENDING" is already scoped to the authed token's own draft.
+ *
+ * if `originalErr` is not a pending-review 422, or no leftover is found, this
+ * function rethrows `originalErr` so the caller surfaces the original failure.
+ * delete failures with 404 (draft already gone) or 422 (draft submitted by a
+ * concurrent caller) are swallowed — the caller's retry will succeed in both
+ * cases. any other delete error is rethrown unchanged.
+ *
+ * known limitation: if two runs on the SAME PR share the authed token and
+ * overlap in time, the loser's createReview 422s on the winner's still-active
+ * draft. recovery would then delete the winner's active draft and the
+ * winner's submitReview would 404. this is not distinguishable from a
+ * genuinely-stranded draft via the review object alone (PENDING reviews
+ * expose no created_at timestamp, and both reviews are authored by the same
+ * bot user). rely on workflow-level concurrency controls (e.g. a concurrency
+ * key keyed to the PR number) to prevent overlap.
+ */
+export declare function clearStrandedPendingReview(ctx: GitHubWriteToolContext, params: {
+    owner: string;
+    repo: string;
+    pull_number: number;
+    originalErr: unknown;
+}): Promise<void>;
+/**
+ * single-step createReview (event != PENDING) with stranded-draft recovery.
+ * the body path goes through createAndSubmitWithFooter which already recovers
+ * from a stranded PENDING draft at its own createReview call. the no-body path
+ * used to call createReview directly with no recovery — so a PR whose previous
+ * body-path run crashed between createReview(PENDING) and submitReview would
+ * permanently 422 any subsequent no-body review (approve-with-no-feedback or
+ * comments-only) until a body-path run happened to clear the draft.
+ */
+export declare function createReviewWithStrandedRecovery(ctx: GitHubWriteToolContext, params: RestEndpointMethodTypes["pulls"]["createReview"]["parameters"]): Promise<Awaited<ReturnType<typeof ctx.octokit.rest.pulls.createReview>>>;
+/**
+ * report the review node ID so the WorkflowRun is marked as "review submitted".
+ * exported for use in main.ts post-agent cleanup.
+ */
+export declare function reportReviewNodeId(ctx: GitHubWriteToolContext, params: {
+    nodeId: string;
+}): Promise<void>;