AI assistants review proposals and draft their descriptions 7d2eb590051f

-- A review an AI assistant answered for the person who asked (hub spec

-- §13.4, #97): the assistant's name, empty for a person's own review.

ALTER TABLE proposal_reviews ADD COLUMN via TEXT NOT NULL DEFAULT '';

- **AI assistants, step three: drafted descriptions (#97).** The new-proposal form and an open proposal's editor have a draft-with button per assistant; the answer, written from the changes and diff, lands in the editor for the person to change before saving.

- **AI assistants, step two: review requests (#97).** Under Reviewers, the author or a writer asks an assistant the repository may use; the hub sends it the proposal's title, description, changes and diff with the site, organisation and repository prompts, and records the answer as a comment review via the assistant, shown as "bob ↳ agent Claude". Approvals count only people, and an assistant's answer never replaces the asker's own verdict. Also `POST …/proposals/{n}/review-requests` in the API, with `via` on reviews.

    /// The AI assistant that answered for `author`, empty for a person's

    /// own review (hub spec §13.4).

    #[serde(default, skip_serializing_if = "String::is_empty")]

    pub via: String,

}

/// `POST .../proposals/{number}/review-requests`: ask an AI assistant the

/// repository may use (hub spec §13.4) to review; it answers as a `comment`

/// review via the assistant.

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]

pub struct AssistantRequest {

    pub assistant: String,

        .route("/repos/{owner}/{name}/proposals/{number}/review-requests", post(request_assistant))

                via: r.row.via,

        Json(Review { id: r.id, author: r.author, verdict: r.verdict, body: r.body, sealed: false, created_ms: r.created_ms, via: r.via }),

/// `POST .../proposals/{number}/review-requests`: ask an AI assistant the

/// repository may use to review (hub spec §13.4). Accepted at once; the

/// answer arrives as a `comment` review via the assistant.

async fn request_assistant(

    State(app): State<Shared>,

    headers: HeaderMap,

    Path((owner, name, number)): Path<(String, String, i64)>,

    Json(body): Json<hub_api::AssistantRequest>,

) -> Result<(StatusCode, Json<hub_api::AssistantRequest>), ApiError> {

    let c = caller(&app, &headers).await?;

    let me = c.require("proposals:write").or_else(|_| c.require("repo:write"))?.clone();

    let (_, row, role) = reach(&app, &c, &owner, &name, Access::Read).await?;

    let p = db::proposals::get(&app.db, row.id, number).await?.ok_or_else(|| not_found("no such proposal"))?;

    if Some(me.id) != p.author_id && role < Role::Write {

        return Err(forbidden("only the author or a writer asks for reviews"));

    }

    if !p.is_open() {

        return Err(ApiError(StatusCode::CONFLICT, "the proposal is not open".into()));

    }

    let a = crate::assistants::enabled_for_repo(&app.db, &row)

        .await?

        .into_iter()

        .find(|a| a.name.eq_ignore_ascii_case(body.assistant.trim()))

        .ok_or_else(|| ApiError(StatusCode::UNPROCESSABLE_ENTITY, format!("no assistant called {} here", body.assistant.trim())))?;

    let asked = hub_api::AssistantRequest { assistant: a.name.clone() };

    crate::assistants::request_review(&app, &row, &p, &me, a).await.map_err(|e| ApiError(StatusCode::CONFLICT, e))?;

    Ok((StatusCode::ACCEPTED, Json(asked)))

}

// ------------------------------------------------------- reviewing

/// At most this many assistant calls per repository per hour.

pub const CALLS_PER_HOUR: usize = 30;

/// Who is answering what, and recent calls per repository.

#[derive(Default)]

pub struct Gate {

    busy: std::collections::HashSet<(i64, String)>,

    recent: std::collections::HashMap<i64, Vec<i64>>,

}

impl Gate {

    /// Take the slot for (proposal, assistant), or say why not.

    fn take(&mut self, repo_id: i64, proposal_id: i64, name: &str) -> Result<(), String> {

        let key = (proposal_id, name.to_lowercase());

        if self.busy.contains(&key) {

            return Err(format!("{name} is already answering this proposal"));

        }

        let now = now_ms();

        let calls = self.recent.entry(repo_id).or_default();

        calls.retain(|t| now - *t < 3_600_000);

        if calls.len() >= CALLS_PER_HOUR {

            return Err(format!("this repository has asked assistants {CALLS_PER_HOUR} times in the last hour; try later"));

        }

        calls.push(now);

        self.busy.insert(key);

        Ok(())

    }

    fn release(&mut self, proposal_id: i64, name: &str) {

        self.busy.remove(&(proposal_id, name.to_lowercase()));

    }

}

/// What a reviewer is told about a proposal: its title, description,

/// changes and diff, cut to `budget` characters.

pub fn review_context(

    row: &crate::db::repos::RepoRow,

    p: &crate::db::proposals::ProposalRow,

    loaded: &crate::web::proposals::Loaded,

    budget: usize,

) -> String {

    let mut head =

        format!("# Proposal #{}: {}\n\nRepository {}/{} · into {} · by {}\n\n", p.number, p.title, row.owner, row.name, p.target, p.author);

    if !p.body.trim().is_empty() {

        head.push_str("## Description\n\n");

        head.push_str(p.body.trim());

        head.push_str("\n\n");

    }

    context_text(head, &loaded.changes, &loaded.diffs, budget)

}

/// What a drafter is told: the title so far, the changes and the diff.

pub fn draft_context(

    row: &crate::db::repos::RepoRow,

    title: &str,

    target: &str,

    changes: &[crate::repos::view::ChangeView],

    diffs: &[oxy_core::repo::FileDiff],

    budget: usize,

) -> String {

    let head = format!(

        "# Proposal: {}\n\nRepository {}/{} · into {}\n\n",

        if title.trim().is_empty() { "(untitled)" } else { title.trim() },

        row.owner,

        row.name,

        target

    );

    context_text(head, changes, diffs, budget)

}

/// `head`, the list of changes, then the diff as `-`/`+` lines per hunk,

/// binary files noted, the diff cut so the whole fits `budget`.

fn context_text(mut text: String, changes: &[crate::repos::view::ChangeView], diffs: &[oxy_core::repo::FileDiff], budget: usize) -> String {

    text.push_str(&format!("## Changes ({})\n\n", changes.len()));

    for c in changes {

        text.push_str(&format!("- {} {}\n", c.short, c.title));

        let body = c.body.trim();

        if !body.is_empty() {

            for line in body.lines().take(20) {

                text.push_str("  ");

                text.push_str(line);

                text.push('\n');

            }

        }

    }

    text.push_str("\n## Diff\n\n");

    let head = text.chars().count();

    let mut diff = String::new();

    for f in diffs {

        diff.push_str(&format!("### {} ({})\n", f.path, f.kind));

        if let Some(from) = &f.from {

            diff.push_str(&format!("renamed from {from}\n"));

        }

        let binary = f.hunks.iter().any(|h| h.added.iter().chain(h.removed.iter().map(|(_, l)| l)).any(|l| l.contains(&0)));

        if binary {

            diff.push_str("(binary)\n\n");

            continue;

        }

        diff.push_str("```\n");

        for h in &f.hunks {

            diff.push_str(&format!("@@ after line {} @@\n", h.base_line));

            for (_, l) in &h.removed {

                diff.push('-');

                diff.push_str(String::from_utf8_lossy(l).trim_end_matches('\n'));

                diff.push('\n');

            }

            for l in &h.added {

                diff.push('+');

                diff.push_str(String::from_utf8_lossy(l).trim_end_matches('\n'));

                diff.push('\n');

            }

        }

        diff.push_str("```\n\n");

    }

    let room = budget.saturating_sub(head + 80);

    if diff.chars().count() > room {

        let cut: String = diff.chars().take(room).collect();

        text.push_str(&cut);

        text.push_str("\n\n(the diff was cut here to fit the context budget)\n");

    } else {

        text.push_str(&diff);

    }

    text

}

/// The system prompt for a review: who the assistant is, what a review

/// here is, then the prompts the levels set.

pub fn review_system_prompt(a: &Assistant, site: &str, prompts: &str) -> String {

    let mut s = format!(

        "You are {name}, an AI assistant reviewing a proposal on {site}, an OxygenHub site. \

         A person asked for your review; it is recorded as a review comment made via you, under their name. \

         You cannot approve: only people approve. Answer in Markdown: start with a one-paragraph summary, \

         then findings (correctness first, then clarity), each naming the file and quoting the lines it is about; \

         keep praise out unless something is notably well done; say so plainly when you find nothing wrong.",

        name = a.name

    );

    if !prompts.trim().is_empty() {

        s.push_str("\n\n");

        s.push_str(prompts.trim());

    }

    s

}

/// Ask `a` to review proposal `p` for `by`: records the request, calls the

/// endpoint in the background, and stores the answer as a `comment` review

/// via the assistant (or an event saying why none came). `Err` is for the

/// person who asked, when nothing was started.

pub async fn request_review(

    app: &Shared,

    row: &crate::db::repos::RepoRow,

    p: &crate::db::proposals::ProposalRow,

    by: &crate::db::accounts::Account,

    a: Assistant,

) -> Result<(), String> {

    app.assistant_gate.lock().unwrap_or_else(|e| e.into_inner()).take(row.id, p.id, &a.name)?;

    let pool = &app.db;

    crate::db::proposals::add_event(pool, p.id, &by.username, &format!("asked {} to review", a.name), "").await.ok();

    crate::db::accounts::audit(

        pool,

        Some(by),

        "assistant.asked",

        &format!("{}/{}", row.owner, row.name),

        &format!("{} #{}", a.name, p.number),

    )

    .await

    .ok();

    let (app, row, p, by) = (app.clone(), row.clone(), p.clone(), by.clone());

    tokio::spawn(async move {

        let outcome = answer_review(&app, &row, &p, &a).await;

        app.assistant_gate.lock().unwrap_or_else(|e| e.into_inner()).release(p.id, &a.name);

        match outcome {

            Ok(body) => {

                if crate::db::proposals::add_review_via(&app.db, p.id, by.id, &by.username, "comment", &body, &a.name).await.is_ok() {

                    crate::db::proposals::add_event(&app.db, p.id, &by.username, &format!("review.comment via {}", a.name), "").await.ok();

                    crate::web::proposals::reviewed(&app, &row, &p, &by, "comment").await;

                    crate::hooks::emit(

                        &app,

                        &row,

                        "review",

                        &by.username,

                        serde_json::json!({ "number": p.number, "verdict": "comment", "via": a.name }),

                    )

                    .await;

                }

            }

            Err(why) => {

                crate::db::proposals::add_event(&app.db, p.id, &by.username, &format!("{} did not answer", a.name), &why).await.ok();

            }

        }

    });

    Ok(())

}

async fn answer_review(

    app: &Shared,

    row: &crate::db::repos::RepoRow,

    p: &crate::db::proposals::ProposalRow,

    a: &Assistant,

) -> Result<String, String> {

    let repo = crate::repos::names::RepoName::new(&row.owner, &row.name).ok_or("bad repository name")?;

    let loaded = crate::web::proposals::load(app, &repo, p.clone()).await.map_err(|e| format!("the proposal could not be loaded: {e}"))?;

    let budget = usize::try_from(a.budget).unwrap_or(DEFAULT_BUDGET as usize).max(1_000);

    let prompts = prompt_for_repo(&app.db, row).await.map_err(|e| e.to_string())?;

    let system = review_system_prompt(a, &app.config.site.name, &prompts);

    let user = review_context(row, p, &loaded, budget.saturating_sub(system.chars().count()));

    ask(app, a, &system, &user).await

}

// -------------------------------------------------------- drafting

/// The system prompt for drafting a proposal's description.

pub fn draft_system_prompt(a: &Assistant, site: &str, prompts: &str) -> String {

    let mut s = format!(

        "You are {name}, an AI assistant drafting the description of a proposal on {site}, an OxygenHub site, \

         for the person who will open or edit it; they read and change your draft before saving, and the draft is theirs. \

         Write Markdown for the description field only: no title line, no greeting, no sign-off. \

         Say what the changes do and why, what a reviewer should look at, and how to verify them; \

         keep to what the diff shows, and keep it short.",

        name = a.name

    );

    if !prompts.trim().is_empty() {

        s.push_str("\n\n");

        s.push_str(prompts.trim());

    }

    s

}

/// What a description is drafted from.

pub struct Draft<'a> {

    /// The proposal's id, or minus the repository's for one not yet opened:

    /// one draft per assistant at a time for it.

    pub slot: i64,

    pub title: &'a str,

    pub target: &'a str,

    pub changes: &'a [crate::repos::view::ChangeView],

    pub diffs: &'a [oxy_core::repo::FileDiff],

}

/// Ask `a` for a description, now; the answer goes into the editor,

/// nothing is saved. `Err` is for the person.

pub async fn draft_description(

    app: &Shared,

    row: &crate::db::repos::RepoRow,

    by: &crate::db::accounts::Account,

    a: &Assistant,

    d: Draft<'_>,

) -> Result<String, String> {

    let Draft { slot, title, target, changes, diffs } = d;

    app.assistant_gate.lock().unwrap_or_else(|e| e.into_inner()).take(row.id, slot, &a.name)?;

    crate::db::accounts::audit(&app.db, Some(by), "assistant.drafted", &format!("{}/{}", row.owner, row.name), &a.name).await.ok();

    let budget = usize::try_from(a.budget).unwrap_or(DEFAULT_BUDGET as usize).max(1_000);

    let prompts = prompt_for_repo(&app.db, row).await.map_err(|e| e.to_string());

    let outcome = match prompts {

        Ok(prompts) => {

            let system = draft_system_prompt(a, &app.config.site.name, &prompts);

            let user = draft_context(row, title, target, changes, diffs, budget.saturating_sub(system.chars().count()));

            ask(app, a, &system, &user).await

        }

        Err(e) => Err(e),

    };

    app.assistant_gate.lock().unwrap_or_else(|e| e.into_inner()).release(slot, &a.name);

    outcome.map(|t| t.trim().to_string())

}

    /// The AI assistant that answered for the author (migration 0036),

    /// empty for the author's own review.

    #[sqlx(default)]

    pub via: String,

    add_review_via(pool, proposal_id, author_id, author, verdict, body, "").await

}

