indusagi-coding-agent 0.2.12 → 0.2.13

package/src/review-agent/server.ts

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+import { randomUUID } from "node:crypto";
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { loadReviewAgentConfig, type ReviewAgentConfig } from "./config.js";
+import { GitHubAppTokenProvider } from "./github.js";
+import { IndusagiReviewer } from "./reviewer.js";
+import { ReviewService } from "./service.js";
+import { SupabaseReviewStore } from "./supabase.js";
+import type { ReviewRequest } from "./contract.js";
+import { parsePullRequestWebhook, verifyGithubSignature } from "./webhook.js";
+
+const MAX_WEBHOOK_BYTES = 2 * 1024 * 1024;
+
+function json(res: ServerResponse, status: number, body: unknown): void {
+  const data = JSON.stringify(body);
+  res.writeHead(status, { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(data) });
+  res.end(data);
+}
+
+async function readBody(req: IncomingMessage): Promise<string> {
+  const declared = Number(req.headers["content-length"] ?? 0);
+  if (declared > MAX_WEBHOOK_BYTES) throw new Error("payload_too_large");
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const chunk of req) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    size += buffer.length;
+    if (size > MAX_WEBHOOK_BYTES) throw new Error("payload_too_large");
+    chunks.push(buffer);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+class StaticTokenProvider {
+  constructor(private readonly token: string) {}
+  async installationToken(): Promise<string> { return this.token; }
+}
+
+export function createReviewAgentRuntime(config: ReviewAgentConfig) {
+  const store = new SupabaseReviewStore(config.supabaseUrl, config.supabaseServiceKey);
+  const tokenProvider = config.githubApp
+    ? new GitHubAppTokenProvider(config.githubApp.appId, config.githubApp.privateKey)
+    : new StaticTokenProvider(config.githubToken!);
+  const reviewer = new IndusagiReviewer({
+    modelId: config.modelId,
+    thinking: "high",
+    getApiKey: (provider) => config.providerKeys[provider],
+  });
+  const service = new ReviewService({
+    store,
+    tokenProvider,
+    reviewer,
+    workerId: `${process.env.HOSTNAME ?? "local"}-${process.pid}-${randomUUID().slice(0, 8)}`,
+  });
+  return { store, service };
+}
+
+interface WebhookRuntime {
+  store: {
+    recordDelivery(deliveryId: string, eventName: string): Promise<boolean>;
+    enqueueWebhook(request: ReviewRequest, eventName: string): Promise<{ jobId?: string; duplicate: boolean }>;
+  };
+  poll: () => Promise<unknown>;
+}
+
+export function createWebhookHandler(
+  config: Pick<ReviewAgentConfig, "githubWebhookSecret" | "githubApp">,
+  runtime: WebhookRuntime,
+) {
+  return async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    try {
+      const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+      if (req.method === "GET" && url.pathname === "/healthz") {
+        json(res, 200, { ok: true, service: "indusagi-review-agent" });
+        return;
+      }
+      if (req.method !== "POST" || url.pathname !== "/webhooks/github") {
+        json(res, 404, { error: "not_found" });
+        return;
+      }
+
+      const payload = await readBody(req);
+      const signature = typeof req.headers["x-hub-signature-256"] === "string"
+        ? req.headers["x-hub-signature-256"]
+        : null;
+      if (!verifyGithubSignature(payload, signature, config.githubWebhookSecret)) {
+        json(res, 401, { error: "invalid_signature" });
+        return;
+      }
+
+      const eventName = typeof req.headers["x-github-event"] === "string" ? req.headers["x-github-event"] : "";
+      const deliveryId = typeof req.headers["x-github-delivery"] === "string" ? req.headers["x-github-delivery"] : "";
+      if (!deliveryId) {
+        json(res, 400, { error: "missing_delivery_id" });
+        return;
+      }
+      if (eventName === "ping") {
+        if (!await runtime.store.recordDelivery(deliveryId, eventName)) {
+          json(res, 202, { accepted: true, duplicate: true });
+          return;
+        }
+        json(res, 200, { ok: true, message: "pong" });
+        return;
+      }
+      if (eventName !== "pull_request") {
+        if (!await runtime.store.recordDelivery(deliveryId, eventName || "unknown")) {
+          json(res, 202, { accepted: true, duplicate: true });
+          return;
+        }
+        json(res, 202, { accepted: true, ignored: true });
+        return;
+      }
+
+      const request = parsePullRequestWebhook(payload, deliveryId, {
+        allowMissingInstallation: !config.githubApp,
+      });
+      if (!request) {
+        if (!await runtime.store.recordDelivery(deliveryId, eventName)) {
+          json(res, 202, { accepted: true, duplicate: true });
+          return;
+        }
+        json(res, 202, { accepted: true, ignored: true });
+        return;
+      }
+      const result = await runtime.store.enqueueWebhook(request, eventName);
+      if (result.duplicate) {
+        json(res, 202, { accepted: true, duplicate: true });
+        return;
+      }
+      json(res, 202, { accepted: true, jobId: result.jobId });
+      void runtime.poll();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (message === "payload_too_large") {
+        json(res, 413, { error: message });
+      } else {
+        console.error(`[review-agent] request failed: ${message}`);
+        json(res, 500, { error: "internal_error" });
+      }
+    }
+  };
+}
+
+interface WorkerRuntime {
+  store: Pick<SupabaseReviewStore, "recoverStaleJobs">;
+  service: Pick<ReviewService, "runOnce" | "reconcileCheckRunOnce">;
+}
+
+export function createWorkerPoll(
+  config: Pick<ReviewAgentConfig, "maxJobsPerTick">,
+  runtime: WorkerRuntime,
+  options: {
+    recoveryIntervalMs?: number;
+    now?: () => number;
+    logger?: Pick<Console, "error">;
+  } = {},
+) {
+  const recoveryIntervalMs = options.recoveryIntervalMs ?? 60_000;
+  const now = options.now ?? Date.now;
+  const logger = options.logger ?? console;
+  let workerBusy = false;
+  let lastRecoveryAt = Number.NEGATIVE_INFINITY;
+
+  return async (): Promise<void> => {
+    if (workerBusy) return;
+    workerBusy = true;
+    try {
+      const currentTime = now();
+      if (currentTime - lastRecoveryAt >= recoveryIntervalMs) {
+        await runtime.store.recoverStaleJobs();
+        lastRecoveryAt = currentTime;
+      }
+      for (let index = 0; index < config.maxJobsPerTick; index++) {
+        if (!await runtime.service.runOnce()) break;
+      }
+      await runtime.service.reconcileCheckRunOnce();
+    } catch (error) {
+      logger.error(`[review-agent] worker poll failed: ${error instanceof Error ? error.message : String(error)}`);
+    } finally {
+      workerBusy = false;
+    }
+  };
+}
+
+export async function startReviewAgentServer(config = loadReviewAgentConfig()) {
+  const runtime = createReviewAgentRuntime(config);
+  const poll = createWorkerPoll(config, runtime);
+  const timer = setInterval(() => void poll(), config.pollIntervalMs);
+  timer.unref();
+  void poll();
+
+  const server = createServer(createWebhookHandler(config, { store: runtime.store, poll }));
+
+  await new Promise<void>((resolve) => server.listen(config.port, config.host, resolve));
+  console.log(`[review-agent] listening on http://${config.host}:${config.port}`);
+
+  const close = async () => {
+    clearInterval(timer);
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  };
+  return { server, close, config };
+}
+
+function isProgramEntry(): boolean {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try { return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url)); } catch { return false; }
+}
+
+if (isProgramEntry()) {
+  startReviewAgentServer().then(({ close }) => {
+    const shutdown = () => void close().finally(() => process.exit(0));
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+  }).catch((error) => {
+    process.stderr.write(`indusagi-review-agent: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  });
+}

package/src/review-agent/service.ts

@@ -0,0 +1,165 @@
+import type { ReviewOutput } from "./contract.js";
+import { GitHubClient } from "./github.js";
+import type { IndusagiReviewer } from "./reviewer.js";
+import type { CheckRunReconciliation, ReviewJob, SupabaseReviewStore } from "./supabase.js";
+
+interface TokenProvider {
+  installationToken(installationId: number): Promise<string>;
+}
+
+interface ReviewStorePort {
+  claim(workerId: string): Promise<ReviewJob | null>;
+  setCheckRun(job: ReviewJob, checkRunId: number): Promise<void>;
+  complete(job: ReviewJob, review: ReviewOutput, githubReviewId?: number, commentId?: number): Promise<void>;
+  markCheckRunComplete(jobId: string): Promise<void>;
+  nextCheckRunReconciliation(): Promise<CheckRunReconciliation | null>;
+  fail(job: ReviewJob, message: string, retryable?: boolean): Promise<void>;
+  renewLease(job: ReviewJob, leaseSeconds?: number): Promise<boolean>;
+}
+
+class StaleReviewJobError extends Error {}
+class LostReviewLeaseError extends Error {}
+
+function isLeaseOwnershipError(error: unknown): boolean {
+  return error instanceof LostReviewLeaseError ||
+    (error instanceof Error && /lease ownership|lease lost/i.test(error.message));
+}
+
+interface ReviewerPort {
+  review(context: Awaited<ReturnType<GitHubClient["getPullRequestContext"]>>, github: GitHubClient): Promise<ReviewOutput>;
+}
+
+export interface ReviewServiceOptions {
+  store: ReviewStorePort | SupabaseReviewStore;
+  tokenProvider: TokenProvider;
+  githubFactory?: (token: string) => GitHubClient;
+  reviewer: ReviewerPort | IndusagiReviewer;
+  workerId: string;
+  leaseHeartbeatMs?: number;
+  leaseSeconds?: number;
+  logger?: Pick<Console, "info" | "warn" | "error">;
+}
+
+export class ReviewService {
+  private readonly githubFactory: (token: string) => GitHubClient;
+  private readonly logger: Pick<Console, "info" | "warn" | "error">;
+  private readonly leaseHeartbeatMs: number;
+  private readonly leaseSeconds: number;
+
+  constructor(private readonly options: ReviewServiceOptions) {
+    this.githubFactory = options.githubFactory ?? ((token) => new GitHubClient(token));
+    this.logger = options.logger ?? console;
+    this.leaseHeartbeatMs = options.leaseHeartbeatMs ?? 60_000;
+    this.leaseSeconds = options.leaseSeconds ?? 300;
+  }
+
+  async runOnce(): Promise<boolean> {
+    const job = await this.options.store.claim(this.options.workerId);
+    if (!job) return false;
+    let leaseLost = false;
+    let renewing = false;
+    const heartbeat = setInterval(() => {
+      if (renewing || leaseLost) return;
+      renewing = true;
+      void this.options.store.renewLease(job, this.leaseSeconds).then((owned) => {
+        if (!owned) leaseLost = true;
+      }).catch((error) => {
+        this.logger.warn(`[review-agent] lease heartbeat failed for ${job.id}: ${error instanceof Error ? error.message : String(error)}`);
+      }).finally(() => { renewing = false; });
+    }, this.leaseHeartbeatMs);
+    heartbeat.unref?.();
+    const assertLease = () => {
+      if (leaseLost) throw new LostReviewLeaseError(`review job lease lost: ${job.id}`);
+    };
+    try {
+      await this.process(job, assertLease);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.logger.error(`[review-agent] ${job.repository}#${job.pullNumber} failed: ${message}`);
+      if (!isLeaseOwnershipError(error)) {
+        await this.options.store.fail(job, message, !(error instanceof StaleReviewJobError));
+      }
+    } finally {
+      clearInterval(heartbeat);
+    }
+    return true;
+  }
+
+  async reconcileCheckRunOnce(): Promise<boolean> {
+    const pending = await this.options.store.nextCheckRunReconciliation();
+    if (!pending) return false;
+    const token = await this.options.tokenProvider.installationToken(pending.installationId);
+    const github = this.githubFactory(token);
+    await github.completeCheckRun(pending.owner, pending.repo, pending.checkRunId, pending.review, "success");
+    await this.options.store.markCheckRunComplete(pending.id);
+    return true;
+  }
+
+  private async process(job: ReviewJob, assertLease: () => void): Promise<void> {
+    const token = await this.options.tokenProvider.installationToken(job.installationId);
+    const github = this.githubFactory(token);
+    let checkRunId = job.checkRunId;
+    if (checkRunId === undefined) {
+      try {
+        assertLease();
+        checkRunId = await github.createCheckRun(job.owner, job.repo, job.headSha, `Indusagi Code Review`, job.id);
+        await this.options.store.setCheckRun(job, checkRunId);
+      } catch (error) {
+        if (isLeaseOwnershipError(error)) {
+          throw new LostReviewLeaseError(error instanceof Error ? error.message : "review job lease lost");
+        }
+        this.logger.warn(`[review-agent] could not create check run for ${job.repository}#${job.pullNumber}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+
+    try {
+      const context = await github.getPullRequestContext(job.owner, job.repo, job.pullNumber);
+      assertLease();
+      if (context.headSha !== job.headSha) {
+        throw new StaleReviewJobError(`stale review job: expected head ${job.headSha}, current head is ${context.headSha}`);
+      }
+
+      const review = await this.options.reviewer.review(context, github);
+      assertLease();
+      let githubReviewId: number | undefined;
+      let commentId: number | undefined;
+      try {
+        githubReviewId = await github.postReview(job.owner, job.repo, job.pullNumber, job.headSha, review);
+      } catch (error) {
+        this.logger.warn(`[review-agent] formal review rejected; using sticky comment: ${error instanceof Error ? error.message : String(error)}`);
+        commentId = await github.postStickyComment(job.owner, job.repo, job.pullNumber, review);
+      }
+
+      assertLease();
+      await this.options.store.complete(job, review, githubReviewId, commentId);
+      if (checkRunId !== undefined) {
+        try {
+          await github.completeCheckRun(job.owner, job.repo, checkRunId, review, "success");
+          await this.options.store.markCheckRunComplete(job.id);
+        } catch (error) {
+          this.logger.warn(`[review-agent] could not complete check run ${checkRunId}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+      }
+      this.logger.info(`[review-agent] completed ${job.repository}#${job.pullNumber} at ${job.headSha}`);
+    } catch (error) {
+      if (isLeaseOwnershipError(error)) {
+        throw new LostReviewLeaseError(error instanceof Error ? error.message : "review job lease lost");
+      }
+      if (checkRunId !== undefined) {
+        const message = error instanceof Error ? error.message : String(error);
+        const failureReview: ReviewOutput = {
+          summary: message.slice(0, 1_000),
+          risk: "high",
+          findings: [],
+          testPlan: [],
+        };
+        try {
+          await github.completeCheckRun(job.owner, job.repo, checkRunId, failureReview, "failure");
+        } catch (checkError) {
+          this.logger.warn(`[review-agent] could not fail check run ${checkRunId}: ${checkError instanceof Error ? checkError.message : String(checkError)}`);
+        }
+      }
+      throw error;
+    }
+  }
+}

package/src/review-agent/supabase.ts

@@ -0,0 +1,209 @@
+import type { ReviewOutput, ReviewRequest } from "./contract.js";
+
+export interface ReviewJob {
+  id: string;
+  installationId: number;
+  repository: string;
+  owner: string;
+  repo: string;
+  pullNumber: number;
+  headSha: string;
+  title: string;
+  attempts: number;
+  maxAttempts: number;
+  workerId: string;
+  leaseToken: string;
+  checkRunId?: number;
+}
+
+export interface CheckRunReconciliation {
+  id: string;
+  installationId: number;
+  owner: string;
+  repo: string;
+  checkRunId: number;
+  review: ReviewOutput;
+}
+
+function toJob(row: Record<string, any>): ReviewJob {
+  return {
+    id: String(row.id),
+    installationId: Number(row.installation_id),
+    repository: String(row.repository),
+    owner: String(row.owner),
+    repo: String(row.repo),
+    pullNumber: Number(row.pr_number),
+    headSha: String(row.head_sha),
+    title: String(row.title),
+    attempts: Number(row.attempts ?? 0),
+    maxAttempts: Number(row.max_attempts ?? 3),
+    workerId: String(row.worker_id ?? ""),
+    leaseToken: String(row.lease_token ?? ""),
+    ...(row.check_run_id != null ? { checkRunId: Number(row.check_run_id) } : {}),
+  };
+}
+
+export class SupabaseReviewStore {
+  private readonly baseUrl: string;
+
+  constructor(
+    url: string,
+    private readonly serviceKey: string,
+    private readonly fetcher: typeof fetch = fetch,
+    private readonly requestTimeoutMs = 30_000,
+  ) {
+    this.baseUrl = url.replace(/\/$/, "");
+  }
+
+  private async request<T>(path: string, init: RequestInit = {}): Promise<T> {
+    const response = await this.fetcher(`${this.baseUrl}${path}`, {
+      ...init,
+      signal: init.signal ?? AbortSignal.timeout(this.requestTimeoutMs),
+      headers: {
+        apikey: this.serviceKey,
+        Authorization: `Bearer ${this.serviceKey}`,
+        "Content-Type": "application/json",
+        ...(init.headers as Record<string, string> | undefined),
+      },
+    });
+    if (!response.ok) {
+      throw new Error(`Supabase ${init.method ?? "GET"} ${path} failed (${response.status}): ${(await response.text()).slice(0, 500)}`);
+    }
+    if (response.status === 204) return undefined as T;
+    return await response.json() as T;
+  }
+
+  async recordDelivery(deliveryId: string, eventName: string): Promise<boolean> {
+    const rows = await this.request<Array<Record<string, unknown>>>(
+      "/rest/v1/indusagi_review_deliveries?on_conflict=delivery_id",
+      {
+        method: "POST",
+        headers: { Prefer: "resolution=ignore-duplicates,return=representation" },
+        body: JSON.stringify({ delivery_id: deliveryId, event_name: eventName }),
+      },
+    );
+    return rows.length > 0;
+  }
+
+  async enqueueWebhook(request: ReviewRequest, eventName: string): Promise<{ jobId?: string; duplicate: boolean }> {
+    const rows = await this.request<Array<{ job_id?: unknown; duplicate?: unknown }>>(
+      "/rest/v1/rpc/enqueue_indusagi_review_job",
+      {
+        method: "POST",
+        body: JSON.stringify({
+          p_delivery_id: request.deliveryId,
+          p_event_name: eventName,
+          p_installation_id: request.installationId,
+          p_repository: request.repository,
+          p_owner: request.owner,
+          p_repo: request.repo,
+          p_pr_number: request.pullNumber,
+          p_head_sha: request.headSha,
+          p_title: request.title,
+        }),
+      },
+    );
+    const row = rows[0];
+    if (!row || typeof row.duplicate !== "boolean") throw new Error("Supabase returned no webhook enqueue result");
+    if (!row.duplicate && (typeof row.job_id !== "string" || !row.job_id)) {
+      throw new Error("Supabase returned no queued review job id");
+    }
+    return {
+      ...(typeof row.job_id === "string" && row.job_id ? { jobId: row.job_id } : {}),
+      duplicate: row.duplicate,
+    };
+  }
+
+  async claim(workerId: string): Promise<ReviewJob | null> {
+    const rows = await this.request<Array<Record<string, any>>>("/rest/v1/rpc/claim_indusagi_review_job", {
+      method: "POST",
+      body: JSON.stringify({ p_worker_id: workerId }),
+    });
+    return rows[0] ? toJob(rows[0]) : null;
+  }
+
+  async setCheckRun(job: ReviewJob, checkRunId: number): Promise<void> {
+    await this.ownedPatch(job, { check_run_id: checkRunId });
+  }
+
+  async complete(job: ReviewJob, review: ReviewOutput, githubReviewId?: number, commentId?: number): Promise<void> {
+    await this.ownedPatch(job, {
+      status: "completed",
+      review,
+      github_review_id: githubReviewId ?? null,
+      github_comment_id: commentId ?? null,
+      completed_at: new Date().toISOString(),
+      worker_id: null,
+      claimed_at: null,
+      lease_expires_at: null,
+      error: null,
+    });
+  }
+
+  async markCheckRunComplete(jobId: string): Promise<void> {
+    await this.patch(jobId, { check_completed_at: new Date().toISOString() });
+  }
+
+  async nextCheckRunReconciliation(): Promise<CheckRunReconciliation | null> {
+    const path = "/rest/v1/indusagi_review_jobs?status=eq.completed&check_run_id=not.is.null&check_completed_at=is.null&review=not.is.null&select=id,installation_id,owner,repo,check_run_id,review&order=completed_at.asc&limit=1";
+    const rows = await this.request<Array<Record<string, any>>>(path);
+    const row = rows[0];
+    if (!row) return null;
+    return {
+      id: String(row.id),
+      installationId: Number(row.installation_id),
+      owner: String(row.owner),
+      repo: String(row.repo),
+      checkRunId: Number(row.check_run_id),
+      review: row.review as ReviewOutput,
+    };
+  }
+
+  async fail(job: ReviewJob, message: string, retryable = true): Promise<void> {
+    const retry = retryable && job.attempts < job.maxAttempts;
+    const delaySeconds = Math.min(300, Math.max(5, 5 * 2 ** Math.max(0, job.attempts - 1)));
+    await this.ownedPatch(job, {
+      status: retry ? "pending" : "failed",
+      error: message.slice(0, 4_000),
+      worker_id: null,
+      claimed_at: null,
+      lease_expires_at: null,
+      ...(retry ? { available_at: new Date(Date.now() + delaySeconds * 1_000).toISOString() } : { completed_at: new Date().toISOString() }),
+    });
+  }
+
+  async recoverStaleJobs(staleMinutes = 15): Promise<void> {
+    await this.request("/rest/v1/rpc/recover_stale_indusagi_review_jobs", {
+      method: "POST",
+      body: JSON.stringify({ p_stale_minutes: staleMinutes }),
+    });
+  }
+
+  async renewLease(job: ReviewJob, leaseSeconds = 300): Promise<boolean> {
+    const rows = await this.ownedPatch(job, {
+      lease_expires_at: new Date(Date.now() + leaseSeconds * 1_000).toISOString(),
+    }, false);
+    return rows.length > 0;
+  }
+
+  private async ownedPatch(job: ReviewJob, values: Record<string, unknown>, required = true): Promise<Array<Record<string, unknown>>> {
+    if (!job.workerId || !job.leaseToken) throw new Error("review job has no lease ownership");
+    const leaseFloor = encodeURIComponent(new Date().toISOString());
+    const filters = `id=eq.${encodeURIComponent(job.id)}&status=eq.running&worker_id=eq.${encodeURIComponent(job.workerId)}&lease_token=eq.${encodeURIComponent(job.leaseToken)}&lease_expires_at=gt.${leaseFloor}`;
+    const rows = await this.request<Array<Record<string, unknown>>>(`/rest/v1/indusagi_review_jobs?${filters}`, {
+      method: "PATCH",
+      headers: { Prefer: "return=representation" },
+      body: JSON.stringify({ ...values, updated_at: new Date().toISOString() }),
+    });
+    if (required && rows.length === 0) throw new Error("review job lease ownership was lost");
+    return rows;
+  }
+
+  private async patch(jobId: string, values: Record<string, unknown>): Promise<void> {
+    await this.request(`/rest/v1/indusagi_review_jobs?id=eq.${encodeURIComponent(jobId)}`, {
+      method: "PATCH",
+      headers: { Prefer: "return=minimal" },
+      body: JSON.stringify({ ...values, updated_at: new Date().toISOString() }),
+    });
+  }
+}

package/src/review-agent/webhook.ts

@@ -0,0 +1,76 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import type { ReviewRequest } from "./contract.js";
+
+const REVIEW_ACTIONS = new Set(["opened", "reopened", "synchronize", "ready_for_review"]);
+
+export function verifyGithubSignature(
+  payload: string,
+  signature: string | null | undefined,
+  secret: string,
+): boolean {
+  if (!secret || !signature?.startsWith("sha256=")) return false;
+  const expected = `sha256=${createHmac("sha256", secret).update(payload).digest("hex")}`;
+  const actualBuffer = Buffer.from(signature);
+  const expectedBuffer = Buffer.from(expected);
+  return actualBuffer.length === expectedBuffer.length && timingSafeEqual(actualBuffer, expectedBuffer);
+}
+
+function object(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined;
+}
+
+export function parsePullRequestWebhook(
+  payload: string,
+  deliveryId: string,
+  options: { allowMissingInstallation?: boolean } = {},
+): ReviewRequest | null {
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(payload);
+  } catch {
+    throw new Error("GitHub webhook body is not valid JSON");
+  }
+  const body = object(decoded);
+  const action = typeof body?.action === "string" ? body.action : "";
+  if (!REVIEW_ACTIONS.has(action)) return null;
+
+  const installation = object(body?.installation);
+  const repository = object(body?.repository);
+  const pull = object(body?.pull_request);
+  const head = object(pull?.head);
+  const fullName = typeof repository?.full_name === "string" ? repository.full_name : "";
+  const separator = fullName.indexOf("/");
+  const installationId = installation?.id == null && options.allowMissingInstallation
+    ? 0
+    : Number(installation?.id);
+  const pullNumber = Number(body?.number ?? pull?.number);
+  const headSha = typeof head?.sha === "string" ? head.sha : "";
+  const title = typeof pull?.title === "string" ? pull.title : "";
+  const draft = pull?.draft === true;
+
+  if (draft && action !== "ready_for_review") return null;
+  if (
+    !deliveryId || separator <= 0 || separator === fullName.length - 1 ||
+    !Number.isInteger(installationId) || installationId < 0 ||
+    (!options.allowMissingInstallation && installationId === 0) ||
+    !Number.isInteger(pullNumber) || pullNumber <= 0 ||
+    !headSha || !title
+  ) {
+    throw new Error("GitHub pull_request webhook is missing required fields");
+  }
+
+  return {
+    deliveryId,
+    action,
+    installationId,
+    repository: fullName,
+    owner: fullName.slice(0, separator),
+    repo: fullName.slice(separator + 1),
+    pullNumber,
+    headSha,
+    title,
+    draft,
+  };
+}