translate comment

Remove the openrouter-rs dependency in favor of a minimal in-tree
OpenRouter chat-completions client, and drop the BOT_NAME and
SANDBOX_ENABLED config options. Reviews now always run inside the
sandbox, and the review prompt asks the model to read files with the
available tools instead of embedding the diff.

.devcontainer/Dockerfile

@@ -1,4 +1,4 @@
-FROM debian:trixie
+FROM rust:1.98-trixie
 
 ARG USERNAME=dev
 ARG USER_UID=1000
@@ -18,11 +18,11 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     && rm -rf /var/lib/apt/lists/*
 
 RUN groupadd --gid ${USER_GID:-1000} $USERNAME \
-    && useradd --uid ${USER_UID:-1000} --gid ${USER_GID:-1000} -m $USERNAME
+    && useradd --uid ${USER_UID:-1000} --gid ${USER_GID:-1000} -m $USERNAME \
+    && rustup component add clippy \
+    && rustup component add rustfmt
+
+
 
 USER $USERNAME
 WORKDIR /home/$USERNAME
-
-ENV PATH="/home/${USERNAME}/.cargo/bin:${PATH}"
-
-RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable

.devcontainer/devcontainer.json

@@ -12,6 +12,11 @@
     "containerEnv": {
         "SHELL": "/bin/bash"
     },
+    "customizations": {
+        "vscode": {
+            "extensions": ["fill-labs.dependi", "rust-lang.rust-analyzer", "tamasfe.even-better-toml"]
+        }
+    },
     "workspaceMount": "source=${localWorkspaceFolder},target=/workspaces/herald,type=bind",
     "workspaceFolder": "/workspaces/herald",
    	"runArgs": ["--userns=keep-id", "--security-opt", "label=disable"],

.dockerignore

@@ -1,4 +0,0 @@
-target/
-.env
-.devcontainer/
-docs/

.env.example

@@ -1,5 +1,4 @@
 HTTP_PORT=3000
-BOT_NAME=Herald
 
 WEBHOOK_SIG_HEADER_SECRET=
 
@@ -17,3 +16,9 @@ GITEA_TIMEOUT=30
 SENTRY_DSN=
 RUST_LOG=info
 RUST_BACKTRACE=1
+
+METRICS_BIND_ADDR=
+
+# Sandboxed tool execution
+CONTAINER_RUNTIME=docker
+SANDBOX_MAX_ITERATIONS=8

.woodpecker/tests.yml

@@ -3,13 +3,27 @@ when:
         - push
 
 steps:
+    - name: fmt
+      image: rust:1.98
+      commands:
+          - rustup component add rustfmt
+          - cargo fmt --all -- --check
+
     - name: clippy
-      image: rust:1.96
+      image: rust:1.98
       commands:
           - rustup component add clippy
-          - cargo clippy
+          - cargo clippy --workspace --all-targets --all-features -- -D warnings
 
     - name: test
-      image: rust:1.96
+      image: rust:1.98
       commands:
-          - cargo test
+          - cargo test --workspace --all-targets
+
+    - name: container-build
+      image: quay.io/buildah/stable
+      privileged: true
+      volumes:
+          - /data/woodpecker-builds:/data
+      commands:
+          - buildah bud -f Containerfile -t herald-ci .

.zed/settings.json

@@ -1,9 +1,20 @@
 {
+    "languages": {
+        "Rust": {
+            "format_on_save": "on",
+            "formatter": "language_server"
+        }
+    },
     "lsp": {
         "rust-analyzer": {
             "initialization_options": {
                 "check": {
-                    "command": "clippy"
+                    "command": "clippy",
+                    "extraArgs": [
+                        "--",
+                        "-D",
+                        "warnings"
+                    ]
                 }
             }
         }

Cargo.toml

@@ -1,32 +1,31 @@
-[package]
-name = "herald"
-version = "1.0.1"
-edition = "2024"
+[workspace]
+members = [
+    "crates/herald-server",
+    "crates/devcontainer-rs",
+]
+resolver = "3"
 
-[profile.release]
-debug = 1
-
-[dependencies]
-reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }
-tokio = { version = "1.52", features = ["full"] }
-tokio-stream = "0.1"
+[workspace.dependencies]
+reqwest = { version = "0.13", default-features = false, features = ["json", "native-tls", "stream"] }
+tokio = { version = "1.53", features = ["full"] }
 tokio-util = "0.7"
 futures-util = "0.3"
 serde_json = "1.0"
 serde = { version = "1.0", features = ["derive"] }
-sentry = { version = "0.48", features = ["tower-axum-matched-path"] }
-sentry-anyhow = { version = "0.48", features = ["backtrace"] }
-openrouter-rs = "0.10"
+sentry = { version = "0.49", features = ["tower-axum-matched-path"] }
+sentry-anyhow = { version = "0.49", features = ["backtrace"] }
 dotenvy = "0.15"
 tower = "0.5"
-tower-http = {version = "0.6", features = ["trace"] }
+tower-http = { version = "0.7", features = ["trace"] }
 tracing = "0.1"
-tracing-subscriber = { version = "0.3", features=["env-filter"] }
+tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 axum = "0.8"
-anyhow = { version = "1.0", features = ["backtrace"] }
+anyhow = { version = "1", features = ["backtrace"] }
 thiserror = "2.0"
-hmac = "0.13"
-sha2 = "0.11"
+ring = "0.17"
 hex = "0.4"
-subtle = "2.6"
-bytes = "1.11"
+metrics = "0.24"
+metrics-exporter-prometheus = { version = "0.18", default-features = false, features = ["http-listener"] }
+
+[profile.release]
+debug = 1

Containerfile

@@ -1,12 +1,15 @@
-FROM rust:1.96 as builder
+FROM rust:1.97-trixie as builder
 
 WORKDIR /app
-COPY . .
-RUN cargo build --release
+
+COPY Cargo.toml Cargo.lock ./
+COPY crates/ crates/
+
+RUN cargo build --release --package herald-server
 
 
 FROM debian:trixie-slim
 
 WORKDIR /app
-COPY --from=builder /app/target/release/herald .
-CMD [ "./herald" ]
+COPY --from=builder /app/target/release/herald-server .
+CMD [ "./herald-server" ]

README.md

@@ -9,6 +9,7 @@ Herald is a Gitea bot that performs automated AI-powered code reviews on pull re
 - Concurrent review processing with configurable parallelism
 - Graceful shutdown — in-progress reviews finish before the process exits
 - Error tracking via Sentry
+- Prometheus metrics endpoint for monitoring
 - Tiny memory footprint (~4MB) thanks to Rust
 
 ## Installation
@@ -25,7 +26,6 @@ Herald reads its configuration from environment variables (a `.env` file is supp
 | Variable | Description |
 |---|---|
 | `HTTP_PORT` | Port to listen on |
-| `BOT_NAME` | The bot's Gitea username (used to detect mentions) |
 | `WEBHOOK_SIG_HEADER_SECRET` | Gitea webhook secret for signature verification |
 | `OPEN_ROUTER_API_KEY` | OpenRouter API key |
 | `OPEN_ROUTER_MODEL` | Model to use (e.g. `deepseek/deepseek-v4-flash`) |
@@ -34,8 +34,37 @@ Herald reads its configuration from environment variables (a `.env` file is supp
 | `GITEA_URL` | Base URL of your Gitea instance |
 | `GITEA_TOKEN` | Gitea API token |
 | `GITEA_TIMEOUT` | Gitea API request timeout in seconds |
+| `METRICS_BIND_ADDR` | *(optional)* Bind address for the Prometheus metrics endpoint (e.g. `0.0.0.0:9100`). If unset, the metrics exporter is disabled. |
 | `SENTRY_DSN` | *(optional)* Sentry DSN for error tracking |
 | `RUST_LOG` | *(optional)* Log level, defaults to `info` |
+| `CONTAINER_RUNTIME` | *(optional)* Container runtime binary used for the sandbox (`docker` or `podman`). Defaults to `docker` |
+| `SANDBOX_MAX_ITERATIONS` | *(optional)* Maximum number of tool-calling iterations per sandboxed review. Defaults to `8` |
+
+## Sandboxed reviews
+
+Herald reviews pull requests inside an ephemeral
+[Dev Container](https://containers.dev/). For each review it:
+
+1. clones the pull request head into a temporary directory,
+2. builds and starts the repository's devcontainer (`devcontainer-rs`),
+3. reads the pull request diff and file list from the Gitea API with
+   `GITEA_TOKEN` (so private repositories work), tells the model which files and
+   lines changed — additions and deletions, with the line numbers of the new and
+   old versions of the file respectively — then lets it explore the repository
+   with read-only tools (`ls`, `read_file`, `grep`, `find`) run inside the
+   container: the code itself is not sent, so the model reads it at those lines,
+4. posts the review, anchoring each comment on the added or removed line it
+   refers to, and removes the container and the temporary clone.
+
+The container runtime is selected with `CONTAINER_RUNTIME` (`docker` or
+`podman`). The repository must contain a `.devcontainer/devcontainer.json`.
+
+Each sandbox is isolated: it gets its own image tag, container and network. The
+container starts with network access so the `postCreateCommand` /
+`postStartCommand` hooks can install dependencies (e.g. `npm install`); once the
+hooks have run, the container is disconnected from the network for the rest of
+the review. Every container command is bounded by a timeout, and the container,
+network and image are removed when the review ends (including on failure).
 
 ## Development
 
@@ -51,3 +80,40 @@ cargo run
 ```
 
 Copy `.env.example` to `.env` and fill in your values before running.
+
+## Metrics
+
+Herald optionally exposes a Prometheus metrics endpoint, useful for scraping with an [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) or any Prometheus-compatible scraper.
+
+Set `METRICS_BIND_ADDR` (e.g. `0.0.0.0:9100`) to enable it. The metrics are then available at `http://<host>:9100/metrics`.
+
+### Exposed metrics
+
+| Metric | Type | Description |
+|---|---|---|
+| `herald_webhooks_received_total` | counter | Total webhooks received (label: `event_type`) |
+| `herald_webhooks_duplicate_total` | counter | Webhooks rejected as duplicates (label: `event_type`) |
+| `herald_webhooks_channel_full_total` | counter | Webhooks dropped because the bot channel was full (label: `event_type`) |
+| `herald_bot_tasks_active` | gauge | Bot tasks currently in progress |
+| `herald_bot_tasks_completed_total` | counter | Bot tasks completed successfully (label: `event_type`) |
+| `herald_bot_tasks_failed_total` | counter | Bot tasks that failed (label: `event_type`) |
+| `herald_openrouter_cost_cents_total` | counter | Total OpenRouter cost in cents (divide by 100 for USD) |
+
+### OTel collector example
+
+```yaml
+receivers:
+  prometheus:
+    config:
+      scrape_configs:
+        - job_name: herald
+          scrape_interval: 15s
+          static_configs:
+            - targets: ["herald:9100"]
+
+service:
+  pipelines:
+    metrics:
+      receivers: [prometheus]
+      exporters: [otlp]
+```

crates/devcontainer-rs/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "devcontainer-rs"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+tokio = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+anyhow = { workspace = true }
+thiserror = { workspace = true }
+
+[dev-dependencies]
+tempfile = "3"

crates/devcontainer-rs/src/container.rs

@@ -0,0 +1,649 @@
+//! Primitives de cycle de vie de container pour un [`DevContainer`] analysé.
+//!
+//! Ce module invoque un runtime de containers (`docker` ou `podman`) pour construire
+//! l'image devcontainer, démarrer un container avec le workspace monté, exécuter les
+//! hooks `postCreateCommand` / `postStartCommand` et lancer des commandes à l'intérieur
+//! du container en cours d'exécution.
+//!
+//! Il est volontairement agnostique du runtime : tout binaire exposant l'interface
+//! CLI `docker` (y compris `podman`) peut être utilisé via [`ContainerRuntime::new`].
+//!
+//! # Isolation
+//!
+//! Chaque sandbox dispose de son propre tag d'image, de son propre container et de
+//! son propre réseau. Le container démarre attaché à ce réseau afin que les hooks
+//! `postCreateCommand` / `postStartCommand` puissent récupérer des dépendances
+//! (par ex. `npm install`) ; une fois les hooks exécutés, le container est déconnecté
+//! du réseau pour le reste de sa durée de vie. Chaque commande est bornée par un timeout.
+
+use std::{
+    path::{Path, PathBuf},
+    process::Stdio,
+    time::{Duration, SystemTime, UNIX_EPOCH},
+};
+
+use tokio::process::Command;
+
+use crate::DevContainer;
+
+/// Timeout appliqué aux opérations de build/run/stop/remove.
+const DEFAULT_COMMAND_TIMEOUT: Duration = Duration::from_secs(600);
+
+/// Timeout appliqué aux commandes exécutées dans un container en cours d'exécution.
+const DEFAULT_EXEC_TIMEOUT: Duration = Duration::from_secs(60);
+
+/// Résultat d'une commande exécutée dans un container.
+#[derive(Debug, Clone)]
+pub struct ExecOutput {
+    /// Code de sortie, ou `-1` si le processus a été terminé par un signal.
+    pub status: i32,
+    pub stdout: String,
+    pub stderr: String,
+}
+
+impl ExecOutput {
+    pub fn success(&self) -> bool {
+        self.status == 0
+    }
+
+    /// Transforme un code de sortie non nul en [`ContainerError::Command`].
+    pub fn ensure_success(self, program: &str, args: &[String]) -> Result<Self, ContainerError> {
+        if self.success() {
+            return Ok(self);
+        }
+
+        Err(ContainerError::Command {
+            program: program.to_string(),
+            args: args.join(" "),
+            status: self.status,
+            stderr: self.stderr.trim().to_string(),
+        })
+    }
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum ContainerError {
+    #[error("failed to run `{program}`: {source}")]
+    Spawn {
+        program: String,
+        source: std::io::Error,
+    },
+
+    #[error("`{program} {args}` failed with status {status}: {stderr}")]
+    Command {
+        program: String,
+        args: String,
+        status: i32,
+        stderr: String,
+    },
+
+    #[error("`{program} {args}` timed out after {timeout:?}")]
+    Timeout {
+        program: String,
+        args: String,
+        timeout: Duration,
+    },
+}
+
+/// Un binaire de runtime de containers exposant l'interface CLI `docker`.
+#[derive(Debug, Clone)]
+pub struct ContainerRuntime {
+    program: String,
+    timeout: Duration,
+}
+
+impl ContainerRuntime {
+    pub fn new(program: impl Into<String>) -> Self {
+        Self {
+            program: program.into(),
+            timeout: DEFAULT_COMMAND_TIMEOUT,
+        }
+    }
+
+    pub fn docker() -> Self {
+        Self::new("docker")
+    }
+
+    pub fn podman() -> Self {
+        Self::new("podman")
+    }
+
+    /// Remplace le timeout appliqué aux opérations de build/run/stop/remove.
+    pub fn with_timeout(mut self, timeout: Duration) -> Self {
+        self.timeout = timeout;
+        self
+    }
+
+    pub fn program(&self) -> &str {
+        &self.program
+    }
+
+    pub fn timeout(&self) -> Duration {
+        self.timeout
+    }
+
+    /// Vérifie que le binaire du runtime est présent et répond.
+    pub async fn available(&self) -> bool {
+        Command::new(&self.program)
+            .arg("version")
+            .stdin(Stdio::null())
+            .stdout(Stdio::null())
+            .stderr(Stdio::null())
+            .status()
+            .await
+            .map(|status| status.success())
+            .unwrap_or(false)
+    }
+
+    /// Exécute le runtime avec les arguments donnés, en capturant stdout/stderr.
+    ///
+    /// Seuls les échecs de lancement (spawn) et les timeouts sont des erreurs ; un
+    /// code non nul est renvoyé dans [`ExecOutput`] afin que les appelants réagissent.
+    pub async fn run(&self, args: &[String]) -> Result<ExecOutput, ContainerError> {
+        self.run_with_timeout(args, self.timeout).await
+    }
+
+    /// Comme [`run`](Self::run), mais avec un timeout explicite.
+    pub async fn run_with_timeout(
+        &self,
+        args: &[String],
+        timeout: Duration,
+    ) -> Result<ExecOutput, ContainerError> {
+        let output = Command::new(&self.program)
+            .args(args)
+            .stdin(Stdio::null())
+            .kill_on_drop(true)
+            .output();
+
+        match tokio::time::timeout(timeout, output).await {
+            Ok(Ok(output)) => Ok(ExecOutput {
+                status: output.status.code().unwrap_or(-1),
+                stdout: String::from_utf8_lossy(&output.stdout).into_owned(),
+                stderr: String::from_utf8_lossy(&output.stderr).into_owned(),
+            }),
+            Ok(Err(source)) => Err(ContainerError::Spawn {
+                program: self.program.clone(),
+                source,
+            }),
+            Err(_) => Err(ContainerError::Timeout {
+                program: self.program.clone(),
+                args: args.join(" "),
+                timeout,
+            }),
+        }
+    }
+}
+
+/// Un devcontainer en cours d'exécution.
+#[derive(Debug, Clone)]
+pub struct Container {
+    runtime: ContainerRuntime,
+    name: String,
+    workspace_folder: String,
+    remote_user: Option<String>,
+    network: Option<String>,
+    image: Option<String>,
+}
+
+impl Container {
+    pub fn name(&self) -> &str {
+        &self.name
+    }
+
+    pub fn workspace_folder(&self) -> &str {
+        &self.workspace_folder
+    }
+
+    /// Exécute une commande dans le container et renvoie sa sortie.
+    ///
+    /// La commande est transmise sous forme de vecteur d'arguments (argv, sans shell),
+    /// donc aucun échappement ni interpolation n'est effectué.
+    pub async fn exec(&self, cmd: &[&str]) -> Result<ExecOutput, ContainerError> {
+        self.exec_with_timeout(cmd, DEFAULT_EXEC_TIMEOUT).await
+    }
+
+    async fn exec_with_timeout(
+        &self,
+        cmd: &[&str],
+        timeout: Duration,
+    ) -> Result<ExecOutput, ContainerError> {
+        let mut args = vec!["exec".to_string()];
+
+        if let Some(user) = &self.remote_user {
+            args.push("--user".to_string());
+            args.push(user.clone());
+        }
+
+        args.push(self.name.clone());
+        args.extend(cmd.iter().map(|arg| arg.to_string()));
+
+        self.runtime.run_with_timeout(&args, timeout).await
+    }
+
+    /// Exécute un script shell dans le container via `sh -c`.
+    pub async fn exec_shell(&self, script: &str) -> Result<ExecOutput, ContainerError> {
+        self.exec(&["sh", "-c", script]).await
+    }
+
+    /// Arrête le container.
+    pub async fn stop(&self) -> Result<(), ContainerError> {
+        let args = vec!["stop".to_string(), self.name.clone()];
+        self.runtime
+            .run(&args)
+            .await?
+            .ensure_success(self.runtime.program(), &args)?;
+        Ok(())
+    }
+
+    /// Supprime le container, son réseau et son image.
+    ///
+    /// La suppression du réseau et de l'image est best-effort : ils peuvent déjà être absents.
+    pub async fn remove(&self) -> Result<(), ContainerError> {
+        let args = vec![
+            "rm".to_string(),
+            "-f".to_string(),
+            "-v".to_string(),
+            self.name.clone(),
+        ];
+        self.runtime
+            .run(&args)
+            .await?
+            .ensure_success(self.runtime.program(), &args)?;
+
+        if let Some(network) = &self.network {
+            let args = vec!["network".to_string(), "rm".to_string(), network.clone()];
+            let _ = self.runtime.run(&args).await;
+        }
+
+        if let Some(image) = &self.image {
+            let args = vec!["rmi".to_string(), image.clone()];
+            let _ = self.runtime.run(&args).await;
+        }
+
+        Ok(())
+    }
+}
+
+impl DevContainer {
+    /// Nom de l'image de base dérivé du nom du devcontainer.
+    pub fn image_name(&self) -> String {
+        let base = self.name.as_deref().unwrap_or("devcontainer");
+        format!("devcontainer-rs/{}", sanitize(base))
+    }
+
+    /// Tag d'image unique pour une exécution de sandbox donnée.
+    ///
+    /// L'unicité est importante : deux sandboxes concurrentes (éventuellement pour des
+    /// dépôts différents partageant un nom de devcontainer) ne doivent pas se disputer le même tag.
+    pub fn image_tag(&self) -> String {
+        format!("{}:{}", self.image_name(), unique_suffix())
+    }
+
+    /// Arguments passés à `docker build` (tout ce qui suit le verbe `build`).
+    pub fn build_args(&self, image_tag: &str) -> Vec<String> {
+        let context = self
+            .container_file_path
+            .parent()
+            .unwrap_or_else(|| Path::new("."));
+
+        let mut args = vec![
+            "-f".to_string(),
+            self.container_file_path.display().to_string(),
+            "-t".to_string(),
+            image_tag.to_string(),
+        ];
+
+        for (key, value) in &self.build_args {
+            args.push("--build-arg".to_string());
+            args.push(format!("{key}={value}"));
+        }
+
+        args.push(context.display().to_string());
+        args
+    }
+
+    /// Arguments passés à `docker run` (tout ce qui suit le verbe `run`).
+    pub fn run_args(
+        &self,
+        workspace_dir: &Path,
+        container_name: &str,
+        image_tag: &str,
+        network: Option<&str>,
+    ) -> Vec<String> {
+        let workspace_folder = self.workspace_folder();
+
+        let mut args = vec![
+            "-d".to_string(),
+            "--name".to_string(),
+            container_name.to_string(),
+            "-v".to_string(),
+            format!("{}:{}", workspace_dir.display(), workspace_folder),
+            "-w".to_string(),
+            workspace_folder.to_string(),
+        ];
+
+        if let Some(network) = network {
+            args.push("--network".to_string());
+            args.push(network.to_string());
+        }
+
+        if let Some(user) = &self.remote_user {
+            args.push("--user".to_string());
+            args.push(user.clone());
+        }
+
+        for (key, value) in &self.container_env {
+            args.push("-e".to_string());
+            args.push(format!("{key}={value}"));
+        }
+
+        args.extend(self.run_args.iter().cloned());
+
+        args.push(image_tag.to_string());
+        // Maintient le container en vie pour pouvoir y exécuter `exec`.
+        args.push("sleep".to_string());
+        args.push("infinity".to_string());
+
+        args
+    }
+
+    /// Dossier de workspace dans le container, par défaut `/workspaces/workspace`.
+    pub fn workspace_folder(&self) -> String {
+        self.workspace_folder
+            .clone()
+            .unwrap_or_else(|| "/workspaces/workspace".to_string())
+    }
+
+    /// Nom de container unique pour cette exécution.
+    pub fn container_name(&self) -> String {
+        let base = self.name.as_deref().unwrap_or("devcontainer");
+        format!("devcontainer-rs-{}-{}", sanitize(base), unique_suffix())
+    }
+
+    /// Construit l'image devcontainer sous `image_tag`.
+    pub async fn build(
+        &self,
+        runtime: &ContainerRuntime,
+        image_tag: &str,
+    ) -> Result<(), ContainerError> {
+        let mut args = vec!["build".to_string()];
+        args.extend(self.build_args(image_tag));
+
+        runtime
+            .run(&args)
+            .await?
+            .ensure_success(runtime.program(), &args)?;
+
+        Ok(())
+    }
+
+    /// Construit l'image, démarre le container avec le workspace monté, exécute les
+    /// hooks `postCreateCommand` / `postStartCommand` avec accès au réseau, puis
+    /// déconnecte le container du réseau.
+    ///
+    /// En cas d'échec, le container, le réseau et l'image sont nettoyés avant de
+    /// renvoyer l'erreur, afin qu'aucune ressource ne soit laissée en place.
+    pub async fn up(
+        &self,
+        runtime: &ContainerRuntime,
+        workspace_dir: &Path,
+    ) -> Result<Container, ContainerError> {
+        let image_tag = self.image_tag();
+        self.build(runtime, &image_tag).await?;
+
+        let name = self.container_name();
+        let network = format!("{name}-net");
+
+        // Réseau dédié afin de pouvoir couper la connectivité après les hooks.
+        let args = vec!["network".to_string(), "create".to_string(), network.clone()];
+        if let Err(err) = runtime
+            .run(&args)
+            .await
+            .and_then(|out| out.ensure_success(runtime.program(), &args))
+        {
+            let _ = runtime.run(&["rmi".to_string(), image_tag]).await;
+            return Err(err);
+        }
+
+        let mut args = vec!["run".to_string()];
+        args.extend(self.run_args(workspace_dir, &name, &image_tag, Some(&network)));
+
+        if let Err(err) = runtime
+            .run(&args)
+            .await
+            .and_then(|out| out.ensure_success(runtime.program(), &args))
+        {
+            let _ = runtime
+                .run(&["network".to_string(), "rm".to_string(), network])
+                .await;
+            let _ = runtime.run(&["rmi".to_string(), image_tag]).await;
+            return Err(err);
+        }
+
+        let container = Container {
+            runtime: runtime.clone(),
+            name,
+            workspace_folder: self.workspace_folder(),
+            remote_user: self.remote_user.clone(),
+            network: Some(network.clone()),
+            image: Some(image_tag),
+        };
+
+        // Les hooks s'exécutent avec accès au réseau (installation de dépendances, etc.).
+        if let Err(err) = self.run_hooks(&container).await {
+            let _ = container.remove().await;
+            return Err(err);
+        }
+
+        // Coupe l'accès réseau pour le reste de la durée de vie de la sandbox.
+        let args = vec![
+            "network".to_string(),
+            "disconnect".to_string(),
+            network,
+            container.name.clone(),
+        ];
+        if let Err(err) = runtime
+            .run(&args)
+            .await
+            .and_then(|out| out.ensure_success(runtime.program(), &args))
+        {
+            let _ = container.remove().await;
+            return Err(err);
+        }
+
+        Ok(container)
+    }
+
+    async fn run_hooks(&self, container: &Container) -> Result<(), ContainerError> {
+        // Les hooks peuvent installer des dépendances, ils utilisent donc le timeout
+        // long des commandes plutôt que le court réservé à l'exécution des outils.
+        let timeout = container.runtime.timeout();
+
+        for command in [&self.post_create_command, &self.post_start_command]
+            .into_iter()
+            .flatten()
+        {
+            let output = container
+                .exec_with_timeout(&["sh", "-c", command], timeout)
+                .await?;
+            output.ensure_success(
+                container.runtime.program(),
+                &["exec".to_string(), command.clone()],
+            )?;
+        }
+
+        Ok(())
+    }
+}
+
+/// Nettoie une chaîne pour qu'elle puisse servir de nom d'image/container docker.
+fn sanitize(input: &str) -> String {
+    let sanitized: String = input
+        .chars()
+        .map(|c| {
+            if c.is_ascii_alphanumeric() || c == '-' || c == '_' || c == '.' {
+                c.to_ascii_lowercase()
+            } else {
+                '-'
+            }
+        })
+        .collect();
+
+    let trimmed = sanitized.trim_matches(|c| c == '-' || c == '.' || c == '_');
+    if trimmed.is_empty() {
+        "devcontainer".to_string()
+    } else {
+        trimmed.to_string()
+    }
+}
+
+/// Suffixe unique à une exécution de sandbox, combinant l'identifiant de processus et un horodatage.
+fn unique_suffix() -> String {
+    let nanos = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|duration| duration.as_nanos())
+        .unwrap_or(0);
+
+    format!("{}-{}", std::process::id(), nanos)
+}
+
+/// Normalise lexicalement un chemin, en résolvant `.` et `..` sans toucher au
+/// système de fichiers. Renvoie `None` si le chemin sort de sa racine.
+pub fn normalize(path: &Path) -> Option<PathBuf> {
+    use std::path::Component;
+
+    let mut out = PathBuf::new();
+    for component in path.components() {
+        match component {
+            Component::RootDir => out.push("/"),
+            Component::CurDir => {}
+            Component::ParentDir => {
+                if !out.pop() {
+                    return None;
+                }
+            }
+            Component::Normal(part) => out.push(part),
+            Component::Prefix(_) => return None,
+        }
+    }
+
+    Some(out)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs;
+
+    fn devcontainer(dir: &Path) -> DevContainer {
+        let devcontainer_path = dir.join("devcontainer.json");
+        let dockerfile_path = dir.join("Dockerfile");
+
+        fs::write(&dockerfile_path, "FROM alpine\n").unwrap();
+        fs::write(
+            &devcontainer_path,
+            r#"{
+                "name": "My Project",
+                "build": {
+                    "dockerfile": "Dockerfile",
+                    "args": { "VERSION": "1" }
+                },
+                "workspaceFolder": "/workspaces/my-project",
+                "containerEnv": { "RUST_LOG": "debug" },
+                "remoteUser": "dev",
+                "runArgs": ["--userns=keep-id"]
+            }"#,
+        )
+        .unwrap();
+
+        let runtime = tokio::runtime::Runtime::new().unwrap();
+        runtime.block_on(crate::parse(&devcontainer_path)).unwrap()
+    }
+
+    #[test]
+    fn image_name_is_sanitized() {
+        let dir = tempfile::tempdir().unwrap();
+        let dc = devcontainer(dir.path());
+        assert_eq!(dc.image_name(), "devcontainer-rs/my-project");
+    }
+
+    #[test]
+    fn image_tags_are_unique() {
+        let dir = tempfile::tempdir().unwrap();
+        let dc = devcontainer(dir.path());
+        assert_ne!(dc.image_tag(), dc.image_tag());
+    }
+
+    #[test]
+    fn build_args_include_dockerfile_tag_build_args_and_context() {
+        let dir = tempfile::tempdir().unwrap();
+        let dc = devcontainer(dir.path());
+        let args = dc.build_args("devcontainer-rs/my-project:test");
+
+        assert_eq!(args[0], "-f");
+        assert!(args[1].ends_with("Dockerfile"));
+        assert_eq!(args[2], "-t");
+        assert_eq!(args[3], "devcontainer-rs/my-project:test");
+        assert!(args.contains(&"--build-arg".to_string()));
+        assert!(args.contains(&"VERSION=1".to_string()));
+        assert_eq!(args.last().unwrap(), &dir.path().display().to_string());
+    }
+
+    #[test]
+    fn run_args_mount_workspace_and_keep_alive() {
+        let dir = tempfile::tempdir().unwrap();
+        let dc = devcontainer(dir.path());
+        let workspace = Path::new("/tmp/clone");
+        let args = dc.run_args(
+            workspace,
+            "devcontainer-rs-my-project-42",
+            "devcontainer-rs/my-project:test",
+            Some("sandbox-net"),
+        );
+
+        assert!(args.contains(&"-d".to_string()));
+        assert!(args.contains(&"--name".to_string()));
+        assert!(args.contains(&"devcontainer-rs-my-project-42".to_string()));
+        assert!(args.contains(&"/tmp/clone:/workspaces/my-project".to_string()));
+        assert!(args.contains(&"--network".to_string()));
+        assert!(args.contains(&"sandbox-net".to_string()));
+        assert!(args.contains(&"--user".to_string()));
+        assert!(args.contains(&"dev".to_string()));
+        assert!(args.contains(&"RUST_LOG=debug".to_string()));
+        assert!(args.contains(&"--userns=keep-id".to_string()));
+        assert!(args.contains(&"devcontainer-rs/my-project:test".to_string()));
+        assert_eq!(
+            &args[args.len() - 2..],
+            &["sleep".to_string(), "infinity".to_string()]
+        );
+    }
+
+    #[test]
+    fn normalize_rejects_escaping_paths() {
+        assert_eq!(
+            normalize(Path::new("/workspaces/project/src/../main.rs")),
+            Some(PathBuf::from("/workspaces/project/main.rs"))
+        );
+        assert_eq!(normalize(Path::new("/workspaces/../../etc/passwd")), None);
+    }
+
+    #[tokio::test]
+    async fn run_captures_output() {
+        let runtime = ContainerRuntime::new("echo");
+        let output = runtime.run(&["hello".to_string()]).await.unwrap();
+
+        assert!(output.success());
+        assert_eq!(output.stdout.trim(), "hello");
+    }
+
+    #[tokio::test]
+    async fn run_times_out_and_kills_the_process() {
+        let runtime = ContainerRuntime::new("sleep");
+        let err = runtime
+            .run_with_timeout(&["10".to_string()], Duration::from_millis(50))
+            .await
+            .unwrap_err();
+
+        assert!(matches!(err, ContainerError::Timeout { .. }));
+    }
+}

crates/devcontainer-rs/src/lib.rs

@@ -0,0 +1,248 @@
+use std::{
+    collections::HashMap,
+    path::{Path, PathBuf},
+};
+
+use serde::Deserialize;
+
+mod container;
+
+pub use container::{Container, ContainerError, ContainerRuntime, ExecOutput, normalize};
+
+#[derive(Debug, Deserialize)]
+pub struct DevContainerBuildSchema {
+    #[serde(default)]
+    pub dockerfile: String,
+    #[serde(default)]
+    pub args: HashMap<String, String>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct DevContainerSchema {
+    #[serde(default)]
+    pub name: Option<String>,
+    pub build: DevContainerBuildSchema,
+
+    #[serde(rename = "workspaceFolder", default)]
+    pub workspace_folder: Option<String>,
+
+    #[serde(rename = "containerEnv", default)]
+    pub container_env: HashMap<String, String>,
+
+    #[serde(rename = "postCreateCommand", default)]
+    pub post_create_command: Option<String>,
+
+    #[serde(rename = "postStartCommand", default)]
+    pub post_start_command: Option<String>,
+
+    #[serde(rename = "remoteUser", default)]
+    pub remote_user: Option<String>,
+
+    #[serde(rename = "runArgs", default)]
+    pub run_args: Vec<String>,
+}
+
+#[derive(Debug)]
+pub struct DevContainer {
+    pub container_file_path: PathBuf,
+    pub name: Option<String>,
+    pub build_args: HashMap<String, String>,
+    pub container_env: HashMap<String, String>,
+    pub workspace_folder: Option<String>,
+    pub post_create_command: Option<String>,
+    pub post_start_command: Option<String>,
+    pub remote_user: Option<String>,
+    pub run_args: Vec<String>,
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum ParseError {
+    #[error("failed to read devcontainer file `{path}`: {source}")]
+    Read {
+        path: PathBuf,
+        source: std::io::Error,
+    },
+
+    #[error("invalid devcontainer JSON in `{path}`: {source}")]
+    Json {
+        path: PathBuf,
+        source: serde_json::Error,
+    },
+
+    #[error("container file `{0}` does not exist or is not a regular file")]
+    ContainerFileNotFound(PathBuf),
+
+    #[error("the devcontainer file path has no parent directory: `{0}`")]
+    InvalidDevContainerPath(PathBuf),
+}
+
+impl TryFrom<(DevContainerSchema, PathBuf)> for DevContainer {
+    type Error = ParseError;
+
+    fn try_from(
+        (schema, devcontainer_path): (DevContainerSchema, PathBuf),
+    ) -> Result<Self, Self::Error> {
+        let base_dir = devcontainer_path
+            .parent()
+            .ok_or_else(|| ParseError::InvalidDevContainerPath(devcontainer_path.clone()))?;
+
+        let container_file_path = base_dir.join(schema.build.dockerfile);
+
+        if !container_file_path.is_file() {
+            return Err(ParseError::ContainerFileNotFound(container_file_path));
+        }
+
+        let build_args = schema
+            .build
+            .args
+            .into_iter()
+            .map(|(k, v)| (k, substitute_local_env(&v)))
+            .collect();
+
+        let container_env = schema
+            .container_env
+            .into_iter()
+            .map(|(k, v)| (k, substitute_local_env(&v)))
+            .collect();
+
+        Ok(Self {
+            container_file_path,
+            name: schema.name,
+            build_args,
+            container_env,
+            workspace_folder: schema.workspace_folder,
+            post_create_command: schema.post_create_command,
+            post_start_command: schema.post_start_command,
+            remote_user: schema.remote_user,
+            run_args: schema.run_args,
+        })
+    }
+}
+
+/// Résout les références `${localEnv:VAR}` et `${localEnv:VAR:default}` à l'aide de
+/// l'environnement du processus courant, comme décrit par la spécification devcontainer.
+/// Les variables non résolues sans valeur par défaut sont remplacées par une chaîne vide.
+fn substitute_local_env(input: &str) -> String {
+    const PREFIX: &str = "${localEnv:";
+
+    let mut out = String::with_capacity(input.len());
+    let mut rest = input;
+
+    while let Some(start) = rest.find(PREFIX) {
+        out.push_str(&rest[..start]);
+        let after = &rest[start + PREFIX.len()..];
+
+        match after.find('}') {
+            Some(end) => {
+                let inner = &after[..end];
+                let (key, default) = match inner.split_once(':') {
+                    Some((key, default)) => (key, Some(default)),
+                    None => (inner, None),
+                };
+
+                match std::env::var(key) {
+                    Ok(value) => out.push_str(&value),
+                    Err(_) => out.push_str(default.unwrap_or("")),
+                }
+
+                rest = &after[end + 1..];
+            }
+            None => {
+                out.push_str(PREFIX);
+                rest = after;
+            }
+        }
+    }
+
+    out.push_str(rest);
+    out
+}
+
+pub async fn parse(path: impl AsRef<Path>) -> Result<DevContainer, ParseError> {
+    let path = path.as_ref().to_path_buf();
+    let contents = tokio::fs::read_to_string(&path)
+        .await
+        .map_err(|source| ParseError::Read {
+            path: path.clone(),
+            source,
+        })?;
+
+    let schema = serde_json::from_str::<DevContainerSchema>(&contents).map_err(|source| {
+        ParseError::Json {
+            path: path.clone(),
+            source,
+        }
+    })?;
+
+    DevContainer::try_from((schema, path))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs;
+
+    #[tokio::test]
+    async fn parses_devcontainer_file() {
+        let dir = tempfile::tempdir().unwrap();
+        let devcontainer_path = dir.path().join("devcontainer.json");
+        let dockerfile_path = dir.path().join("Dockerfile");
+
+        fs::write(&dockerfile_path, "FROM alpine\n").unwrap();
+        fs::write(
+            &devcontainer_path,
+            r#"{
+                "name": "test",
+                "build": {
+                    "dockerfile": "Dockerfile",
+                    "args": {
+                        "VERSION": "1"
+                    }
+                },
+                "workspaceFolder": "/workspace",
+                "containerEnv": {
+                    "RUST_LOG": "debug"
+                },
+                "remoteUser": "dev",
+                "runArgs": ["--userns=keep-id"]
+            }"#,
+        )
+        .unwrap();
+
+        let config = parse(&devcontainer_path).await.unwrap();
+
+        assert_eq!(config.name.as_deref(), Some("test"));
+        assert_eq!(config.container_file_path, dockerfile_path);
+        assert_eq!(config.build_args.get("VERSION").unwrap(), "1");
+        assert_eq!(config.container_env.get("RUST_LOG").unwrap(), "debug");
+        assert_eq!(config.workspace_folder.as_deref(), Some("/workspace"));
+        assert_eq!(config.remote_user.as_deref(), Some("dev"));
+        assert_eq!(config.run_args, vec!["--userns=keep-id"]);
+    }
+
+    #[test]
+    fn substitutes_local_env_with_default() {
+        unsafe { std::env::set_var("DEVCONTAINER_TEST_UID", "1000") };
+
+        assert_eq!(
+            substitute_local_env("${localEnv:DEVCONTAINER_TEST_UID}"),
+            "1000"
+        );
+        assert_eq!(
+            substitute_local_env("uid=${localEnv:DEVCONTAINER_TEST_UID}"),
+            "uid=1000"
+        );
+        assert_eq!(
+            substitute_local_env("${localEnv:DEVCONTAINER_TEST_MISSING:fallback}"),
+            "fallback"
+        );
+        assert_eq!(
+            substitute_local_env("${localEnv:DEVCONTAINER_TEST_MISSING}"),
+            ""
+        );
+        assert_eq!(
+            substitute_local_env("no variables here"),
+            "no variables here"
+        );
+    }
+}

crates/herald-server/Cargo.toml

@@ -0,0 +1,28 @@
+[package]
+name = "herald-server"
+version = "1.2.0"
+edition = "2024"
+
+[dependencies]
+reqwest = { workspace = true }
+tokio = { workspace = true }
+tokio-util = { workspace = true }
+futures-util = { workspace = true }
+serde_json = { workspace = true }
+serde = { workspace = true }
+sentry = { workspace = true }
+sentry-anyhow = { workspace = true }
+dotenvy = { workspace = true }
+tower = { workspace = true }
+tower-http = { workspace = true }
+tracing = { workspace = true }
+tracing-subscriber = { workspace = true }
+axum = { workspace = true }
+anyhow = { workspace = true }
+thiserror = { workspace = true }
+ring = { workspace = true }
+hex = { workspace = true }
+metrics = { workspace = true }
+metrics-exporter-prometheus = { workspace = true }
+devcontainer-rs = { path = "../devcontainer-rs" }
+tempfile = "3"

crates/herald-server/src/api.rs

@@ -4,12 +4,10 @@ use axum::http::Request;
 use axum::response::IntoResponse;
 use axum::routing::{get, post};
 use axum::{Json, Router};
-use hmac::{Hmac, KeyInit, Mac};
 use reqwest::StatusCode;
+use ring::hmac;
 use sentry::integrations::tower::{NewSentryLayer, SentryHttpLayer};
 use serde_json::Value;
-use sha2::Sha256;
-use subtle::ConstantTimeEq;
 use tower::ServiceBuilder;
 use tower_http::trace::TraceLayer;
 use tracing::{info, instrument};
@@ -19,6 +17,7 @@ use tokio_util::sync::CancellationToken;
 use crate::consts::{GITEA_EVENT_TYPE_HEADER_NAME, GITEA_SIG_HEADER_NAME, MAX_WEBHOOK_BODY_SIZE};
 use crate::errors::AppError;
 use crate::gitea::WebhookType;
+use crate::metrics;
 use crate::state::AppState;
 
 pub async fn start(app_state: AppState, shutdown: CancellationToken) -> anyhow::Result<()> {
@@ -58,13 +57,18 @@ async fn webhook(
 ) -> Result<impl IntoResponse, AppError> {
     tracing::Span::current().record("webhook_type", tracing::field::debug(&wb));
 
+    let event_type = wb.event_type_str();
+    metrics::webhook_received(event_type);
+
     let event_id = wb.event_id();
     if app_state.bot.check_and_mark(event_id).await {
+        metrics::webhook_duplicate(event_type);
         return Err(AppError::AlreadyProcessedErr);
     }
 
     if app_state.bot_tx.try_send(wb).is_err() {
         app_state.bot.unmark(event_id).await;
+        metrics::webhook_channel_full(event_type);
         return Err(AppError::ChannelFullErr);
     }
 
@@ -105,7 +109,7 @@ where
             });
         });
 
-        let webhook = parse_webhook(&type_header, &app_state.config.bot_name, &body_bytes)?;
+        let webhook = parse_webhook(&type_header, &app_state.bot.name(), &body_bytes)?;
         Ok(WebhookExtract(webhook))
     }
 }
@@ -137,12 +141,7 @@ fn parse_webhook(header: &str, bot_name: &str, body_bytes: &[u8]) -> Result<Webh
 fn verify_signature(secret_key: &[u8], sig_header: &str, body: &[u8]) -> Result<(), AppError> {
     let sig_header_decoded =
         hex::decode(sig_header).map_err(|_| AppError::WebHookSigHeaderInvalidErr)?;
-    let mut mac = Hmac::<Sha256>::new_from_slice(secret_key).map_err(anyhow::Error::from)?;
+    let key = hmac::Key::new(hmac::HMAC_SHA256, secret_key);
 
-    mac.update(body);
-
-    let generated_hmac = mac.finalize().into_bytes();
-    bool::from(generated_hmac.ct_eq(&sig_header_decoded))
-        .then_some(())
-        .ok_or(AppError::WebHookSigHeaderInvalidErr)
+    hmac::verify(&key, body, &sig_header_decoded).map_err(|_| AppError::WebHookSigHeaderInvalidErr)
 }

crates/herald-server/src/bot.rs

@@ -1,10 +1,11 @@
 use crate::{
-    env::EnvConfig,
     gitea::{GiteaAPI, WebhookType},
+    metrics,
     open_router::OpenRouterClient,
+    sandbox::SandboxConfig,
 };
-use serde::Deserialize;
-use std::{collections::HashSet, sync::Arc, time::Duration};
+use serde::{Deserialize, Deserializer};
+use std::{collections::HashSet, sync::Arc};
 use tokio::sync::Mutex;
 use tokio_util::sync::CancellationToken;
 use tracing::{error, info, instrument};
@@ -20,39 +21,80 @@ pub struct ReviewResult {
 pub struct ReviewItem {
     pub filename: String,
     pub line: Option<u64>,
-    pub code: String,
+    #[serde(default, deserialize_with = "deserialize_side")]
+    pub side: Option<ReviewSide>,
     pub message: String,
 }
 
+/// Which version of the file a review comment is anchored on.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ReviewSide {
+    /// The line was added by the pull request: `line` is a line number of the
+    /// new version of the file.
+    Added,
+    /// The line was removed by the pull request: `line` is a line number of the
+    /// old version of the file.
+    Removed,
+}
+
+impl ReviewSide {
+    /// Reads the side the model asked for, tolerating casing and synonyms.
+    fn parse(raw: &str) -> Option<Self> {
+        match raw.trim().to_ascii_lowercase().as_str() {
+            "added" | "add" | "new" | "right" => Some(Self::Added),
+            "removed" | "remove" | "deleted" | "delete" | "old" | "left" => Some(Self::Removed),
+            _ => None,
+        }
+    }
+}
+
+/// Reads the side the model asked for. An unreadable value is ignored instead of
+/// failing the whole review: the side is then resolved from the changed lines.
+fn deserialize_side<'de, D>(deserializer: D) -> Result<Option<ReviewSide>, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    let raw = Option::<serde_json::Value>::deserialize(deserializer)?;
+
+    Ok(raw
+        .as_ref()
+        .and_then(serde_json::Value::as_str)
+        .and_then(ReviewSide::parse))
+}
+
 #[derive(Clone)]
 pub struct Bot {
-    config: EnvConfig,
+    bot_name: String,
     gitea_api: GiteaAPI,
     open_router_client: OpenRouterClient,
-    http_client: reqwest::Client,
     max_concurrent: usize,
+    open_router_model: String,
+    sandbox: SandboxConfig,
     actions_handled: Arc<Mutex<HashSet<u64>>>,
 }
 
 impl Bot {
-    pub fn new(config: EnvConfig) -> anyhow::Result<Self> {
-        let gitea_timeout = config.gitea_timeout;
-        let open_router_timeout = config.open_router_timeout;
-
-        Ok(Self {
-            gitea_api: GiteaAPI::new(&config.gitea_url, &config.gitea_token, gitea_timeout)?,
-            open_router_client: OpenRouterClient::new(
-                &config.open_router_api_key,
-                &config.open_router_model,
-                open_router_timeout,
-            )?,
-            max_concurrent: config.bot_max_concurrent,
-            config,
+    pub fn new(
+        bot_name: String,
+        gitea_api: GiteaAPI,
+        open_router_client: OpenRouterClient,
+        max_concurrent: usize,
+        open_router_model: String,
+        sandbox: SandboxConfig,
+    ) -> Self {
+        Self {
+            bot_name,
+            gitea_api,
+            open_router_client,
+            max_concurrent,
+            open_router_model,
+            sandbox,
             actions_handled: Arc::new(Mutex::new(HashSet::new())),
-            http_client: reqwest::Client::builder()
-                .timeout(Duration::from_secs(gitea_timeout))
-                .build()?,
-        })
+        }
+    }
+
+    pub fn name(&self) -> String {
+        self.bot_name.clone()
     }
 
     pub async fn start(
@@ -84,10 +126,12 @@ impl Bot {
             info!(queued = rx.len(), active = tasks.len(), "Webhook received");
             let permit = sem.clone().acquire_owned().await?;
             let self_clone = self.clone();
+            metrics::increment_task_active();
 
             tasks.spawn(async move {
                 self_clone.exec(wb).await;
                 drop(permit);
+                metrics::decrement_task_active();
             });
         }
 
@@ -99,6 +143,8 @@ impl Bot {
 
     #[instrument(skip(self, webhook), fields(repo, pr))]
     pub async fn exec(&self, webhook: WebhookType) {
+        let event_type_str = webhook.event_type_str();
+
         match &webhook {
             WebhookType::Review(p) => {
                 tracing::Span::current().record("repo", &p.repository.full_name);
@@ -106,20 +152,27 @@ impl Bot {
             }
         };
 
+        let tools = crate::sandbox::tools::for_webhook(&webhook);
+
         let exec_result = match webhook {
             WebhookType::Review(review_payload) => crate::bot_actions::review::exec_review(
                 &self.gitea_api,
                 &self.open_router_client,
-                &self.http_client,
-                &self.config.open_router_model,
+                &self.open_router_model,
+                &self.sandbox,
+                tools,
                 review_payload,
             ),
         }
         .await;
 
         match exec_result {
-            Ok(_) => info!("Task completed"),
+            Ok(_) => {
+                metrics::task_completed(event_type_str);
+                info!("Task completed");
+            }
             Err(err) => {
+                metrics::task_failed(event_type_str);
                 error!(%err, "Task error");
                 sentry_anyhow::capture_anyhow(&err);
             }

crates/herald-server/src/bot_actions/review.rs

@@ -0,0 +1,863 @@
+use tracing::{info, instrument, warn};
+
+use crate::{
+    bot::{ReviewResult, ReviewSide},
+    consts::{BOT_PROCESS_MSG, REVIEW_PROMPT, SANDBOX_SYSTEM_PROMPT},
+    gitea::{GiteaAPI, PullRequestFile, ReviewPayload},
+    metrics,
+    open_router::{OpenRouterClient, Tool},
+    sandbox::{Sandbox, SandboxConfig, agent},
+};
+
+#[instrument(skip(gitea_api, open_router_client, sandbox_config, tools, review_payload))]
+pub async fn exec_review(
+    gitea_api: &GiteaAPI,
+    open_router_client: &OpenRouterClient,
+    model: &str,
+    sandbox_config: &SandboxConfig,
+    tools: Vec<Tool>,
+    review_payload: ReviewPayload,
+) -> anyhow::Result<()> {
+    tracing::info!(
+        repo = %review_payload.repository.full_name,
+        pr = review_payload.pull_request.number,
+        action = %review_payload.action,
+        "Starting review"
+    );
+
+    let new_comment = gitea_api
+        .comment(
+            &BOT_PROCESS_MSG.replace("{model}", model),
+            &review_payload.repository.full_name,
+            review_payload.pull_request.number,
+        )
+        .await?;
+
+    let bot_result: Result<ReviewResult, anyhow::Error> = async {
+        let full_name = &review_payload.repository.full_name;
+        let index = review_payload.pull_request.number;
+
+        let git_diff = gitea_api.pull_request_diff(full_name, index).await?;
+
+        // The file list only refines the paths and describes the changes: a
+        // failure is not fatal, the diff is the source of truth for the lines.
+        let files = match gitea_api.pull_request_files(full_name, index).await {
+            Ok(files) => files,
+            Err(err) => {
+                warn!(%err, "Failed to list the pull request files");
+                Vec::new()
+            }
+        };
+
+        let mut changed_lines = parse_changed_lines(&git_diff);
+        resolve_filenames(&mut changed_lines, &files);
+
+        let changes = format_changes(&files, &changed_lines);
+
+        let bot_request = REVIEW_PROMPT
+            .replace("{subject}", &review_payload.pull_request.title)
+            .replace("{comment}", &review_payload.comment.body)
+            .replace("{changes}", &changes);
+
+        let (message, cost) = run_sandboxed_review(
+            gitea_api,
+            open_router_client,
+            sandbox_config,
+            tools,
+            &review_payload,
+            &bot_request,
+        )
+        .await?;
+
+        let mut review_result = serde_json::from_str::<ReviewResult>(&message)?;
+        resolve_review_sides(&mut review_result, &changed_lines);
+
+        review_result.cost = cost;
+        if let Some(cost) = review_result.cost {
+            metrics::openrouter_cost_usd(cost);
+        }
+
+        let final_review_markdown = review_result_to_markdown(&review_result);
+
+        gitea_api
+            .post_pull_request_review(
+                &review_result,
+                &final_review_markdown,
+                &review_payload.repository.full_name,
+                review_payload.pull_request.number,
+            )
+            .await?;
+
+        Ok(review_result)
+    }
+    .await;
+
+    match bot_result {
+        Ok(_) => {
+            gitea_api
+                .delete_comment(&review_payload.repository.full_name, new_comment.id)
+                .await
+        }
+        Err(e) => {
+            gitea_api
+                .edit_comment(
+                    &format!("Error while reviewing: {}", e),
+                    &review_payload.repository.full_name,
+                    new_comment.id,
+                )
+                .await
+        }
+    }
+}
+
+/// Runs the review inside a sandbox container, letting the model explore the
+/// repository with tools before answering.
+async fn run_sandboxed_review(
+    gitea_api: &GiteaAPI,
+    open_router_client: &OpenRouterClient,
+    sandbox_config: &SandboxConfig,
+    tools: Vec<Tool>,
+    review_payload: &ReviewPayload,
+    bot_request: &str,
+) -> anyhow::Result<(String, Option<f64>)> {
+    let repo_url = gitea_api.repo_clone_url(&review_payload.repository.full_name);
+
+    let sandbox = Sandbox::create(
+        &sandbox_config.runtime,
+        &repo_url,
+        gitea_api.token(),
+        review_payload.pull_request.number,
+    )
+    .await?;
+
+    let result = agent::run(
+        open_router_client,
+        &sandbox,
+        tools,
+        SANDBOX_SYSTEM_PROMPT,
+        bot_request,
+        sandbox_config.max_iterations,
+    )
+    .await;
+
+    if let Err(err) = sandbox.cleanup().await {
+        warn!(%err, "Failed to clean up sandbox container");
+    }
+
+    let result = result?;
+    info!(
+        iterations = result.iterations,
+        cost = ?result.cost,
+        "Sandboxed review finished"
+    );
+
+    Ok((result.message, result.cost))
+}
+
+fn review_result_to_markdown(review_result: &ReviewResult) -> String {
+    if review_result.reviews.is_empty() {
+        return String::from("No issues found. ✅");
+    }
+
+    let mut md = String::from("## Review Feedback\n\n");
+
+    md.push_str(&format!(
+        "### {} issues found.\n\n",
+        review_result.reviews.len()
+    ));
+
+    if !review_result.comment.is_empty() {
+        md.push_str("\n---\n\n");
+        md.push_str("### Summary\n\n");
+        md.push_str(&review_result.comment);
+        md.push('\n');
+    }
+
+    if let Some(cost) = review_result.cost {
+        md.push_str("\n---\n\n");
+        md.push_str(&format!("### Cost: ${}", cost));
+        md.push('\n');
+    }
+
+    md
+}
+
+/// The lines a pull request changed, per file.
+///
+/// Line numbers are the ones Gitea expects to place a review comment:
+/// [`ReviewSide::Added`] numbers refer to the new version of the file (sent as
+/// `new_position`), [`ReviewSide::Removed`] numbers to the old version (sent as
+/// `old_position`).
+type ChangedLines = Vec<ChangedFile>;
+
+struct ChangedFile {
+    filename: String,
+    added: Vec<u64>,
+    removed: Vec<u64>,
+}
+
+impl ChangedFile {
+    fn new(filename: &str) -> Self {
+        Self {
+            filename: String::from(filename),
+            added: Vec::new(),
+            removed: Vec::new(),
+        }
+    }
+
+    /// Lines that can be commented on for the given side.
+    fn lines(&self, side: ReviewSide) -> &[u64] {
+        match side {
+            ReviewSide::Added => &self.added,
+            ReviewSide::Removed => &self.removed,
+        }
+    }
+
+    /// Side a line belongs to, used when the model did not state one.
+    fn side_of(&self, line: u64) -> Option<ReviewSide> {
+        if self.added.contains(&line) {
+            Some(ReviewSide::Added)
+        } else if self.removed.contains(&line) {
+            Some(ReviewSide::Removed)
+        } else {
+            None
+        }
+    }
+}
+
+/// Lists the lines changed by the diff, per file, on both sides.
+///
+/// Only the line numbers are kept: the model reads the code itself through the
+/// sandbox tools.
+fn parse_changed_lines(git_diff: &str) -> ChangedLines {
+    let mut files = Vec::new();
+    let mut current_file: Option<String> = None;
+    let mut in_hunk = false;
+    let mut old_line: u64 = 0;
+    let mut new_line: u64 = 0;
+
+    for line in git_diff.lines() {
+        if line.starts_with("diff --git ") {
+            current_file = None;
+            in_hunk = false;
+            continue;
+        }
+
+        // `--- a/x` and `+++ b/x` only appear before the first hunk of a file.
+        // Inside a hunk, a line may legitimately start with them: removing
+        // `--x` gives `---x`, adding `++i;` gives `+++i;`.
+        if !in_hunk && (line.starts_with("--- ") || line.starts_with("+++ ")) {
+            // A header is never a content line: `+++ /dev/null` on a deleted
+            // file keeps the path of the other side in place.
+            if let Some(path) = header_file_path(line) {
+                current_file = Some(path);
+            }
+            continue;
+        }
+
+        if line.starts_with("@@") {
+            if let Some((old_start, new_start)) = parse_hunk_starts(line) {
+                old_line = old_start;
+                new_line = new_start;
+                in_hunk = true;
+            }
+            continue;
+        }
+
+        let Some(filename) = current_file.as_deref() else {
+            continue;
+        };
+
+        match line.as_bytes().first() {
+            Some(b' ') => {
+                old_line += 1;
+                new_line += 1;
+            }
+            Some(b'-') => {
+                changed_file(&mut files, filename).removed.push(old_line);
+                old_line += 1;
+            }
+            Some(b'+') => {
+                changed_file(&mut files, filename).added.push(new_line);
+                new_line += 1;
+            }
+            // `\ No newline at end of file`, and anything unexpected: a line
+            // that advances neither side.
+            _ => {}
+        }
+    }
+
+    files
+}
+
+/// Path of the file on one side of the diff, from a `--- a/<path>` or
+/// `+++ b/<path>` header line.
+///
+/// These lines are the only unambiguous source for the path: the `diff --git`
+/// line is cut at the first space, and it names the old path of a renamed file.
+/// `None` for `/dev/null`, which leaves the path of the other side in place.
+fn header_file_path(line: &str) -> Option<String> {
+    let (prefix, raw) = match line.strip_prefix("--- ") {
+        Some(raw) => ("a/", raw),
+        None => ("b/", line.strip_prefix("+++ ")?),
+    };
+
+    let path = decode_git_path(raw);
+
+    Some(String::from(path.strip_prefix(prefix)?))
+}
+
+/// Decodes a path as git writes it in a diff header: git wraps it in quotes and
+/// escapes the bytes that need it (`\303\251` for `é`) when the path contains
+/// non-printable or non-ASCII characters.
+fn decode_git_path(raw: &str) -> String {
+    let Some(quoted) = raw.strip_prefix('"').and_then(|raw| raw.strip_suffix('"')) else {
+        return String::from(raw);
+    };
+
+    let bytes = quoted.as_bytes();
+    let mut decoded = Vec::with_capacity(bytes.len());
+    let mut index = 0;
+
+    while let Some(byte) = bytes.get(index) {
+        index += 1;
+
+        if *byte != b'\\' {
+            decoded.push(*byte);
+            continue;
+        }
+
+        match bytes.get(index) {
+            // Octal escapes are the ones that matter for a path: git uses them
+            // for every non-ASCII byte.
+            Some(digit @ b'0'..=b'7') => {
+                let mut value = u32::from(digit - b'0');
+                let mut digits = 1;
+
+                while digits < 3 {
+                    match bytes.get(index + digits) {
+                        Some(next @ b'0'..=b'7') => {
+                            value = value * 8 + u32::from(next - b'0');
+                            digits += 1;
+                        }
+                        _ => break,
+                    }
+                }
+
+                decoded.push(u8::try_from(value).unwrap_or(b'?'));
+                index += digits;
+            }
+            Some(escaped) => {
+                decoded.push(match escaped {
+                    b't' => b'\t',
+                    b'n' => b'\n',
+                    b'r' => b'\r',
+                    other => *other,
+                });
+                index += 1;
+            }
+            None => decoded.push(b'\\'),
+        }
+    }
+
+    String::from_utf8_lossy(&decoded).into_owned()
+}
+
+/// Replaces the paths parsed from the diff with the exact paths reported by the
+/// API, which are the ones the model sees in the sandbox.
+fn resolve_filenames(changed_lines: &mut ChangedLines, files: &[PullRequestFile]) {
+    for changed in changed_lines.iter_mut() {
+        let parsed = changed.filename.as_str();
+
+        let Some(file) = files.iter().find(|file| file.filename == parsed) else {
+            if !files.is_empty() {
+                warn!(path = %parsed, "Changed file is not in the pull request file list");
+            }
+            continue;
+        };
+
+        changed.filename = file.filename.clone();
+    }
+}
+
+/// Renders the changes for the model: the files the pull request touches, then
+/// the lines to review per file.
+fn format_changes(files: &[PullRequestFile], changed_lines: &ChangedLines) -> String {
+    let mut sections = Vec::new();
+
+    if !files.is_empty() {
+        let described = files
+            .iter()
+            .map(describe_file)
+            .collect::<Vec<_>>()
+            .join(", ");
+
+        sections.push(format!("Files changed by the pull request: {described}"));
+    }
+
+    sections.push(format!(
+        "Lines to review, per file:\n{}",
+        format_changed_lines(changed_lines)
+    ));
+
+    sections.join("\n\n")
+}
+
+/// Describes a changed file for the model, including how it changed.
+fn describe_file(file: &PullRequestFile) -> String {
+    match &file.previous_filename {
+        Some(previous) => format!("{} ({} from {})", file.filename, file.status, previous),
+        None => format!("{} ({})", file.filename, file.status),
+    }
+}
+
+/// Borrows the entry of `files` for a file, creating it on its first change.
+fn changed_file<'a>(files: &'a mut ChangedLines, filename: &str) -> &'a mut ChangedFile {
+    let index = match files.iter().position(|file| file.filename == filename) {
+        Some(index) => index,
+        None => {
+            files.push(ChangedFile::new(filename));
+            files.len() - 1
+        }
+    };
+
+    &mut files[index]
+}
+
+/// Renders the changed lines as `filename: added 1, 2 / removed 3`, one file per
+/// line, keeping only the sides the file actually has.
+fn format_changed_lines(changed_lines: &ChangedLines) -> String {
+    changed_lines
+        .iter()
+        .map(|file| {
+            let mut sides = Vec::new();
+
+            for (label, lines) in [("added", &file.added), ("removed", &file.removed)] {
+                if !lines.is_empty() {
+                    sides.push(format!("{label} {}", format_line_numbers(lines)));
+                }
+            }
+
+            format!("{}: {}", file.filename, sides.join(" / "))
+        })
+        .collect::<Vec<_>>()
+        .join("\n")
+}
+
+fn format_line_numbers(lines: &[u64]) -> String {
+    lines
+        .iter()
+        .map(u64::to_string)
+        .collect::<Vec<_>>()
+        .join(", ")
+}
+
+/// Resolves the side each review is anchored on and drops the reviews that do
+/// not match a line the pull request changes.
+///
+/// The model is asked to pick a line and a side from the provided lists, but
+/// nothing forces it to, and Gitea accepts any position: a wrong one places the
+/// comment on an unrelated line of the file instead of failing. A review that
+/// omits its side is resolved from the lists, and one that matches no changed
+/// line is dropped.
+fn resolve_review_sides(review_result: &mut ReviewResult, changed_lines: &ChangedLines) {
+    let mut dropped = Vec::new();
+
+    review_result.reviews.retain_mut(|review| {
+        let side = review.line.and_then(|line| {
+            let file = changed_lines
+                .iter()
+                .find(|file| file.filename == review.filename)?;
+
+            let side = review.side.or_else(|| file.side_of(line))?;
+
+            file.lines(side).contains(&line).then_some(side)
+        });
+
+        match side {
+            Some(side) => {
+                review.side = Some(side);
+                true
+            }
+            None => {
+                dropped.push(match review.line {
+                    Some(line) => format!("{}:{line}", review.filename),
+                    None => format!("{}:no line", review.filename),
+                });
+                false
+            }
+        }
+    });
+
+    if !dropped.is_empty() {
+        warn!(
+            dropped = dropped.len(),
+            reviews = %dropped.join(", "),
+            "Dropped reviews that are not anchored on a changed line"
+        );
+    }
+}
+
+/// Extracts the old and new starting line numbers of a hunk header such as
+/// `@@ -12,3 +12,5 @@`. The counts are optional and git may append a section
+/// heading after the closing `@@`.
+fn parse_hunk_starts(hunk_header: &str) -> Option<(u64, u64)> {
+    let body = hunk_header.strip_prefix("@@ ")?;
+    let body = body.split(" @@").next()?;
+
+    let (old, new) = body.split_once(" +")?;
+    let old = old.strip_prefix('-')?.split(',').next()?;
+    let new = new.split(',').next()?;
+
+    Some((old.parse().ok()?, new.parse().ok()?))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::bot::ReviewItem;
+
+    /// Additions, a removal and a line changed on both sides.
+    const DIFF: &str = concat!(
+        "diff --git a/src/foo.rs b/src/foo.rs\n",
+        "--- a/src/foo.rs\n",
+        "+++ b/src/foo.rs\n",
+        "@@ -1,4 +1,6 @@\n",
+        " fn main() {\n",
+        "+    let x = 1;\n",
+        "-    let removed = 0;\n",
+        "     println!(\"hello\");\n",
+        "+    let y = 2;\n",
+        "+    let z = 3;\n",
+        " }\n",
+        "diff --git a/src/bar.rs b/src/bar.rs\n",
+        "--- a/src/bar.rs\n",
+        "+++ b/src/bar.rs\n",
+        "@@ -10,4 +10,6 @@\n",
+        " old context\n",
+        "+    let a = 10;\n",
+        " more context\n",
+        "+    let b = 20;\n",
+    );
+
+    /// A pull request that only deletes a file.
+    const DELETION_ONLY: &str = concat!(
+        "diff --git a/src/old.rs b/src/old.rs\n",
+        "deleted file mode 100644\n",
+        "--- a/src/old.rs\n",
+        "+++ /dev/null\n",
+        "@@ -1,3 +0,0 @@\n",
+        "-fn a() {}\n",
+        "-fn b() {}\n",
+        "-fn c() {}\n",
+    );
+
+    /// A hunk whose content starts with `+++` / `---`, which must not be taken
+    /// for the file headers.
+    const TRICKY_CONTENT: &str = concat!(
+        "diff --git a/src/tricky.js b/src/tricky.js\n",
+        "--- a/src/tricky.js\n",
+        "+++ b/src/tricky.js\n",
+        "@@ -1,4 +1,4 @@\n",
+        " let i = 0;\n",
+        "+++i;\n",
+        "---x;\n",
+        " console.log(i);\n",
+    );
+
+    /// A pull request that renames a file.
+    const RENAMED: &str = concat!(
+        "diff --git a/src/old.rs b/src/new.rs\n",
+        "similarity index 50%\n",
+        "rename from src/old.rs\n",
+        "rename to src/new.rs\n",
+        "--- a/src/old.rs\n",
+        "+++ b/src/new.rs\n",
+        "@@ -1,1 +1,1 @@\n",
+        "-fn old() {}\n",
+        "+fn new() {}\n",
+    );
+
+    /// A file whose path contains a space, which the `diff --git` line cannot
+    /// express without ambiguity.
+    const PATH_WITH_SPACE: &str = concat!(
+        "diff --git a/src/my file.rs b/src/my file.rs\n",
+        "--- a/src/my file.rs\n",
+        "+++ b/src/my file.rs\n",
+        "@@ -1,1 +1,2 @@\n",
+        " fn a() {}\n",
+        "+fn b() {}\n",
+    );
+
+    /// A file whose path git quotes and escapes (`caf\\303\\251.md` is
+    /// `caf\u{e9}.md`).
+    const QUOTED_PATH: &str = concat!(
+        "diff --git \"a/docs/caf\\303\\251.md\" \"b/docs/caf\\303\\251.md\"\n",
+        "--- \"a/docs/caf\\303\\251.md\"\n",
+        "+++ \"b/docs/caf\\303\\251.md\"\n",
+        "@@ -1,1 +1,2 @@\n",
+        " intro\n",
+        "+ajout\n",
+    );
+
+    fn review(filename: &str, line: Option<u64>, side: Option<ReviewSide>) -> ReviewItem {
+        ReviewItem {
+            filename: String::from(filename),
+            line,
+            side,
+            message: String::from("message"),
+        }
+    }
+
+    fn review_result(reviews: Vec<ReviewItem>) -> ReviewResult {
+        ReviewResult {
+            reviews,
+            comment: String::new(),
+            cost: None,
+        }
+    }
+
+    fn pull_request_file(
+        filename: &str,
+        previous_filename: Option<&str>,
+        status: &str,
+    ) -> PullRequestFile {
+        PullRequestFile {
+            filename: String::from(filename),
+            previous_filename: previous_filename.map(String::from),
+            status: String::from(status),
+        }
+    }
+
+    #[test]
+    fn changed_lines_are_listed_per_file_and_side() {
+        let expected = concat!(
+            "src/foo.rs: added 2, 4, 5 / removed 2\n",
+            "src/bar.rs: added 11, 13"
+        );
+
+        assert_eq!(format_changed_lines(&parse_changed_lines(DIFF)), expected);
+    }
+
+    #[test]
+    fn a_deletion_only_pull_request_lists_removed_lines() {
+        let expected = "src/old.rs: removed 1, 2, 3";
+
+        assert_eq!(
+            format_changed_lines(&parse_changed_lines(DELETION_ONLY)),
+            expected
+        );
+    }
+
+    #[test]
+    fn hunk_content_starting_with_plus_or_minus_is_counted() {
+        let expected = "src/tricky.js: added 2 / removed 2";
+
+        assert_eq!(
+            format_changed_lines(&parse_changed_lines(TRICKY_CONTENT)),
+            expected
+        );
+    }
+
+    #[test]
+    fn a_renamed_file_uses_its_new_path() {
+        let expected = "src/new.rs: added 1 / removed 1";
+
+        assert_eq!(
+            format_changed_lines(&parse_changed_lines(RENAMED)),
+            expected
+        );
+    }
+
+    #[test]
+    fn a_path_with_a_space_is_read_from_the_headers() {
+        let expected = "src/my file.rs: added 2";
+
+        assert_eq!(
+            format_changed_lines(&parse_changed_lines(PATH_WITH_SPACE)),
+            expected
+        );
+    }
+
+    #[test]
+    fn a_quoted_path_is_decoded() {
+        let expected = "docs/café.md: added 2";
+
+        assert_eq!(
+            format_changed_lines(&parse_changed_lines(QUOTED_PATH)),
+            expected
+        );
+    }
+
+    #[test]
+    fn filenames_are_resolved_against_the_api_list() {
+        let mut changed_lines = parse_changed_lines(DIFF);
+        let files = vec![
+            pull_request_file("src/bar.rs", None, "modified"),
+            pull_request_file("src/foo.rs", Some("src/renamed.rs"), "renamed"),
+        ];
+
+        resolve_filenames(&mut changed_lines, &files);
+
+        assert_eq!(changed_lines[0].filename, "src/foo.rs");
+        assert_eq!(changed_lines[1].filename, "src/bar.rs");
+    }
+
+    #[test]
+    fn a_file_absent_from_the_api_list_keeps_the_diff_path() {
+        let mut changed_lines = parse_changed_lines(DIFF);
+        let files = vec![pull_request_file("src/bar.rs", None, "modified")];
+
+        resolve_filenames(&mut changed_lines, &files);
+
+        assert_eq!(changed_lines[0].filename, "src/foo.rs");
+        assert_eq!(changed_lines[1].filename, "src/bar.rs");
+    }
+
+    #[test]
+    fn changes_describe_the_files_then_the_lines() {
+        let changed_lines = parse_changed_lines(DELETION_ONLY);
+        let files = vec![pull_request_file("src/old.rs", None, "deleted")];
+
+        let expected = concat!(
+            "Files changed by the pull request: src/old.rs (deleted)\n",
+            "\n",
+            "Lines to review, per file:\n",
+            "src/old.rs: removed 1, 2, 3"
+        );
+
+        assert_eq!(format_changes(&files, &changed_lines), expected);
+    }
+
+    #[test]
+    fn changes_without_the_api_list_only_hold_the_lines() {
+        let changed_lines = parse_changed_lines(DELETION_ONLY);
+
+        let expected = "Lines to review, per file:\nsrc/old.rs: removed 1, 2, 3";
+
+        assert_eq!(format_changes(&[], &changed_lines), expected);
+    }
+
+    #[test]
+    fn a_renamed_file_is_described_with_its_previous_path() {
+        let file = pull_request_file("src/new.rs", Some("src/old.rs"), "renamed");
+
+        assert_eq!(describe_file(&file), "src/new.rs (renamed from src/old.rs)");
+    }
+
+    #[test]
+    fn reviews_keep_their_changed_line_and_resolve_their_side() {
+        let changed_lines = parse_changed_lines(DIFF);
+        let mut review_result = review_result(vec![
+            review("src/foo.rs", Some(4), Some(ReviewSide::Added)),
+            review("src/foo.rs", Some(2), Some(ReviewSide::Removed)),
+            review("src/bar.rs", Some(13), None),
+        ]);
+
+        resolve_review_sides(&mut review_result, &changed_lines);
+
+        let sides = review_result
+            .reviews
+            .iter()
+            .map(|review| review.side)
+            .collect::<Vec<_>>();
+
+        assert_eq!(
+            sides,
+            vec![
+                Some(ReviewSide::Added),
+                Some(ReviewSide::Removed),
+                Some(ReviewSide::Added)
+            ]
+        );
+    }
+
+    #[test]
+    fn a_line_changed_on_both_sides_defaults_to_added() {
+        let changed_lines = parse_changed_lines(DIFF);
+        let mut review_result = review_result(vec![review("src/foo.rs", Some(2), None)]);
+
+        resolve_review_sides(&mut review_result, &changed_lines);
+
+        assert_eq!(review_result.reviews[0].side, Some(ReviewSide::Added));
+    }
+
+    #[test]
+    fn reviews_outside_changed_lines_are_dropped() {
+        let changed_lines = parse_changed_lines(DIFF);
+        let mut review_result = review_result(vec![
+            // valid
+            review("src/foo.rs", Some(2), Some(ReviewSide::Added)),
+            // a line that exists but is not part of the change
+            review("src/foo.rs", Some(3), None),
+            // a line beyond the change
+            review("src/foo.rs", Some(999), None),
+            // a changed line, but on the wrong side
+            review("src/foo.rs", Some(4), Some(ReviewSide::Removed)),
+            // a line changed in another file
+            review("src/foo.rs", Some(11), None),
+            // an unknown file
+            review("src/baz.rs", Some(1), None),
+            // no line at all
+            review("src/bar.rs", None, None),
+        ]);
+
+        resolve_review_sides(&mut review_result, &changed_lines);
+
+        assert_eq!(review_result.reviews.len(), 1);
+        assert_eq!(review_result.reviews[0].filename, "src/foo.rs");
+        assert_eq!(review_result.reviews[0].line, Some(2));
+        assert_eq!(review_result.reviews[0].side, Some(ReviewSide::Added));
+    }
+
+    #[test]
+    fn a_deleted_line_is_kept_as_a_removed_anchor() {
+        let changed_lines = parse_changed_lines(DELETION_ONLY);
+        let mut review_result = review_result(vec![
+            review("src/old.rs", Some(2), Some(ReviewSide::Removed)),
+            review("src/old.rs", Some(2), Some(ReviewSide::Added)),
+        ]);
+
+        resolve_review_sides(&mut review_result, &changed_lines);
+
+        assert_eq!(review_result.reviews.len(), 1);
+        assert_eq!(review_result.reviews[0].side, Some(ReviewSide::Removed));
+    }
+
+    #[test]
+    fn odd_sides_from_the_model_are_tolerated() {
+        let changed_lines = parse_changed_lines(DIFF);
+        let mut review_result: ReviewResult = serde_json::from_str(
+            r#"{
+                "reviews": [
+                    { "filename": "src/foo.rs", "line": 4, "side": "Added", "message": "a" },
+                    { "filename": "src/foo.rs", "line": 2, "side": "new", "message": "b" },
+                    { "filename": "src/foo.rs", "line": 2, "side": "REMOVED", "message": "c" },
+                    { "filename": "src/foo.rs", "line": 2, "side": "banana", "message": "d" },
+                    { "filename": "src/foo.rs", "line": 5, "message": "e" }
+                ],
+                "comment": ""
+            }"#,
+        )
+        .unwrap();
+
+        resolve_review_sides(&mut review_result, &changed_lines);
+
+        let sides = review_result
+            .reviews
+            .iter()
+            .map(|review| review.side)
+            .collect::<Vec<_>>();
+
+        assert_eq!(
+            sides,
+            vec![
+                Some(ReviewSide::Added),
+                Some(ReviewSide::Added),
+                Some(ReviewSide::Removed),
+                Some(ReviewSide::Added),
+                Some(ReviewSide::Added)
+            ]
+        );
+    }
+}

crates/herald-server/src/consts.rs

@@ -0,0 +1,58 @@
+pub const GITEA_SIG_HEADER_NAME: &str = "x-gitea-signature";
+pub const GITEA_EVENT_TYPE_HEADER_NAME: &str = "x-gitea-event-type";
+
+pub const MAX_WEBHOOK_BODY_SIZE: usize = 1024 * 1024; // 1 MiB
+pub const MAX_DIFF_SIZE: usize = 1024 * 1024; // 1 MiB
+
+pub const BOT_PROCESS_MSG: &str = "
+    Review in progress with the model \"{model}\"...
+";
+
+pub const SANDBOX_SYSTEM_PROMPT: &str = "
+    You are a senior software engineer reviewing a pull request.
+
+    The repository is checked out in your working directory. Use the provided
+    tools (ls, read_file, grep, find) to explore the code and gather the context
+    you need before answering. Paths are relative to the repository root.
+
+    When you have enough information, answer with the requested JSON only.
+";
+
+pub const REVIEW_PROMPT: &str = "
+    You are a senior software engineer reviewing code changes.
+
+    Check good practices and code quality.
+
+    This is the pull request subject: \"{subject}\"
+
+    This is the user comment: \"{comment}\"
+
+    The pull request changes these files and lines:
+
+    {changes}
+
+    `added` line numbers refer to the new version of the file, `removed` line
+    numbers to the old version, as they appear in the diff.
+
+    The code is not provided: read the files you need with the available tools
+    before answering. Review only the listed lines.
+
+    Return your feedback, in french, with only this json format, reviews must contain each review
+    All fields are mandatory.
+    (filename field must contain the full path with extension; line must be one of the
+    listed line numbers for that file, and side must be \"added\" when the line comes
+    from the `added` list or \"removed\" when it comes from the `removed` list)
+    and comment must contain a final summary:
+
+    {
+        \"reviews\": [
+            {
+                \"filename\": \"\",
+                \"line\": ,
+                \"side\": \"\",
+                \"message\": \"\"
+            }
+        ],
+        \"comment\": \"\"
+    }
+";

crates/herald-server/src/env.rs

@@ -7,16 +7,17 @@ pub struct EnvConfig {
     pub open_router_api_key: String,
     pub open_router_model: String,
     pub open_router_timeout: u64,
-    pub bot_name: String,
     pub bot_max_concurrent: usize,
     pub gitea_url: String,
     pub gitea_token: String,
     pub gitea_timeout: u64,
+    pub metrics_bind_addr: Option<String>,
+    pub container_runtime: String,
+    pub sandbox_max_iterations: usize,
 }
 
 pub fn load_config() -> anyhow::Result<EnvConfig> {
     let http_port = try_get_env("HTTP_PORT")?.parse()?;
-    let bot_name = try_get_env("BOT_NAME")?;
     let webhook_secret = try_get_env("WEBHOOK_SIG_HEADER_SECRET")?;
     let open_router_api_key = try_get_env("OPEN_ROUTER_API_KEY")?;
     let open_router_model = try_get_env("OPEN_ROUTER_MODEL")?;
@@ -25,11 +26,17 @@ pub fn load_config() -> anyhow::Result<EnvConfig> {
     let gitea_url = try_get_env("GITEA_URL")?;
     let gitea_token = try_get_env("GITEA_TOKEN")?;
     let gitea_timeout = try_get_env("GITEA_TIMEOUT")?.parse()?;
+    let metrics_bind_addr = std::env::var("METRICS_BIND_ADDR").ok();
+    let container_runtime =
+        std::env::var("CONTAINER_RUNTIME").unwrap_or_else(|_| "docker".to_string());
+    let sandbox_max_iterations = std::env::var("SANDBOX_MAX_ITERATIONS")
+        .ok()
+        .and_then(|value| value.parse().ok())
+        .unwrap_or(8);
 
     Ok(EnvConfig {
         http_port,
         webhook_secret,
-        bot_name,
         open_router_api_key,
         open_router_model,
         open_router_timeout,
@@ -37,6 +44,9 @@ pub fn load_config() -> anyhow::Result<EnvConfig> {
         gitea_url,
         gitea_token,
         gitea_timeout,
+        metrics_bind_addr,
+        container_runtime,
+        sandbox_max_iterations,
     })
 }
 

crates/herald-server/src/gitea.rs

@@ -1,14 +1,28 @@
 use std::time::Duration;
 
+use futures_util::stream::TryStreamExt;
 use serde::Deserialize;
 use serde_json::{Value, json};
-use tracing::instrument;
+use tokio::io::AsyncReadExt;
+use tokio_util::io::StreamReader;
+use tracing::{instrument, warn};
 
-use crate::{bot::ReviewResult, errors::AppError};
+use crate::{
+    bot::{ReviewResult, ReviewSide},
+    consts::MAX_DIFF_SIZE,
+    errors::AppError,
+};
+
+/// Page size requested when listing the files of a pull request.
+const FILE_PAGE_SIZE: u64 = 50;
+
+/// Maximum number of pages fetched for a pull request file list.
+const MAX_FILE_PAGES: u64 = 10;
 
 #[derive(Clone)]
 pub struct GiteaAPI {
     base_url: String,
+    token: String,
     client: reqwest::Client,
 }
 
@@ -22,6 +36,7 @@ impl GiteaAPI {
 
         Ok(Self {
             base_url: String::from(base_url),
+            token: String::from(token),
             client: reqwest::Client::builder()
                 .timeout(Duration::from_secs(timeout))
                 .default_headers(default_headers)
@@ -29,6 +44,35 @@ impl GiteaAPI {
         })
     }
 
+    /// API token used to authenticate against Gitea.
+    pub fn token(&self) -> &str {
+        &self.token
+    }
+
+    /// HTTPS clone URL for a repository, suitable for `git clone`.
+    pub fn repo_clone_url(&self, full_name: &str) -> String {
+        format!(
+            "{}/{}.git",
+            self.base_url.trim_end_matches('/'),
+            full_name.trim_start_matches('/')
+        )
+    }
+
+    #[instrument(skip(self))]
+    pub async fn get_authorized_user(&self) -> anyhow::Result<User> {
+        let url = format!("{}/api/v1/user", self.base_url);
+        let res = self.client.get(url).send().await?;
+
+        if !res.status().is_success() {
+            return Err(anyhow::anyhow!(
+                "Failed to get authorized user: {}",
+                res.status()
+            ));
+        }
+
+        res.json::<User>().await.map_err(anyhow::Error::from)
+    }
+
     #[instrument(skip(self))]
     pub async fn comment(
         &self,
@@ -104,6 +148,70 @@ impl GiteaAPI {
         Ok(())
     }
 
+    /// Raw unified diff of a pull request.
+    ///
+    /// The API endpoint is used rather than the `diff_url` carried by the
+    /// webhook: that one points at a web route, which is session authenticated
+    /// and therefore does not serve private repositories to an API token.
+    #[instrument(skip(self))]
+    pub async fn pull_request_diff(&self, full_name: &str, index: u64) -> anyhow::Result<String> {
+        let url = format!(
+            "{}/api/v1/repos/{}/pulls/{}.diff",
+            self.base_url, full_name, index
+        );
+
+        let res = self.client.get(url).send().await?;
+
+        if !res.status().is_success() {
+            return Err(anyhow::anyhow!(
+                "Failed to download pull request diff: {}",
+                res.status()
+            ));
+        }
+
+        read_capped(res).await
+    }
+
+    /// Files changed by a pull request, with their exact path and status.
+    #[instrument(skip(self))]
+    pub async fn pull_request_files(
+        &self,
+        full_name: &str,
+        index: u64,
+    ) -> anyhow::Result<Vec<PullRequestFile>> {
+        let mut files = Vec::new();
+
+        for page in 1..=MAX_FILE_PAGES {
+            let url = format!(
+                "{}/api/v1/repos/{}/pulls/{}/files?limit={FILE_PAGE_SIZE}&page={page}",
+                self.base_url, full_name, index
+            );
+
+            let res = self.client.get(url).send().await?;
+
+            if !res.status().is_success() {
+                return Err(anyhow::anyhow!(
+                    "Failed to list pull request files: {}",
+                    res.status()
+                ));
+            }
+
+            let page_files = res.json::<Vec<PullRequestFile>>().await?;
+
+            // The instance may cap the page size below the requested one, so a
+            // short page is not the end of the list: an empty one is.
+            if page_files.is_empty() {
+                return Ok(files);
+            }
+
+            files.extend(page_files);
+        }
+
+        warn!(files = files.len(), "Pull request file list was truncated");
+
+        Ok(files)
+    }
+
     #[instrument(skip(self, review_result))]
     pub async fn post_pull_request_review(
         &self,
@@ -117,19 +225,27 @@ impl GiteaAPI {
             self.base_url, full_name, index
         );
 
-        let comments = &review_result
+        let comments = review_result
             .reviews
             .iter()
-            .filter(|r| r.line.is_some())
-            .map(|r| {
-                let path = r.filename.clone();
-                let line = r.line.unwrap_or(0);
-                let body = r.message.clone();
+            .filter_map(|review| {
+                let line = review.line?;
+                let path = review.filename.clone();
+                let body = review.message.clone();
 
-                json!({
+                // A line removed by the pull request only exists in the old
+                // version of the file, so it is anchored with `old_position`.
+                Some(match review.side {
+                    Some(ReviewSide::Removed) => json!({
+                        "path": path,
+                        "old_position": line,
+                        "body": body
+                    }),
+                    _ => json!({
                         "path": path,
                         "new_position": line,
                         "body": body
+                    }),
                 })
             })
             .collect::<Vec<_>>();
@@ -153,6 +269,23 @@ impl GiteaAPI {
     }
 }
 
+/// Reads a response body, refusing to buffer more than [`MAX_DIFF_SIZE`].
+async fn read_capped(response: reqwest::Response) -> anyhow::Result<String> {
+    let stream = response.bytes_stream().map_err(std::io::Error::other);
+
+    let mut buf = Vec::with_capacity(MAX_DIFF_SIZE);
+    StreamReader::new(stream)
+        .take((MAX_DIFF_SIZE + 1) as u64)
+        .read_to_end(&mut buf)
+        .await?;
+
+    if buf.len() > MAX_DIFF_SIZE {
+        anyhow::bail!("Pull request diff exceeds the maximum allowed size of 1 MiB");
+    }
+
+    Ok(String::from_utf8_lossy(&buf).into_owned())
+}
+
 #[derive(Debug)]
 pub enum WebhookType {
     Review(ReviewPayload),
@@ -164,6 +297,12 @@ impl WebhookType {
             WebhookType::Review(payload) => payload.comment.id,
         }
     }
+
+    pub fn event_type_str(&self) -> &'static str {
+        match self {
+            WebhookType::Review(_) => "review",
+        }
+    }
 }
 
 #[derive(Deserialize, Debug)]
@@ -176,8 +315,6 @@ pub struct ReviewPayload {
 
 #[derive(Deserialize, Debug)]
 pub struct PullRequest {
-    pub id: u64,
-    pub diff_url: String,
     pub number: u64,
     pub title: String,
 }
@@ -186,12 +323,11 @@ pub struct PullRequest {
 pub struct Comment {
     pub id: u64,
     pub body: String,
-    pub user: User,
 }
 
 #[derive(Deserialize, Debug)]
 pub struct User {
-    pub id: u64,
+    pub login: String,
 }
 
 #[derive(Deserialize, Debug)]
@@ -199,6 +335,18 @@ pub struct Repository {
     pub full_name: String,
 }
 
+/// A file changed by a pull request, as reported by the API.
+#[derive(Deserialize, Debug)]
+pub struct PullRequestFile {
+    /// Path of the file in the new version of the repository.
+    pub filename: String,
+    /// Previous path, for a renamed file.
+    #[serde(default)]
+    pub previous_filename: Option<String>,
+    /// `added`, `modified`, `deleted`, `renamed`…
+    pub status: String,
+}
+
 impl WebhookType {
     pub fn from_event(event: &str, bot_name: &str, json: Value) -> Result<Self, AppError> {
         let wb = match event {
@@ -248,7 +396,8 @@ mod tests {
                 "id": 7,
                 "body": "@test_bot LGTM",
                 "user": {
-                    "id": 100
+                    "id": 100,
+                    "login": "test_user"
                 }
             }
         });
@@ -259,10 +408,8 @@ mod tests {
         match result.unwrap() {
             WebhookType::Review(payload) => {
                 assert_eq!(payload.action, "created");
-                assert_eq!(payload.pull_request.id, 42);
                 assert_eq!(payload.comment.id, 7);
                 assert_eq!(payload.comment.body, "@test_bot LGTM");
-                assert_eq!(payload.comment.user.id, 100);
             }
         }
     }
@@ -312,7 +459,8 @@ mod tests {
                 "id": 1,
                 "body": "@test_bot body",
                 "user": {
-                    "id": 1
+                    "id": 1,
+                    "login": "test_user"
                 }
             }
         });
@@ -343,17 +491,16 @@ mod tests {
                 "id": 12,
                 "body": "Needs work",
                 "user": {
-                    "id": 200
+                    "id": 200,
+                    "login": "test_user"
                 }
             }
         });
 
         let payload: ReviewPayload = serde_json::from_value(json).unwrap();
         assert_eq!(payload.action, "created");
-        assert_eq!(payload.pull_request.id, 99);
         assert_eq!(payload.comment.id, 12);
         assert_eq!(payload.comment.body, "Needs work");
-        assert_eq!(payload.comment.user.id, 200);
     }
 
     #[test]
@@ -380,7 +527,8 @@ mod tests {
                 "id": 1,
                 "body": "@other_bot do something",
                 "user": {
-                    "id": 1
+                    "id": 1,
+                    "login": "test_user"
                 }
             }
         });
@@ -406,7 +554,8 @@ mod tests {
                 "id": 1,
                 "body": "just a comment without bot mention",
                 "user": {
-                    "id": 1
+                    "id": 1,
+                    "login": "test_user"
                 }
             }
         });

crates/herald-server/src/main.rs

@@ -1,6 +1,10 @@
-use std::sync::Arc;
-
-use crate::{bot::Bot, gitea::WebhookType, state::AppState};
+use crate::{
+    bot::Bot,
+    gitea::{GiteaAPI, WebhookType},
+    open_router::OpenRouterClient,
+    sandbox::SandboxConfig,
+    state::AppState,
+};
 
 use dotenvy::dotenv;
 use tokio::signal::unix::{SignalKind, signal};
@@ -15,7 +19,9 @@ mod consts;
 mod env;
 mod errors;
 mod gitea;
+mod metrics;
 mod open_router;
+mod sandbox;
 mod state;
 
 fn main() -> anyhow::Result<()> {
@@ -32,14 +38,12 @@ fn main() -> anyhow::Result<()> {
     let _sentry_guard = if let Ok(sentry_dsn) = env::try_get_env("SENTRY_DSN") {
         info!("Initialize sentry");
 
-        Some(sentry::init((
-            sentry_dsn,
-            sentry::ClientOptions {
-                release: sentry::release_name!(),
-                send_default_pii: true,
-                ..Default::default()
-            },
-        )))
+        Some(sentry::init(
+            sentry::ClientOptions::new()
+                .dsn(&sentry_dsn)
+                .maybe_release(sentry::release_name!())
+                .send_default_pii(true),
+        ))
     } else {
         warn!("SENTRY_DSN not set, sentry will not be initialized");
         None
@@ -51,17 +55,50 @@ fn main() -> anyhow::Result<()> {
 async fn run() -> anyhow::Result<()> {
     let config = env::load_config()?;
 
+    if let Some(metric_bind_addr) = &config.metrics_bind_addr {
+        metrics::install(metric_bind_addr)?;
+    }
+
+    let gitea_api = GiteaAPI::new(&config.gitea_url, &config.gitea_token, config.gitea_timeout)?;
+    let gitea_user = gitea_api.get_authorized_user().await?;
+
     info!(
         port = config.http_port,
         model = %config.open_router_model,
         gitea_url = %config.gitea_url,
-        bot_name = %config.bot_name,
+        bot_name = %gitea_user.login,
         "Starting Herald"
     );
 
+    let open_router_client = OpenRouterClient::new(
+        &config.open_router_api_key,
+        &config.open_router_model,
+        config.open_router_timeout,
+    )?;
+
     let shutdown = CancellationToken::new();
 
-    let bot = Bot::new(config.clone())?;
+    let sandbox = SandboxConfig {
+        runtime: devcontainer_rs::ContainerRuntime::new(config.container_runtime.clone()),
+        max_iterations: config.sandbox_max_iterations,
+    };
+
+    if !sandbox.runtime.available().await {
+        warn!(
+            runtime = sandbox.runtime.program(),
+            "Container runtime is not available, every review will fail"
+        );
+    }
+
+    let bot = Bot::new(
+        gitea_user.login,
+        gitea_api,
+        open_router_client,
+        config.bot_max_concurrent,
+        config.open_router_model.clone(),
+        sandbox,
+    );
+
     let (tx, rx) = tokio::sync::mpsc::channel::<WebhookType>(config.bot_max_concurrent * 2);
     let app_state = AppState {
         bot_tx: tx,

crates/herald-server/src/metrics.rs

@@ -0,0 +1,88 @@
+use std::{net::SocketAddr, str::FromStr};
+
+use metrics::{Unit, counter, describe_counter, describe_gauge, gauge};
+
+pub fn webhook_received(event_type: &str) {
+    counter!("herald_webhooks_received_total", "event_type" => event_type.to_string()).increment(1);
+}
+
+pub fn webhook_duplicate(event_type: &str) {
+    counter!("herald_webhooks_duplicate_total", "event_type" => event_type.to_string())
+        .increment(1);
+}
+
+pub fn webhook_channel_full(event_type: &str) {
+    counter!("herald_webhooks_channel_full_total", "event_type" => event_type.to_string())
+        .increment(1);
+}
+
+pub fn increment_task_active() {
+    gauge!("herald_bot_tasks_active").increment(1.0);
+}
+
+pub fn decrement_task_active() {
+    gauge!("herald_bot_tasks_active").decrement(1.0);
+}
+
+pub fn task_completed(event_type: &str) {
+    counter!("herald_bot_tasks_completed_total", "event_type" => event_type.to_string())
+        .increment(1);
+}
+
+pub fn task_failed(event_type: &str) {
+    counter!("herald_bot_tasks_failed_total", "event_type" => event_type.to_string()).increment(1);
+}
+
+pub fn openrouter_cost_usd(cost: f64) {
+    counter!("herald_openrouter_cost_cents_total").increment((cost * 100.0).round() as u64);
+}
+
+pub fn describe() {
+    describe_counter!(
+        "herald_webhooks_received_total",
+        Unit::Count,
+        "Total webhooks received"
+    );
+    describe_counter!(
+        "herald_webhooks_duplicate_total",
+        Unit::Count,
+        "Webhooks rejected as duplicates"
+    );
+    describe_counter!(
+        "herald_webhooks_channel_full_total",
+        Unit::Count,
+        "Webhooks dropped because the bot channel was full"
+    );
+    describe_gauge!(
+        "herald_bot_tasks_active",
+        Unit::Count,
+        "Bot tasks currently in progress"
+    );
+    describe_counter!(
+        "herald_bot_tasks_completed_total",
+        Unit::Count,
+        "Bot tasks completed successfully"
+    );
+    describe_counter!(
+        "herald_bot_tasks_failed_total",
+        Unit::Count,
+        "Bot tasks that failed"
+    );
+    describe_counter!(
+        "herald_openrouter_cost_cents_total",
+        Unit::Count,
+        "Total OpenRouter cost in cents (divide by 100 for USD)"
+    );
+}
+
+pub fn install(bind_addr: &str) -> anyhow::Result<()> {
+    describe();
+
+    let builder = metrics_exporter_prometheus::PrometheusBuilder::new();
+    builder
+        .with_http_listener(SocketAddr::from_str(bind_addr)?)
+        .install()?;
+
+    tracing::info!(bind_addr, "Prometheus metrics exporter installed");
+    Ok(())
+}

crates/herald-server/src/open_router.rs

@@ -0,0 +1,441 @@
+//! Minimal OpenRouter chat-completions client.
+//!
+//! Herald only needs a non-streaming `POST /chat/completions` with optional
+//! tool calling, so the wire types are implemented in-tree instead of pulling a
+//! third-party SDK (and its own `reqwest` version) into the workspace.
+//!
+//! Only the response fields Herald consumes are modelled: `content`,
+//! `tool_calls` and `usage.cost`. Unknown fields are ignored.
+
+use std::time::Duration;
+
+use anyhow::Context;
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use tracing::instrument;
+
+/// OpenRouter API root, version prefix included.
+const BASE_URL: &str = "https://openrouter.ai/api/v1";
+
+/// The model decides on its own which tool to call.
+const TOOL_CHOICE_AUTO: &str = "auto";
+
+/// Result of a completion that may contain tool calls.
+pub struct ToolChatResult {
+    pub message: Option<String>,
+    pub tool_calls: Vec<ToolCall>,
+    pub cost: Option<f64>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
+#[serde(rename_all = "lowercase")]
+pub enum Role {
+    System,
+    User,
+    Assistant,
+    Tool,
+}
+
+/// A single turn of the conversation.
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct Message {
+    pub role: Role,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub content: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub tool_calls: Option<Vec<ToolCall>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub tool_call_id: Option<String>,
+}
+
+impl Message {
+    pub fn new(role: Role, content: impl Into<String>) -> Self {
+        Self {
+            role,
+            content: Some(content.into()),
+            tool_calls: None,
+            tool_call_id: None,
+        }
+    }
+
+    /// Assistant turn requesting tool calls. Models often answer with tool
+    /// calls but no text, in which case the content is sent as `null`.
+    pub fn assistant_with_tool_calls(
+        content: impl Into<String>,
+        tool_calls: Vec<ToolCall>,
+    ) -> Self {
+        let content = content.into();
+
+        Self {
+            role: Role::Assistant,
+            content: (!content.is_empty()).then_some(content),
+            tool_calls: Some(tool_calls),
+            tool_call_id: None,
+        }
+    }
+
+    /// Result of a tool call, linked to the request by `tool_call_id`.
+    pub fn tool_response(tool_call_id: impl Into<String>, content: impl Into<String>) -> Self {
+        Self {
+            role: Role::Tool,
+            content: Some(content.into()),
+            tool_calls: None,
+            tool_call_id: Some(tool_call_id.into()),
+        }
+    }
+}
+
+/// A tool the model may call.
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct Tool {
+    #[serde(rename = "type", default = "function_type")]
+    pub kind: String,
+    pub function: FunctionDefinition,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct FunctionDefinition {
+    pub name: String,
+    pub description: String,
+    /// JSON schema describing the accepted arguments.
+    pub parameters: Value,
+}
+
+impl Tool {
+    pub fn new(name: impl Into<String>, description: impl Into<String>, parameters: Value) -> Self {
+        Self {
+            kind: function_type(),
+            function: FunctionDefinition {
+                name: name.into(),
+                description: description.into(),
+                parameters,
+            },
+        }
+    }
+}
+
+/// A tool call requested by the model.
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct ToolCall {
+    pub id: String,
+    #[serde(rename = "type", default = "function_type")]
+    pub kind: String,
+    pub function: FunctionCall,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct FunctionCall {
+    pub name: String,
+    /// Arguments as a JSON-encoded string. Kept verbatim so that echoing the
+    /// call back into the conversation does not re-encode or corrupt it.
+    pub arguments: String,
+}
+
+impl ToolCall {
+    pub fn id(&self) -> &str {
+        &self.id
+    }
+
+    pub fn name(&self) -> &str {
+        &self.function.name
+    }
+
+    pub fn arguments_json(&self) -> &str {
+        &self.function.arguments
+    }
+}
+
+fn function_type() -> String {
+    String::from("function")
+}
+
+#[derive(Serialize)]
+struct ChatRequest<'a> {
+    model: &'a str,
+    messages: &'a [Message],
+    reasoning: Reasoning,
+    tools: &'a [Tool],
+    tool_choice: &'a str,
+}
+
+/// OpenRouter reasoning config; Herald always asks for reasoning.
+#[derive(Serialize)]
+struct Reasoning {
+    enabled: bool,
+}
+
+#[derive(Deserialize)]
+struct ChatResponse {
+    #[serde(default)]
+    choices: Vec<Choice>,
+    #[serde(default)]
+    usage: Option<Usage>,
+}
+
+#[derive(Deserialize)]
+struct Choice {
+    message: ResponseMessage,
+}
+
+#[derive(Deserialize)]
+struct ResponseMessage {
+    #[serde(default)]
+    content: Option<Content>,
+    #[serde(default)]
+    tool_calls: Option<Vec<ToolCall>>,
+}
+
+/// Message content is a plain string for most models and a list of typed parts
+/// for others; both are collapsed to text.
+#[derive(Deserialize)]
+#[serde(untagged)]
+enum Content {
+    Text(String),
+    Parts(Vec<ContentPart>),
+}
+
+#[derive(Deserialize)]
+struct ContentPart {
+    #[serde(default)]
+    text: Option<String>,
+}
+
+impl Content {
+    fn into_text(self) -> String {
+        match self {
+            Self::Text(text) => text,
+            Self::Parts(parts) => parts
+                .into_iter()
+                .filter_map(|part| part.text)
+                .collect::<Vec<_>>()
+                .join(""),
+        }
+    }
+}
+
+#[derive(Deserialize)]
+struct Usage {
+    #[serde(default)]
+    cost: Option<f64>,
+}
+
+/// Error payload returned by OpenRouter for a failed request.
+#[derive(Deserialize)]
+struct ErrorResponse {
+    error: ErrorDetail,
+}
+
+#[derive(Deserialize)]
+struct ErrorDetail {
+    message: String,
+}
+
+#[derive(Clone)]
+pub struct OpenRouterClient {
+    client: reqwest::Client,
+    api_key: String,
+    model: String,
+}
+
+impl OpenRouterClient {
+    pub fn new(token: &str, model: &str, timeout: u64) -> anyhow::Result<Self> {
+        Ok(Self {
+            client: reqwest::Client::builder()
+                .timeout(Duration::from_secs(timeout))
+                .build()?,
+            api_key: String::from(token),
+            model: String::from(model),
+        })
+    }
+
+    /// Sends a conversation with tool definitions and returns either a final
+    /// message or the tool calls requested by the model.
+    #[instrument(skip(self, messages, tools), err)]
+    pub async fn chat_with_tools(
+        &self,
+        messages: Vec<Message>,
+        tools: Vec<Tool>,
+    ) -> anyhow::Result<ToolChatResult> {
+        let response = self.complete(&messages, &tools).await?;
+
+        let cost = response.usage.and_then(|usage| usage.cost);
+        let message = response
+            .choices
+            .into_iter()
+            .next()
+            .ok_or_else(|| anyhow::anyhow!("No choices in response"))?
+            .message;
+
+        Ok(ToolChatResult {
+            message: message.content.map(Content::into_text),
+            tool_calls: message.tool_calls.unwrap_or_default(),
+            cost,
+        })
+    }
+
+    async fn complete(&self, messages: &[Message], tools: &[Tool]) -> anyhow::Result<ChatResponse> {
+        let request = ChatRequest {
+            model: &self.model,
+            messages,
+            reasoning: Reasoning { enabled: true },
+            tools,
+            tool_choice: TOOL_CHOICE_AUTO,
+        };
+
+        let response = self
+            .client
+            .post(format!("{BASE_URL}/chat/completions"))
+            .bearer_auth(&self.api_key)
+            .json(&request)
+            .send()
+            .await
+            .context("failed to reach OpenRouter")?;
+
+        let status = response.status();
+        if !status.is_success() {
+            let body = response.text().await.unwrap_or_default();
+            anyhow::bail!("OpenRouter returned {status}: {}", error_message(&body));
+        }
+
+        response
+            .json::<ChatResponse>()
+            .await
+            .context("invalid OpenRouter response")
+    }
+}
+
+/// Extracts the message from an OpenRouter error body, falling back to the raw
+/// body when it is not the expected JSON shape.
+fn error_message(body: &str) -> String {
+    serde_json::from_str::<ErrorResponse>(body)
+        .map(|response| response.error.message)
+        .unwrap_or_else(|_| body.trim().to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    /// Builds a tool call the way the API returns one, so the fixture also
+    /// covers deserialization.
+    fn tool_call(id: &str, name: &str, arguments: &str) -> ToolCall {
+        serde_json::from_value(json!({
+            "id": id,
+            "type": "function",
+            "function": { "name": name, "arguments": arguments }
+        }))
+        .unwrap()
+    }
+
+    #[test]
+    fn tool_call_arguments_are_kept_verbatim() {
+        let call = tool_call("call_1", "grep", r#"{"pattern":"fn main"}"#);
+        let message = Message::assistant_with_tool_calls("", vec![call]);
+
+        let serialized = serde_json::to_value(&message).unwrap();
+
+        assert_eq!(serialized["content"], Value::Null);
+        assert_eq!(serialized["tool_calls"][0]["type"], "function");
+        assert_eq!(serialized["tool_calls"][0]["function"]["name"], "grep");
+        assert_eq!(
+            serialized["tool_calls"][0]["function"]["arguments"],
+            r#"{"pattern":"fn main"}"#
+        );
+    }
+
+    #[test]
+    fn tool_response_carries_role_and_tool_call_id() {
+        let message = Message::tool_response("call_1", "src/main.rs");
+        let serialized = serde_json::to_value(&message).unwrap();
+
+        assert_eq!(serialized["role"], "tool");
+        assert_eq!(serialized["tool_call_id"], "call_1");
+        assert_eq!(serialized["content"], "src/main.rs");
+    }
+
+    #[test]
+    fn request_serializes_tool_choice_and_reasoning() {
+        let messages = [Message::new(Role::User, "hi")];
+        let tools = [Tool::new("ls", "List files", json!({"type": "object"}))];
+
+        let request = serde_json::to_value(ChatRequest {
+            model: "some/model",
+            messages: &messages,
+            reasoning: Reasoning { enabled: true },
+            tools: &tools,
+            tool_choice: TOOL_CHOICE_AUTO,
+        })
+        .unwrap();
+
+        assert_eq!(request["model"], "some/model");
+        assert_eq!(request["reasoning"]["enabled"], true);
+        assert_eq!(request["tool_choice"], "auto");
+        assert_eq!(request["tools"][0]["function"]["name"], "ls");
+        assert_eq!(request["messages"][0]["role"], "user");
+    }
+
+    #[test]
+    fn response_parses_tool_calls_and_cost() {
+        let response: ChatResponse = serde_json::from_value(json!({
+            "choices": [{
+                "message": {
+                    "role": "assistant",
+                    "content": null,
+                    "tool_calls": [{
+                        "id": "call_1",
+                        "type": "function",
+                        "function": { "name": "ls", "arguments": "{\"path\":\"src\"}" }
+                    }]
+                }
+            }],
+            "usage": { "cost": 0.0021 }
+        }))
+        .unwrap();
+
+        assert_eq!(response.usage.and_then(|usage| usage.cost), Some(0.0021));
+
+        let message = response.choices.into_iter().next().unwrap().message;
+        assert!(message.content.is_none());
+
+        let calls = message.tool_calls.unwrap();
+        assert_eq!(calls[0].name(), "ls");
+        assert_eq!(calls[0].id(), "call_1");
+        assert_eq!(calls[0].arguments_json(), r#"{"path":"src"}"#);
+    }
+
+    #[test]
+    fn response_parses_parts_content() {
+        let response: ChatResponse = serde_json::from_value(json!({
+            "choices": [{
+                "message": {
+                    "role": "assistant",
+                    "content": [
+                        { "type": "text", "text": "hello " },
+                        { "type": "text", "text": "world" }
+                    ]
+                }
+            }]
+        }))
+        .unwrap();
+
+        assert!(response.usage.is_none());
+
+        let message = response.choices.into_iter().next().unwrap().message;
+        assert_eq!(message.content.unwrap().into_text(), "hello world");
+    }
+
+    #[test]
+    fn error_message_prefers_api_message() {
+        let body = r#"{"error":{"message":"No auth credentials found","code":401}}"#;
+        assert_eq!(error_message(body), "No auth credentials found");
+    }
+
+    #[test]
+    fn error_message_falls_back_to_raw_body() {
+        assert_eq!(
+            error_message("  <html>bad gateway</html>  "),
+            "<html>bad gateway</html>"
+        );
+    }
+}

crates/herald-server/src/sandbox/agent.rs

@@ -0,0 +1,137 @@
+//! Tool-calling loop driving the model against a [`Sandbox`].
+//!
+//! The loop sends the conversation and the available tools to OpenRouter,
+//! executes any requested tool call inside the sandbox and feeds the results
+//! back, until the model produces a final message or the iteration budget is
+//! exhausted.
+
+use anyhow::Context;
+use serde_json::Value;
+use tracing::{debug, warn};
+
+use crate::{
+    open_router::{Message, OpenRouterClient, Role, Tool, ToolCall},
+    sandbox::{Sandbox, tools},
+};
+
+/// Final output of an agent run.
+pub struct AgentResult {
+    pub message: String,
+    pub cost: Option<f64>,
+    pub iterations: usize,
+}
+
+/// Runs the tool-calling loop until the model answers or `max_iterations` is
+/// reached.
+///
+/// `tool_definitions` is the set of tools the model may call; it is selected by
+/// the caller based on the webhook action (see [`tools::for_webhook`]).
+pub async fn run(
+    open_router: &OpenRouterClient,
+    sandbox: &Sandbox,
+    tool_definitions: Vec<Tool>,
+    system_prompt: &str,
+    user_prompt: &str,
+    max_iterations: usize,
+) -> anyhow::Result<AgentResult> {
+    let mut messages = vec![
+        Message::new(Role::System, system_prompt),
+        Message::new(Role::User, user_prompt),
+    ];
+
+    let mut total_cost = 0.0_f64;
+    let mut has_cost = false;
+
+    for iteration in 1..=max_iterations {
+        let response = open_router
+            .chat_with_tools(messages.clone(), tool_definitions.clone())
+            .await?;
+
+        if let Some(cost) = response.cost {
+            total_cost += cost;
+            has_cost = true;
+        }
+
+        if response.tool_calls.is_empty() {
+            return Ok(AgentResult {
+                message: response.message.unwrap_or_default(),
+                cost: has_cost.then_some(total_cost),
+                iterations: iteration,
+            });
+        }
+
+        messages.push(Message::assistant_with_tool_calls(
+            response.message.unwrap_or_default(),
+            response.tool_calls.clone(),
+        ));
+
+        for call in &response.tool_calls {
+            debug!(tool = call.name(), "Executing tool call");
+            let content = execute(sandbox, call).await;
+            messages.push(Message::tool_response(call.id(), content));
+        }
+    }
+
+    warn!(max_iterations, "Agent reached the iteration limit");
+    anyhow::bail!("agent exceeded the maximum number of iterations ({max_iterations})")
+}
+
+async fn execute(sandbox: &Sandbox, call: &ToolCall) -> String {
+    let args = match parse_args(call) {
+        Ok(args) => args,
+        Err(err) => return format!("error: {err}"),
+    };
+
+    match tools::dispatch(sandbox, call.name(), &args).await {
+        Ok(output) => output,
+        Err(err) => format!("error: {err}"),
+    }
+}
+
+fn parse_args(call: &ToolCall) -> anyhow::Result<Value> {
+    let raw = call.arguments_json().trim();
+    if raw.is_empty() {
+        return Ok(Value::Object(serde_json::Map::new()));
+    }
+
+    serde_json::from_str(raw)
+        .with_context(|| format!("invalid arguments for tool `{}`", call.name()))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    /// Builds a tool call the way the API returns one, so the fixture also
+    /// covers deserialization.
+    fn tool_call(name: &str, arguments: &str) -> ToolCall {
+        serde_json::from_value(json!({
+            "id": "call_1",
+            "type": "function",
+            "function": { "name": name, "arguments": arguments }
+        }))
+        .unwrap()
+    }
+
+    #[test]
+    fn parse_args_accepts_empty_arguments() {
+        let call = tool_call("ls", "");
+        assert_eq!(
+            parse_args(&call).unwrap(),
+            Value::Object(serde_json::Map::new())
+        );
+    }
+
+    #[test]
+    fn parse_args_parses_json_object() {
+        let call = tool_call("ls", r#"{"path":"src"}"#);
+        assert_eq!(parse_args(&call).unwrap()["path"], "src");
+    }
+
+    #[test]
+    fn parse_args_rejects_invalid_json() {
+        let call = tool_call("ls", "not json");
+        assert!(parse_args(&call).is_err());
+    }
+}

crates/herald-server/src/sandbox/mod.rs

@@ -0,0 +1,195 @@
+//! Sandboxed tool execution for the AI bot.
+//!
+//! A [`Sandbox`] clones a pull request into a temporary directory, builds and
+//! starts its devcontainer (via `devcontainer-rs`) and exposes command
+//! execution inside the resulting container. The [`tools`] module maps model
+//! tool calls to commands run in that container, and [`agent`] drives the
+//! tool-calling loop against OpenRouter.
+
+pub mod agent;
+pub mod tools;
+
+use std::{
+    path::{Path, PathBuf},
+    process::Stdio,
+};
+
+use anyhow::Context;
+use devcontainer_rs::{Container, ContainerRuntime, ExecOutput};
+use tempfile::TempDir;
+use tracing::{info, instrument};
+
+/// Devcontainer locations recognized within a repository, in priority order.
+const DEVCONTAINER_PATHS: [&str; 2] = [".devcontainer/devcontainer.json", ".devcontainer.json"];
+
+/// Sandbox-related runtime configuration.
+#[derive(Clone)]
+pub struct SandboxConfig {
+    /// Container runtime binary to drive (e.g. `docker`, `podman`).
+    pub runtime: ContainerRuntime,
+    /// Maximum number of tool-calling iterations per agent run.
+    pub max_iterations: usize,
+}
+
+/// A cloned repository running inside an ephemeral devcontainer.
+pub struct Sandbox {
+    // Owns the temporary directory; dropping it cleans up the clone.
+    _workspace: TempDir,
+    container: Container,
+}
+
+impl Sandbox {
+    /// Clones the pull request head, builds the devcontainer and starts it.
+    ///
+    /// The clone is PR-aware: it fetches `refs/pull/<number>/head`, which works
+    /// for both same-repository and forked pull requests.
+    #[instrument(skip(runtime, token), fields(pr = pull_request_number))]
+    pub async fn create(
+        runtime: &ContainerRuntime,
+        repo_url: &str,
+        token: &str,
+        pull_request_number: u64,
+    ) -> anyhow::Result<Self> {
+        let workspace = tempfile::tempdir().context("failed to create sandbox workspace")?;
+        let repo_dir = workspace.path().join("repo");
+
+        clone_pull_request(repo_url, token, pull_request_number, &repo_dir).await?;
+
+        let devcontainer_path = find_devcontainer(&repo_dir)
+            .with_context(|| format!("no devcontainer found in `{repo_url}`"))?;
+
+        let devcontainer = devcontainer_rs::parse(&devcontainer_path).await?;
+
+        info!(image = %devcontainer.image_tag(), "Building and starting sandbox container");
+        let container = devcontainer.up(runtime, &repo_dir).await?;
+
+        Ok(Self {
+            _workspace: workspace,
+            container,
+        })
+    }
+
+    /// Executes a command in the container as an argv vector (no shell).
+    pub async fn exec(&self, cmd: &[&str]) -> anyhow::Result<ExecOutput> {
+        Ok(self.container.exec(cmd).await?)
+    }
+
+    /// Path of the repository inside the container.
+    pub fn workspace_folder(&self) -> &str {
+        self.container.workspace_folder()
+    }
+
+    /// Stops and removes the container. The temporary clone is removed on drop.
+    pub async fn cleanup(self) -> anyhow::Result<()> {
+        self.container.remove().await?;
+        Ok(())
+    }
+}
+
+fn find_devcontainer(repo_dir: &Path) -> Option<PathBuf> {
+    DEVCONTAINER_PATHS
+        .iter()
+        .map(|relative| repo_dir.join(relative))
+        .find(|candidate| candidate.is_file())
+}
+
+async fn clone_pull_request(
+    repo_url: &str,
+    token: &str,
+    pull_request_number: u64,
+    dest: &Path,
+) -> anyhow::Result<()> {
+    let dest = dest.display().to_string();
+
+    run_git(
+        token,
+        &[
+            "clone".to_string(),
+            "--depth".to_string(),
+            "1".to_string(),
+            repo_url.to_string(),
+            dest.clone(),
+        ],
+    )
+    .await?;
+
+    run_git(
+        token,
+        &[
+            "-C".to_string(),
+            dest.clone(),
+            "fetch".to_string(),
+            "--depth".to_string(),
+            "1".to_string(),
+            "origin".to_string(),
+            format!("refs/pull/{pull_request_number}/head"),
+        ],
+    )
+    .await?;
+
+    run_git(
+        token,
+        &[
+            "-C".to_string(),
+            dest,
+            "checkout".to_string(),
+            "FETCH_HEAD".to_string(),
+        ],
+    )
+    .await?;
+
+    Ok(())
+}
+
+/// Runs git with the token injected through `http.extraHeader`, keeping the
+/// secret out of the process arguments.
+async fn run_git(token: &str, args: &[String]) -> anyhow::Result<()> {
+    let output = tokio::process::Command::new("git")
+        .args(args)
+        .env("GIT_CONFIG_COUNT", "1")
+        .env("GIT_CONFIG_KEY_0", "http.extraHeader")
+        .env(
+            "GIT_CONFIG_VALUE_0",
+            format!("Authorization: token {token}"),
+        )
+        .env("GIT_TERMINAL_PROMPT", "0")
+        .stdin(Stdio::null())
+        .output()
+        .await
+        .context("failed to spawn git")?;
+
+    if !output.status.success() {
+        anyhow::bail!(
+            "git {} failed: {}",
+            args.join(" "),
+            String::from_utf8_lossy(&output.stderr).trim()
+        );
+    }
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn find_devcontainer_prefers_dot_devcontainer_dir() {
+        let dir = tempfile::tempdir().unwrap();
+        let nested = dir.path().join(".devcontainer");
+        std::fs::create_dir(&nested).unwrap();
+        std::fs::write(nested.join("devcontainer.json"), "{}").unwrap();
+        std::fs::write(dir.path().join(".devcontainer.json"), "{}").unwrap();
+
+        assert_eq!(
+            find_devcontainer(dir.path()),
+            Some(nested.join("devcontainer.json"))
+        );
+    }
+
+    #[test]
+    fn find_devcontainer_returns_none_when_absent() {
+        let dir = tempfile::tempdir().unwrap();
+        assert_eq!(find_devcontainer(dir.path()), None);
+    }
+}

crates/herald-server/src/sandbox/tools.rs

@@ -0,0 +1,246 @@
+//! Tool definitions exposed to the model and their execution inside a
+//! [`Sandbox`].
+//!
+//! Every tool is read-only and confined to the repository workspace: paths are
+//! resolved relative to the container workspace folder and rejected if they
+//! escape it. Commands are executed as argv vectors (never through a shell),
+//! so tool arguments cannot be used for shell injection.
+
+use std::path::Path;
+
+use anyhow::{Context, bail};
+use devcontainer_rs::{ExecOutput, normalize};
+use serde_json::{Value, json};
+
+use super::Sandbox;
+use crate::{gitea::WebhookType, open_router::Tool};
+
+/// Tools available to the model for a given webhook action.
+///
+/// The match is exhaustive on [`WebhookType`], so adding a new action forces a
+/// decision here about which tools that action may use.
+pub fn for_webhook(webhook: &WebhookType) -> Vec<Tool> {
+    match webhook {
+        WebhookType::Review(_) => review_tools(),
+    }
+}
+
+/// Read-only tools used to explore a repository during a review.
+fn review_tools() -> Vec<Tool> {
+    vec![
+        Tool::new(
+            "ls",
+            "List the entries of a directory inside the repository.",
+            json!({
+                "type": "object",
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "Directory path relative to the repository root. Defaults to the repository root."
+                    }
+                }
+            }),
+        ),
+        Tool::new(
+            "read_file",
+            "Read the content of a text file inside the repository.",
+            json!({
+                "type": "object",
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "File path relative to the repository root."
+                    },
+                    "start_line": {
+                        "type": "integer",
+                        "description": "First line to read (1-based, inclusive). Defaults to the first line."
+                    },
+                    "end_line": {
+                        "type": "integer",
+                        "description": "Last line to read (1-based, inclusive). Defaults to the last line."
+                    }
+                },
+                "required": ["path"]
+            }),
+        ),
+        Tool::new(
+            "grep",
+            "Search for a regular expression across the repository files.",
+            json!({
+                "type": "object",
+                "properties": {
+                    "pattern": {
+                        "type": "string",
+                        "description": "Extended regular expression to search for."
+                    },
+                    "path": {
+                        "type": "string",
+                        "description": "File or directory to search in, relative to the repository root. Defaults to the repository root."
+                    }
+                },
+                "required": ["pattern"]
+            }),
+        ),
+        Tool::new(
+            "find",
+            "Find files by name pattern inside the repository.",
+            json!({
+                "type": "object",
+                "properties": {
+                    "pattern": {
+                        "type": "string",
+                        "description": "Glob pattern matched against file names, e.g. `*.rs`."
+                    },
+                    "path": {
+                        "type": "string",
+                        "description": "Directory to search in, relative to the repository root. Defaults to the repository root."
+                    }
+                },
+                "required": ["pattern"]
+            }),
+        ),
+    ]
+}
+
+/// Executes a tool call and returns its textual result.
+///
+/// Errors are returned as `Err` so the caller can decide whether to surface
+/// them to the model or abort.
+pub async fn dispatch(sandbox: &Sandbox, name: &str, args: &Value) -> anyhow::Result<String> {
+    match name {
+        "ls" => ls(sandbox, args).await,
+        "read_file" => read_file(sandbox, args).await,
+        "grep" => grep(sandbox, args).await,
+        "find" => find(sandbox, args).await,
+        other => bail!("unknown tool `{other}`"),
+    }
+}
+
+async fn ls(sandbox: &Sandbox, args: &Value) -> anyhow::Result<String> {
+    let path = resolve(sandbox, optional_str(args, "path").unwrap_or("."))?;
+    let output = sandbox.exec(&["ls", "-la", "--", &path]).await?;
+    into_stdout(output)
+}
+
+async fn read_file(sandbox: &Sandbox, args: &Value) -> anyhow::Result<String> {
+    let path = resolve(sandbox, required_str(args, "path")?)?;
+
+    let start = args.get("start_line").and_then(Value::as_u64);
+    let end = args.get("end_line").and_then(Value::as_u64);
+
+    let output = if start.is_none() && end.is_none() {
+        sandbox.exec(&["cat", "--", &path]).await?
+    } else {
+        let start = start.unwrap_or(1);
+        let end = end
+            .map(|line| line.to_string())
+            .unwrap_or_else(|| "$".to_string());
+        let range = format!("{start},{end}p");
+        sandbox.exec(&["sed", "-n", &range, "--", &path]).await?
+    };
+
+    into_stdout(output)
+}
+
+async fn grep(sandbox: &Sandbox, args: &Value) -> anyhow::Result<String> {
+    let pattern = required_str(args, "pattern")?;
+    let path = resolve(sandbox, optional_str(args, "path").unwrap_or("."))?;
+
+    let output = sandbox
+        .exec(&["grep", "-rn", "-E", "--", pattern, &path])
+        .await?;
+
+    // grep exits with 1 when there is no match, which is not an error.
+    match output.status {
+        0 | 1 => Ok(output.stdout),
+        _ => bail!("grep failed: {}", output.stderr.trim()),
+    }
+}
+
+async fn find(sandbox: &Sandbox, args: &Value) -> anyhow::Result<String> {
+    let pattern = required_str(args, "pattern")?;
+    let path = resolve(sandbox, optional_str(args, "path").unwrap_or("."))?;
+
+    let output = sandbox
+        .exec(&["find", &path, "-type", "f", "-name", pattern])
+        .await?;
+
+    into_stdout(output)
+}
+
+/// Resolves a tool path against the container workspace folder, rejecting any
+/// path that escapes it.
+fn resolve(sandbox: &Sandbox, path: &str) -> anyhow::Result<String> {
+    let workspace = sandbox.workspace_folder();
+    let candidate = Path::new(workspace).join(path);
+
+    let normalized =
+        normalize(&candidate).with_context(|| format!("path `{path}` escapes the workspace"))?;
+
+    if !normalized.starts_with(workspace) {
+        bail!("path `{path}` escapes the workspace");
+    }
+
+    Ok(normalized.display().to_string())
+}
+
+fn required_str<'a>(args: &'a Value, key: &str) -> anyhow::Result<&'a str> {
+    args.get(key)
+        .and_then(Value::as_str)
+        .with_context(|| format!("`{key}` is required"))
+}
+
+fn optional_str<'a>(args: &'a Value, key: &str) -> Option<&'a str> {
+    args.get(key).and_then(Value::as_str)
+}
+
+fn into_stdout(output: ExecOutput) -> anyhow::Result<String> {
+    if output.success() {
+        Ok(output.stdout)
+    } else {
+        bail!(
+            "command failed (status {}): {}",
+            output.status,
+            output.stderr.trim()
+        )
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::gitea::{Comment, PullRequest, Repository, ReviewPayload};
+
+    fn review_webhook() -> WebhookType {
+        WebhookType::Review(ReviewPayload {
+            action: "created".to_string(),
+            pull_request: PullRequest {
+                number: 1,
+                title: "My PR".to_string(),
+            },
+            repository: Repository {
+                full_name: "owner/repo".to_string(),
+            },
+            comment: Comment {
+                id: 1,
+                body: "@bot review".to_string(),
+            },
+        })
+    }
+
+    #[test]
+    fn review_webhook_exposes_read_only_tools() {
+        let names: Vec<String> = for_webhook(&review_webhook())
+            .into_iter()
+            .map(|tool| tool.function.name)
+            .collect();
+
+        assert_eq!(names, vec!["ls", "read_file", "grep", "find"]);
+    }
+
+    #[test]
+    fn required_str_reports_missing_key() {
+        let err = required_str(&json!({}), "path").unwrap_err();
+        assert!(err.to_string().contains("path"));
+    }
+}

src/bot_actions/review.rs

@@ -1,214 +0,0 @@
-use futures_util::stream::TryStreamExt;
-use tokio::io::AsyncReadExt;
-use tokio_util::io::StreamReader;
-use tracing::instrument;
-
-use crate::{
-    bot::ReviewResult,
-    consts::{BOT_PROCESS_MSG, MAX_DIFF_SIZE, REVIEW_PROMPT},
-    gitea::{GiteaAPI, ReviewPayload},
-    open_router::OpenRouterClient,
-};
-
-#[instrument(skip(gitea_api, open_router_client, http_client, review_payload))]
-pub async fn exec_review(
-    gitea_api: &GiteaAPI,
-    open_router_client: &OpenRouterClient,
-    http_client: &reqwest::Client,
-    model: &str,
-    review_payload: ReviewPayload,
-) -> anyhow::Result<()> {
-    tracing::info!(
-        repo = %review_payload.repository.full_name,
-        pr = review_payload.pull_request.number,
-        action = %review_payload.action,
-        "Starting review"
-    );
-
-    let new_comment = gitea_api
-        .comment(
-            &BOT_PROCESS_MSG.replace("{model}", model),
-            &review_payload.repository.full_name,
-            review_payload.pull_request.number,
-        )
-        .await?;
-
-    let bot_result: Result<ReviewResult, anyhow::Error> = async {
-        let git_diff =
-            download_git_diff(http_client, &review_payload.pull_request.diff_url).await?;
-
-        let diff_for_llm = format_diff_for_review(&git_diff);
-
-        let bot_request = REVIEW_PROMPT
-            .replace("{subject}", &review_payload.pull_request.title)
-            .replace("{comment}", &review_payload.comment.body)
-            .replace("{diff}", &diff_for_llm);
-
-        let chat_result = open_router_client.chat(&bot_request).await?;
-        let mut review_result = serde_json::from_str::<ReviewResult>(&chat_result.message)?;
-
-        review_result.cost = chat_result.cost;
-
-        let final_review_markdown = review_result_to_markdown(&review_result);
-
-        gitea_api
-            .post_pull_request_review(
-                &review_result,
-                &final_review_markdown,
-                &review_payload.repository.full_name,
-                review_payload.pull_request.number,
-            )
-            .await?;
-
-        Ok(review_result)
-    }
-    .await;
-
-    match bot_result {
-        Ok(_) => {
-            gitea_api
-                .delete_comment(&review_payload.repository.full_name, new_comment.id)
-                .await
-        }
-        Err(e) => {
-            gitea_api
-                .edit_comment(
-                    &format!("Error while reviewing: {}", e),
-                    &review_payload.repository.full_name,
-                    new_comment.id,
-                )
-                .await
-        }
-    }
-}
-
-fn review_result_to_markdown(review_result: &ReviewResult) -> String {
-    if review_result.reviews.is_empty() {
-        return String::from("No issues found. ✅");
-    }
-
-    let mut md = String::from("## Review Feedback\n\n");
-
-    md.push_str(&format!(
-        "### {} issues found.\n\n",
-        review_result.reviews.len()
-    ));
-
-    if !review_result.comment.is_empty() {
-        md.push_str("\n---\n\n");
-        md.push_str("### Summary\n\n");
-        md.push_str(&review_result.comment);
-        md.push('\n');
-    }
-
-    if let Some(cost) = review_result.cost {
-        md.push_str("\n---\n\n");
-        md.push_str(&format!("### Cost: ${}", cost));
-        md.push('\n');
-    }
-
-    md
-}
-
-async fn download_git_diff(http_client: &reqwest::Client, url: &str) -> anyhow::Result<String> {
-    let response = http_client.get(url).send().await?;
-    let stream = response.bytes_stream().map_err(std::io::Error::other);
-
-    let mut buf = Vec::with_capacity(MAX_DIFF_SIZE);
-    StreamReader::new(stream)
-        .take((MAX_DIFF_SIZE + 1) as u64)
-        .read_to_end(&mut buf)
-        .await?;
-
-    if buf.len() > MAX_DIFF_SIZE {
-        anyhow::bail!("Git diff exceeds the maximum allowed size of 1 Mo");
-    }
-
-    Ok(String::from_utf8_lossy(&buf).into_owned())
-}
-
-fn format_diff_for_review(git_diff: &str) -> String {
-    let mut output = String::new();
-    let mut current_file: Option<&str> = None;
-    let mut new_line: u64 = 0;
-
-    for line in git_diff.lines() {
-        if let Some(rest) = line.strip_prefix("diff --git a/") {
-            if let Some(end) = rest.find(' ') {
-                current_file = Some(&rest[..end]);
-            }
-            new_line = 0;
-            continue;
-        }
-
-        if line.starts_with("---") || line.starts_with("+++") {
-            continue;
-        }
-
-        if line.starts_with("@@") && line.contains('+') {
-            if let Some(start) = parse_hunk_new_start(line) {
-                new_line = start;
-            }
-            continue;
-        }
-
-        let Some(filename) = current_file else {
-            continue;
-        };
-
-        if line.starts_with(' ') {
-            new_line += 1;
-            continue;
-        }
-
-        if let Some(code) = line.strip_prefix('+') {
-            use std::fmt::Write;
-            let _ = writeln!(output, "{filename}:{new_line}:{code}");
-            new_line += 1;
-        }
-    }
-
-    output
-}
-
-fn parse_hunk_new_start(hunk_header: &str) -> Option<u64> {
-    let plus_part = hunk_header.split('+').nth(1)?;
-    let num_str = plus_part.split(|c: char| !c.is_ascii_digit()).next()?;
-    num_str.parse::<u64>().ok()
-}
-
-#[cfg(test)]
-#[test]
-fn test_format_diff_for_review() {
-    let diff = concat!(
-        "diff --git a/src/foo.rs b/src/foo.rs\n",
-        "--- a/src/foo.rs\n",
-        "+++ b/src/foo.rs\n",
-        "@@ -1,3 +1,6 @@\n",
-        " fn main() {\n",
-        "+    let x = 1;\n",
-        "     println!(\"hello\");\n",
-        "+    let y = 2;\n",
-        "+    let z = 3;\n",
-        " }\n",
-        "diff --git a/src/bar.rs b/src/bar.rs\n",
-        "--- a/src/bar.rs\n",
-        "+++ b/src/bar.rs\n",
-        "@@ -10,4 +10,6 @@\n",
-        " old context\n",
-        "+    let a = 10;\n",
-        " more context\n",
-        "+    let b = 20;\n",
-    );
-
-    let result = format_diff_for_review(diff);
-    let expected = concat!(
-        "src/foo.rs:2:    let x = 1;\n",
-        "src/foo.rs:4:    let y = 2;\n",
-        "src/foo.rs:5:    let z = 3;\n",
-        "src/bar.rs:11:    let a = 10;\n",
-        "src/bar.rs:13:    let b = 20;\n",
-    );
-
-    assert_eq!(result, expected);
-}

src/consts.rs

@@ -1,44 +0,0 @@
-pub const GITEA_SIG_HEADER_NAME: &str = "x-gitea-signature";
-pub const GITEA_EVENT_TYPE_HEADER_NAME: &str = "x-gitea-event-type";
-
-pub const MAX_WEBHOOK_BODY_SIZE: usize = 1024 * 1024; // 1 MiB
-pub const MAX_DIFF_SIZE: usize = 1024 * 1024; // 1 MiB
-
-pub const BOT_PROCESS_MSG: &str = "
-    Review in progress with the model \"{model}\"...
-";
-
-pub const REVIEW_PROMPT: &str = "
-    You are a senior software engineer reviewing code changes.
-
-    Check good practices and code quality.
-
-    This is the pull request subject: \"{subject}\"
-
-    This is the user comment: \"{comment}\"
-
-    The code changes (only added lines, with line numbers):
-
-    {diff}
-
-    Please review the code changes and provide feedback.
-
-    IMPORTANT: the `line` field must be the line number shown before each line.
-    The provided code has the format: `filename:line:code`
-
-    Return your feedback, in french, with only this json format, reviews must contain each review
-    All fields are mandatory.
-    (filename field must contain the full path with extension) and comment must contain a final summary:
-
-    {
-        \"reviews\": [
-            {
-                \"filename\": \"\",
-                \"line\": ,
-                \"code\": \"\",
-                \"message\": \"\"
-            }
-        ],
-        \"comment\": \"\"
-    }
-";

src/open_router.rs

@@ -1,50 +0,0 @@
-use std::time::Duration;
-
-use openrouter_rs::{Message, api::chat::ChatCompletionRequest};
-use tracing::instrument;
-
-pub struct ChatResult {
-    pub message: String,
-    pub cost: Option<f64>,
-}
-
-#[derive(Clone)]
-pub struct OpenRouterClient {
-    client: openrouter_rs::OpenRouterClient,
-    model: String,
-}
-
-impl OpenRouterClient {
-    pub fn new(token: &str, model: &str, timeout: u64) -> anyhow::Result<Self> {
-        Ok(Self {
-            client: openrouter_rs::OpenRouterClient::builder()
-                .api_key(token)
-                .http_client(
-                    reqwest::Client::builder()
-                        .timeout(Duration::from_secs(timeout))
-                        .build()?,
-                )
-                .build()?,
-            model: String::from(model),
-        })
-    }
-
-    #[instrument(skip(self), err)]
-    pub async fn chat(&self, msg: &str) -> anyhow::Result<ChatResult> {
-        let request = ChatCompletionRequest::builder()
-            .model(&self.model)
-            .enable_reasoning()
-            .messages(vec![Message::new(openrouter_rs::types::Role::User, msg)])
-            .build()?;
-
-        let response = self.client.chat().create(&request).await?;
-
-        Ok(ChatResult {
-            message: response.choices[0]
-                .content()
-                .map(String::from)
-                .ok_or(anyhow::anyhow!("No content"))?,
-            cost: response.usage.and_then(|u| u.cost),
-        })
-    }
-}