/// A review answered by an AI assistant (`via`) for `author`, who asked.

pub async fn add_review_via(

    pool: &Pool,

    proposal_id: i64,

    author_id: i64,

    author: &str,

    verdict: &str,

    body: &str,

    via: &str,

) -> sqlx::Result<ReviewRow> {

        "INSERT INTO proposal_reviews (proposal_id, author_id, author, verdict, body, created_ms, via) VALUES (?, ?, ?, ?, ?, ?, ?) RETURNING *",

    .bind(via)

    /// Which assistants are answering which proposals, and recent calls

    /// per repository (hub spec §13.4).

    pub assistant_gate: std::sync::Mutex<assistants::Gate>,

        assistant_gate: std::sync::Mutex::new(assistants::Gate::default()),

        .route("/{owner}/{name}/proposals/new/draft", post(proposals::new_draft))

        .route("/{owner}/{name}/proposal/{number}/assistant", post(proposals::assistant))

        .route("/{owner}/{name}/proposal/{number}/draft", post(proposals::draft))

    /// What the form holds so far (after a failed open, or a draft).

    title: String,

    body: String,

    /// AI assistants that may draft the description (hub spec §13.4).

    assistants: Vec<String>,

    let assistants = if preview.is_empty() { vec![] } else { assistant_names(&app, &row).await };

        title: String::new(),

        body: String::new(),

        assistants,

    /// For `/proposals/new/draft`: which assistant writes the description.

    #[serde(default)]

    assistant: String,

                title: f.title.clone(),

                body: f.body.clone(),

                assistants: vec![],

    for r in rows.iter().filter(|r| r.via.is_empty()) {

        // An assistant's answer is never the person's own verdict.

    /// AI assistants the viewer may ask, by name (hub spec §13.4).

    assistants: Vec<String>,

    /// A description an assistant just drafted, for the editor.

    draft: Option<String>,

    let assistants: Vec<String> = if (can_request || can_edit) && p.is_open() { assistant_names(app, &row).await } else { Vec::new() };

        assistants,

        draft: None,

    }

}

