terramend 0.2.0

package/dist/mcp/review.d.ts

@@ -0,0 +1,199 @@
+import type { RestEndpointMethodTypes } from "@octokit/rest";
+import type { ToolContext } from "#app/mcp/server";
+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: ToolContext, 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;
+};
+/**
+ * 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 action/modes.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: the
+ * new-commits-mid-review path advances toolState.checkoutSha past the
+ * previously reviewed sha, and a subsequent checkout_pr advances it again.
+ * any call where checkoutSha has moved past the prior reviewedSha is a real
+ * follow-up and goes through. anything else — same sha, 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.
+ */
+export declare function reviewSkipDecision(params: {
+    approved: 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;
+    commit_id?: string;
+    comments?: {
+        path: string;
+        line: number;
+        side?: "LEFT" | "RIGHT";
+        body?: string;
+        suggestion?: string;
+        start_line?: number;
+    }[];
+}, {}>;
+export declare function CreatePullRequestReviewTool(ctx: ToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    pull_number: number;
+    body?: string;
+    approved?: 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;
+    commit_id?: string;
+    comments?: {
+        path: string;
+        line: number;
+        side?: "LEFT" | "RIGHT";
+        body?: string;
+        suggestion?: string;
+        start_line?: number;
+    }[];
+}>>;
+/**
+ * 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: ToolContext, 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: ToolContext, 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: ToolContext, params: {
+    nodeId: string;
+}): Promise<void>;

package/dist/mcp/reviewComments.d.ts

@@ -0,0 +1,178 @@
+import type { Octokit } from "@octokit/rest";
+import type { ToolContext } from "#app/mcp/server";
+export declare const REVIEW_THREADS_QUERY = "\nquery ($owner: String!, $name: String!, $prNumber: Int!) {\n  repository(owner: $owner, name: $name) {\n    pullRequest(number: $prNumber) {\n      reviewThreads(first: 100) {\n        nodes {\n          id\n          path\n          line\n          startLine\n          diffSide\n          isResolved\n          isOutdated\n          comments(first: 50) {\n            nodes {\n              fullDatabaseId\n              body\n              bodyHTML\n              createdAt\n              diffHunk\n              line\n              startLine\n              originalLine\n              originalStartLine\n              author { login }\n              pullRequestReview {\n                databaseId\n                author { login }\n              }\n              reactionGroups {\n                content\n                reactors(first: 10) {\n                  totalCount\n                  nodes {\n                    ... on Actor { login }\n                  }\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  }\n}\n";
+export type ReviewThreadComment = {
+    fullDatabaseId: string | null;
+    body: string;
+    bodyHTML: string;
+    createdAt: string;
+    diffHunk: string;
+    line: number | null;
+    startLine: number | null;
+    originalLine: number | null;
+    originalStartLine: number | null;
+    author: {
+        login: string;
+    } | null;
+    pullRequestReview: {
+        databaseId: number | null;
+        author: {
+            login: string;
+        } | null;
+    } | null;
+    reactionGroups: Array<{
+        content: string;
+        reactors: {
+            totalCount?: number;
+            nodes: Array<{
+                login: string;
+            } | null> | null;
+        } | null;
+    }> | null;
+};
+export type ReviewThread = {
+    id: string;
+    path: string;
+    line: number | null;
+    startLine: number | null;
+    diffSide: "LEFT" | "RIGHT";
+    isResolved: boolean;
+    isOutdated: boolean;
+    comments: {
+        nodes: (ReviewThreadComment | null)[] | null;
+    } | null;
+};
+export type ReviewThreadsQueryResponse = {
+    repository: {
+        pullRequest: {
+            reviewThreads: {
+                nodes: (ReviewThread | null)[] | null;
+            } | null;
+        } | null;
+    } | null;
+};
+export declare function countLines(str: string): number;
+export type ParsedHunk = {
+    header: string;
+    oldStart: number;
+    oldCount: number;
+    newStart: number;
+    newCount: number;
+    content: string[];
+};
+export declare function parseFilePatches(patch: string): ParsedHunk[];
+export declare const GetReviewComments: import("arktype/internal/variants/object.ts").ObjectType<{
+    pull_number: number;
+    review_id: number;
+}, {}>;
+/**
+ * §5.7 — render 👍/👎 totals as a `reactions=` tag attribute so the agent sees
+ * human feedback on its findings inline with the thread (a 👎 on a terramend
+ * root comment is false-positive signal; see the IncrementalReview prompt).
+ * Only the thumbs contents — the other six reaction types carry no
+ * accept/reject semantics — and only when at least one is nonzero, so the
+ * common no-reaction case adds zero tokens.
+ */
+export declare function formatReactionCounts(comment: ReviewThreadComment): string;
+/**
+ * formats thread blocks into markdown with TOC and line numbers.
+ * extracted for testability.
+ */
+export declare function formatReviewThreads(threadBlocks: Array<{
+    path: string;
+    lineRange: string;
+    content: string[];
+}>, header: {
+    pullNumber: number;
+    reviewId: number;
+    reviewer: string;
+    reviewBody?: string;
+}): {
+    toc: string;
+    content: string;
+};
+/**
+ * builds thread blocks from review threads and file patches.
+ * extracted for testability.
+ */
+export declare function buildThreadBlocks(threads: ReviewThread[], filePatchMap: Map<string, ParsedHunk[]>, reviewId: number): {
+    path: string;
+    lineRange: string;
+    content: string[];
+}[];
+interface GetReviewDataInput {
+    octokit: Octokit;
+    owner: string;
+    name: string;
+    pullNumber: number;
+    reviewId: number;
+    approvedBy?: string | undefined;
+    tmpdir: string;
+    githubToken: string;
+}
+export interface FormatReviewDataInput {
+    review: ReviewResponse;
+    threads: ReviewThread[];
+    prFiles: ReviewPrFile[];
+    pullNumber: number;
+    reviewId: number;
+}
+export type ReviewResponse = {
+    body: string | null | undefined;
+    user: {
+        login: string;
+    } | null | undefined;
+};
+export type ReviewPrFile = {
+    filename: string;
+    patch?: string | undefined;
+};
+export declare function formatReviewData(input: FormatReviewDataInput): {
+    threadBlocks: Array<{
+        path: string;
+        lineRange: string;
+        content: string[];
+    }>;
+    reviewer: string;
+    formatted: {
+        toc: string;
+        content: string;
+    };
+} | undefined;
+export declare function getReviewData(input: GetReviewDataInput): Promise<{
+    threadBlocks: Array<{
+        path: string;
+        lineRange: string;
+        content: string[];
+    }>;
+    reviewer: string;
+    formatted: {
+        toc: string;
+        content: string;
+    };
+    truncated: boolean;
+} | undefined>;
+export declare function GetReviewCommentsTool(ctx: ToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    pull_number: number;
+    review_id: number;
+}, {
+    pull_number: number;
+    review_id: number;
+}>>;
+export declare const ListPullRequestReviews: import("arktype/internal/variants/object.ts").ObjectType<{
+    pull_number: number;
+}, {}>;
+export declare function ListPullRequestReviewsTool(ctx: ToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    pull_number: number;
+}, {
+    pull_number: number;
+}>>;
+export declare const ResolveReviewThread: import("arktype/internal/variants/object.ts").ObjectType<{
+    thread_id: string;
+}, {}>;
+export declare function ResolveReviewThreadTool(ctx: ToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    thread_id: string;
+}, {
+    thread_id: string;
+}>>;
+export {};

package/dist/mcp/roots.d.ts

@@ -0,0 +1,58 @@
+import type { LocalToolContext } from "#app/mcp/localContext";
+/**
+ * Multi-root awareness. A repo can hold SEVERAL Terraform root modules — the
+ * dirs you'd run `terraform init/plan/apply` in — not one. hepcare, for example,
+ * has `terraform/` AND `terraform/core/`, plus a child module under
+ * `terraform/modules/`. The scanners run recursively, but plan/validate assume a
+ * single `cwd`; this surfaces the roots so a run can act per-root.
+ *
+ * Heuristic (validated against real repos): a ROOT is a dir whose `*.tf`
+ * declares a PROVIDER CONFIGURATION (`provider "<name>" { … }`) or a BACKEND
+ * (`backend "<type>" { … }`). A CHILD MODULE never configures a provider or a
+ * backend (it only declares `required_providers`), so this cleanly separates the
+ * two. Pure parsing + a single fs walk; no subprocess.
+ */
+export interface TerraformRoot {
+    /** repo-relative dir (POSIX); "" for the top-level. */
+    dir: string;
+    hasBackend: boolean;
+    hasProviderConfig: boolean;
+    tfFileCount: number;
+}
+/** detect whether some concatenated HCL marks a root module. */
+export declare function isRootModuleHcl(hcl: string): {
+    hasBackend: boolean;
+    hasProviderConfig: boolean;
+};
+/**
+ * Discover the Terraform root modules under `cwd`. Walks `*.tf` recursively
+ * (skipping cache/VCS dirs via walkTfFiles), groups by directory, and keeps the
+ * dirs that configure a provider or a backend. Sorted by dir. An empty result
+ * means no obvious root was found — the caller falls back to scanning `cwd`
+ * itself as a single root.
+ */
+export declare function discoverTerraformRoots(cwd: string): TerraformRoot[];
+export interface EnvironmentTwinGroup {
+    /** the shared path shape with the env/region segment replaced by `{env}`. */
+    pattern: string;
+    /** the matched twins: each a dir + the environment/region token it carries. */
+    members: {
+        dir: string;
+        environment: string;
+    }[];
+}
+/**
+ * Detect environment/region TWINS among a set of repo-relative paths (root dirs
+ * and/or `*.tfvars` files): parallel stacks that differ only by an environment
+ * (`dev`/`staging`/`prod`/…) or region (`eu-west-2`) segment. A fix applied to
+ * one should usually be offered for its twins too (§22 — backport / fan-out).
+ *
+ * For each path, finds the LAST segment that is an env token or a region (a
+ * `<env>.tfvars` file counts via its basename), replaces it with `{env}` to form
+ * a pattern, and groups by that pattern. Only groups with ≥2 DISTINCT
+ * environments are returned (a single match isn't a twin set). Pure +
+ * deterministic (sorted).
+ */
+export declare function detectEnvironmentTwins(paths: string[]): EnvironmentTwinGroup[];
+export declare const TerraformRootsParams: import("arktype/internal/variants/object.ts").ObjectType<object, {}>;
+export declare function TerraformRootsTool(ctx: LocalToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<object, object>>;

package/dist/mcp/scope.d.ts

@@ -0,0 +1,15 @@
+import type { ToolContext } from "#app/mcp/server";
+/**
+ * Record a PR/issue this run created so later body edits / comments / reviews on
+ * it pass {@link assertTargetInScope}. Call after a successful
+ * `create_pull_request` / `create_issue`.
+ */
+export declare function recordCreatedTarget(ctx: ToolContext, target: number): void;
+/** true when `target` is the run's triggering issue/PR or one it created. */
+export declare function isTargetInScope(ctx: ToolContext, target: number): boolean;
+/**
+ * Throw if `target` is neither the run's triggering issue/PR nor one it created.
+ * `action` is a short verb phrase used in the error (e.g. "comment on",
+ * "submit a review on", "add labels to").
+ */
+export declare function assertTargetInScope(ctx: ToolContext, target: number, action: string): void;

package/dist/mcp/selectMode.d.ts

@@ -0,0 +1,18 @@
+import type { ToolContext } from "#app/mcp/server";
+export declare const SelectModeParams: import("arktype/internal/variants/object.ts").ObjectType<{
+    mode: string;
+    issue_number?: number;
+}, {}>;
+export type PlanCommentResponsePayload = {
+    error: string;
+} | {
+    commentId: number;
+    body: string;
+};
+export declare function SelectModeTool(ctx: ToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    mode: string;
+    issue_number?: number;
+}, {
+    mode: string;
+    issue_number?: number;
+}>>;

package/dist/mcp/server.d.ts

@@ -0,0 +1,48 @@
+import "#app/mcp/arkConfig";
+import { type AgentId } from "#app/external";
+import type { Mode } from "#app/modes";
+import type { ToolState } from "#app/toolState";
+import type { OctokitWithPlugins } from "#app/utils/github";
+import type { ResolvedPayload } from "#app/utils/payload";
+import type { AccountPlan } from "#app/utils/runContext";
+import type { RunContextData } from "#app/utils/runContextData";
+export interface ToolContext {
+    agentId: AgentId;
+    repo: RunContextData["repo"];
+    payload: ResolvedPayload;
+    octokit: OctokitWithPlugins;
+    githubInstallationToken: string;
+    gitToken: string;
+    apiToken: string;
+    modes: Mode[];
+    postCheckoutScript: string | null;
+    prepushScript: string | null;
+    prApproveEnabled: boolean;
+    modeInstructions: Record<string, string>;
+    toolState: ToolState;
+    runId: number | undefined;
+    mcpServerUrl: string;
+    mcpServerToken: string;
+    tmpdir: string;
+    oss: boolean;
+    plan: AccountPlan;
+    resolvedModel: string | undefined;
+}
+type JsonSchema = Record<string, unknown>;
+type McpHttpServerOptions = {
+    outputSchema?: JsonSchema | undefined;
+};
+/**
+ * Start the MCP HTTP server.
+ *
+ * The returned disposer is idempotent — safe to call multiple times.
+ * Callers (e.g. the inner activity-timeout handler in main.ts) may need to
+ * stop the server before the `await using` block exits; a subsequent
+ * automatic dispose is then a no-op.
+ */
+export declare function startMcpHttpServer(ctx: ToolContext, options?: McpHttpServerOptions): Promise<{
+    url: string;
+    token: string;
+    [Symbol.asyncDispose]: () => Promise<void>;
+}>;
+export {};

package/dist/mcp/shared.d.ts

@@ -0,0 +1,47 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { FastMCP, Tool } from "fastmcp";
+import type { ToolContext } from "#app/mcp/server";
+export declare const tool: <const params>(toolDef: Tool<any, StandardSchemaV1<params>>) => Tool<any, StandardSchemaV1<params>>;
+export interface ToolResult {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean;
+}
+/**
+ * Structured tool-outcome envelope (§3.5 "Structured tool errors"). Every tool
+ * that can be unavailable, skipped, or degrade green returns the SAME shape so a
+ * caller (the agent, or a downstream parser) can branch deterministically:
+ *   - success: `{ ok: true, … }`
+ *   - skip / unavailable / soft failure: `{ ok: false, code, detail }`
+ * where `code` is a stable machine token (snake_case) and `detail` a human
+ * sentence. The newer tools (terraform_roots / terraform_module_interface /
+ * terraform_provider_schema / policy_check) emit this natively; the older
+ * degrade-green tools historically returned `{ ran|found: false,
+ * skipped_reason|reason }`. Those keep their legacy aliases ALONGSIDE the new
+ * fields (the call site spreads `toolSkip(...)` into its existing object) so
+ * prompt + test contracts keep working while the surface converges — additive,
+ * never breaking.
+ */
+export type ToolOk<T extends Record<string, any>> = T & {
+    ok: true;
+};
+/** wrap a success payload with `ok: true`. */
+export declare const toolOk: <T extends Record<string, any>>(data: T) => ToolOk<T>;
+/** the structured skip/unavailable envelope: `{ ok: false, code, detail }`. */
+export declare const toolSkip: (code: string, detail: string) => {
+    ok: false;
+    code: string;
+    detail: string;
+};
+export declare const handleToolSuccess: (data: Record<string, any> | string) => ToolResult;
+export declare const handleToolError: (error: unknown) => ToolResult;
+/**
+ * Helper to wrap a tool execute function with error handling.
+ * Captures ctx in closure so tools don't need to handle try/catch.
+ * @param fn - the function to execute
+ * @param toolName - optional tool name for error logging
+ */
+export declare const execute: <T, R extends Record<string, any> | string>(fn: (params: T) => Promise<R>, toolName?: string) => (params: T) => Promise<ToolResult>;
+export declare const addTools: (ctx: ToolContext, server: FastMCP<any>, tools: Tool<any, any>[]) => FastMCP<any>;

package/dist/mcp/shell.d.ts

@@ -0,0 +1,37 @@
+import type { ToolContext } from "#app/mcp/server";
+export declare const ShellParams: import("arktype/internal/variants/object.ts").ObjectType<{
+    command: string;
+    description: string;
+    timeout?: number;
+    working_directory?: string;
+    background?: boolean;
+}, {}>;
+export type SandboxMethod = "unshare" | "sudo-unshare" | "none";
+/** get the current sandbox method (for testing/diagnostics) */
+export declare function getSandboxMethod(): SandboxMethod;
+/** chars of shell output kept inline in the agent reply. anything past this
+ * blows the agent's context budget on commands that dump big logs (test
+ * runners, build tools, grep on large trees), so the overflow is spilled
+ * to a tempfile the agent can re-read selectively (cat/tail/grep). */
+export declare const MAX_OUTPUT_CHARS = 5000;
+export declare function ShellTool(ctx: ToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    command: string;
+    description: string;
+    timeout?: number;
+    working_directory?: string;
+    background?: boolean;
+}, {
+    command: string;
+    description: string;
+    timeout?: number;
+    working_directory?: string;
+    background?: boolean;
+}>>;
+export declare const KillBackgroundParams: import("arktype/internal/variants/object.ts").ObjectType<{
+    handle: string;
+}, {}>;
+export declare function KillBackgroundTool(ctx: ToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    handle: string;
+}, {
+    handle: string;
+}>>;

package/dist/mcp/staleFix.d.ts

@@ -0,0 +1,51 @@
+import type { ToolContext } from "#app/mcp/server";
+/** true when `branch` is a Terramend remediation/generation branch. */
+export declare function isRemediationBranch(branch: string): boolean;
+/** the `<group-id>` of a `remediate/<group-id>` branch (the scan group id that
+ * keys the fix), or null for a generation branch / non-remediation branch. */
+export declare function groupIdFromBranch(branch: string): string | null;
+/** true when a commit-author login is Terramend's bot (so a commit by it is NOT
+ * a human edit). A null/absent login is treated as non-human: Terramend pushes
+ * with a git identity that often doesn't map to a GitHub user, so requiring a
+ * positive bot match would make every PR look human-touched and never refresh. */
+export declare function isBotActor(login: string | null | undefined): boolean;
+export type StaleFixStatus = "current" | "stale" | "human_touched";
+export type StaleFixAction = "skip" | "refresh" | "escalate";
+export interface StaleFixAssessment {
+    status: StaleFixStatus;
+    action: StaleFixAction;
+    reason: string;
+}
+/**
+ * Decide what a refresh sweep should do with one open remediation PR, from git
+ * facts alone. Pure.
+ *  - a branch carrying NON-bot commits is `human_touched` → `escalate` (never
+ *    force-overwrite a human's work; leave it for review).
+ *  - a branch whose base has NOT advanced is `current` → `skip` (the fix is still
+ *    derived against the live base).
+ *  - otherwise the base moved → `stale` → `refresh`: re-derive the fix on the
+ *    current base, then close it if the concern is already resolved or update it.
+ */
+export declare function assessStaleFix(input: {
+    baseBehindBy: number;
+    hasNonBotCommits: boolean;
+}): StaleFixAssessment;
+export declare const ListRemediationPrsParams: import("arktype/internal/variants/object.ts").ObjectType<{
+    limit?: number;
+}, {}>;
+export declare function ListRemediationPrsTool(ctx: ToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    limit?: number;
+}, {
+    limit?: number;
+}>>;
+export declare const ClosePullRequest: import("arktype/internal/variants/object.ts").ObjectType<{
+    pull_number: number;
+    comment?: string;
+}, {}>;
+export declare function ClosePullRequestTool(ctx: ToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    pull_number: number;
+    comment?: string;
+}, {
+    pull_number: number;
+    comment?: string;
+}>>;