terramend 0.2.0

package/src/utils/retry.test.ts

@@ -0,0 +1,153 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { log } from "#app/utils/cli";
+import { retry } from "#app/utils/retry";
+
+vi.mock("#app/utils/cli", () => ({
+  log: {
+    info: vi.fn(),
+    debug: vi.fn(),
+    warning: vi.fn(),
+    error: vi.fn(),
+    success: vi.fn(),
+  },
+}));
+
+vi.mock("node:timers/promises", () => ({
+  setTimeout: vi.fn(async () => undefined),
+}));
+
+const sleepMock = vi.mocked(sleep);
+const logInfoMock = vi.mocked(log.info);
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("retry", () => {
+  it("returns the result on first success without sleeping", async () => {
+    const fn = vi.fn(async () => "ok");
+    await expect(retry(fn)).resolves.toBe("ok");
+    expect(fn).toHaveBeenCalledTimes(1);
+    expect(sleepMock).not.toHaveBeenCalled();
+  });
+
+  it("retries transient 'fetch failed' errors with default linear backoff", async () => {
+    const fn = vi
+      .fn<() => Promise<string>>()
+      .mockRejectedValueOnce(new Error("fetch failed"))
+      .mockRejectedValueOnce(new Error("fetch failed"))
+      .mockResolvedValueOnce("ok");
+
+    await expect(retry(fn)).resolves.toBe("ok");
+
+    expect(fn).toHaveBeenCalledTimes(3);
+    expect(sleepMock).toHaveBeenNthCalledWith(1, 1000);
+    expect(sleepMock).toHaveBeenNthCalledWith(2, 2000);
+    expect(logInfoMock).toHaveBeenCalledWith(
+      "» operation failed (attempt 1/3), retrying in 1000ms...",
+    );
+  });
+
+  it("retries AbortError by name (default shouldRetry)", async () => {
+    const abortError = new Error("aborted");
+    abortError.name = "AbortError";
+    const fn = vi
+      .fn<() => Promise<string>>()
+      .mockRejectedValueOnce(abortError)
+      .mockResolvedValueOnce("ok");
+
+    await expect(retry(fn)).resolves.toBe("ok");
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it("retries ECONNRESET errors (default shouldRetry)", async () => {
+    const fn = vi
+      .fn<() => Promise<string>>()
+      .mockRejectedValueOnce(new Error("read ECONNRESET"))
+      .mockResolvedValueOnce("ok");
+
+    await expect(retry(fn)).resolves.toBe("ok");
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not retry non-transient errors", async () => {
+    const fn = vi.fn(async () => {
+      throw new Error("boom");
+    });
+    await expect(retry(fn)).rejects.toThrow("boom");
+    expect(fn).toHaveBeenCalledTimes(1);
+    expect(sleepMock).not.toHaveBeenCalled();
+  });
+
+  it("does not retry non-Error rejections (default shouldRetry)", async () => {
+    const fn = vi.fn(async () => {
+      throw "string failure";
+    });
+    await expect(retry(fn)).rejects.toBe("string failure");
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("throws the last error after exhausting all attempts", async () => {
+    const fn = vi.fn(async () => {
+      throw new Error("fetch failed");
+    });
+    await expect(retry(fn, { maxAttempts: 2 })).rejects.toThrow("fetch failed");
+    expect(fn).toHaveBeenCalledTimes(2);
+    expect(sleepMock).toHaveBeenCalledTimes(1);
+    expect(sleepMock).toHaveBeenCalledWith(1000);
+  });
+
+  it("uses delayMs as a linear backoff base", async () => {
+    const fn = vi
+      .fn<() => Promise<string>>()
+      .mockRejectedValueOnce(new Error("e1"))
+      .mockRejectedValueOnce(new Error("e2"))
+      .mockResolvedValueOnce("ok");
+
+    await expect(retry(fn, { maxAttempts: 3, delayMs: 10, shouldRetry: () => true })).resolves.toBe(
+      "ok",
+    );
+
+    expect(sleepMock).toHaveBeenNthCalledWith(1, 10);
+    expect(sleepMock).toHaveBeenNthCalledWith(2, 20);
+  });
+
+  it("honors an explicit delaysMs schedule over maxAttempts", async () => {
+    const fn = vi.fn(async () => {
+      throw new Error("always");
+    });
+    await expect(
+      retry(fn, { delaysMs: [5, 7], maxAttempts: 99, shouldRetry: () => true }),
+    ).rejects.toThrow("always");
+
+    expect(fn).toHaveBeenCalledTimes(3);
+    expect(sleepMock).toHaveBeenNthCalledWith(1, 5);
+    expect(sleepMock).toHaveBeenNthCalledWith(2, 7);
+  });
+
+  it("uses the custom label in the retry log line", async () => {
+    const fn = vi
+      .fn<() => Promise<string>>()
+      .mockRejectedValueOnce(new Error("transient"))
+      .mockResolvedValueOnce("ok");
+
+    await retry(fn, { label: "token exchange", shouldRetry: () => true });
+
+    expect(logInfoMock).toHaveBeenCalledWith(
+      "» token exchange failed (attempt 1/3), retrying in 1000ms...",
+    );
+  });
+
+  it("passes the thrown error to a custom shouldRetry and stops when it returns false", async () => {
+    const error = new Error("fetch failed");
+    const shouldRetry = vi.fn(() => false);
+    const fn = vi.fn(async () => {
+      throw error;
+    });
+
+    await expect(retry(fn, { shouldRetry })).rejects.toBe(error);
+    expect(shouldRetry).toHaveBeenCalledWith(error);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+});

package/src/utils/retry.ts

@@ -0,0 +1,58 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import { log } from "#app/utils/cli";
+
+export type RetryOptions = {
+  maxAttempts?: number;
+  delayMs?: number;
+  /**
+   * explicit delay schedule — one entry per retry (length N ⇒ N+1 attempts).
+   * when set, overrides `maxAttempts` and `delayMs`. e.g. `[1_000, 3_000]`
+   * means up to 3 attempts, sleeping 1s before retry 2 and 3s before retry 3.
+   */
+  delaysMs?: readonly number[];
+  shouldRetry?: (error: unknown) => boolean;
+  label?: string;
+};
+
+const defaultShouldRetry = (error: unknown): boolean => {
+  if (!(error instanceof Error)) return false;
+  // retry on transient network errors
+  return (
+    error.name === "AbortError" ||
+    error.message.includes("fetch failed") ||
+    error.message.includes("ECONNRESET") ||
+    error.message.includes("ETIMEDOUT")
+  );
+};
+
+export async function retry<T>(fn: () => Promise<T>, options: RetryOptions = {}): Promise<T> {
+  const shouldRetry = options.shouldRetry ?? defaultShouldRetry;
+  const label = options.label ?? "operation";
+  const delays = options.delaysMs
+    ? Array.from(options.delaysMs)
+    : Array.from(
+        { length: (options.maxAttempts ?? 3) - 1 },
+        (_, i) => (options.delayMs ?? 1000) * (i + 1),
+      );
+  const maxAttempts = delays.length + 1;
+
+  let lastError: unknown;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+
+      if (attempt === maxAttempts || !shouldRetry(error)) {
+        throw error;
+      }
+
+      const delay = delays[attempt - 1]!;
+      log.info(`» ${label} failed (attempt ${attempt}/${maxAttempts}), retrying in ${delay}ms...`);
+      await sleep(delay);
+    }
+  }
+
+  throw lastError;
+}

package/src/utils/reviewCleanup.ts

@@ -0,0 +1,106 @@
+import type { WriteablePayload } from "#app/external";
+import { reportReviewNodeId } from "#app/mcp/review";
+import type { ToolContext } from "#app/mcp/server";
+import { log } from "#app/utils/cli";
+
+const RE_REVIEW_PREAMBLE =
+  "Incrementally re-review the new commits on this pull request. Use the IncrementalReview mode.";
+
+/**
+ * post-agent review lifecycle: runs after the agent exits (success or timeout).
+ *
+ * normally the agent handles new commits inline: create_pull_request_review
+ * detects HEAD movement and tells the agent to pull and review the delta.
+ * this dispatch is a safety net for cases where the agent couldn't handle
+ * it (timeout, error, etc).
+ *
+ * ordering matters: reportReviewNodeId marks this run "done" FIRST so push
+ * webhooks stop being suppressed by dedup. the HEAD check runs SECOND to
+ * catch any pushes that were suppressed while this run was in-flight.
+ */
+export async function postReviewCleanup(ctx: ToolContext): Promise<void> {
+  const review = ctx.toolState.review;
+  if (!review) return;
+  delete ctx.toolState.review;
+
+  // mark review as submitted — unlocks webhook dedup for new pushes
+  await bestEffort(() => reportReviewNodeId(ctx, { nodeId: review.nodeId }), "reportReviewNodeId");
+
+  // dispatch follow-up if PR HEAD moved past the reviewed commit
+  if (review.reviewedSha) {
+    await bestEffort(
+      () => dispatchFollowUpReReview(ctx, review.reviewedSha!),
+      "follow-up re-review dispatch",
+    );
+  }
+}
+
+async function bestEffort(fn: () => Promise<unknown>, label: string): Promise<void> {
+  try {
+    await fn();
+  } catch (error) {
+    log.debug(`${label} failed: ${error}`);
+  }
+}
+
+async function dispatchFollowUpReReview(ctx: ToolContext, reviewedSha: string): Promise<void> {
+  const issueNumber = ctx.payload.event.issue_number;
+  if (!issueNumber) return;
+
+  const pr = await ctx.octokit.rest.pulls.get({
+    owner: ctx.repo.owner,
+    repo: ctx.repo.name,
+    pull_number: issueNumber,
+  });
+
+  if (pr.data.head.sha === reviewedSha) return;
+  if (pr.data.state !== "open") return;
+  if (pr.data.draft) return;
+
+  log.info(
+    `safety net: pr HEAD moved from ${reviewedSha.slice(0, 7)} to ${pr.data.head.sha.slice(0, 7)} ` +
+      `and agent did not review inline — dispatching follow-up re-review`,
+  );
+
+  const event: WriteablePayload["event"] = {
+    trigger: "pull_request_synchronize",
+    issue_number: issueNumber,
+    is_pr: true,
+    title: pr.data.title,
+    body: null,
+    branch: pr.data.head.ref,
+    before_sha: reviewedSha,
+    silent: true,
+  };
+  if (ctx.payload.event.authorPermission) {
+    event.authorPermission = ctx.payload.event.authorPermission;
+  }
+
+  const payload: WriteablePayload = {
+    "~terramend": true,
+    version: ctx.payload.version,
+    model: ctx.payload.model,
+    prompt: "",
+    eventInstructions: RE_REVIEW_PREAMBLE,
+    event,
+  };
+
+  await ctx.octokit.rest.actions.createWorkflowDispatch({
+    owner: ctx.repo.owner,
+    repo: ctx.repo.name,
+    workflow_id: getCurrentWorkflowFilename(),
+    ref: pr.data.base.repo.default_branch,
+    inputs: { prompt: JSON.stringify(payload) },
+  });
+}
+
+/**
+ * derive the running workflow's filename from `GITHUB_WORKFLOW_REF`, which has the form
+ * `<owner>/<repo>/.github/workflows/<filename>@<ref>` (e.g. `.../terramend.yaml@refs/heads/main`).
+ * falls back to `terramend.yml` if the env var is missing or malformed (shouldn't happen in CI).
+ */
+function getCurrentWorkflowFilename(): string {
+  const ref = process.env.GITHUB_WORKFLOW_REF ?? "";
+  const match = ref.match(/\/([^/]+)@/);
+  return match?.[1] ?? "terramend.yml";
+}

package/src/utils/run.ts

@@ -0,0 +1,99 @@
+import type { AgentResult } from "#app/agents/shared";
+import type { MainResult } from "#app/main";
+import { reportProgress } from "#app/mcp/comment";
+import type { ToolContext } from "#app/mcp/server";
+import { log } from "#app/utils/cli";
+import { reportErrorToComment } from "#app/utils/errorReport";
+
+export interface HandleAgentResultParams {
+  result: AgentResult;
+  toolContext: ToolContext;
+  silent: boolean | undefined;
+}
+
+function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export async function handleAgentResult(ctx: HandleAgentResultParams): Promise<MainResult> {
+  if (!ctx.result.success) {
+    // rendering + posting for the `!success` branch lives in
+    // `finalizeSuccessRun` (called immediately before this function) so the
+    // BYOK billing-exhausted, hang, and api-key bodies land on a single
+    // surface — both for runs with a pre-existing progress comment AND for
+    // silent triggers via `createIfMissing`. see #835.
+    return {
+      success: false,
+      error: ctx.result.error || "Agent execution failed",
+      output: ctx.result.output!,
+    };
+  }
+
+  // IncrementalReview's non-substantive path exits cleanly without
+  // submitting any review, so no MCP write tool flips wasUpdated and the
+  // strict completion check below would otherwise fail the run. The
+  // isReviewMode skip is load-bearing for that path: the agent's exit
+  // code is the completion signal, not a progress-comment write.
+  // (Review mode that submits a real review now flips wasUpdated via
+  // create_pull_request_review, so the skip is redundant for the
+  // substantive-review path but kept for symmetry with IncrementalReview.)
+  // See plans/review_progress_comment_cleanup_b0120f6c.plan.md.
+  const toolState = ctx.toolContext.toolState;
+  const mode = toolState.selectedMode;
+  const isReviewMode = mode === "Review" || mode === "IncrementalReview";
+  if (!isReviewMode && !toolState.wasUpdated && toolState.hadProgressComment && !ctx.silent) {
+    // the agent exited successfully but never landed a GitHub write — either it
+    // answered the mention in raw assistant text (which is never posted, only
+    // logged) or a write tool failed (e.g. report_progress hit a 401). salvage
+    // by delivering the content we have to the progress comment so the user
+    // actually gets the answer instead of a failed run. (finalizeSuccessRun
+    // preserves the progress comment whenever wasUpdated is false, so the write
+    // lands here.)
+    //
+    // stop the todo tracker first: on this path the agent used todowrite but
+    // never called report_progress, so a pending debounced render could still
+    // be queued — draining it keeps it from clobbering the salvaged answer and
+    // from holding the event loop open. mirrors ReportProgressTool.
+    const tracker = toolState.todoTracker;
+    if (tracker) {
+      tracker.cancel();
+      await tracker.settled();
+    }
+    // `lastProgressBody` is the body a failed report_progress already assembled
+    // (task-list collapsible included), so use it verbatim; otherwise fall back
+    // to the agent's final assistant text and append the collapsible the way
+    // report_progress would.
+    let salvage = toolState.lastProgressBody?.trim();
+    if (!salvage) {
+      const output = ctx.result.output?.trim();
+      const collapsible = tracker?.renderCollapsible({ completeInProgress: true });
+      salvage = output && collapsible ? `${output}\n\n${collapsible}` : output;
+    }
+    if (salvage) {
+      try {
+        await reportProgress(ctx.toolContext, { body: salvage });
+        log.success("Task complete.");
+        return { success: true, output: ctx.result.output || "" };
+      } catch (writeError) {
+        // the write itself is failing (auth/permissions) — surface THAT, not
+        // the generic "no progress" message, so the real cause isn't masked.
+        const error = `failed to deliver agent result: ${getErrorMessage(writeError)}`;
+        await reportErrorToComment({ toolState, error, title: "Error" }).catch(() => {});
+        return { success: false, error, output: ctx.result.output || "" };
+      }
+    }
+
+    const error = ctx.result.error || "agent completed without reporting progress";
+    try {
+      await reportErrorToComment({ toolState, error, title: "Error" });
+    } catch {}
+    return { success: false, error, output: ctx.result.output || "" };
+  }
+
+  log.success("Task complete.");
+
+  return {
+    success: true,
+    output: ctx.result.output || "",
+  };
+}

package/src/utils/runContext.ts

@@ -0,0 +1,145 @@
+import type { PushPermission, ShellPermission } from "#app/external";
+import { apiFetch } from "#app/utils/apiFetch";
+import type { RepoContext } from "#app/utils/github";
+
+export interface Mode {
+  id: string;
+  name: string;
+  description: string;
+  prompt: string;
+}
+
+/**
+ * server-parsed TOC entry for `Repo.learnings`. depth is 1-6 (h1-h6),
+ * line numbers are 1-indexed against the raw body. computed by
+ * `parseLearningsHeadings` in `utils/learningsToc.ts` (server side) and
+ * shipped over the run-context JSON boundary; the canonical declaration
+ * lives there. duplicated here because the action runtime can't reach
+ * across into the proprietary root-level codebase, and the JSON wire
+ * means typecheck can't enforce shape equality across both sides.
+ */
+export interface LearningsHeading {
+  depth: 1 | 2 | 3 | 4 | 5 | 6;
+  title: string;
+  startLine: number;
+  endLine: number;
+}
+
+export interface RepoSettings {
+  model: string | null;
+  modes: Mode[];
+  setupScript: string | null;
+  postCheckoutScript: string | null;
+  prepushScript: string | null;
+  stopScript: string | null;
+  push: PushPermission;
+  shell: ShellPermission;
+  prApproveEnabled: boolean;
+  modeInstructions: Record<string, string>;
+  learnings: string | null;
+  learningsHeadings: LearningsHeading[];
+  envAllowlist: string | null;
+}
+
+/**
+ * Account-level billing plan. Orthogonal to repo-level OSS status. Mirrors
+ * the server's `AccountPlan` in `utils/billing.ts`. `"none"` = free tier,
+ * `"payg"` = card on file / pay-as-you-go.
+ */
+export type AccountPlan = "none" | "payg";
+
+export interface RunContext {
+  settings: RepoSettings;
+  apiToken: string;
+  oss: boolean;
+  plan: AccountPlan;
+}
+
+const defaultSettings: RepoSettings = {
+  model: null,
+  modes: [],
+  setupScript: null,
+  postCheckoutScript: null,
+  prepushScript: null,
+  stopScript: null,
+  push: "restricted",
+  shell: "restricted",
+  prApproveEnabled: false,
+  modeInstructions: {},
+  learnings: null,
+  learningsHeadings: [],
+  envAllowlist: null,
+};
+
+const defaultRunContext: RunContext = {
+  settings: defaultSettings,
+  apiToken: "",
+  oss: false,
+  plan: "none",
+};
+
+/**
+ * fetch run context from Terramend API
+ * returns settings + API token for subsequent calls
+ * returns defaults if fetch fails
+ */
+export async function fetchRunContext(params: {
+  token: string;
+  repoContext: RepoContext;
+  oidcToken?: string | undefined;
+}): Promise<RunContext> {
+  const timeoutMs = 30000;
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${params.token}`,
+    };
+    if (params.oidcToken) {
+      headers["X-GitHub-OIDC-Token"] = params.oidcToken;
+    }
+
+    const response = await apiFetch({
+      path: `/api/repo/${params.repoContext.owner}/${params.repoContext.name}/run-context`,
+      headers,
+      signal: controller.signal,
+    });
+
+    clearTimeout(timeoutId);
+
+    if (!response.ok) {
+      return defaultRunContext;
+    }
+
+    const data = (await response.json()) as {
+      settings: RepoSettings | null;
+      apiToken: string;
+      oss?: boolean;
+      plan?: AccountPlan;
+    } | null;
+
+    if (data === null) {
+      return defaultRunContext;
+    }
+
+    return {
+      settings: {
+        ...defaultSettings,
+        ...data.settings,
+        modes: data.settings?.modes ?? [],
+        setupScript: data.settings?.setupScript ?? null,
+        postCheckoutScript: data.settings?.postCheckoutScript ?? null,
+        prepushScript: data.settings?.prepushScript ?? null,
+        stopScript: data.settings?.stopScript ?? null,
+        learningsHeadings: data.settings?.learningsHeadings ?? [],
+      },
+      apiToken: data.apiToken,
+      oss: data.oss ?? false,
+      plan: data.plan ?? "none",
+    };
+  } catch {
+    clearTimeout(timeoutId);
+    return defaultRunContext;
+  }
+}

package/src/utils/runContextData.ts

@@ -0,0 +1,58 @@
+import * as core from "@actions/core";
+import type { Octokit } from "@octokit/rest";
+import { log } from "#app/utils/cli";
+import { type OctokitWithPlugins, parseRepoContext } from "#app/utils/github";
+import { type AccountPlan, fetchRunContext, type RepoSettings } from "#app/utils/runContext";
+import packageJson from "#package.json" with { type: "json" };
+
+export interface RunContextData {
+  repo: {
+    owner: string;
+    name: string;
+    data: Awaited<ReturnType<Octokit["repos"]["get"]>>["data"];
+  };
+  repoSettings: RepoSettings;
+  apiToken: string;
+  oss: boolean;
+  plan: AccountPlan;
+}
+
+interface ResolveRunContextDataParams {
+  octokit: OctokitWithPlugins;
+  token: string;
+}
+
+/**
+ * initialize run context data: parse context, fetch repo info and settings
+ */
+export async function resolveRunContextData(
+  params: ResolveRunContextDataParams,
+): Promise<RunContextData> {
+  log.info(`» running Terramend v${packageJson.version}...`);
+
+  const repoContext = parseRepoContext();
+
+  let oidcToken: string | undefined;
+  try {
+    oidcToken = await core.getIDToken("terramend-api");
+  } catch {
+    // OIDC not available (local dev, non-actions environment, fork PRs)
+  }
+
+  const [repoResponse, runContext] = await Promise.all([
+    params.octokit.repos.get({ owner: repoContext.owner, repo: repoContext.name }),
+    fetchRunContext({ token: params.token, repoContext, oidcToken }),
+  ]);
+
+  return {
+    repo: {
+      owner: repoContext.owner,
+      name: repoContext.name,
+      data: repoResponse.data,
+    },
+    repoSettings: runContext.settings,
+    apiToken: runContext.apiToken,
+    oss: runContext.oss,
+    plan: runContext.plan,
+  };
+}