#[derive(Deserialize)]

pub struct AssistantForm {

    #[serde(rename = "_csrf")]

    csrf_token: String,

    assistant: String,

}

/// `POST /{owner}/{name}/proposal/{number}/assistant`: the author or a

/// writer asks an AI assistant to review (hub spec §13.4). The answer

/// comes later as a review via the assistant.

pub async fn assistant(

    State(app): State<Shared>,

    viewer: Viewer,

    Path((owner, name, number)): Path<(String, String, i64)>,

    Form(f): Form<AssistantForm>,

) -> Result<Response, Error> {

    let shell = Shell::new(&app, &format!("/{owner}/{name}/proposal/{number}"), &viewer);

    let me = require(&viewer, &shell)?;

    csrf(&viewer, &f.csrf_token, &shell)?;

    let (_, row, role) = lookup(&app, &shell, &viewer, &owner, &name).await?;

    let p = pdb::get(&app.db, row.id, number)

        .await

        .map_err(|e| Error::from_db(shell.clone(), e))?

        .ok_or_else(|| Error::not_found(shell.clone()))?;

    if Some(me.account.id) != p.author_id && role < Role::Write {

        return Err(Error::not_found(shell));

    }

    if !p.is_open() {

        return Ok(back(&owner, &name, number, "conversation", None, Some("The proposal is not open.".into())));

    }

    let Some(a) = crate::assistants::enabled_for_repo(&app.db, &row)

        .await

        .map_err(|e| Error::from_db(shell.clone(), e))?

        .into_iter()

        .find(|a| a.name.eq_ignore_ascii_case(f.assistant.trim()))

    else {

        return Ok(back(&owner, &name, number, "conversation", None, Some(format!("No assistant called {} here.", f.assistant.trim()))));

    };

    let who = a.name.clone();

    match crate::assistants::request_review(&app, &row, &p, &me.account, a).await {

        Ok(()) => Ok(back(

            &owner,

            &name,

            number,

            "conversation",

            Some(format!("Asked {who} to review; its answer appears here when it comes.")),

            None,

        )),

        Err(e) => Ok(back(&owner, &name, number, "conversation", None, Some(format!("Not asked: {e}.")))),

    }

}

