feat(server): agent review single-pass detection, server-side delivery, bot command (#957)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: FelixTJDietrich

.github/workflows/ci-docker-build.yml

@@ -128,7 +128,7 @@ jobs:
     with:
       image-name: "ls1intum/hephaestus/agent-claude-code"
       docker-file: "./docker/agents/claude-code/Dockerfile"
-      docker-context: "./docker/agents/claude-code"
+      docker-context: "./docker/agents"
       registry: "ghcr.io"
       tags: |
         ${{ github.ref_name }}
@@ -149,7 +149,7 @@ jobs:
     with:
       image-name: "ls1intum/hephaestus/agent-opencode"
       docker-file: "./docker/agents/opencode/Dockerfile"
-      docker-context: "./docker/agents/opencode"
+      docker-context: "./docker/agents"
       registry: "ghcr.io"
       tags: |
         ${{ github.ref_name }}

docker/agents/claude-code/Dockerfile

@@ -4,7 +4,7 @@
 ARG NODE_TAG=22-slim
 FROM node:${NODE_TAG}
 
-RUN apt-get update -qq && apt-get install -y --no-install-recommends git findutils tree jq && \
+RUN apt-get update -qq && apt-get install -y --no-install-recommends git findutils tree jq curl && \
     rm -rf /var/lib/apt/lists/*
 
 ARG CLAUDE_CODE_VERSION=2.1.76
@@ -14,6 +14,14 @@ RUN npm install -g @anthropic-ai/claude-code@${CLAUDE_CODE_VERSION} && \
     echo '{"hasCompletedOnboarding":true}' > /home/agent/.claude.json && \
     chown -R 1000:1000 /home/agent /workspace
 
+# Bun runtime for precomputation scripts (static analysis before agent runs)
+ARG BUN_VERSION=1.3.11
+RUN curl -fsSL https://bun.sh/install | BUN_INSTALL=/usr/local bash -s "bun-v${BUN_VERSION}"
+
+# Precompute runner + shared libraries (practice scripts injected at runtime from DB)
+COPY --chown=1000:1000 precompute/runner.ts /opt/precompute/runner.ts
+COPY --chown=1000:1000 precompute/lib/ /opt/precompute/lib/
+
 # Git security: neutralize hooks and external commands from mounted repos.
 # System-level config cannot be overridden by repo-local .git/config.
 RUN git config --system core.hooksPath /nonexistent && \

docker/agents/opencode/Dockerfile

@@ -4,7 +4,7 @@
 ARG NODE_TAG=22-slim
 FROM node:${NODE_TAG}
 
-RUN apt-get update -qq && apt-get install -y --no-install-recommends git findutils tree jq && \
+RUN apt-get update -qq && apt-get install -y --no-install-recommends git findutils tree jq curl ca-certificates unzip && \
     rm -rf /var/lib/apt/lists/*
 
 ARG OPENCODE_VERSION=1.2.26
@@ -13,6 +13,18 @@ RUN npm install -g opencode-ai@${OPENCODE_VERSION} && \
     mkdir -p /home/agent /workspace && \
     chown -R 1000:1000 /home/agent /workspace
 
+# Bun runtime for precomputation scripts (static analysis before agent runs)
+ARG BUN_VERSION=1.3.11
+RUN curl -fsSL "https://github.com/oven-sh/bun/releases/download/bun-v${BUN_VERSION}/bun-linux-x64.zip" -o /tmp/bun.zip && \
+    unzip -o /tmp/bun.zip -d /tmp && \
+    mv /tmp/bun-linux-x64/bun /usr/local/bin/bun && \
+    chmod +x /usr/local/bin/bun && \
+    rm -rf /tmp/bun*
+
+# Precompute runner + shared libraries (practice scripts injected at runtime from DB)
+COPY --chown=1000:1000 precompute/runner.ts /opt/precompute/runner.ts
+COPY --chown=1000:1000 precompute/lib/ /opt/precompute/lib/
+
 # Git security: neutralize hooks and external commands from mounted repos.
 # System-level config cannot be overridden by repo-local .git/config.
 RUN git config --system core.hooksPath /nonexistent && \

docker/agents/precompute/lib/diff-parser.ts

@@ -0,0 +1,81 @@
+import type { DiffFile, DiffHunk } from "./types";
+
+/**
+ * Parse a unified diff (with optional [L<n>] annotations) into structured DiffFile objects.
+ * Returns a Map of file path -> DiffFile.
+ */
+export function parseDiff(diffContent: string): Map<string, DiffFile> {
+  const files = new Map<string, DiffFile>();
+
+  // Split on "diff --git" boundaries
+  const fileDiffs = diffContent.split(/^diff --git /m).filter(Boolean);
+
+  for (const fileDiff of fileDiffs) {
+    const lines = fileDiff.split("\n");
+
+    // Extract file path from "a/path b/path"
+    const headerMatch = lines[0]?.match(/a\/(.+?)\s+b\/(.+)/);
+    if (!headerMatch) continue;
+    const filePath = headerMatch[2];
+
+    const addedLines = new Map<number, string>();
+    const removedLines = new Map<number, string>();
+    const hunks: DiffHunk[] = [];
+
+    let currentHunk: DiffHunk | null = null;
+    let newLineNum = 0;
+    let oldLineNum = 0;
+
+    for (const line of lines) {
+      // Hunk header: @@ -oldStart,oldCount +newStart,newCount @@
+      const hunkMatch = line.match(/^@@\s+-(\d+)(?:,(\d+))?\s+\+(\d+)(?:,(\d+))?\s+@@/);
+      if (hunkMatch) {
+        currentHunk = {
+          oldStart: parseInt(hunkMatch[1]),
+          oldCount: parseInt(hunkMatch[2] ?? "1"),
+          newStart: parseInt(hunkMatch[3]),
+          newCount: parseInt(hunkMatch[4] ?? "1"),
+          lines: [],
+        };
+        hunks.push(currentHunk);
+        oldLineNum = currentHunk.oldStart;
+        newLineNum = currentHunk.newStart;
+        continue;
+      }
+
+      if (!currentHunk) continue;
+
+      // Strip [L<n>] annotation if present
+      const stripped = line.replace(/^\[L\d+\]\s*/, "");
+
+      if (stripped.startsWith("+") && !stripped.startsWith("+++")) {
+        addedLines.set(newLineNum, stripped.slice(1));
+        currentHunk.lines.push(stripped);
+        newLineNum++;
+      } else if (stripped.startsWith("-") && !stripped.startsWith("---")) {
+        removedLines.set(oldLineNum, stripped.slice(1));
+        currentHunk.lines.push(stripped);
+        oldLineNum++;
+      } else if (!stripped.startsWith("\\")) {
+        // Context line
+        currentHunk.lines.push(stripped);
+        newLineNum++;
+        oldLineNum++;
+      }
+    }
+
+    // Normalize path: strip leading ./
+    const normalizedPath = filePath.replace(/^\.\//, "");
+    files.set(normalizedPath, { path: normalizedPath, addedLines, removedLines, hunks });
+  }
+
+  return files;
+}
+
+/** Check if a given file path + line number is in the diff (on a + line) */
+export function isInDiff(diffFiles: Map<string, DiffFile>, filePath: string, lineNum: number): boolean {
+  // Try exact match first, then suffix match
+  const df = diffFiles.get(filePath) ?? [...diffFiles.values()].find(f => filePath.endsWith(f.path) || f.path.endsWith(filePath));
+  if (!df) return false;
+  return df.addedLines.has(lineNum);
+}

docker/agents/precompute/lib/grep.ts

@@ -0,0 +1,98 @@
+import type { Hint } from "./types";
+import type { DiffFile } from "./types";
+import { isInDiff } from "./diff-parser";
+
+interface GrepMatch {
+  file: string;
+  line: number;
+  content: string;
+}
+
+/**
+ * Run grep on a directory. Returns structured matches.
+ *
+ * @param pattern — regex pattern (or fixed string if fixedString=true)
+ * @param dir — directory to search
+ * @param opts.glob — file glob filter (REQUIRED for language-specific searches, defaults to all files)
+ * @param opts.maxResults — cap results (default 500)
+ * @param opts.fixedString — use -F instead of -E (default false)
+ */
+export async function grep(
+  pattern: string,
+  dir: string,
+  opts: { glob?: string; maxResults?: number; fixedString?: boolean } = {}
+): Promise<GrepMatch[]> {
+  const { glob = "*", maxResults = 500, fixedString = false } = opts;
+
+  const fixedFlag = fixedString ? "-F" : "-E";
+  // Use single quotes for pattern to avoid shell interpretation; escape any ' in pattern
+  const escapedPattern = pattern.replace(/'/g, "'\\''");
+  const cmd = `grep -rn ${fixedFlag} --include='${glob}' -m ${maxResults} '${escapedPattern}' '${dir}' 2>/dev/null || true`;
+
+  const result = await Bun.spawn(["bash", "-c", cmd], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const stdout = await new Response(result.stdout).text();
+  const matches: GrepMatch[] = [];
+
+  for (const line of stdout.split("\n")) {
+    if (!line.trim()) continue;
+    // Format: filepath:linenum:content
+    const m = line.match(/^(.+?):(\d+):(.*)$/);
+    if (m) {
+      matches.push({
+        file: m[1].replace(dir + "/", ""), // relative path
+        line: parseInt(m[2]),
+        content: m[3].trim(),
+      });
+    }
+  }
+
+  return matches;
+}
+
+/**
+ * Convert grep matches to Hints with diff awareness and context flags.
+ */
+export function matchesToHints(
+  matches: GrepMatch[],
+  pattern: string,
+  diffFiles: Map<string, DiffFile>,
+  flagFn?: (match: GrepMatch) => Record<string, boolean>
+): Hint[] {
+  return matches.map(m => ({
+    file: m.file,
+    line: m.line,
+    pattern,
+    context: m.content,
+    inDiff: isInDiff(diffFiles, m.file, m.line),
+    flags: flagFn ? flagFn(m) : {},
+  }));
+}
+
+/**
+ * Read a file and return its lines (1-indexed Map).
+ */
+export async function readFileLines(path: string): Promise<Map<number, string>> {
+  try {
+    const content = await Bun.file(path).text();
+    const lines = new Map<number, string>();
+    content.split("\n").forEach((line, i) => lines.set(i + 1, line));
+    return lines;
+  } catch {
+    return new Map();
+  }
+}
+
+/**
+ * Find all files matching a given extension in a directory.
+ */
+export async function findFiles(dir: string, extension: string): Promise<string[]> {
+  const result = await Bun.spawn(["bash", "-c", `find "${dir}" -name "*.${extension}" -not -path "*/.*" -not -path "*/.build/*" -not -path "*/node_modules/*" 2>/dev/null`], {
+    stdout: "pipe",
+  });
+  const stdout = await new Response(result.stdout).text();
+  return stdout.split("\n").filter(Boolean);
+}

docker/agents/precompute/lib/types.ts

@@ -0,0 +1,56 @@
+/** Precomputation types — hints and directions, never verdicts */
+
+export interface Hint {
+  file: string;
+  line: number;
+  pattern: string;
+  context: string;
+  inDiff: boolean;
+  flags: Record<string, boolean | number | string>;
+}
+
+export interface PracticeResult {
+  practice: string;
+  status: "ok" | "error" | "timeout";
+  hints: Hint[];
+  metrics: Record<string, number>;
+  directions: string[];
+}
+
+export interface DiffFile {
+  path: string;
+  addedLines: Map<number, string>;
+  removedLines: Map<number, string>;
+  hunks: DiffHunk[];
+}
+
+export interface DiffHunk {
+  oldStart: number;
+  oldCount: number;
+  newStart: number;
+  newCount: number;
+  lines: string[];
+}
+
+/**
+ * Pull request metadata — matches the JSON produced by
+ * PullRequestReviewHandler.buildPullRequestMetadata() on the server.
+ * Scripts should import this instead of declaring ad-hoc types.
+ */
+export interface PullRequestMetadata {
+  pr_number: number;
+  pr_url: string;
+  repository_full_name: string;
+  source_branch: string;
+  target_branch: string;
+  commit_sha: string;
+  enriched: boolean;
+  title?: string;
+  body?: string;
+  state?: string;
+  is_draft?: boolean;
+  additions?: number;
+  deletions?: number;
+  changed_files?: number;
+  author?: string;
+}