/// The assistants a repository may use, by name.

async fn assistant_names(app: &Shared, row: &db::repos::RepoRow) -> Vec<String> {

    crate::assistants::enabled_for_repo(&app.db, row).await.unwrap_or_default().into_iter().map(|a| a.name).collect()

}

/// The changes and the file diffs a proposal from `source` into `target`

/// would carry.

async fn preview_diff(

    app: &Shared,

    repo: &RepoName,

    target: &str,

    source: &str,

) -> Result<(Vec<ChangeView>, Vec<oxy_core::repo::FileDiff>), crate::repos::RepoError> {

    let Some((fork, bookmark)) = parse_source(app, repo, source) else { return Ok((vec![], vec![])) };

    let target = target.to_string();

    let fork_dir = fork.as_ref().map(|f| app.repos.dir(f));

    app.repos

        .read(repo, move |r, cache| {

            let projection = match &fork_dir {

                Some(dir) => {

                    let fork_repo = oxy_core::repo::Repo::open(dir)?;

                    let heads = fork_repo.bookmarks()?.into_iter().find(|b| b.name == bookmark).map(|b| b.heads).unwrap_or_default();

                    pl::project(r, cache, &target, Source::Fork { fork: &fork_repo, heads })?

                }

                None => {

                    let heads = r.bookmarks()?.into_iter().find(|b| b.name == bookmark).map(|b| b.heads).unwrap_or_default();

                    pl::project(r, cache, &target, Source::Bookmark(heads))?

                }

            };

            Ok((projection.changes, projection.files))

        })

        .await

}

/// `POST /{owner}/{name}/proposals/new/draft`: an assistant drafts the

/// description from the changes the proposal would add; the form comes

/// back with the draft to edit (hub spec §13.4).

pub async fn new_draft(

    State(app): State<Shared>,

    viewer: Viewer,

    Path((owner, name)): Path<(String, String)>,

    Form(f): Form<NewForm>,

) -> Result<Page<NewProposalPage>, Error> {

    let shell = Shell::new(&app, &format!("/{owner}/{name}/proposals/new"), &viewer);

    let me = require(&viewer, &shell)?;

    csrf(&viewer, &f.csrf_token, &shell)?;

    let (repo, row, role) = lookup(&app, &shell, &viewer, &owner, &name).await?;

    let bookmarks =

        app.repos.read(&repo, |r, _| Ok(r.bookmarks()?.into_iter().map(|b| b.name).collect::<Vec<_>>())).await.unwrap_or_default();

    let (preview, conflicted) = preview_for(&app, &repo, &f.target, &f.source).await.unwrap_or((vec![], false));

    let assistants = if preview.is_empty() { vec![] } else { assistant_names(&app, &row).await };

    let mut page = NewProposalPage {

        shell,

        repo: RepoShell::new(&app, &row, "proposals").with_role(role),

        bookmarks,

        source: f.source.clone(),

        target: f.target.clone(),

        error: None,

        preview,

        conflicted,

        title: f.title.clone(),

        body: f.body.clone(),

        assistants,

    };

    let assistant = crate::assistants::enabled_for_repo(&app.db, &row)

        .await

        .unwrap_or_default()

        .into_iter()

        .find(|a| a.name.eq_ignore_ascii_case(f.assistant.trim()));

    let Some(a) = assistant else {

        page.error = Some(format!("No assistant called {} here.", f.assistant.trim()));

        return Ok(Page(page));

    };

    if page.preview.is_empty() {

        page.error = Some("Nothing to describe: the source adds nothing to the target.".into());

        return Ok(Page(page));

    }

    let (changes, diffs) = match preview_diff(&app, &repo, &f.target, &f.source).await {

        Ok(x) => x,

        Err(e) => {

            page.error = Some(e.to_string());

            return Ok(Page(page));

        }

    };

    let d = crate::assistants::Draft { slot: -row.id, title: &f.title, target: &f.target, changes: &changes, diffs: &diffs };

    match crate::assistants::draft_description(&app, &row, &me.account, &a, d).await {

        Ok(text) => page.body = text,

        Err(why) => page.error = Some(format!("{} did not answer: {why}.", a.name)),

    }

    Ok(Page(page))

}

#[derive(Deserialize)]

pub struct DraftForm {

    #[serde(rename = "_csrf")]

    csrf_token: String,

    assistant: String,

    #[serde(default)]

    title: String,

}

/// `POST /{owner}/{name}/proposal/{number}/draft`: an assistant drafts the

/// description of an open proposal from its changes; the editor opens

/// with the draft, nothing is saved (hub spec §13.4).

pub async fn draft(

    State(app): State<Shared>,

    viewer: Viewer,

    Path((owner, name, number)): Path<(String, String, i64)>,

    Form(f): Form<DraftForm>,

) -> Result<Response, Error> {

    let shell = Shell::new(&app, &format!("/{owner}/{name}/proposal/{number}"), &viewer);

    let me = require(&viewer, &shell)?;

    csrf(&viewer, &f.csrf_token, &shell)?;

    let (repo, row, role) = lookup(&app, &shell, &viewer, &owner, &name).await?;

    let p = pdb::get(&app.db, row.id, number)

        .await

        .map_err(|e| Error::from_db(shell.clone(), e))?

        .ok_or_else(|| Error::not_found(shell.clone()))?;

    if Some(me.account.id) != p.author_id && role < Role::Maintain {

        return Err(Error::not_found(shell));

    }

    let Some(a) = crate::assistants::enabled_for_repo(&app.db, &row)

        .await

        .map_err(|e| Error::from_db(shell.clone(), e))?

        .into_iter()

        .find(|a| a.name.eq_ignore_ascii_case(f.assistant.trim()))

    else {

        return Ok(back(&owner, &name, number, "conversation", None, Some(format!("No assistant called {} here.", f.assistant.trim()))));

    };

    let loaded = crate::web::proposals::load(&app, &repo, p.clone()).await.map_err(|e| Error::from_repo(shell.clone(), e))?;

    let title = if f.title.trim().is_empty() { p.title.clone() } else { f.title.clone() };

    let d = crate::assistants::Draft { slot: p.id, title: &title, target: &p.target, changes: &loaded.changes, diffs: &loaded.diffs };

    let draft = crate::assistants::draft_description(&app, &row, &me.account, &a, d).await;

    match draft {

        Ok(text) => {

            let mut page = detail(&app, shell, &viewer, &owner, &name, number, "conversation".into(), None, None).await?;

            page.0.draft = Some(text);

            Ok(page.into_response())

        }

        Err(why) => Ok(back(&owner, &name, number, "conversation", None, Some(format!("{} did not answer: {why}.", a.name)))),

/// A stand-in chat-completions endpoint that answers with a fixed review

/// and keeps the body of each call.

async fn mock_assistant(answer: &'static str) -> (String, std::sync::Arc<std::sync::Mutex<Vec<String>>>) {

    use std::sync::{Arc, Mutex};

    let seen: Arc<Mutex<Vec<String>>> = Arc::new(Mutex::new(vec![]));

    let s2 = seen.clone();

    let router = axum::Router::new().route(

        "/v1/chat/completions",

        axum::routing::post(move |headers: axum::http::HeaderMap, body: String| {

            let s2 = s2.clone();

            async move {

                let auth = headers.get("authorization").and_then(|v| v.to_str().ok()).unwrap_or("").to_string();

                s2.lock().unwrap().push(format!("{auth} {body}"));

                axum::Json(serde_json::json!({ "choices": [{ "message": { "role": "assistant", "content": answer } }] }))

            }

        }),

    );

    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();

    let port = listener.local_addr().unwrap().port();

    tokio::spawn(async move { axum::serve(listener, router).await.unwrap() });

    (format!("http://127.0.0.1:{port}/v1/chat/completions"), seen)

}

#[tokio::test(flavor = "multi_thread")]

async fn an_assistant_reviews_a_proposal_via_the_person_who_asked() {

    let h = hub().await;

    let app = &h.app;

    let andy = register(app, "andy").await;

    let bob = register(app, "bob").await;

    let repo = RepoName::parse("andy/demo").unwrap();

    app.repos.create(&repo, None).unwrap();

    db::repos::create(&app.db, "andy", "demo", "", hub_api::Visibility::Public).await.unwrap();

    let work = tempfile::tempdir().unwrap();

    let mut client = Repo::init(work.path()).unwrap();

    client.create_identity("Andy McCall", "[email protected]", oxy_core::repo::IdentityScope::User).unwrap();

    client.config.set("remote.origin.url", &format!("{}/andy/demo", h.base)).unwrap();

    client.config.set("remote.origin.token", "site").unwrap();

    client.config.set("core.sign", "change").unwrap();

    client.save_config().unwrap();

    write(work.path(), "a.txt", b"one\ntwo\n");

    client.snapshot("t").unwrap();

    let base = client.commit("base", &[]).unwrap();

    assert!(client.push("origin", false).unwrap().iter().all(|r| r.ok));

    client.bookmark_create("feature", Some(&[base])).unwrap();

    client.bookmark_switch("feature", false).unwrap();

    write(work.path(), "a.txt", b"one\ntwo\nthree\n");

    client.snapshot("t").unwrap();

    client.commit("add three", &[]).unwrap();

    assert!(client.push_bookmark("origin", "feature", false).unwrap().iter().all(|r| r.ok));

    let preview = get(app, "/andy/demo/proposals/new?source=feature&target=main", Some(&bob)).await;

    let csrf_b = csrf_of(&preview.body);

    let r = post(

        app,

        "/andy/demo/proposals/new",

        Some(&bob),

        &format!("_csrf={csrf_b}&title=Add+three&body=Please&target=main&source=feature"),

    )

    .await;

    assert_eq!(r.status, StatusCode::SEE_OTHER, "{}", r.body);

    // Nothing to ask until the site has an assistant.

    let page = get(app, "/andy/demo/proposal/1", Some(&bob)).await.body;

    assert!(!page.contains("ask Claude"), "{page}");

    let (endpoint, seen) = mock_assistant("**Summary.** Adds a third line.\n\n- a.txt line 3: fine.").await;

    let admin = get(app, "/admin", Some(&andy)).await.body;

    let csrf_a = csrf_of(&admin);

    let ep = endpoint.replace(':', "%3A").replace('/', "%2F");

    let r = post(

        app,

        "/admin/assistants",

        Some(&andy),

        &format!("_csrf={csrf_a}&action=add&name=Claude&endpoint={ep}&api=chat-completions&model=claude-opus-5-5&token=sk-test&enabled=1"),

    )

    .await;

    assert!(r.body.contains("Claude added."), "{}", r.body);

    let r =

        post(app, "/admin/assistants", Some(&andy), &format!("_csrf={csrf_a}&action=prompt&prompt=Review+for+correctness+first.")).await;

    assert!(r.body.contains("Prompt saved."), "{}", r.body);

    // Claude drafts a description for a proposal not yet opened, and for

    // the open one; neither is saved until the person says so.

    let page = get(app, "/andy/demo/proposals/new?source=feature&target=main", Some(&bob)).await.body;

    assert!(page.contains("draft with Claude"), "{page}");

    let r = post(

        app,

        "/andy/demo/proposals/new/draft",

        Some(&bob),

        &format!("_csrf={}&title=Add+three&body=&target=main&source=feature&assistant=Claude", csrf_of(&page)),

    )

    .await;

    assert_eq!(r.status, StatusCode::OK, "{}", r.body);

    assert!(r.body.contains("rows=\"8\">**Summary.** Adds a third line.") && r.body.contains("value=\"Add three\""), "{}", r.body);

    {

        let calls = seen.lock().unwrap();

        assert_eq!(calls.len(), 1);

        assert!(

            calls[0].contains("drafting the description") && calls[0].contains("+three") && calls[0].contains("Proposal: Add three"),

            "{}",

            calls[0]

        );

    }

    let page = get(app, "/andy/demo/proposal/1", Some(&bob)).await.body;

    assert!(page.contains("draft with Claude"), "{page}");

    let r =

        post(app, "/andy/demo/proposal/1/draft", Some(&bob), &format!("_csrf={}&assistant=Claude&title=Add+three", csrf_of(&page))).await;

    assert_eq!(r.status, StatusCode::OK, "{}", r.body);

    assert!(

        r.body.contains("tl-editform open") && r.body.contains("aria-label=\"Description (Markdown)\">**Summary.** Adds a third line."),

        "{}",

        r.body

    );

    assert!(r.body.contains("nothing is saved until you update"), "{}", r.body);

    assert_eq!(db::proposals::get(&app.db, 1, 1).await.unwrap().unwrap().body, "Please", "the description is untouched");

    assert_eq!(seen.lock().unwrap().len(), 2);

    seen.lock().unwrap().clear();

    // Andy approves; then Bob, the author, asks Claude.

    let page = get(app, "/andy/demo/proposal/1", Some(&andy)).await.body;

    let r = post(app, "/andy/demo/proposal/1/review", Some(&andy), &format!("_csrf={}&verdict=approve&body=good", csrf_of(&page))).await;

    assert_eq!(r.status, StatusCode::SEE_OTHER, "{}", r.body);

    let page = get(app, "/andy/demo/proposal/1", Some(&bob)).await.body;

    assert!(page.contains("ask Claude"), "{page}");

    let r = act(app, "/andy/demo/proposal/1/assistant", Some(&bob), &format!("_csrf={}&assistant=claude", csrf_of(&page))).await;

    assert!(r.body.contains("Asked Claude to review"), "{}", r.body);

    let mut reviews = vec![];

    for _ in 0..100 {

        reviews = db::proposals::reviews(&app.db, 1).await.unwrap();

        if reviews.iter().any(|r| r.via == "Claude") {

            break;

        }

        tokio::time::sleep(std::time::Duration::from_millis(100)).await;

    }

    let claude = reviews.iter().find(|r| r.via == "Claude").expect("the assistant's review arrived");

    assert_eq!((claude.author.as_str(), claude.verdict.as_str()), ("bob", "comment"));

    assert!(claude.body.contains("Adds a third line"));

    {

        let calls = seen.lock().unwrap();

        assert_eq!(calls.len(), 1);

        let c = &calls[0];

        assert!(c.starts_with("Bearer sk-test "), "{c}");

        assert!(

            c.contains("You are Claude") && c.contains("Review for correctness first."),

            "the system prompt and the site's prompt: {c}"

        );

        assert!(c.contains("Proposal #1: Add three") && c.contains("a.txt (modified)") && c.contains("+three"), "the context: {c}");

    }

    // Shown as Bob via Claude, with the event; Andy's approval still counts.

    let page = get(app, "/andy/demo/proposal/1", Some(&andy)).await.body;

    assert!(

        page.contains("<strong>bob</strong></a> <span class=\"mute\" aria-hidden=\"true\">↳</span> <span class=\"tag\"")

            && page.contains("<strong>Claude</strong>"),

        "{page}"

    );

    assert!(page.contains("asked Claude to review") && page.contains("Adds a third line"), "{page}");

    let p = db::proposals::get(&app.db, 1, 1).await.unwrap().unwrap();

    let loaded = oxygenhub::web::proposals::load(app, &repo, p).await.unwrap();

    let v = oxygenhub::web::proposals::verdict(app, &loaded, 1).await.unwrap();

    assert!(v.approvals.iter().any(|a| a.account == "andy"), "{:?}", v.approvals.iter().map(|a| &a.account).collect::<Vec<_>>());

    // The API lists the review via Claude and takes requests too.

    let r = send(app, "GET", "/api/v1/repos/andy/demo/proposals/1/reviews", None, None, None).await;

    assert!(r.body.contains("\"via\":\"Claude\""), "{}", r.body);

    // A stranger cannot ask; an unknown assistant is refused.

    post(app, "/andy/demo/proposal/1/assistant", None, "_csrf=x&assistant=Claude").await;

    assert_eq!(seen.lock().unwrap().len(), 1, "no call for a stranger");

    let page = get(app, "/andy/demo/proposal/1", Some(&bob)).await.body;

    let r = act(app, "/andy/demo/proposal/1/assistant", Some(&bob), &format!("_csrf={}&assistant=HAL", csrf_of(&page))).await;

    assert!(r.body.contains("No assistant called HAL"), "{}", r.body);

}

The author or a writer can **ask for a review** from anyone who can read the repository (not the author), under Reviewers on the proposal page or with `POST /api/v1/repos/{o}/{n}/proposals/{number}/reviewers` and `{"reviewers": [...]}`; `DELETE .../reviewers/{username}` withdraws a request. Each person asked gets a notification (`proposal.review_requested`), the timeline records it, the proposal's JSON lists `requested_reviewers`, and a review from that person answers the request. Every review notifies the proposal's author (`proposal.review`). An AI assistant the repository may use (§13.4) can be asked the same way; its answer is a `comment` review recorded via the assistant under the asker's name.

### 13.4 AI assistants (done 2026-10-04; settings API planned)

- **Request review.** Under Reviewers on the proposal page, the author or a writer sees an **ask NAME** button per assistant the repository may use. Asking records the event (`asked NAME to review`) and the audit entry (`assistant.asked`), then a background task builds the context (title, description, the list of changes, the diff of each changed file as `-`/`+` lines per hunk, binary files noted, the whole cut to the assistant's context budget less the prompt), prefixes a fixed system prompt (who it is, that it answers for the person who asked, that it cannot approve, the shape of a review) with the levels' prompts, calls the endpoint, and records the answer as a review of verdict `comment` whose author is the person who asked and whose **via** (migration 0036) is the assistant, shown as "bob ↳ agent Claude reviewed" in the timeline, exactly as agent-signed changes are shown (§6). An assistant never approves: approvals count only people, and an assistant's review never replaces the asker's own latest verdict. The proposal's author is told as for any review; the `review` webhook carries `via`. No answer leaves an event (`NAME did not answer: why`) and no review.

- **Draft the description.** The new-proposal form (anyone who may open one) and an open proposal's editor (the author or a maintainer) have a **draft with NAME** button per assistant. It asks the assistant, now, for a description from the title so far, the changes (titles and the first lines of their messages) and the diff, under a fixed system prompt (description field only, what and why, what to look at, how to verify) plus the levels' prompts, and puts the answer in the editor with a note; nothing is saved until the person updates or opens the proposal. The audit log records `assistant.drafted`; the same per-repository hourly limit applies.

- **Limits.** One request per assistant per proposal at a time, 30 assistant calls per repository per hour (in memory), a 60-second call timeout, answers kept to 64 KiB, and a context budget (characters) per assistant.

- **API.** `POST /repos/{o}/{n}/proposals/{n}/review-requests {"assistant": NAME}` (the author or a writer; 202 when started, 409 when that assistant is already answering or the repository is over its hourly limit, 422 for a name the repository cannot use); reviews carry `via`. Settings endpoints are planned. Hub actions by an assistant are attributed "ASSISTANT via WHO" everywhere, so a project can require that a human has approved regardless of what an assistant said.

    <li>Where the site, an organisation or a repository has set up <strong>AI assistants</strong> (Settings), you can ask one to review under Reviewers, or have it draft the description; its answer is recorded as yours <em>via</em> the assistant, with an <span class="tag">agent</span> badge. Only people approve.</li>

      <form class="tl-editform{% if draft.is_some() %} open{% endif %}" id="edit" method="post" action="{{ repo.url }}/proposal/{{ p.number }}/edit">

        <textarea id="ebody" name="body" class="md" rows="10" aria-label="Description (Markdown)">{% if let Some(d) = draft %}{{ d }}{% else %}{{ p.body }}{% endif %}</textarea>

        {% if draft.is_some() %}<p class="small mute">Drafted by an assistant; nothing is saved until you update the proposal.</p>{% endif %}

        <div class="tl-actions"><a class="go" href="#description">Cancel</a> {% for a in assistants %}<button type="submit" class="small" formaction="{{ repo.url }}/proposal/{{ p.number }}/draft" formnovalidate name="assistant" value="{{ a }}" title="{{ a }}, an AI assistant, drafts the description from the changes; you edit it before saving"><span class="tag">agent</span> draft with {{ a }}</button> {% endfor %}<button type="submit" class="primary-btn">Update proposal</button></div>

      <div class="tl-head"><a href="/{{ r.row.author }}"><strong>{{ r.row.author }}</strong></a>{% if !r.row.via.is_empty() %} <span class="mute" aria-hidden="true">↳</span> <span class="tag" title="An AI assistant answered for {{ r.row.author }}, who asked it">agent</span> <strong>{{ r.row.via }}</strong>{% endif %} {% if r.row.verdict == "approve" %}{% if r.sealed %}<span class="sig sig-valid">◈</span> approved and sealed{% else %}<span class="sig sig-unsigned">○</span> approved, seal pending{% endif %}{% else if r.row.verdict == "changes" %}<span class="sig sig-invalid">✘</span> requested changes{% else %}reviewed{% endif %} <time title="{{ r.row.created_ms|when_i }}">{{ r.row.created_ms|ago_i }}</time></div>

    {% if !assistants.is_empty() %}<div class="side-assist">{% for a in assistants %}<form class="tiny inline" method="post" action="{{ repo.url }}/proposal/{{ p.number }}/assistant"><input type="hidden" name="_csrf" value="{{ shell.csrf }}"><input type="hidden" name="assistant" value="{{ a }}"><button type="submit" title="Ask {{ a }}, an AI assistant, to review; its answer is recorded as your review via {{ a }}"><span class="tag">agent</span> ask {{ a }}</button></form>{% endfor %}</div>{% endif %}

  <label for="title">Title</label><input type="text" id="title" name="title" required value="{% if !title.is_empty() %}{{ title }}{% else if preview.len() == 1 %}{{ preview[0].title }}{% endif %}">

  <label for="body">Description (Markdown)</label><textarea id="body" name="body" class="md" rows="8">{{ body }}</textarea>

  {% if !assistants.is_empty() %}<div class="side-assist">{% for a in assistants %}<button type="submit" class="small" formaction="{{ repo.url }}/proposals/new/draft" formnovalidate name="assistant" value="{{ a }}" title="{{ a }}, an AI assistant, drafts the description from the changes; you edit it before opening"><span class="tag">agent</span> draft with {{ a }}</button>{% endfor %}</div>{% endif %}

.side-assist { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 8px; }

.side-assist form.inline { display: inline; margin: 0; }

.tl-editform:target, .tl-editform.open { display: block; }

.tl-card:has(.tl-editform:target) .tl-view, .tl-card:has(.tl-editform.open) .tl-view { display: none; }