Watch
0
0
Fork
You've already forked hyperhive
0

Compare commits

...
61 changed files with 2740 additions and 1914 deletions

View file

@ -32,8 +32,9 @@ hand-maintained per-file tree drifts out of sync with the code.
the meta flake, lifecycle (`nixos-container` shellouts), gateway / the meta flake, lifecycle (`nixos-container` shellouts), gateway /
forge / matrix provisioning, per-container stats, and the axum forge / matrix provisioning, per-container stats, and the axum
operator dashboard (`dashboard.rs`). Largest crate. operator dashboard (`dashboard.rs`). Largest crate.
- **`hive-ag3nt/`** — in-container harness; one `hive` binary for every - **`hive-ag3nt/`** — in-container harness; three sibling binaries for
agent. Turn-loop *policy* layer (`turn.rs`) over the `hive-claude` every agent (`hive-agent` serve loop, `hive-agent-mcp`,
`hive-agent-wake`). Turn-loop *policy* layer (`turn.rs`) over the `hive-claude`
driver, embedded MCP server (`mcp.rs`) + its claude launch-config layer driver, embedded MCP server (`mcp.rs`) + its claude launch-config layer
(`mcp_config.rs`: tool-group/capability → `--allowedTools`, `--mcp-config` (`mcp_config.rs`: tool-group/capability → `--allowedTools`, `--mcp-config`
render), per-agent web UI (`web_ui/` module dir), event + turn-stats render), per-agent web UI (`web_ui/` module dir), event + turn-stats

93
Cargo.lock generated
View file

@ -630,6 +630,16 @@ version = "0.4.2"
source = "registry+https://github.com/rust-lang/crates.io-index" source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3d52eff69cd5e647efe296129160853a42795992097e8af39800e1060caeea9b" checksum = "3d52eff69cd5e647efe296129160853a42795992097e8af39800e1060caeea9b"
[[package]]
name = "core-foundation"
version = "0.9.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "91e195e091a93c46f7102ec7818a2aa394e1e1771c3ab4825963fa03e45afb8f"
dependencies = [
"core-foundation-sys",
"libc",
]
[[package]] [[package]]
name = "core-foundation" name = "core-foundation"
version = "0.10.1" version = "0.10.1"
@ -862,6 +872,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7cd812cc2bc1d69d4764bd80df88b4317eaef9e773c75226407d9bc0876b211c" checksum = "7cd812cc2bc1d69d4764bd80df88b4317eaef9e773c75226407d9bc0876b211c"
dependencies = [ dependencies = [
"powerfmt", "powerfmt",
"serde_core",
] ]
[[package]] [[package]]
@ -924,6 +935,15 @@ version = "1.16.0"
source = "registry+https://github.com/rust-lang/crates.io-index" source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "91622ff5e7162018101f2fea40d6ebf4a78bbe5a49736a2020649edf9693679e" checksum = "91622ff5e7162018101f2fea40d6ebf4a78bbe5a49736a2020649edf9693679e"
[[package]]
name = "encoding_rs"
version = "0.8.35"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "75030f3c4f45dafd7586dd6780965a8c7e8e285a5ecb86713e63a79c5b2766f3"
dependencies = [
"cfg-if",
]
[[package]] [[package]]
name = "equivalent" name = "equivalent"
version = "1.0.2" version = "1.0.2"
@ -1057,6 +1077,27 @@ version = "0.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index" source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2" checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2"
[[package]]
name = "forgejo-api"
version = "0.11.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4c51fffa047d5836a4d89179a20b21b7e41ad97e713104752169d819b83c9158"
dependencies = [
"base64ct",
"bytes",
"futures",
"reqwest",
"serde",
"serde_json",
"soft_assert",
"thiserror 1.0.69",
"time",
"tokio",
"url",
"urlencoding",
"zeroize",
]
[[package]] [[package]]
name = "form_urlencoded" name = "form_urlencoded"
version = "1.2.2" version = "1.2.2"
@ -1338,6 +1379,7 @@ dependencies = [
"anyhow", "anyhow",
"axum", "axum",
"clap", "clap",
"forgejo-api",
"futures-util", "futures-util",
"hive-claude", "hive-claude",
"hive-sh4re", "hive-sh4re",
@ -1348,11 +1390,13 @@ dependencies = [
"serde", "serde",
"serde_json", "serde_json",
"tempfile", "tempfile",
"time",
"tokio", "tokio",
"tokio-stream", "tokio-stream",
"tower-http", "tower-http",
"tracing", "tracing",
"tracing-subscriber", "tracing-subscriber",
"url",
] ]
[[package]] [[package]]
@ -1384,6 +1428,7 @@ dependencies = [
"clap", "clap",
"clap-markdown", "clap-markdown",
"clap_complete", "clap_complete",
"forgejo-api",
"hive-sh4re", "hive-sh4re",
"libc", "libc",
"listenfd", "listenfd",
@ -1398,6 +1443,7 @@ dependencies = [
"tokio-stream", "tokio-stream",
"tracing", "tracing",
"tracing-subscriber", "tracing-subscriber",
"url",
] ]
[[package]] [[package]]
@ -1417,9 +1463,12 @@ version = "0.1.0"
dependencies = [ dependencies = [
"anyhow", "anyhow",
"clap", "clap",
"forgejo-api",
"reqwest", "reqwest",
"serde", "serde",
"serde_json", "serde_json",
"time",
"url",
] ]
[[package]] [[package]]
@ -1631,9 +1680,11 @@ dependencies = [
"percent-encoding", "percent-encoding",
"pin-project-lite", "pin-project-lite",
"socket2", "socket2",
"system-configuration",
"tokio", "tokio",
"tower-service", "tower-service",
"tracing", "tracing",
"windows-registry",
] ]
[[package]] [[package]]
@ -3018,6 +3069,7 @@ checksum = "eddd3ca559203180a307f12d114c268abf583f59b03cb906fd0b3ff8646c1147"
dependencies = [ dependencies = [
"base64", "base64",
"bytes", "bytes",
"encoding_rs",
"futures-channel", "futures-channel",
"futures-core", "futures-core",
"futures-util", "futures-util",
@ -3030,6 +3082,7 @@ dependencies = [
"hyper-util", "hyper-util",
"js-sys", "js-sys",
"log", "log",
"mime",
"mime_guess", "mime_guess",
"percent-encoding", "percent-encoding",
"pin-project-lite", "pin-project-lite",
@ -3457,7 +3510,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b7f4bc775c73d9a02cde8bf7b2ec4c9d12743edf609006c7facc23998404cd1d" checksum = "b7f4bc775c73d9a02cde8bf7b2ec4c9d12743edf609006c7facc23998404cd1d"
dependencies = [ dependencies = [
"bitflags", "bitflags",
"core-foundation", "core-foundation 0.10.1",
"core-foundation-sys", "core-foundation-sys",
"libc", "libc",
"security-framework-sys", "security-framework-sys",
@ -3689,6 +3742,12 @@ dependencies = [
"windows-sys 0.61.2", "windows-sys 0.61.2",
] ]
[[package]]
name = "soft_assert"
version = "0.1.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b5097ec7ea7218135541ad96348f1441d0c616537dd4ed9c47205920c35d7d97"
[[package]] [[package]]
name = "spki" name = "spki"
version = "0.7.3" version = "0.7.3"
@ -3786,6 +3845,27 @@ dependencies = [
"syn", "syn",
] ]
[[package]]
name = "system-configuration"
version = "0.7.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a13f3d0daba03132c0aa9767f98351b3488edc2c100cda2d2ec2b04f3d8d3c8b"
dependencies = [
"bitflags",
"core-foundation 0.9.4",
"system-configuration-sys",
]
[[package]]
name = "system-configuration-sys"
version = "0.6.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8e1d1b10ced5ca923a1fcb8d03e96b8d3268065d724548c0211415ff6ac6bac4"
dependencies = [
"core-foundation-sys",
"libc",
]
[[package]] [[package]]
name = "tempfile" name = "tempfile"
version = "3.27.0" version = "3.27.0"
@ -4596,6 +4676,17 @@ version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index" source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
[[package]]
name = "windows-registry"
version = "0.6.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "02752bf7fbdcce7f2a27a742f798510f3e5ad88dbe84871e5168e2120c3d5720"
dependencies = [
"windows-link",
"windows-result",
"windows-strings",
]
[[package]] [[package]]
name = "windows-result" name = "windows-result"
version = "0.4.1" version = "0.4.1"

View file

@ -68,6 +68,14 @@ reqwest = { version = "0.12", default-features = false, features = [
"json", "json",
"rustls-tls", "rustls-tls",
] } ] }
forgejo-api = { version = "0.11", default-features = false, features = [
"rustls-tls",
] }
url = "2"
time = { version = "0.3", default-features = false, features = [
"formatting",
"parsing",
] }
petgraph = { version = "0.8", default-features = false, features = ["std"] } petgraph = { version = "0.8", default-features = false, features = ["std"] }
matrix-sdk = { version = "0.14", default-features = false, features = [ matrix-sdk = { version = "0.14", default-features = false, features = [
"rustls-tls", "rustls-tls",

View file

@ -214,7 +214,8 @@ nspawn agent. Open questions, not yet wired:
## Harness systemd unit shape ## Harness systemd unit shape
One harness binary (`hive`), one `harness-base.nix` template, one One harness serve binary (`hive-agent`, with its `hive-agent-mcp` /
`hive-agent-wake` siblings), one `harness-base.nix` template, one
service unit (`systemd.services.hive-ag3nt`) for all agents. There service unit (`systemd.services.hive-ag3nt`) for all agents. There
is no longer a separate manager service name or role distinction in is no longer a separate manager service name or role distinction in
the harness — privilege differences live server-side in the broker the harness — privilege differences live server-side in the broker
@ -259,7 +260,8 @@ bit set` regardless of `hyperhive.user.passwordlessSudo`.
### `serviceConfig` highlights ### `serviceConfig` highlights
- `ExecStart = pkgs.hyperhive/bin/hive serve` — single binary. - `ExecStart = pkgs.hyperhive/bin/hive-agent` — same binary for
every agent.
- `Restart = on-failure`, `RestartSec = 2` — keeps the harness - `Restart = on-failure`, `RestartSec = 2` — keeps the harness
resilient across transient crashes without thundering retries. resilient across transient crashes without thundering retries.
- `RuntimeDirectory = "hive-config"` → `/run/hive-config/` owned by - `RuntimeDirectory = "hive-config"` → `/run/hive-config/` owned by

View file

@ -71,7 +71,12 @@ Two things live in the `agent-configs` Forgejo organization:
The `hive-forge` CLI (separate workspace crate, see The `hive-forge` CLI (separate workspace crate, see
[`README.md`](../README.md) file map) wraps the Forgejo REST API [`README.md`](../README.md) file map) wraps the Forgejo REST API
with the per-agent token; agents call it for issue / PR / comment with the per-agent token; agents call it for issue / PR / comment
ops as if it were a peer. ops as if it were a peer. All REST calls across the workspace
(`hive-forge` verbs, hive-c0re provisioning, this poller) go through
the typed `forgejo-api` crate; only non-`/api/v1` web-router routes
(attachment / artifact downloads, log streaming) and the poller's
enrichment fetches of server-provided subject URLs stay on raw
reqwest.
## Notification poller (`hive-ag3nt/src/forge_notify.rs`) ## Notification poller (`hive-ag3nt/src/forge_notify.rs`)
@ -146,11 +151,14 @@ one path still marked-read directly (no read-before-comment value).
The poller starts disabled and stays that way for any of: The poller starts disabled and stays that way for any of:
- `HIVE_FORGE_URL` not set (no forge configured for this hive). - `HIVE_FORGE_URL` not set (no forge configured for this hive), or
not parseable as a URL.
- `<state>/forge-token` missing or empty (agent has no forge - `<state>/forge-token` missing or empty (agent has no forge
account — pre-provisioning or destroy-without-purge race). account — pre-provisioning or destroy-without-purge race).
- Initial `reqwest::Client::builder` fails (extremely unlikely; - Initial client construction fails (the typed `forgejo-api` client
treated as fatal-to-the-task only). for the API calls, or the plain reqwest client kept for the
best-effort enrichment fetches of server-provided subject URLs;
both extremely unlikely; treated as fatal-to-the-task only).
Disabled = the spawned task returns immediately. All other failure Disabled = the spawned task returns immediately. All other failure
modes (HTTP errors, parse errors, mark-read failures) are modes (HTTP errors, parse errors, mark-read failures) are

View file

@ -5,7 +5,8 @@ claude has access to in return.
## The loop ## The loop
Each agent harness (`hive serve` — one binary for all agents) runs: Each agent harness (`hive-agent` — one serve-loop binary for all
agents) runs:
1. Long-poll `Recv` on its socket. The host-side broker 1. Long-poll `Recv` on its socket. The host-side broker
(`broker.rs::recv_blocking_batch`) returns immediately if there's (`broker.rs::recv_blocking_batch`) returns immediately if there's
@ -51,38 +52,37 @@ Each agent harness (`hive serve` — one binary for all agents) runs:
## Harness binary shape ## Harness binary shape
One `hive` binary for all agents. The earlier split into Three sibling binaries out of the one `hive-ag3nt` crate, all
`hive-ag3nt` + `hive-m1nd` was collapsed because the privilege role-agnostic. (The earlier split into `hive-ag3nt` + `hive-m1nd`
boundary lives server-side at the broker socket was collapsed because the privilege boundary lives server-side at
(`/run/hive/mcp.sock`): `ManagerRequest` calls are refused by the the broker socket (`/run/hive/mcp.sock`): `ManagerRequest` calls are
standard agent socket regardless of who sends them. refused by the standard agent socket regardless of who sends them.)
Three subcommands: - `hive-agent` — long-running harness loop (the inbox poll +
- `serve` — long-running harness loop (the inbox poll +
claude-pump + ack/requeue cycle described above). claude-pump + ack/requeue cycle described above).
- `mcp` — MCP server. Default: stdio child claude spawns via - `hive-agent-mcp` — MCP server. Default: stdio child claude spawns
`--mcp-config` per turn. With `--http <addr>`, runs as a persistent via `--mcp-config` per turn (the serve loop renders the config to
streamable-HTTP daemon instead (used by the `hive-mcp-http` point at this sibling of its own `/proc/self/exe`). With
systemd unit when `hyperhive.mcp.httpPort` is set). `--http <addr>`, runs as a persistent streamable-HTTP daemon
- `wake --from <name> --body <body>` — push a message into our own instead (used by the `hive-mcp-http` systemd unit when
inbox so the next turn fires with the given body. Used by `hyperhive.mcp.httpPort` is set).
co-process daemons (matrix bridge, scraper, webhook listeners) - `hive-agent-wake --from <name> --body <body>` — push a message into
to nudge claude on external events. `--body -` reads from stdin. our own inbox so the next turn fires with the given body. Used by
co-process helpers (scrapers, webhook listeners) to nudge claude on
external events. `--body -` reads from stdin.
### `Surface` trait + zero-sized type tags ### `Surface` trait + zero-sized type tags
`AgentRequest` / `AgentResponse` (= `ManagerRequest` / `ManagerResponse` — `AgentRequest` / `AgentResponse` (= `ManagerRequest` / `ManagerResponse` —
type aliases) are the wire types. There is one role: agent. type aliases) are the wire types. There is one role: agent.
`bin/hive.rs` factors the turn loop through a `Surface` trait with one `bin/hive-agent.rs` factors the turn loop through a `Surface` trait
zero-sized impl (`AgentSurface`) wrapping: with one zero-sized impl (`AgentSurface`) wrapping:
- One async method per wire op: `ack_turn`, `requeue_inflight`, - One async method per wire op: `ack_turn`, `requeue_inflight`,
`inbox_unread`, `post_turn_counts`, `send_to_parent`, `inbox_unread`, `post_turn_counts`, `send_to_parent`, `recv_next`.
`recv_next`, `wake_external`.
`main()` calls `serve_main::<AgentSurface>` for all roles. The turn `main()` calls `serve_main::<AgentSurface>` for all roles. The turn
loop (`serve_loop` / `handle_turn` / `wake`) has no per-role branches. loop (`serve_loop` / `handle_turn`) has no per-role branches.
### Boot wiring ### Boot wiring

View file

@ -138,7 +138,7 @@ External MCP servers (and any other in-container process) can
inject a wake-up event into the agent's inbox via the per-agent inject a wake-up event into the agent's inbox via the per-agent
socket at `/run/hive/mcp.sock`. Two equivalent paths: socket at `/run/hive/mcp.sock`. Two equivalent paths:
- **Shell out to `hive wake --from <label> --body <text>`** - **Shell out to `hive-agent-wake --from <label> --body <text>`**
(use `--body -` to read body from stdin). Already on the (use `--body -` to read body from stdin). Already on the
container's `PATH` since the harness binary is in container's `PATH` since the harness binary is in
`systemPackages`. Convenient for shell-script integrations and `systemPackages`. Convenient for shell-script integrations and

View file

@ -10,6 +10,9 @@ workspace = true
anyhow.workspace = true anyhow.workspace = true
axum.workspace = true axum.workspace = true
reqwest.workspace = true reqwest.workspace = true
forgejo-api.workspace = true
url.workspace = true
time.workspace = true
futures-util = "0.3" futures-util = "0.3"
clap.workspace = true clap.workspace = true
hive-claude.workspace = true hive-claude.workspace = true
@ -28,9 +31,8 @@ tracing-subscriber.workspace = true
[dev-dependencies] [dev-dependencies]
tempfile = "3" tempfile = "3"
[[bin]] # Three sibling harness binaries for all agents (auto-discovered from
# Unified harness binary for all agents. Privilege boundary is # `src/bin/`): `hive-agent` (serve loop), `hive-agent-mcp` (MCP
# server), `hive-agent-wake` (wake CLI). Privilege boundary is
# enforced server-side at the socket (tool groups / manager surface). # enforced server-side at the socket (tool groups / manager surface).
# See `docs/turn-loop.md::Harness binary shape`. # See `docs/turn-loop.md::Harness binary shape`.
name = "hive"
path = "src/bin/hive.rs"

View file

@ -0,0 +1,43 @@
//! MCP-server binary. Default is stdio — spawned by `claude` via
//! `--mcp-config`; tools dispatch through `/run/hive/mcp.sock` back into
//! the hyperhive broker. Pass `--http <addr>` to instead run a long-lived
//! streamable-http listener (persistent daemon, the `hive-mcp-http`
//! systemd unit) that claude reconnects to each turn, avoiding the
//! per-turn stdio re-registration race. Sibling of `hive-agent` (the
//! serve loop that renders the `--mcp-config` blob pointing here) and
//! `hive-agent-wake`.
use std::path::PathBuf;
use anyhow::Result;
use clap::Parser;
use hive_ag3nt::{DEFAULT_SOCKET, mcp};
#[derive(Parser)]
#[command(name = "hive-agent-mcp", about = "hyperhive MCP server")]
struct Cli {
/// Path to the per-agent MCP socket (bind-mounted from the host).
#[arg(long, default_value = DEFAULT_SOCKET)]
socket: PathBuf,
/// Serve over streamable-http on this address (e.g.
/// `127.0.0.1:8790`) instead of stdio. Bind loopback only.
#[arg(long)]
http: Option<std::net::SocketAddr>,
}
#[tokio::main]
async fn main() -> Result<()> {
tracing_subscriber::fmt()
.with_env_filter(
tracing_subscriber::EnvFilter::try_from_default_env()
.unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("info")),
)
.init();
let cli = Cli::parse();
match cli.http {
Some(addr) => mcp::serve_http(cli.socket, addr).await,
None => mcp::serve_agent_stdio(cli.socket).await,
}
}

View file

@ -0,0 +1,60 @@
//! Wake CLI: inject a wake-up event into this container's harness inbox
//! so the next turn fires with the given body. Intended for extra MCP
//! servers / helpers (scraper, webhook listener, etc.) that need to
//! nudge claude on external events; the built-in daemons (matrix, bash)
//! talk to the socket directly instead. Sibling of `hive-agent` and
//! `hive-agent-mcp`.
use std::path::PathBuf;
use anyhow::Result;
use clap::Parser;
use hive_ag3nt::{DEFAULT_SOCKET, client};
use hive_sh4re::{AgentRequest, AgentResponse};
#[derive(Parser)]
#[command(name = "hive-agent-wake", about = "hyperhive harness wake signal")]
struct Cli {
/// Path to the per-agent MCP socket (bind-mounted from the host).
#[arg(long, default_value = DEFAULT_SOCKET)]
socket: PathBuf,
#[arg(long)]
from: String,
/// Body of the wake message. Pass `-` to read from stdin.
#[arg(long)]
body: String,
}
#[tokio::main]
async fn main() -> Result<()> {
tracing_subscriber::fmt()
.with_env_filter(
tracing_subscriber::EnvFilter::try_from_default_env()
.unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("info")),
)
.init();
let cli = Cli::parse();
let body = if cli.body == "-" {
let mut buf = String::new();
std::io::Read::read_to_string(&mut std::io::stdin(), &mut buf)?;
buf
} else {
cli.body
};
let resp: AgentResponse = client::request(
&cli.socket,
&AgentRequest::Wake {
from: cli.from,
body,
},
)
.await?;
match resp {
AgentResponse::Ok => Ok(()),
AgentResponse::Err { message } => anyhow::bail!("wake: {message}"),
other => anyhow::bail!("wake: unexpected response {other:?}"),
}
}

View file

@ -1,7 +1,9 @@
//! Unified hyperhive harness binary. Dispatches one of three subcommands //! Harness serve-loop binary. Long-polls the broker inbox and drives one
//! (`serve` / `mcp` / `wake`). There is one role: agent. The `Surface` //! claude turn per message. There is one role: agent. The `Surface`
//! trait + `AgentSurface` zero-sized type tag keeps the turn loop //! trait + `AgentSurface` zero-sized type tag keeps the turn loop
//! generic and testable. Architecture lives in //! generic and testable. Siblings: `hive-agent-mcp` (the MCP server this
//! loop points claude at) and `hive-agent-wake` (external wake CLI).
//! Architecture lives in
//! [`docs/turn-loop.md::Harness binary shape`](../../../docs/turn-loop.md). //! [`docs/turn-loop.md::Harness binary shape`](../../../docs/turn-loop.md).
use std::path::{Path, PathBuf}; use std::path::{Path, PathBuf};
@ -9,58 +11,23 @@ use std::sync::{Arc, Mutex};
use std::time::Duration; use std::time::Duration;
use anyhow::Result; use anyhow::Result;
use clap::{Parser, Subcommand}; use clap::Parser;
use hive_ag3nt::events::{Bus, LiveEvent, TurnState}; use hive_ag3nt::events::{Bus, LiveEvent, TurnState};
use hive_ag3nt::login::{self, LoginState}; use hive_ag3nt::login::{self, LoginState};
use hive_ag3nt::turn_stats::TurnStats; use hive_ag3nt::turn_stats::TurnStats;
use hive_ag3nt::{ use hive_ag3nt::{DEFAULT_SOCKET, DEFAULT_WEB_PORT, client, plugins, serve_common, turn, web_ui};
DEFAULT_SOCKET, DEFAULT_WEB_PORT, client, mcp, plugins, serve_common, turn, web_ui,
};
use hive_sh4re::{AgentRequest, AgentResponse, HelperEvent, SYSTEM_SENDER}; use hive_sh4re::{AgentRequest, AgentResponse, HelperEvent, SYSTEM_SENDER};
#[derive(Parser)] #[derive(Parser)]
#[command(name = "hive", about = "hyperhive harness")] #[command(name = "hive-agent", about = "hyperhive harness serve loop")]
struct Cli { struct Cli {
/// Path to the per-agent MCP socket (bind-mounted from the host). /// Path to the per-agent MCP socket (bind-mounted from the host).
#[arg(long, global = true, default_value = DEFAULT_SOCKET)] #[arg(long, default_value = DEFAULT_SOCKET)]
socket: PathBuf, socket: PathBuf,
#[command(subcommand)] /// Inbox poll interval in milliseconds.
cmd: Cmd, #[arg(long, default_value_t = 1000)]
} poll_ms: u64,
#[derive(Subcommand)]
enum Cmd {
/// Run the long-lived harness loop. Polls inbox; replies via
/// `claude --print` when available.
Serve {
/// Inbox poll interval in milliseconds.
#[arg(long, default_value_t = 1000)]
poll_ms: u64,
},
/// Run the MCP server. Default is stdio — spawned by `claude` via
/// `--mcp-config`; tools dispatch through `/run/hive/mcp.sock` back
/// into the hyperhive broker. Pass `--http <addr>` to instead run a
/// long-lived streamable-http listener (persistent daemon) that
/// claude reconnects to each turn, avoiding the per-turn stdio
/// re-registration race.
Mcp {
/// Serve over streamable-http on this address (e.g.
/// `127.0.0.1:8790`) instead of stdio. Bind loopback only.
#[arg(long)]
http: Option<std::net::SocketAddr>,
},
/// Inject a wake-up event into this harness's inbox so the next
/// turn fires with the given body. Intended for extra MCP servers
/// / helpers (matrix bridge, scraper, webhook listener, etc.) that
/// need to nudge claude on external events.
Wake {
#[arg(long)]
from: String,
/// Body of the wake message. Pass `-` to read from stdin.
#[arg(long)]
body: String,
},
} }
#[tokio::main] #[tokio::main]
@ -73,15 +40,7 @@ async fn main() -> Result<()> {
.init(); .init();
let cli = Cli::parse(); let cli = Cli::parse();
serve_main::<AgentSurface>(&cli.socket, cli.poll_ms).await
match cli.cmd {
Cmd::Serve { poll_ms } => serve_main::<AgentSurface>(&cli.socket, poll_ms).await,
Cmd::Mcp { http } => match http {
Some(addr) => mcp::serve_http(cli.socket, addr).await,
None => mcp::serve_agent_stdio(cli.socket).await,
},
Cmd::Wake { from, body } => wake::<AgentSurface>(&cli.socket, from, body).await,
}
} }
// ---------- shared turn helpers ---------- // ---------- shared turn helpers ----------
@ -261,13 +220,6 @@ trait Surface {
/// generic `serve_loop` doesn't need the per-role Response enum /// generic `serve_loop` doesn't need the per-role Response enum
/// at all. /// at all.
fn recv_next(socket: &Path) -> impl Future<Output = RecvOutcome>; fn recv_next(socket: &Path) -> impl Future<Output = RecvOutcome>;
/// External `wake` subcommand (the `hive wake` CLI command, used
/// by co-process daemons like matrix to push events into the
/// harness inbox). Errors out via `anyhow::bail!` so the calling
/// binary surfaces them on stderr.
fn wake_external(socket: &Path, from: String, body: String)
-> impl Future<Output = Result<()>>;
} }
// ---------- AgentSurface ---------- // ---------- AgentSurface ----------
@ -383,16 +335,6 @@ impl Surface for AgentSurface {
} }
} }
} }
async fn wake_external(socket: &Path, from: String, body: String) -> Result<()> {
let resp: AgentResponse =
client::request(socket, &AgentRequest::Wake { from, body }).await?;
match resp {
AgentResponse::Ok => Ok(()),
AgentResponse::Err { message } => anyhow::bail!("wake: {message}"),
other => anyhow::bail!("wake: unexpected response {other:?}"),
}
}
} }
// ---------- generic turn loop ---------- // ---------- generic turn loop ----------
@ -673,20 +615,6 @@ async fn handle_turn<S: Surface>(
} }
} }
/// External `hive wake` subcommand — push a message into our own
/// inbox so the next turn fires with the given body. Reads the body
/// from stdin when `body == "-"`.
async fn wake<S: Surface>(socket: &Path, from: String, body: String) -> Result<()> {
let body = if body == "-" {
let mut buf = String::new();
std::io::Read::read_to_string(&mut std::io::stdin(), &mut buf)?;
buf
} else {
body
};
S::wake_external(socket, from, body).await
}
#[cfg(test)] #[cfg(test)]
mod continue_tests { mod continue_tests {
use super::{TurnControl, should_self_continue, synthetic_continue}; use super::{TurnControl, should_self_continue, synthetic_continue};

View file

@ -24,9 +24,18 @@ use std::fmt::Write as _;
use std::path::{Path, PathBuf}; use std::path::{Path, PathBuf};
use std::time::Duration; use std::time::Duration;
use forgejo_api::structs::{
NotificationThread, NotifyGetListQuery, NotifyReadThreadQuery, NotifySubjectType,
};
use forgejo_api::{Auth, Forgejo, ForgejoError};
use time::OffsetDateTime;
use time::format_description::well_known::Rfc3339;
use tracing::{debug, info, warn}; use tracing::{debug, info, warn};
const POLL_INTERVAL_SECS: u64 = 30; const POLL_INTERVAL_SECS: u64 = 30;
/// Per-request cap applied to every forge call — natively on the reqwest
/// enrichment client, via `tokio::time::timeout` around the typed
/// `forgejo-api` client (which exposes no timeout knob of its own).
const HTTP_TIMEOUT_SECS: u64 = 10; const HTTP_TIMEOUT_SECS: u64 = 10;
/// Page size of the unread-notifications fetch. This is also the hard /// Page size of the unread-notifications fetch. This is also the hard
/// bound on the persisted delivery-dedupe cursor: each poll prunes the /// bound on the persisted delivery-dedupe cursor: each poll prunes the
@ -52,7 +61,7 @@ const TOKEN_RETRY_MAX: u32 = 20;
/// claim it's "new" — see docs/forge.md, "new vs activity on". /// claim it's "new" — see docs/forge.md, "new vs activity on".
const NEW_ITEM_TOLERANCE_SECS: i64 = 120; const NEW_ITEM_TOLERANCE_SECS: i64 = 120;
/// Spawn point: called once from `hive serve`. Returns immediately if the forge is not /// Spawn point: called once from the `hive-agent` serve loop. Returns immediately if the forge is not
/// configured. Otherwise loops forever, polling every /// configured. Otherwise loops forever, polling every
/// `POLL_INTERVAL_SECS` seconds. Errors are never fatal. /// `POLL_INTERVAL_SECS` seconds. Errors are never fatal.
/// ///
@ -97,6 +106,27 @@ pub async fn run(socket: PathBuf) {
} }
}; };
// Typed Forgejo client for the API calls with stable shapes (identity
// probe, notification list, mark-read). The plain reqwest client below
// stays for the best-effort enrichment fetches of `subject.url` /
// `latest_comment_url`: those follow server-provided URLs whose payload
// shape is heterogeneous (issue vs comment vs review), which the typed
// client cannot express (its `Endpoint` trait is sealed).
let base_url = match url::Url::parse(&forge_url) {
Ok(u) => u,
Err(e) => {
warn!("forge_notify: invalid HIVE_FORGE_URL {forge_url}: {e}");
return;
}
};
let forge = match Forgejo::new(Auth::Token(&token), base_url) {
Ok(f) => f,
Err(e) => {
warn!("forge_notify: failed to build forge client: {e}");
return;
}
};
let client = match reqwest::Client::builder() let client = match reqwest::Client::builder()
.timeout(Duration::from_secs(HTTP_TIMEOUT_SECS)) .timeout(Duration::from_secs(HTTP_TIMEOUT_SECS))
.build() .build()
@ -111,13 +141,15 @@ pub async fn run(socket: PathBuf) {
// Fetch own login once for self-notification filtering. Falls back // Fetch own login once for self-notification filtering. Falls back
// to empty string on failure — no filtering (safe degradation; see // to empty string on failure — no filtering (safe degradation; see
// `docs/forge.md::Self-notification filtering`). // `docs/forge.md::Self-notification filtering`).
let own_login = { let own_login = tokio::time::timeout(
let url = format!("{forge_url}/api/v1/user"); Duration::from_secs(HTTP_TIMEOUT_SECS),
fetch_json(&client, &url, &token) forge.user_get_current().send(),
.await )
.and_then(|v| v["login"].as_str().map(std::borrow::ToOwned::to_owned)) .await
.unwrap_or_default() .ok()
}; .and_then(Result::ok)
.and_then(|u| u.login)
.unwrap_or_default();
if own_login.is_empty() { if own_login.is_empty() {
warn!("forge_notify: could not resolve own login — self-notification filtering disabled"); warn!("forge_notify: could not resolve own login — self-notification filtering disabled");
} else { } else {
@ -160,15 +192,7 @@ pub async fn run(socket: PathBuf) {
loop { loop {
interval.tick().await; interval.tick().await;
poll_once( poll_once(&forge, &client, &token, &socket, &mut delivered, &own_login).await;
&client,
&forge_url,
&token,
&socket,
&mut delivered,
&own_login,
)
.await;
} }
} }
@ -188,14 +212,16 @@ async fn fetch_json(client: &reqwest::Client, url: &str, token: &str) -> Option<
} }
/// Map a Forgejo notification `subject.type` to a human-readable label. /// Map a Forgejo notification `subject.type` to a human-readable label.
/// Known values: "Pull", "Issue", "Commit", "Repository". Any unknown /// `Commit` / `Repository` keep their API names, matching the old raw
/// type is passed through as-is so new Forgejo types degrade gracefully /// pass-through of types we don't relabel; a missing type degrades to
/// rather than silently collapsing into a generic label. /// `?` like every other absent field.
fn notif_type_label(t: &str) -> &str { fn notif_type_label(t: Option<NotifySubjectType>) -> &'static str {
match t { match t {
"Pull" => "PR", Some(NotifySubjectType::Pull) => "PR",
"Issue" => "issue", Some(NotifySubjectType::Issue) => "issue",
other => other, Some(NotifySubjectType::Commit) => "Commit",
Some(NotifySubjectType::Repository) => "Repository",
None => "?",
} }
} }
@ -349,14 +375,19 @@ fn review_state_label(state: &str) -> Option<&str> {
async fn format_notification( async fn format_notification(
client: &reqwest::Client, client: &reqwest::Client,
token: &str, token: &str,
notif: &serde_json::Value, notif: &PolledNotification,
own_login: &str, own_login: &str,
) -> Option<String> { ) -> Option<String> {
let title = notif["subject"]["title"].as_str().unwrap_or("?"); let subj = notif.thread.subject.as_ref();
let notif_type = notif["subject"]["type"].as_str().unwrap_or("?"); let title = subj.and_then(|s| s.title.as_deref()).unwrap_or("?");
let html_url = notif["subject"]["html_url"] let subject_type = subj.and_then(|s| s.r#type);
.as_str() // forgejo-api maps a blank `html_url` (Go marshals empty strings) to
.unwrap_or_else(|| notif["subject"]["url"].as_str().unwrap_or("")); // `None`, so the API-url fallback also covers present-but-empty —
// deliberate: a fetchable API link beats the raw-HTTP predecessor's
// empty `url:` line.
let html_url = subj
.and_then(|s| s.html_url.as_ref().or(s.url.as_ref()))
.map_or("", url::Url::as_str);
// Extract issue/PR number from the html_url. URL ends with /issues/N or // Extract issue/PR number from the html_url. URL ends with /issues/N or
// /pulls/N (possibly followed by #anchor for comments). Best-effort. // /pulls/N (possibly followed by #anchor for comments). Best-effort.
@ -369,19 +400,24 @@ async fn format_notification(
.unwrap_or_default(); .unwrap_or_default();
// Repo slug for multi-repo disambiguation. Falls back gracefully when absent. // Repo slug for multi-repo disambiguation. Falls back gracefully when absent.
let repo = notif["repository"]["full_name"] let repo = notif
.as_str() .thread
.repository
.as_ref()
.and_then(|r| r.full_name.as_deref())
.map(|r| format!(" {r}")) .map(|r| format!(" {r}"))
.unwrap_or_default(); .unwrap_or_default();
// API URLs for fetching content // API URLs for fetching content
let subject_api_url = notif["subject"]["url"].as_str().unwrap_or(""); let subject_api_url = subj
let comment_api_url = notif["subject"]["latest_comment_url"] .and_then(|s| s.url.as_ref())
.as_str() .map_or("", url::Url::as_str);
.unwrap_or(""); let comment_api_url = subj
let comment_html_url = notif["subject"]["latest_comment_html_url"] .and_then(|s| s.latest_comment_url.as_ref())
.as_str() .map_or("", url::Url::as_str);
.unwrap_or(""); let comment_html_url = subj
.and_then(|s| s.latest_comment_html_url.as_ref())
.map_or("", url::Url::as_str);
// Always fetch subject detail for assignee/reviewer metadata so // Always fetch subject detail for assignee/reviewer metadata so
// the meta suffix can show current ownership without a follow-up // the meta suffix can show current ownership without a follow-up
@ -394,7 +430,7 @@ async fn format_notification(
// Forgejo's notification `subject.type` is "Pull" / "Issue", never // Forgejo's notification `subject.type` is "Pull" / "Issue", never
// "Pull Request". // "Pull Request".
let is_pr = notif_type == "Pull"; let is_pr = subject_type == Some(NotifySubjectType::Pull);
let meta_suffix = build_meta_suffix(subject.as_ref(), is_pr); let meta_suffix = build_meta_suffix(subject.as_ref(), is_pr);
// Determine whether this notification was triggered by a comment/review or // Determine whether this notification was triggered by a comment/review or
@ -403,7 +439,7 @@ async fn format_notification(
let meta = NotifMeta { let meta = NotifMeta {
title, title,
notif_type, subject_type,
html_url, html_url,
num, num,
repo, repo,
@ -422,14 +458,14 @@ async fn format_notification(
) )
.await .await
} else { } else {
format_state_change_notification(notif, &meta, own_login) format_state_change_notification(notif.thread.updated_at, &notif.state, &meta, own_login)
} }
} }
/// Shared notification metadata extracted from the raw Forgejo JSON. /// Shared notification metadata extracted from the polled notification.
struct NotifMeta<'a> { struct NotifMeta<'a> {
title: &'a str, title: &'a str,
notif_type: &'a str, subject_type: Option<NotifySubjectType>,
html_url: &'a str, html_url: &'a str,
num: String, num: String,
repo: String, repo: String,
@ -522,7 +558,7 @@ async fn format_comment_notification(
}; };
let NotifMeta { let NotifMeta {
title, title,
notif_type, subject_type,
num, num,
repo, repo,
meta_suffix, meta_suffix,
@ -547,7 +583,7 @@ async fn format_comment_notification(
Some(out) Some(out)
} else { } else {
// Regular comment. // Regular comment.
let kind = format!("comment on {}{num}{repo}", notif_type_label(notif_type)); let kind = format!("comment on {}{num}{repo}", notif_type_label(*subject_type));
let mut out = format!( let mut out = format!(
"[{kind}] {title}\nurl: {url}\n\n{author}: {body_for_embed}{truncated_mentions}" "[{kind}] {title}\nurl: {url}\n\n{author}: {body_for_embed}{truncated_mentions}"
); );
@ -563,17 +599,17 @@ async fn format_comment_notification(
/// path applies. Only creations are dropped: a later state change on the /// path applies. Only creations are dropped: a later state change on the
/// agent's own subject is driven by someone else and stays a wake. /// agent's own subject is driven by someone else and stays a wake.
fn format_state_change_notification( fn format_state_change_notification(
notif: &serde_json::Value, event_time: Option<OffsetDateTime>,
notif_state: &str,
meta: &NotifMeta<'_>, meta: &NotifMeta<'_>,
own_login: &str, own_login: &str,
) -> Option<String> { ) -> Option<String> {
// Classification uses notif["subject"]["state"] directly — Forgejo // Classification uses the raw `subject.state` string extracted in
// returns "open" / "closed" / "merged" here. We do NOT rely on // `parse_notification` — Forgejo returns "open" / "closed" / "merged"
// fetching the PR/issue detail for `merged`: // there. We do NOT rely on fetching the PR/issue detail for `merged`:
// - `subject.url` points to the *issues* endpoint, which returns // - `subject.url` points to the *issues* endpoint, which returns
// `pull_request.merged`, not top-level `merged`. // `pull_request.merged`, not top-level `merged`.
// - Forgejo API type is "Pull" / "Issue", never "Pull Request". // - Forgejo API type is "Pull" / "Issue", never "Pull Request".
let notif_state = notif["subject"]["state"].as_str().unwrap_or("");
// "New" = the subject is open (or state is absent). Used below for // "New" = the subject is open (or state is absent). Used below for
// the review-request override. // the review-request override.
@ -581,7 +617,7 @@ fn format_state_change_notification(
let NotifMeta { let NotifMeta {
title, title,
notif_type, subject_type,
html_url, html_url,
num, num,
repo, repo,
@ -589,7 +625,7 @@ fn format_state_change_notification(
subject, subject,
is_pr, is_pr,
} = meta; } = meta;
let label = notif_type_label(notif_type); let label = notif_type_label(*subject_type);
// Only claim "new" when the notification actually fired at creation // Only claim "new" when the notification actually fired at creation
// time. A review submitted with no body carries no // time. A review submitted with no body carries no
// `latest_comment_url`, so it lands here instead of on the comment // `latest_comment_url`, so it lands here instead of on the comment
@ -598,7 +634,7 @@ fn format_state_change_notification(
// on"): agents dismiss it as a // on"): agents dismiss it as a
// duplicate of the original open notification. When we can't confirm // duplicate of the original open notification. When we can't confirm
// creation, fall back to a neutral "activity on" label. // creation, fall back to a neutral "activity on" label.
let looks_new = notification_is_creation(notif, subject.as_ref()); let looks_new = notification_is_creation(event_time, subject.as_ref());
// Self-authored creation filter: skip an agent being woken by its own // Self-authored creation filter: skip an agent being woken by its own
// freshly-opened issue/PR. The subject payload is already fetched (for // freshly-opened issue/PR. The subject payload is already fetched (for
@ -668,81 +704,66 @@ fn format_state_change_notification(
/// new item behind the neutral fallback. See docs/forge.md, "new vs /// new item behind the neutral fallback. See docs/forge.md, "new vs
/// activity on". /// activity on".
fn notification_is_creation( fn notification_is_creation(
notif: &serde_json::Value, event: Option<OffsetDateTime>,
subject: Option<&serde_json::Value>, subject: Option<&serde_json::Value>,
) -> bool { ) -> bool {
let created = subject let created = subject
.and_then(|s| s["created_at"].as_str()) .and_then(|s| s["created_at"].as_str())
.and_then(parse_rfc3339_secs); .and_then(parse_rfc3339);
let event = notif["updated_at"].as_str().and_then(parse_rfc3339_secs);
match (created, event) { match (created, event) {
(Some(c), Some(e)) => (e - c).abs() <= NEW_ITEM_TOLERANCE_SECS, (Some(c), Some(e)) => (e - c).whole_seconds().abs() <= NEW_ITEM_TOLERANCE_SECS,
_ => true, _ => true,
} }
} }
/// Minimal dependency-free RFC 3339 / ISO 8601 parser → Unix epoch /// Parse an RFC 3339 timestamp as Forgejo emits them
/// seconds. Forgejo emits timestamps like `2026-06-13T11:18:42+02:00` /// (`2026-06-13T11:18:42+02:00` or `...Z`, optionally with fractional
/// or `...Z`, optionally with fractional seconds. We only need /// seconds). Returns `None` on any shape `time` doesn't recognise so
/// second-granularity comparison, so the fractional part is skipped. /// callers can fall back gracefully.
/// Returns `None` on any shape we don't recognise so callers can fall fn parse_rfc3339(s: &str) -> Option<OffsetDateTime> {
/// back gracefully. OffsetDateTime::parse(s, &Rfc3339).ok()
fn parse_rfc3339_secs(s: &str) -> Option<i64> {
if s.len() < 19 {
return None;
}
let year: i64 = s.get(0..4)?.parse().ok()?;
let month: i64 = s.get(5..7)?.parse().ok()?;
let day: i64 = s.get(8..10)?.parse().ok()?;
let hour: i64 = s.get(11..13)?.parse().ok()?;
let minute: i64 = s.get(14..16)?.parse().ok()?;
let second: i64 = s.get(17..19)?.parse().ok()?;
let mut epoch =
days_from_civil(year, month, day) * 86_400 + hour * 3_600 + minute * 60 + second;
// Remainder after seconds: optional `.fff` fraction, then a zone.
let mut rest = &s[19..];
if let Some(frac) = rest.strip_prefix('.') {
let end = frac
.find(|c: char| !c.is_ascii_digit())
.unwrap_or(frac.len());
rest = &frac[end..];
}
// Zone: `Z`/empty = UTC; otherwise `±HH:MM`. Subtract the offset to
// normalise to UTC epoch seconds.
if !(rest.is_empty() || rest.starts_with('Z')) {
let sign = rest.as_bytes()[0];
let off = &rest[1..];
// Accept `HH:MM` (Forgejo's form) and bare `HHMM`; minutes optional.
// Both fields fail the same way — a present-but-unparseable component
// returns `None` rather than one silently defaulting.
let (hh, mm) = match off.split_once(':') {
Some((h, m)) => (h, m),
None => (off.get(0..2)?, off.get(2..4).unwrap_or("00")),
};
let oh: i64 = hh.parse().ok()?;
let om: i64 = if mm.is_empty() { 0 } else { mm.parse().ok()? };
let offset = oh * 3_600 + om * 60;
match sign {
b'+' => epoch -= offset,
b'-' => epoch += offset,
_ => return None,
}
}
Some(epoch)
} }
/// Days since the Unix epoch for a proleptic-Gregorian `y-m-d` /// One notification from the poll page: the typed thread plus two raw
/// (Howard Hinnant's `days_from_civil`). Valid for all dates Forgejo /// fields the typed structs can't carry faithfully.
/// can emit. struct PolledNotification {
fn days_from_civil(y: i64, m: i64, d: i64) -> i64 { thread: NotificationThread,
let y = if m <= 2 { y - 1 } else { y }; /// Raw `subject.state`. Forgejo reports `"merged"` for merged PRs
let era = (if y >= 0 { y } else { y - 399 }) / 400; /// (`services/convert/notification.go`), which forgejo-api's
let yoe = y - era * 400; /// `StateType` (open/closed only) rejects at deserialization — so
let doy = (153 * (if m > 2 { m - 3 } else { m + 9 }) + 2) / 5 + d - 1; /// the state is extracted verbatim before the typed parse and
let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy; /// matched as a string, exactly like the pre-typed code.
era * 146_097 + doe - 719_468 state: String,
/// Raw `updated_at` string, byte-identical to what Forgejo sent, so
/// the persisted delivery-dedupe cursor keeps its exact format
/// across the typed-client port (no spurious re-deliveries from a
/// reformatting round-trip).
updated_at: String,
}
/// Parse one notification JSON object: pull out the raw `subject.state`
/// and `updated_at` (see [`PolledNotification`]), null the state so the
/// closed `StateType` enum can't reject it, and deserialize the rest
/// into the typed [`NotificationThread`]. Returns `None` (with a warn)
/// for an item the typed struct can't represent — the rest of the page
/// still delivers.
fn parse_notification(mut value: serde_json::Value) -> Option<PolledNotification> {
let state = value["subject"]["state"].as_str().unwrap_or("").to_owned();
if let Some(s) = value.get_mut("subject").and_then(|s| s.get_mut("state")) {
*s = serde_json::Value::Null;
}
let updated_at = value["updated_at"].as_str().unwrap_or("").to_owned();
match serde_json::from_value::<NotificationThread>(value) {
Ok(thread) => Some(PolledNotification {
thread,
state,
updated_at,
}),
Err(e) => {
warn!("forge_notify: notification parse error: {e}");
None
}
}
} }
#[allow( #[allow(
@ -752,33 +773,45 @@ fn days_from_civil(y: i64, m: i64, d: i64) -> i64 {
functions for state shared across all three phases" functions for state shared across all three phases"
)] )]
async fn poll_once( async fn poll_once(
forge: &Forgejo,
client: &reqwest::Client, client: &reqwest::Client,
forge_url: &str,
token: &str, token: &str,
socket: &Path, socket: &Path,
delivered: &mut HashMap<u64, String>, delivered: &mut HashMap<u64, String>,
own_login: &str, own_login: &str,
) { ) {
let url = format!("{forge_url}/api/v1/notifications?all=false&limit={UNREAD_FETCH_LIMIT}"); // Fetch the page as raw JSON (`response_type::<String>`) instead of the
let resp = match client // crate's `Vec<NotificationThread>`: one merged-PR notification
.get(&url) // (`subject.state = "merged"`, unrepresentable in `StateType`) would
.header("Authorization", format!("token {token}")) // otherwise poison deserialization of the whole page. HTTP-level errors
.send() // still surface as `ForgejoError` exactly like the fully-typed call;
.await // `parse_notification` below does the per-item typed parse.
{ let query = NotifyGetListQuery {
Ok(r) => r, all: Some(false),
Err(e) => { ..NotifyGetListQuery::default()
debug!("forge_notify: poll request failed: {e}");
return;
}
}; };
let request = forge
.notify_get_list(query)
.page_size(u32::try_from(UNREAD_FETCH_LIMIT).unwrap_or(u32::MAX))
.response_type::<String>();
let raw =
match tokio::time::timeout(Duration::from_secs(HTTP_TIMEOUT_SECS), request.send()).await {
Ok(Ok(raw)) => raw,
Ok(Err(ForgejoError::UnexpectedStatusCode(status))) => {
debug!("forge_notify: poll status {status}");
return;
}
Ok(Err(e)) => {
debug!("forge_notify: poll request failed: {e}");
return;
}
Err(_) => {
debug!("forge_notify: poll request failed: timed out");
return;
}
};
if !resp.status().is_success() { let values: Vec<serde_json::Value> = match serde_json::from_str(&raw) {
debug!("forge_notify: poll status {}", resp.status());
return;
}
let notifications: Vec<serde_json::Value> = match resp.json().await {
Ok(v) => v, Ok(v) => v,
Err(e) => { Err(e) => {
warn!("forge_notify: response parse error: {e}"); warn!("forge_notify: response parse error: {e}");
@ -786,22 +819,25 @@ async fn poll_once(
} }
}; };
if notifications.is_empty() { if values.is_empty() {
return; return;
} }
debug!( debug!(
count = notifications.len(), count = values.len(),
"forge_notify: delivering notifications" "forge_notify: delivering notifications"
); );
let notifications: Vec<PolledNotification> =
values.into_iter().filter_map(parse_notification).collect();
// Tracks whether the dedupe cursor changed this poll (a new delivery // Tracks whether the dedupe cursor changed this poll (a new delivery
// recorded, or the prune below dropped now-read threads) so we only // recorded, or the prune below dropped now-read threads) so we only
// rewrite the on-disk cursor when there's something to persist. // rewrite the on-disk cursor when there's something to persist.
let mut cursor_dirty = false; let mut cursor_dirty = false;
for notif in &notifications { for notif in &notifications {
let Some(id) = notif["id"].as_u64() else { let Some(id) = notif.thread.id.and_then(|id| u64::try_from(id).ok()) else {
continue; continue;
}; };
@ -810,7 +846,7 @@ async fn poll_once(
// Skip it silently unless its `updated_at` advanced since the // Skip it silently unless its `updated_at` advanced since the
// version we last delivered a wake for (i.e. genuinely new // version we last delivered a wake for (i.e. genuinely new
// activity). See the `delivered` cursor note in `run`. // activity). See the `delivered` cursor note in `run`.
let updated_at = notif["updated_at"].as_str().unwrap_or("").to_owned(); let updated_at = notif.updated_at.clone();
if !should_deliver(delivered, id, &updated_at) { if !should_deliver(delivered, id, &updated_at) {
debug!(%id, "forge_notify: skipping (already delivered this version)"); debug!(%id, "forge_notify: skipping (already delivered this version)");
continue; continue;
@ -820,7 +856,7 @@ async fn poll_once(
// None means self-echo — mark read silently, no delivery. // None means self-echo — mark read silently, no delivery.
let Some(body) = body_opt else { let Some(body) = body_opt else {
mark_read(client, forge_url, token, id).await; mark_read(forge, id).await;
continue; continue;
}; };
@ -864,7 +900,7 @@ async fn poll_once(
// loud in tests/dev if a future pagination change silently breaks it. // loud in tests/dev if a future pagination change silently breaks it.
let current_ids: HashSet<u64> = notifications let current_ids: HashSet<u64> = notifications
.iter() .iter()
.filter_map(|n| n["id"].as_u64()) .filter_map(|n| n.thread.id.and_then(|id| u64::try_from(id).ok()))
.collect(); .collect();
let before_prune = delivered.len(); let before_prune = delivered.len();
delivered.retain(|id, _| current_ids.contains(id)); delivered.retain(|id, _| current_ids.contains(id));
@ -899,21 +935,31 @@ fn should_deliver(delivered: &HashMap<u64, String>, id: u64, updated_at: &str) -
/// deliberately left unread for the read-before-comment guard, and a failed /// deliberately left unread for the read-before-comment guard, and a failed
/// delivery is left unread + out of the dedupe cursor so it resurfaces on the /// delivery is left unread + out of the dedupe cursor so it resurfaces on the
/// next poll tick. /// next poll tick.
async fn mark_read(client: &reqwest::Client, forge_url: &str, token: &str, id: u64) { async fn mark_read(forge: &Forgejo, id: u64) {
let mark_url = format!("{forge_url}/api/v1/notifications/threads/{id}"); let Ok(thread_id) = i64::try_from(id) else {
match client // Thread ids originate from `i64` in the poll parse, so an
.patch(&mark_url) // unrepresentable value can't actually reach here.
.header("Authorization", format!("token {token}")) return;
.send() };
.await // `to_status: None` → Forgejo's default transition (unread → read),
{ // matching the old bare PATCH. The 205 response body is the thread
Err(e) => { // JSON, which can carry `subject.state = "merged"` — take it as an
// opaque `String` (see `poll_once`) so a merged PR doesn't turn a
// successful mark-read into a spurious parse error.
let request = forge
.notify_read_thread(thread_id, NotifyReadThreadQuery { to_status: None })
.response_type::<String>();
match tokio::time::timeout(Duration::from_secs(HTTP_TIMEOUT_SECS), request.send()).await {
Err(_) => {
warn!(%id, "forge_notify: mark-read request failed — notification will resurface");
}
Ok(Err(e @ ForgejoError::ReqwestError(_))) => {
warn!(%id, error = ?e, "forge_notify: mark-read request failed — notification will resurface"); warn!(%id, error = ?e, "forge_notify: mark-read request failed — notification will resurface");
} }
Ok(r) if !r.status().is_success() => { Ok(Err(e)) => {
warn!(%id, status = %r.status(), "forge_notify: mark-read returned non-2xx — notification will resurface"); warn!(%id, error = %e, "forge_notify: mark-read returned non-2xx — notification will resurface");
} }
Ok(_) => { Ok(Ok(_)) => {
debug!(%id, "forge_notify: marked read"); debug!(%id, "forge_notify: marked read");
} }
} }
@ -1129,39 +1175,98 @@ mod tests {
} }
#[test] #[test]
fn parse_rfc3339_secs_handles_offsets_and_z() { fn parse_rfc3339_handles_offsets_and_z() {
// Same instant expressed three ways must parse equal. // Same instant expressed three ways must parse equal
let utc = parse_rfc3339_secs("2026-06-13T09:18:42Z").unwrap(); // (`OffsetDateTime` comparison is instant-based).
let plus2 = parse_rfc3339_secs("2026-06-13T11:18:42+02:00").unwrap(); let utc = parse_rfc3339("2026-06-13T09:18:42Z").unwrap();
let minus5 = parse_rfc3339_secs("2026-06-13T04:18:42-05:00").unwrap(); let plus2 = parse_rfc3339("2026-06-13T11:18:42+02:00").unwrap();
let minus5 = parse_rfc3339("2026-06-13T04:18:42-05:00").unwrap();
assert_eq!(utc, plus2); assert_eq!(utc, plus2);
assert_eq!(utc, minus5); assert_eq!(utc, minus5);
// Fractional seconds are skipped (second granularity). // Fractional seconds parse; second-granularity comparison holds.
assert_eq!(parse_rfc3339_secs("2026-06-13T09:18:42.512Z").unwrap(), utc); assert_eq!(
parse_rfc3339("2026-06-13T09:18:42.512Z")
.unwrap()
.unix_timestamp(),
utc.unix_timestamp(),
);
} }
#[test] #[test]
fn parse_rfc3339_secs_rejects_garbage() { fn parse_rfc3339_rejects_garbage() {
assert!(parse_rfc3339_secs("").is_none()); assert!(parse_rfc3339("").is_none());
assert!(parse_rfc3339_secs("not-a-date").is_none()); assert!(parse_rfc3339("not-a-date").is_none());
assert!(parse_rfc3339_secs("2026-06-13").is_none()); assert!(parse_rfc3339("2026-06-13").is_none());
} }
#[test] #[test]
fn notification_is_creation_flags_fresh_and_later_activity() { fn notification_is_creation_flags_fresh_and_later_activity() {
// Fresh PR: notification event time == created_at → "new".
let fresh = serde_json::json!({ "updated_at": "2026-06-13T11:18:42+02:00" });
let subject = serde_json::json!({ "created_at": "2026-06-13T11:18:40+02:00" }); let subject = serde_json::json!({ "created_at": "2026-06-13T11:18:40+02:00" });
assert!(notification_is_creation(&fresh, Some(&subject)));
// Fresh PR: notification event time == created_at → "new".
let fresh = parse_rfc3339("2026-06-13T11:18:42+02:00");
assert!(notification_is_creation(fresh, Some(&subject)));
// Review hours later on the same PR → not a creation. // Review hours later on the same PR → not a creation.
let later = serde_json::json!({ "updated_at": "2026-06-13T14:55:00+02:00" }); let later = parse_rfc3339("2026-06-13T14:55:00+02:00");
assert!(!notification_is_creation(&later, Some(&subject))); assert!(!notification_is_creation(later, Some(&subject)));
// Missing timestamps → default to creation (preserve prior behavior). // Missing timestamps → default to creation (preserve prior behavior).
let empty = serde_json::json!({}); assert!(notification_is_creation(None, None));
assert!(notification_is_creation(&empty, None)); assert!(notification_is_creation(None, Some(&subject)));
assert!(notification_is_creation(&empty, Some(&subject))); assert!(notification_is_creation(
fresh,
Some(&serde_json::json!({}))
));
}
#[test]
fn parse_notification_tolerates_merged_state() {
// forgejo-api's `StateType` has no "merged" variant; the raw
// extraction must keep the item parseable AND preserve the
// string for the `PR merged` wrapper.
let polled = parse_notification(serde_json::json!({
"id": 7,
"updated_at": "2026-06-13T11:18:42+02:00",
"url": "http://forge/api/v1/notifications/threads/7",
"subject": {
"title": "t",
"type": "Pull",
"state": "merged",
"html_url": "http://forge/o/r/pulls/5",
"latest_comment_html_url": "",
"latest_comment_url": "",
"url": "http://forge/api/v1/repos/o/r/issues/5",
},
}))
.expect("merged-state notification must parse");
assert_eq!(polled.state, "merged");
// Cursor string is the raw `updated_at`, byte-identical.
assert_eq!(polled.updated_at, "2026-06-13T11:18:42+02:00");
assert_eq!(polled.thread.id, Some(7));
assert_eq!(
polled.thread.subject.as_ref().and_then(|s| s.r#type),
Some(NotifySubjectType::Pull),
);
}
#[test]
fn parse_notification_missing_subject_degrades() {
let polled = parse_notification(serde_json::json!({
"id": 1,
"updated_at": "2026-06-22T16:00:00Z",
"url": "",
}))
.expect("subject-less notification must parse");
assert_eq!(polled.state, "");
assert!(polled.thread.subject.is_none());
}
#[test]
fn parse_notification_rejects_unrepresentable_item() {
// A non-object item can't become a `NotificationThread`; it is
// dropped alone instead of failing the page.
assert!(parse_notification(serde_json::json!("nonsense")).is_none());
} }
/// Build a `NotifMeta` for the state-change formatter tests. The `&str` /// Build a `NotifMeta` for the state-change formatter tests. The `&str`
@ -1169,7 +1274,7 @@ mod tests {
fn state_change_meta(subject: serde_json::Value) -> NotifMeta<'static> { fn state_change_meta(subject: serde_json::Value) -> NotifMeta<'static> {
NotifMeta { NotifMeta {
title: "subject title", title: "subject title",
notif_type: "Issue", subject_type: Some(NotifySubjectType::Issue),
html_url: "http://forge/issues/1", html_url: "http://forge/issues/1",
num: " #1".to_owned(), num: " #1".to_owned(),
repo: " [agents/x]".to_owned(), repo: " [agents/x]".to_owned(),
@ -1183,15 +1288,13 @@ mod tests {
fn state_change_drops_self_authored_creation() { fn state_change_drops_self_authored_creation() {
// No timestamps ⇒ treated as a creation; poster login == own_login. // No timestamps ⇒ treated as a creation; poster login == own_login.
let meta = state_change_meta(serde_json::json!({ "user": { "login": "damocles" } })); let meta = state_change_meta(serde_json::json!({ "user": { "login": "damocles" } }));
let notif = serde_json::json!({ "subject": { "state": "open" } }); assert!(format_state_change_notification(None, "open", &meta, "damocles").is_none());
assert!(format_state_change_notification(&notif, &meta, "damocles").is_none());
} }
#[test] #[test]
fn state_change_keeps_other_authored_creation() { fn state_change_keeps_other_authored_creation() {
let meta = state_change_meta(serde_json::json!({ "user": { "login": "someone-else" } })); let meta = state_change_meta(serde_json::json!({ "user": { "login": "someone-else" } }));
let notif = serde_json::json!({ "subject": { "state": "open" } }); assert!(format_state_change_notification(None, "open", &meta, "damocles").is_some());
assert!(format_state_change_notification(&notif, &meta, "damocles").is_some());
} }
#[test] #[test]
@ -1203,10 +1306,7 @@ mod tests {
"user": { "login": "damocles" }, "user": { "login": "damocles" },
"created_at": "2020-01-01T00:00:00Z", "created_at": "2020-01-01T00:00:00Z",
})); }));
let notif = serde_json::json!({ let event = parse_rfc3339("2026-06-22T16:00:00Z");
"subject": { "state": "closed" }, assert!(format_state_change_notification(event, "closed", &meta, "damocles").is_some());
"updated_at": "2026-06-22T16:00:00Z",
});
assert!(format_state_change_notification(&notif, &meta, "damocles").is_some());
} }
} }

View file

@ -1,6 +1,7 @@
//! Shared in-container harness code for the single `hive` binary that //! Shared in-container harness code for the sibling `hive-agent` /
//! serves every agent role (the manager is just an agent role, not a //! `hive-agent-mcp` / `hive-agent-wake` binaries, which serve every
//! separate binary). //! agent role (the manager is just an agent role, not a separate set
//! of binaries).
pub mod client; pub mod client;
pub mod events; pub mod events;

View file

@ -330,13 +330,13 @@ fn load_extra_mcp() -> std::collections::BTreeMap<String, ExtraMcpServer> {
} }
/// Render the MCP config blob claude reads from `--mcp-config <path>`. /// Render the MCP config blob claude reads from `--mcp-config <path>`.
/// `agent_binary` is the path (or PATH-resolvable name) of the `hive-ag3nt` /// `mcp_binary` is the path (or PATH-resolvable name) of the
/// executable; `socket` is the hyperhive per-agent socket bind-mounted into /// `hive-agent-mcp` bridge executable; `socket` is the hyperhive per-agent
/// the container (forwarded to the child as `--socket <path>`). Merges in /// socket bind-mounted into the container (forwarded to the child as
/// any extra MCP servers declared via `hyperhive.extraMcpServers` in the /// `--socket <path>`). Merges in any extra MCP servers declared via
/// agent's NixOS config. /// `hyperhive.extraMcpServers` in the agent's NixOS config.
#[must_use] #[must_use]
pub fn render_claude_config(agent_binary: &str, socket: &std::path::Path) -> String { pub fn render_claude_config(mcp_binary: &str, socket: &std::path::Path) -> String {
let mut servers = serde_json::Map::new(); let mut servers = serde_json::Map::new();
// When the harness is configured to run the built-in server as a // When the harness is configured to run the built-in server as a
// persistent streamable-http daemon (loopback port in // persistent streamable-http daemon (loopback port in
@ -353,8 +353,8 @@ pub fn render_claude_config(agent_binary: &str, socket: &std::path::Path) -> Str
"url": format!("http://127.0.0.1:{port}/mcp"), "url": format!("http://127.0.0.1:{port}/mcp"),
}), }),
None => serde_json::json!({ None => serde_json::json!({
"command": agent_binary, "command": mcp_binary,
"args": ["--socket", socket.display().to_string(), "mcp"], "args": ["--socket", socket.display().to_string()],
"env": {} "env": {}
}), }),
}; };

View file

@ -1,4 +1,5 @@
//! Pure helpers factored out of the `hive` serve loop (`bin/hive.rs`). //! Pure helpers factored out of the harness serve loop
//! (`bin/hive-agent.rs`).
//! Only functions with no wire-type dependency live here; //! Only functions with no wire-type dependency live here;
//! request/response-flavored helpers (`requeue_inflight`, `ack_turn`, etc.) //! request/response-flavored helpers (`requeue_inflight`, `ack_turn`, etc.)
//! stay in the binary because they touch the request enum variants directly. //! stay in the binary because they touch the request enum variants directly.
@ -60,7 +61,7 @@ pub struct TurnRowArgs<'a> {
} }
/// Assemble a `TurnStatRow` from the harness's per-turn state. Lives here /// Assemble a `TurnStatRow` from the harness's per-turn state. Lives here
/// (rather than inline in the `hive` serve loop) so it stays wire-type-free /// (rather than inline in the serve loop) so it stays wire-type-free
/// and unit-testable; the binary just feeds it the post-turn counts. /// and unit-testable; the binary just feeds it the post-turn counts.
#[must_use] #[must_use]
pub fn build_row(args: TurnRowArgs<'_>) -> TurnStatRow { pub fn build_row(args: TurnRowArgs<'_>) -> TurnStatRow {

View file

@ -108,8 +108,9 @@ impl TurnFiles {
/// Drop the MCP config blob claude reads from `--mcp-config <path>`. /// Drop the MCP config blob claude reads from `--mcp-config <path>`.
/// `socket` is the hyperhive per-container socket (forwarded to the child /// `socket` is the hyperhive per-container socket (forwarded to the child
/// as `--socket <path>`). The MCP subcommand is always `mcp` on the single /// as `--socket <path>`). The MCP server is the `hive-agent-mcp` binary
/// `hive` binary resolved from `/proc/self/exe`. /// installed next to the running `hive-agent` (resolved as a sibling of
/// `/proc/self/exe`; PATH-resolvable name as the fallback).
/// ///
/// # Errors /// # Errors
/// ///
@ -120,7 +121,8 @@ pub async fn write_mcp_config(socket: &Path) -> Result<PathBuf> {
let path = parent.join("claude-mcp-config.json"); let path = parent.join("claude-mcp-config.json");
let exe = std::env::current_exe() let exe = std::env::current_exe()
.ok() .ok()
.map_or_else(|| "hive".into(), |p| p.display().to_string()); .and_then(|p| Some(p.parent()?.join("hive-agent-mcp")))
.map_or_else(|| "hive-agent-mcp".into(), |p| p.display().to_string());
let body = mcp_config::render_claude_config(&exe, socket); let body = mcp_config::render_claude_config(&exe, socket);
tokio::fs::write(&path, body).await?; tokio::fs::write(&path, body).await?;
tracing::info!(path = %path.display(), "wrote claude MCP config"); tracing::info!(path = %path.display(), "wrote claude MCP config");
@ -146,7 +148,7 @@ pub async fn write_system_prompt(socket: &Path, label: &str) -> Result<PathBuf>
/// `result_kind = "compacted"` in turn stats so the stats page can distinguish /// `result_kind = "compacted"` in turn stats so the stats page can distinguish
/// those turns. Both `Ok(true)` and `Ok(false)` are ack'd; the error cases /// those turns. Both `Ok(true)` and `Ok(false)` are ack'd; the error cases
/// each map to a distinct serve-loop action (see [`emit_turn_end`] and the /// each map to a distinct serve-loop action (see [`emit_turn_end`] and the
/// `hive` serve loop). /// `hive-agent` serve loop).
pub type TurnOutcome = std::result::Result<bool, TurnError>; pub type TurnOutcome = std::result::Result<bool, TurnError>;
/// The ways a turn can end without a usable result. Each is deliberately *not* /// The ways a turn can end without a usable result. Each is deliberately *not*
@ -287,7 +289,7 @@ pub fn make_session(bus: &Bus) -> AgentSession {
/// the whole turn is retried a single time before bubbling `AuthFailed` to /// the whole turn is retried a single time before bubbling `AuthFailed` to
/// the serve loop (which parks for re-login). /// the serve loop (which parks for re-login).
/// ///
/// Called once per turn by the `hive` serve loop, which owns the shared /// Called once per turn by the `hive-agent` serve loop, which owns the shared
/// `session` ([`make_session`]) and threads it in. /// `session` ([`make_session`]) and threads it in.
pub async fn drive_turn( pub async fn drive_turn(
prompt: &str, prompt: &str,

View file

@ -12,6 +12,8 @@ chrono.workspace = true
base64.workspace = true base64.workspace = true
bcrypt.workspace = true bcrypt.workspace = true
reqwest.workspace = true reqwest.workspace = true
forgejo-api.workspace = true
url.workspace = true
clap.workspace = true clap.workspace = true
clap_complete.workspace = true clap_complete.workspace = true
clap-markdown = "0.1" clap-markdown = "0.1"

View file

@ -18,8 +18,11 @@ pub use repos::{
}; };
pub use users::{core_token, ensure_user_for, provision_user_token}; pub use users::{core_token, ensure_user_for, provision_user_token};
use std::sync::OnceLock;
use anyhow::{Context, Result}; use anyhow::{Context, Result};
use reqwest::StatusCode; use forgejo_api::{Auth, Forgejo};
use url::Url;
use repos::{ensure_mirrors, ensure_operators_team, ensure_org}; use repos::{ensure_mirrors, ensure_operators_team, ensure_org};
use users::{ use users::{
@ -105,34 +108,20 @@ async fn forge_admin(args: &[&str]) -> Result<String> {
Ok(stdout) Ok(stdout)
} }
/// Thin Forgejo REST helper. Sends `method` to `url` with a JSON body /// Typed Forgejo API client for the local forge ([`FORGE_HTTP`]),
/// and `Authorization: token <token>`, returns the HTTP status code. /// authenticated as `token`. All Forgejo API calls that don't shell
/// All Forgejo API calls that don't shell out to `forgejo admin` go /// out to `forgejo admin` go through clients built here — one place
/// through here — one place for auth header, content-type, error /// for the base URL and auth. Tokens differ per call site (core admin
/// propagation, and the shared reqwest Client. /// token vs per-agent tokens), so the token is passed per call; the
/// Returns the response status **and body**. The body lets callers log /// base URL is parsed once. Failures surface as
/// *why* Forgejo rejected a request (e.g. the validation message on a /// `forgejo_api::ForgejoError`, whose Display carries the HTTP status
/// 422); status-only callers just bind `(status, _)`. Body read is /// and the API's error message (e.g. the validation reason on a 422).
/// best-effort — a read error yields an empty string rather than pub(crate) fn api(token: &str) -> Result<Forgejo> {
/// failing the whole call. static URL: OnceLock<Url> = OnceLock::new();
async fn forge_http( let url = URL
method: reqwest::Method, .get_or_init(|| Url::parse(FORGE_HTTP).expect("FORGE_HTTP is a valid URL"))
url: &str, .clone();
token: &str, Forgejo::new(Auth::Token(token), url).context("build forgejo api client")
body: &str,
) -> Result<(StatusCode, String)> {
let client = reqwest::Client::new();
let resp = client
.request(method, url)
.header("Authorization", format!("token {token}"))
.header("Content-Type", "application/json")
.body(body.to_owned())
.send()
.await
.with_context(|| format!("forge HTTP request to {url}"))?;
let status = resp.status();
let text = resp.text().await.unwrap_or_default();
Ok((status, text))
} }
/// Whether `ns` is a hive-managed Forgejo namespace that agent-initiated /// Whether `ns` is a hive-managed Forgejo namespace that agent-initiated

View file

@ -4,10 +4,12 @@
//! boundary; moved verbatim from the `forge` module root. //! boundary; moved verbatim from the `forge` module root.
use anyhow::Context; use anyhow::Context;
use forgejo_api::ForgejoError;
use forgejo_api::structs::{MergePullRequestOption, MergePullRequestOptionDo};
use crate::coordinator::Coordinator; use crate::coordinator::Coordinator;
use super::{CONFIG_ORG, FORGE_HTTP, core_token, forge_http}; use super::{CONFIG_ORG, api, core_token};
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
// PR-based config-flow merge primitives (part of the // PR-based config-flow merge primitives (part of the
@ -242,35 +244,57 @@ pub async fn ff_push_to_main(repo: &str, sha: &str) -> Result<(), ForgeMergeErro
} }
/// Mark PR `pr` as **manually merged** at `sha` (Forgejo /// Mark PR `pr` as **manually merged** at `sha` (Forgejo
/// `POST …/pulls/{pr}/merge` with `Do=manually-merged`, `MergeCommitID=sha`). /// `repo_merge_pull_request` with `Do=manually-merged`, `MergeCommitID=sha`).
/// `ff_push_to_main` must have already set `main` to `sha` (Forgejo requires /// `ff_push_to_main` must have already set `main` to `sha` (Forgejo requires
/// the branch already be at the merge commit). On a non-2xx, re-reads the PR /// the branch already be at the merge commit). On an API rejection, re-reads
/// head to distinguish drift (`HeadDrift`) from a generic failure (`Other`) — /// the PR head to distinguish drift (`HeadDrift`) from a generic failure
/// best-effort, since the handler's pre-merge head re-read is the real gate. /// (`Other`) — best-effort, since the handler's pre-merge head re-read is
/// the real gate. A transport failure skips the drift re-read (it couldn't
/// reach the forge either) and surfaces as `Other` directly.
/// ///
/// # Errors /// # Errors
/// `HeadDrift` if the PR head no longer matches `sha`; `Other` otherwise. /// `HeadDrift` if the PR head no longer matches `sha`; `Other` otherwise.
pub async fn mark_pr_merged(repo: &str, pr: u64, sha: &str) -> Result<(), ForgeMergeError> { pub async fn mark_pr_merged(repo: &str, pr: u64, sha: &str) -> Result<(), ForgeMergeError> {
let token = core_token() let token = core_token()
.ok_or_else(|| ForgeMergeError::Other(anyhow::anyhow!("forge core token absent")))?; .ok_or_else(|| ForgeMergeError::Other(anyhow::anyhow!("forge core token absent")))?;
let url = format!("{FORGE_HTTP}/api/v1/repos/{repo}/pulls/{pr}/merge"); let (owner, name) = repo.split_once('/').ok_or_else(|| {
let body = format!(r#"{{"Do":"manually-merged","MergeCommitID":"{sha}"}}"#); ForgeMergeError::Other(anyhow::anyhow!("forge repo `{repo}` is not owner/name"))
let (status, _) = forge_http(reqwest::Method::POST, &url, &token, &body) })?;
let index = i64::try_from(pr)
.map_err(|_| ForgeMergeError::Other(anyhow::anyhow!("PR index {pr} overflows i64")))?;
let body = MergePullRequestOption {
r#do: MergePullRequestOptionDo::ManuallyMerged,
merge_commit_id: Some(sha.to_owned()),
merge_message_field: None,
merge_title_field: None,
delete_branch_after_merge: None,
force_merge: None,
head_commit_id: None,
merge_when_checks_succeed: None,
};
let client = api(&token).map_err(ForgeMergeError::Other)?;
match client
.repo_merge_pull_request(owner, name, index, body)
.await .await
.context("POST pulls/<pr>/merge (manually-merged)")?; {
if status.is_success() { Ok(()) => Ok(()),
return Ok(()); Err(ForgejoError::ReqwestError(e)) => Err(ForgeMergeError::Other(
} anyhow::Error::from(e).context("POST pulls/<pr>/merge (manually-merged)"),
// Best-effort drift detection: if the live head no longer matches `sha`, )),
// that's a head-drift race; otherwise surface as a hard failure. Err(e) => {
match pr_head_sha(repo, pr).await { // Best-effort drift detection: if the live head no longer matches
Ok(actual) if actual != sha => Err(ForgeMergeError::HeadDrift { // `sha`, that's a head-drift race; otherwise surface as a hard
expected: sha.to_string(), // failure.
actual, match pr_head_sha(repo, pr).await {
}), Ok(actual) if actual != sha => Err(ForgeMergeError::HeadDrift {
_ => Err(ForgeMergeError::Other(anyhow::anyhow!( expected: sha.to_string(),
"mark PR #{pr} in {repo} manually-merged at {sha} failed: HTTP {status}" actual,
))), }),
_ => Err(ForgeMergeError::Other(anyhow::Error::from(e).context(
format!("mark PR #{pr} in {repo} manually-merged at {sha}"),
))),
}
}
} }
} }

View file

@ -1,99 +1,190 @@
//! Repo + org plumbing on the local Forgejo: org / repo creation, //! Repo + org plumbing on the local Forgejo: org / repo creation,
//! the meta + shared-docs + knowledge repos, per-agent config-repo //! the meta + shared-docs + knowledge repos, per-agent config-repo
//! mirroring (`push_config` / `push_meta`), collaborator grants, //! mirroring (`push_config` / `push_meta`), collaborator grants,
//! pull-mirrors, and branch-protection rules. Shared HTTP helpers + //! pull-mirrors, and branch-protection rules. The typed API-client
//! org-name constants live in the module root (`super`). //! constructor + org-name constants live in the module root (`super`).
use std::path::Path; use std::path::Path;
use anyhow::{Context, Result}; use anyhow::{Context, Result};
use forgejo_api::structs::{
AddCollaboratorOption, AddCollaboratorOptionPermission, CreateBranchProtectionOption,
CreateOrgOption, CreateRepoOption, CreateTeamOption, CreateTeamOptionPermission,
EditRepoOption, MigrateRepoOptions, MigrateRepoOptionsService, Repository,
};
use forgejo_api::{ApiErrorKind, ForgejoError};
use reqwest::StatusCode;
use tokio::process::Command; use tokio::process::Command;
use crate::coordinator::Coordinator; use crate::coordinator::Coordinator;
use super::{ use super::{
AGENTS_ORG, CONFIG_ORG, FORGE_HTTP, KNOWLEDGE_REPO, OPERATORS_TEAM, SHARED_DOCS_REPO, AGENTS_ORG, CONFIG_ORG, FORGE_HTTP, KNOWLEDGE_REPO, OPERATORS_TEAM, SHARED_DOCS_REPO,
SHARED_ORG, core_token, forge_http, is_present, SHARED_ORG, api, core_token, is_present,
}; };
/// JSON body for a private, empty repo defaulting to `main`. /// Creation options for an empty repo defaulting to `main`.
fn repo_body(name: &str) -> String { fn repo_option(name: &str, private: bool) -> CreateRepoOption {
format!(r#"{{"name":"{name}","auto_init":false,"private":true,"default_branch":"main"}}"#) CreateRepoOption {
auto_init: Some(false),
default_branch: Some("main".to_owned()),
description: None,
gitignores: None,
issue_labels: None,
license: None,
name: name.to_owned(),
object_format_name: None,
private: Some(private),
readme: None,
template: None,
trust_model: None,
}
} }
/// JSON body for a public, empty repo defaulting to `main`. /// `EditRepoOption` with every field unset — repo edits only ever
fn repo_body_public(name: &str) -> String { /// change the one field the caller sets on top (Forgejo leaves `None`
format!(r#"{{"name":"{name}","auto_init":false,"private":false,"default_branch":"main"}}"#) /// fields untouched).
fn sparse_edit_repo_option() -> EditRepoOption {
EditRepoOption {
allow_fast_forward_only_merge: None,
allow_manual_merge: None,
allow_merge_commits: None,
allow_rebase: None,
allow_rebase_explicit: None,
allow_rebase_update: None,
allow_squash_merge: None,
archived: None,
autodetect_manual_merge: None,
default_allow_maintainer_edit: None,
default_branch: None,
default_delete_branch_after_merge: None,
default_merge_style: None,
default_update_style: None,
description: None,
enable_prune: None,
external_tracker: None,
external_wiki: None,
globally_editable_wiki: None,
has_actions: None,
has_issues: None,
has_packages: None,
has_projects: None,
has_pull_requests: None,
has_releases: None,
has_wiki: None,
ignore_whitespace_conflicts: None,
internal_tracker: None,
mirror_interval: None,
name: None,
private: None,
template: None,
website: None,
wiki_branch: None,
}
}
/// Whether a create-style call failed because the object already
/// exists. Forgejo signals this as HTTP 409 (conflict) or 422
/// (validation). The typed client surfaces those as
/// `ApiErrorKind::Other(409)` / `ValidationFailed` when the endpoint
/// spec lists the status, or as a bare `UnexpectedStatusCode`
/// otherwise — match all shapes defensively.
fn is_already_exists(e: &ForgejoError) -> bool {
match e {
ForgejoError::ApiError(api) => match api.error_kind() {
ApiErrorKind::ValidationFailed => true,
ApiErrorKind::Other(s) => *s == StatusCode::CONFLICT,
_ => false,
},
ForgejoError::UnexpectedStatusCode(s) => {
*s == StatusCode::CONFLICT || *s == StatusCode::UNPROCESSABLE_ENTITY
}
_ => false,
}
}
/// Whether an error is specifically an HTTP 409 conflict (and NOT a
/// 422): the migrate endpoint's 422 is a validation error (bad
/// `clone_addr` / service) and must surface, so it can't share
/// [`is_already_exists`]'s 422 tolerance.
fn is_conflict(e: &ForgejoError) -> bool {
match e {
ForgejoError::ApiError(api) => {
matches!(api.error_kind(), ApiErrorKind::Other(s) if *s == StatusCode::CONFLICT)
}
ForgejoError::UnexpectedStatusCode(s) => *s == StatusCode::CONFLICT,
_ => false,
}
}
/// Whether an error is Forgejo saying 404 — the resource is absent,
/// as opposed to a transport / auth / server failure.
fn is_not_found(e: &ForgejoError) -> bool {
match e {
ForgejoError::ApiError(api) => {
matches!(api.error_kind(), ApiErrorKind::NotFound { .. })
}
ForgejoError::UnexpectedStatusCode(s) => *s == StatusCode::NOT_FOUND,
_ => false,
}
}
/// Fold a repo-creation result's "already exists" (409 / 422) into
/// success. `label` is `<owner>/<name>` — purely for log + error
/// context.
fn created_or_exists(res: Result<Repository, ForgejoError>, label: &str) -> Result<()> {
match res {
Ok(_) => {
tracing::info!(%label, "forge: created repo");
Ok(())
}
Err(e) if is_already_exists(&e) => {
tracing::debug!(%label, "forge: repo already exists");
Ok(())
}
Err(e) => Err(e).with_context(|| format!("create repo {label}")),
}
} }
/// Set an existing repo to public visibility. No-op if the repo is /// Set an existing repo to public visibility. No-op if the repo is
/// already public. Used for `internal/knowledge` which may have been /// already public. Used for `internal/knowledge` which may have been
/// created as private on an older deployment. /// created as private on an older deployment.
async fn set_repo_public(owner: &str, repo: &str, token: &str) -> Result<()> { async fn set_repo_public(owner: &str, repo: &str, token: &str) -> Result<()> {
let url = format!("{FORGE_HTTP}/api/v1/repos/{owner}/{repo}"); let mut edit = sparse_edit_repo_option();
let (status, _) = edit.private = Some(false);
forge_http(reqwest::Method::PATCH, &url, token, r#"{"private":false}"#).await?; api(token)?
match status.as_u16() { .repo_edit(owner, repo, edit)
200 => { .await
tracing::debug!(%owner, %repo, "forge: repo set to public"); .with_context(|| format!("edit {owner}/{repo} (set public)"))?;
Ok(()) tracing::debug!(%owner, %repo, "forge: repo set to public");
} Ok(())
other => anyhow::bail!("PATCH {owner}/{repo} (set public) returned HTTP {other}"),
}
} }
/// Create `name` inside org `org` as a public repo. Idempotent. /// Create `name` inside org `org` as a public repo. Idempotent.
async fn ensure_org_repo_public(org: &str, name: &str, token: &str) -> Result<()> { async fn ensure_org_repo_public(org: &str, name: &str, token: &str) -> Result<()> {
create_repo( let res = api(token)?
&format!("{FORGE_HTTP}/api/v1/orgs/{org}/repos"), .create_org_repo(org, repo_option(name, false))
&repo_body_public(name), .await;
token, created_or_exists(res, &format!("{org}/{name}"))
&format!("{org}/{name}"),
)
.await
}
/// POST a repo-creation request to `url` and fold "already exists"
/// (HTTP 409 / 422) into success. `label` is `<owner>/<name>` — purely
/// for log + error context.
async fn create_repo(url: &str, body: &str, token: &str, label: &str) -> Result<()> {
let (status, _) = forge_http(reqwest::Method::POST, url, token, body).await?;
match status.as_u16() {
201 => {
tracing::info!(%label, "forge: created repo");
Ok(())
}
409 | 422 => {
tracing::debug!(%label, "forge: repo already exists");
Ok(())
}
other => anyhow::bail!("POST {url} ({label}) returned HTTP {other}"),
}
} }
/// Create a repo in the token-owner's own namespace. `token` belongs /// Create a repo in the token-owner's own namespace. `token` belongs
/// to the user we want the repo owned by (we use `core`'s token for /// to the user we want the repo owned by (we use `core`'s token for
/// `core/meta`). Idempotent. /// `core/meta`). Idempotent.
pub async fn ensure_repo(name: &str, token: &str) -> Result<()> { pub async fn ensure_repo(name: &str, token: &str) -> Result<()> {
create_repo( let res = api(token)?
&format!("{FORGE_HTTP}/api/v1/user/repos"), .create_current_user_repo(repo_option(name, true))
&repo_body(name), .await;
token, created_or_exists(res, &format!("core/{name}"))
&format!("core/{name}"),
)
.await
} }
/// Create `name` inside org `org` (used for `agent-configs/<agent>`). /// Create `name` inside org `org` (used for `agent-configs/<agent>`).
/// Idempotent. /// Idempotent.
async fn ensure_org_repo(org: &str, name: &str, token: &str) -> Result<()> { async fn ensure_org_repo(org: &str, name: &str, token: &str) -> Result<()> {
create_repo( let res = api(token)?
&format!("{FORGE_HTTP}/api/v1/orgs/{org}/repos"), .create_org_repo(org, repo_option(name, true))
&repo_body(name), .await;
token, created_or_exists(res, &format!("{org}/{name}"))
&format!("{org}/{name}"),
)
.await
} }
/// Push `dir` (the meta repo) to `core/meta` on the local forge. /// Push `dir` (the meta repo) to `core/meta` on the local forge.
@ -141,7 +232,14 @@ pub async fn ensure_config_repo(name: &str) -> Result<()> {
ensure_org_repo(CONFIG_ORG, name, &token).await?; ensure_org_repo(CONFIG_ORG, name, &token).await?;
// Agent = write collaborator: it can push config-PR branches + open PRs, // Agent = write collaborator: it can push config-PR branches + open PRs,
// but the branch protection below keeps it off `main` directly. // but the branch protection below keeps it off `main` directly.
add_collaborator(CONFIG_ORG, name, name, "write", &token).await?; add_collaborator(
CONFIG_ORG,
name,
name,
AddCollaboratorOptionPermission::Write,
&token,
)
.await?;
// Protect `main` core-only, fast-forward-only (no auto force-push). // Protect `main` core-only, fast-forward-only (no auto force-push).
apply_config_repo_branch_protection(name, &token).await apply_config_repo_branch_protection(name, &token).await
} }
@ -154,43 +252,20 @@ pub async fn ensure_shared_docs_repo(core_token: &str) -> Result<()> {
} }
/// Grant agent `name` read-only collaborator access to `internal/docs`. /// Grant agent `name` read-only collaborator access to `internal/docs`.
/// Idempotent: HTTP 204 (already a collaborator) is treated as success. /// Idempotent: re-adding an existing collaborator succeeds (Forgejo
/// Mirrors `meta_read_access` so agents can clone the shared docs repo /// answers 204 either way). Mirrors `meta_read_access` so agents can
/// without authentication hassle. /// clone the shared docs repo without authentication hassle.
pub async fn shared_docs_access(name: &str, core_token: &str) -> Result<()> { pub async fn shared_docs_access(name: &str, core_token: &str) -> Result<()> {
let url = add_collaborator(
format!("{FORGE_HTTP}/api/v1/repos/{SHARED_ORG}/{SHARED_DOCS_REPO}/collaborators/{name}"); SHARED_ORG,
let body = r#"{"permission":"read"}"#; SHARED_DOCS_REPO,
let out = Command::new("curl") name,
.args([ AddCollaboratorOptionPermission::Read,
"-sS", core_token,
"-o", )
"/dev/null", .await?;
"-w", tracing::info!(%name, "forge: granted shared-docs read access");
"%{http_code}", Ok(())
"-X",
"PUT",
"-H",
"Content-Type: application/json",
"-H",
&format!("Authorization: token {core_token}"),
"-d",
body,
&url,
])
.output()
.await
.context("invoke curl PUT internal/docs/collaborators")?;
let code = String::from_utf8_lossy(&out.stdout).trim().to_owned();
match code.as_str() {
"204" => {
tracing::info!(%name, "forge: granted shared-docs read access");
Ok(())
}
other => anyhow::bail!(
"PUT {SHARED_ORG}/{SHARED_DOCS_REPO}/collaborators/{name} returned HTTP {other}"
),
}
} }
/// Ensure the `internal/knowledge` repo exists and is public. /// Ensure the `internal/knowledge` repo exists and is public.
@ -208,38 +283,19 @@ pub async fn ensure_knowledge_repo(core_token: &str) -> Result<()> {
/// Grant agent `name` read-only collaborator access to `core/meta` on /// Grant agent `name` read-only collaborator access to `core/meta` on
/// the forge so the agent can clone/fetch the meta flake. Idempotent: /// the forge so the agent can clone/fetch the meta flake. Idempotent:
/// HTTP 204 (already a collaborator) is treated as success. /// re-adding an existing collaborator succeeds (Forgejo answers 204
/// either way).
pub async fn meta_read_access(name: &str, core_token: &str) -> Result<()> { pub async fn meta_read_access(name: &str, core_token: &str) -> Result<()> {
let url = format!("{FORGE_HTTP}/api/v1/repos/core/meta/collaborators/{name}"); add_collaborator(
let body = r#"{"permission":"read"}"#; "core",
let out = Command::new("curl") "meta",
.args([ name,
"-sS", AddCollaboratorOptionPermission::Read,
"-o", core_token,
"/dev/null", )
"-w", .await?;
"%{http_code}", tracing::info!(%name, "forge: granted meta read access");
"-X", Ok(())
"PUT",
"-H",
"Content-Type: application/json",
"-H",
&format!("Authorization: token {core_token}"),
"-d",
body,
&url,
])
.output()
.await
.context("invoke curl PUT core/meta/collaborators")?;
let code = String::from_utf8_lossy(&out.stdout).trim().to_owned();
match code.as_str() {
"204" => {
tracing::info!(%name, "forge: granted meta read access");
Ok(())
}
other => anyhow::bail!("PUT core/meta/collaborators/{name} returned HTTP {other}"),
}
} }
/// Add `http://localhost:3000/core/meta.git` as the `meta` remote in /// Add `http://localhost:3000/core/meta.git` as the `meta` remote in
@ -339,22 +395,29 @@ pub async fn push_config(name: &str) -> Result<()> {
Ok(()) Ok(())
} }
/// POST `/api/v1/orgs` to create an org named `name`. Idempotent: /// Create an org named `name` (`org_create`). Idempotent: HTTP 422
/// HTTP 422 ("user already exists") is treated as success. /// ("user already exists") / 409 is treated as success.
pub(super) async fn ensure_org(name: &str, admin_token: &str) -> Result<()> { pub(super) async fn ensure_org(name: &str, admin_token: &str) -> Result<()> {
let body = format!(r#"{{"username":"{name}"}}"#); let org = CreateOrgOption {
let url = format!("{FORGE_HTTP}/api/v1/orgs"); description: None,
let (status, _) = forge_http(reqwest::Method::POST, &url, admin_token, &body).await?; email: None,
match status.as_u16() { full_name: None,
201 => { location: None,
repo_admin_change_team_access: None,
username: name.to_owned(),
visibility: None,
website: None,
};
match api(admin_token)?.org_create(org).await {
Ok(_) => {
tracing::info!(%name, "forge: created org"); tracing::info!(%name, "forge: created org");
Ok(()) Ok(())
} }
422 | 409 => { Err(e) if is_already_exists(&e) => {
tracing::debug!(%name, "forge: org already exists"); tracing::debug!(%name, "forge: org already exists");
Ok(()) Ok(())
} }
other => anyhow::bail!("POST /api/v1/orgs name={name} returned HTTP {other}"), Err(e) => Err(e).with_context(|| format!("create org {name}")),
} }
} }
@ -414,63 +477,82 @@ const MIRROR_INTERVAL: &str = "8h0m0s";
/// Idempotent: if the repo already exists this function patches its /// Idempotent: if the repo already exists this function patches its
/// `mirror_interval` to ensure it matches (covers mirrors that were /// `mirror_interval` to ensure it matches (covers mirrors that were
/// created before the interval was introduced). A 409 on the migrate /// created before the interval was introduced). A 409 on the migrate
/// POST (a race between the GET check and the POST) is also success. /// call (a race between the existence check and the migrate) is also
/// success.
async fn ensure_mirror_repo( async fn ensure_mirror_repo(
upstream: &str, upstream: &str,
owner: &str, owner: &str,
repo: &str, repo: &str,
admin_token: &str, admin_token: &str,
) -> Result<()> { ) -> Result<()> {
let repo_url = format!("{FORGE_HTTP}/api/v1/repos/{owner}/{repo}"); let client = api(admin_token)?;
let (status, _) = forge_http(reqwest::Method::GET, &repo_url, admin_token, "").await?; match client.repo_get(owner, repo).await {
if status.is_success() { Ok(_) => {
// Mirror already present. Patch interval so mirrors seeded before // Mirror already present. Patch interval so mirrors seeded before
// this field was introduced (or with a different value) converge. // this field was introduced (or with a different value) converge.
let patch_body = serde_json::json!({ "mirror_interval": MIRROR_INTERVAL }).to_string(); let mut edit = sparse_edit_repo_option();
let (patch_status, patch_text) = edit.mirror_interval = Some(MIRROR_INTERVAL.to_owned());
forge_http(reqwest::Method::PATCH, &repo_url, admin_token, &patch_body).await?; match client.repo_edit(owner, repo, edit).await {
if patch_status.is_success() { Ok(_) => {
tracing::debug!(%owner, %repo, interval = MIRROR_INTERVAL, "forge: pull-mirror interval updated"); tracing::debug!(%owner, %repo, interval = MIRROR_INTERVAL, "forge: pull-mirror interval updated");
} else { }
tracing::warn!( Err(e) => {
%owner, %repo, status = %patch_status, body = %patch_text, tracing::warn!(
"forge: failed to set mirror_interval on existing pull-mirror" %owner, %repo, error = %e,
); "forge: failed to set mirror_interval on existing pull-mirror"
);
}
}
return Ok(());
}
// Absent — fall through to migrate.
Err(e) if is_not_found(&e) => {}
// Anything else (transport, auth, 5xx) leaves the repo's existence
// unknown: migrating anyway would fold a 409 into success and skip
// the interval patch this pass. Surface it instead.
Err(e) => {
return Err(e).with_context(|| format!("get pull-mirror {owner}/{repo}"));
} }
return Ok(());
} }
// serde_json::json! → the upstream URL is escaped safely (no string let opts = MigrateRepoOptions {
// interpolation into the JSON body). auth_password: None,
let body = serde_json::json!({ auth_token: None,
"clone_addr": upstream, auth_username: None,
"repo_owner": owner, clone_addr: upstream.to_owned(),
"repo_name": repo, description: None,
"mirror": true, issues: None,
labels: None,
lfs: None,
lfs_endpoint: None,
milestones: None,
mirror: Some(true),
// Periodic refresh instead of on-access sync — keeps CI isolated // Periodic refresh instead of on-access sync — keeps CI isolated
// from external DNS failures at clone time. // from external DNS failures at clone time.
"interval": MIRROR_INTERVAL, mirror_interval: Some(MIRROR_INTERVAL.to_owned()),
"service": "git", private: Some(false),
"private": false, pull_requests: None,
}) releases: None,
.to_string(); repo_name: repo.to_owned(),
let url = format!("{FORGE_HTTP}/api/v1/repos/migrate"); repo_owner: Some(owner.to_owned()),
let (status, text) = forge_http(reqwest::Method::POST, &url, admin_token, &body).await?; service: Some(MigrateRepoOptionsService::Git),
match status.as_u16() { uid: None,
201 => { wiki: None,
};
match client.repo_migrate(opts).await {
Ok(_) => {
tracing::info!(%owner, %repo, %upstream, interval = MIRROR_INTERVAL, "forge: created pull-mirror"); tracing::info!(%owner, %repo, %upstream, interval = MIRROR_INTERVAL, "forge: created pull-mirror");
Ok(()) Ok(())
} }
// 409 = a race created it between our GET check and here (the GET // 409 = a race created it between our existence check and here (the
// is the real idempotency guard). NOT 422: for the migrate endpoint // check is the real idempotency guard). NOT 422: for the migrate
// 422 is a validation error (bad clone_addr / service), so it must // endpoint 422 is a validation error (bad clone_addr / service), so
// surface via the bail arm, not be swallowed as "already exists". // it must surface via the error arm, not be swallowed as "already
409 => { // exists" — hence `is_conflict`, not `is_already_exists`.
Err(e) if is_conflict(&e) => {
tracing::debug!(%owner, %repo, "forge: pull-mirror already exists (race)"); tracing::debug!(%owner, %repo, "forge: pull-mirror already exists (race)");
Ok(()) Ok(())
} }
other => { Err(e) => Err(e).with_context(|| format!("migrate pull-mirror {owner}/{repo}")),
anyhow::bail!("POST /api/v1/repos/migrate {owner}/{repo} returned HTTP {other}: {text}")
}
} }
} }
@ -488,48 +570,101 @@ async fn ensure_mirror_repo(
/// repos unprotected — operator-merged config PRs then bypassed the deploy /// repos unprotected — operator-merged config PRs then bypassed the deploy
/// pipeline and silently didn't apply. /// pipeline and silently didn't apply.
pub(super) async fn ensure_operators_team(org: &str, token: &str) -> Result<()> { pub(super) async fn ensure_operators_team(org: &str, token: &str) -> Result<()> {
let url = format!("{FORGE_HTTP}/api/v1/orgs/{org}/teams"); let team = CreateTeamOption {
let body = format!( can_create_org_repo: Some(false),
r#"{{"name":"{OPERATORS_TEAM}","description":"hyperhive operators — merge gate for agent repos","permission":"write","includes_all_repositories":true,"can_create_org_repo":false}}"# description: Some("hyperhive operators — merge gate for agent repos".to_owned()),
); includes_all_repositories: Some(true),
let (status, _) = forge_http(reqwest::Method::POST, &url, token, &body).await?; name: OPERATORS_TEAM.to_owned(),
match status.as_u16() { permission: Some(CreateTeamOptionPermission::Write),
201 => { units: None,
units_map: None,
};
match api(token)?.org_create_team(org, team).await {
Ok(_) => {
tracing::info!(%org, "forge: created {OPERATORS_TEAM} team"); tracing::info!(%org, "forge: created {OPERATORS_TEAM} team");
Ok(()) Ok(())
} }
409 | 422 => { Err(e) if is_already_exists(&e) => {
tracing::debug!(%org, "forge: {OPERATORS_TEAM} team already exists"); tracing::debug!(%org, "forge: {OPERATORS_TEAM} team already exists");
Ok(()) Ok(())
} }
other => { Err(e) => Err(e).with_context(|| format!("create team {org}/{OPERATORS_TEAM}")),
anyhow::bail!("POST /orgs/{org}/teams ({OPERATORS_TEAM}) returned HTTP {other}")
}
} }
} }
/// Add `user` as a collaborator on `owner/repo` at `permission` /// Add `user` as a collaborator on `owner/repo` at `permission`.
/// (`read` / `write` / `admin`). Idempotent: 201 (added) and 204 (already a /// Idempotent: adding an existing collaborator just updates its
/// collaborator / permission updated) both count as success. /// permission (Forgejo answers 204 either way; a 201 from older
/// versions is tolerated defensively).
async fn add_collaborator( async fn add_collaborator(
owner: &str, owner: &str,
repo: &str, repo: &str,
user: &str, user: &str,
permission: &str, permission: AddCollaboratorOptionPermission,
token: &str, token: &str,
) -> Result<()> { ) -> Result<()> {
let url = format!("{FORGE_HTTP}/api/v1/repos/{owner}/{repo}/collaborators/{user}"); let res = api(token)?
let body = format!(r#"{{"permission":"{permission}"}}"#); .repo_add_collaborator(
let (status, _) = forge_http(reqwest::Method::PUT, &url, token, &body).await?; owner,
match status.as_u16() { repo,
201 | 204 => { user,
tracing::debug!(%owner, %repo, %user, %permission, "forge: collaborator set"); AddCollaboratorOption {
Ok(()) permission: Some(permission),
} },
other => { )
anyhow::bail!("PUT {owner}/{repo}/collaborators/{user} returned HTTP {other}") .await;
match res {
Ok(()) => {}
Err(ForgejoError::UnexpectedStatusCode(s)) if s == StatusCode::CREATED => {}
Err(e) => {
return Err(e).with_context(|| format!("add collaborator {user} to {owner}/{repo}"));
} }
} }
tracing::debug!(%owner, %repo, %user, ?permission, "forge: collaborator set");
Ok(())
}
/// `CreateBranchProtectionOption` protecting `main` with every other
/// field unset — Forgejo treats `None` fields as their defaults, same
/// as the sparse JSON bodies the raw-HTTP predecessor sent. Callers
/// set the whitelist/approval fields they need on top.
fn main_branch_protection_option() -> CreateBranchProtectionOption {
CreateBranchProtectionOption {
apply_to_admins: None,
approvals_whitelist_teams: None,
approvals_whitelist_username: None,
block_on_official_review_requests: None,
block_on_outdated_branch: None,
block_on_rejected_reviews: None,
branch_name: Some("main".to_owned()),
dismiss_stale_approvals: None,
enable_approvals_whitelist: None,
enable_merge_whitelist: None,
enable_push: None,
enable_push_whitelist: None,
enable_status_check: None,
ignore_stale_approvals: None,
merge_whitelist_teams: None,
merge_whitelist_usernames: None,
protected_file_patterns: None,
push_whitelist_deploy_keys: None,
push_whitelist_teams: None,
push_whitelist_usernames: None,
require_signed_commits: None,
required_approvals: None,
rule_name: None,
status_check_contexts: None,
unprotected_file_patterns: None,
}
}
/// Whether a branch-protection create failed because a rule for the
/// branch already exists: 409/422 ([`is_already_exists`]) or the 200
/// Forgejo answers instead of 201 for a duplicate rule (unlisted in
/// the endpoint spec, so it surfaces as `UnexpectedStatusCode(200)`).
fn is_protection_already_present(e: &ForgejoError) -> bool {
is_already_exists(e)
|| matches!(e, ForgejoError::UnexpectedStatusCode(s) if *s == StatusCode::OK)
} }
/// Apply the operator merge-gate branch protection to `repo`'s default /// Apply the operator merge-gate branch protection to `repo`'s default
@ -538,21 +673,26 @@ async fn add_collaborator(
/// agent, not in the team) cannot merge its own PR. Idempotent: an existing /// agent, not in the team) cannot merge its own PR. Idempotent: an existing
/// rule for the branch (200/409/422) is treated as success. /// rule for the branch (200/409/422) is treated as success.
async fn apply_operator_branch_protection(repo: &str, token: &str) -> Result<()> { async fn apply_operator_branch_protection(repo: &str, token: &str) -> Result<()> {
let url = format!("{FORGE_HTTP}/api/v1/repos/{AGENTS_ORG}/{repo}/branch_protections"); let mut rule = main_branch_protection_option();
let body = format!( rule.enable_merge_whitelist = Some(true);
r#"{{"branch_name":"main","enable_merge_whitelist":true,"merge_whitelist_teams":["{OPERATORS_TEAM}"],"enable_approvals_whitelist":true,"approvals_whitelist_teams":["{OPERATORS_TEAM}"],"required_approvals":1,"block_on_official_review_requests":true}}"# rule.merge_whitelist_teams = Some(vec![OPERATORS_TEAM.to_owned()]);
); rule.enable_approvals_whitelist = Some(true);
let (status, _) = forge_http(reqwest::Method::POST, &url, token, &body).await?; rule.approvals_whitelist_teams = Some(vec![OPERATORS_TEAM.to_owned()]);
match status.as_u16() { rule.required_approvals = Some(1);
201 => { rule.block_on_official_review_requests = Some(true);
match api(token)?
.repo_create_branch_protection(AGENTS_ORG, repo, rule)
.await
{
Ok(_) => {
tracing::info!(%repo, "forge: applied operator branch protection"); tracing::info!(%repo, "forge: applied operator branch protection");
Ok(()) Ok(())
} }
200 | 409 | 422 => { Err(e) if is_protection_already_present(&e) => {
tracing::debug!(%repo, "forge: branch protection already present"); tracing::debug!(%repo, "forge: branch protection already present");
Ok(()) Ok(())
} }
other => anyhow::bail!("POST {AGENTS_ORG}/{repo}/branch_protections returned HTTP {other}"), Err(e) => Err(e).with_context(|| format!("create branch protection {AGENTS_ORG}/{repo}")),
} }
} }
@ -564,45 +704,63 @@ async fn apply_operator_branch_protection(repo: &str, token: &str) -> Result<()>
/// (`run_merge_config_pr`). The agent can never push `main` directly. /// (`run_merge_config_pr`). The agent can never push `main` directly.
/// - **operator-team approval is required** to merge, and the author (not in /// - **operator-team approval is required** to merge, and the author (not in
/// the team) cannot self-approve. /// the team) cannot self-approve.
/// - **`enable_force_push` is `false`** — `main` only ever advances by /// - **force-pushing `main` stays impossible** — `main` only ever advances by
/// fast-forward. The merge handler's `ff_push_to_main` is already a /// fast-forward. The merge handler's `ff_push_to_main` is already a
/// non-force push, so it lands fine. The legacy `push_config` mirror DOES /// non-force push, so it lands fine. The legacy `push_config` mirror DOES
/// force-push (it re-points status tags and rewinds `main` on a failed-build /// force-push (it re-points status tags and rewinds `main` on a failed-build
/// rollback), so the protection now rejects those non-ff updates — that /// rollback), so the protection rejects those non-ff updates — that
/// mirror runs best-effort until the agent-opened PR-merge flow retires it. /// mirror runs best-effort until the agent-opened PR-merge flow retires it.
/// (Auto force-push is intentionally not allowed: per operator directive a /// (Auto force-push is intentionally not allowed: per operator directive a
/// silent force-push is a bug, not a feature.) /// silent force-push is a bug, not a feature. The raw-HTTP predecessor
/// sent `"enable_force_push":false` + `"allow_manual_merge":true` in this
/// body; neither is a `CreateBranchProtectionOption` field, so Forgejo
/// ignored both keys — dropping them changes nothing: force-push
/// protection defaults to off, and `allow_manual_merge` is a *repo*
/// setting, not a branch-protection one.)
/// ///
/// Idempotent: an existing rule for the branch (200/409/422) is success. /// Idempotent: an existing rule for the branch (200/409/422) is success.
async fn apply_config_repo_branch_protection(repo: &str, token: &str) -> Result<()> { async fn apply_config_repo_branch_protection(repo: &str, token: &str) -> Result<()> {
let url = format!("{FORGE_HTTP}/api/v1/repos/{CONFIG_ORG}/{repo}/branch_protections"); let client = api(token)?;
let body = format!( let mut rule = main_branch_protection_option();
r#"{{"branch_name":"main","enable_push_whitelist":true,"push_whitelist_usernames":["core"],"enable_merge_whitelist":true,"merge_whitelist_usernames":["core"],"enable_approvals_whitelist":true,"approvals_whitelist_teams":["{OPERATORS_TEAM}"],"required_approvals":1,"block_on_official_review_requests":true,"allow_manual_merge":true,"enable_force_push":false}}"# rule.enable_push_whitelist = Some(true);
); rule.push_whitelist_usernames = Some(vec!["core".to_owned()]);
let (status, resp_body) = forge_http(reqwest::Method::POST, &url, token, &body).await?; rule.enable_merge_whitelist = Some(true);
if status.as_u16() == 201 { rule.merge_whitelist_usernames = Some(vec!["core".to_owned()]);
rule.enable_approvals_whitelist = Some(true);
rule.approvals_whitelist_teams = Some(vec![OPERATORS_TEAM.to_owned()]);
rule.required_approvals = Some(1);
rule.block_on_official_review_requests = Some(true);
let Err(create_err) = client
.repo_create_branch_protection(CONFIG_ORG, repo, rule)
.await
else {
tracing::info!(%repo, "forge: applied config-repo branch protection"); tracing::info!(%repo, "forge: applied config-repo branch protection");
return Ok(()); return Ok(());
} };
// Non-201 is ambiguous: it can mean "rule already exists" (idempotent // A create failure is ambiguous: it can mean "rule already exists"
// success) OR a silent rejection — e.g. a 422 where Forgejo refused // (idempotent success) OR a silent rejection — e.g. a 422 where Forgejo
// the request and created NO rule. The old code treated 200/409/422 // refused the request and created NO rule. The old code treated
// all as success, so a rejected POST left the repo unprotected with // 200/409/422 all as success, so a rejected POST left the repo
// no error (the reported case: a new agent's config repo had no // unprotected with no error (the reported case: a new agent's config
// `main` rule and nothing was logged). Don't trust the status code: // repo had no `main` rule and nothing was logged). Don't trust the
// verify the `main` rule actually exists, and on failure surface the // status: verify the `main` rule actually exists, and on failure
// POST's response body so the real reason is in the journal. // surface the create error (its Display carries Forgejo's validation
let main_url = format!("{url}/main"); // message) so the real reason is in the journal.
let (check, _) = forge_http(reqwest::Method::GET, &main_url, token, "").await?; match client
if check.as_u16() == 200 { .repo_get_branch_protection(CONFIG_ORG, repo, "main")
tracing::debug!(%repo, %status, "forge: config-repo branch protection already present"); .await
Ok(()) {
} else { Ok(_) => {
anyhow::bail!( tracing::debug!(
"branch protection for {CONFIG_ORG}/{repo} not applied: POST -> HTTP {status} \ %repo, create_error = %create_err,
(body: {body}); GET main -> HTTP {check}, no `main` rule present", "forge: config-repo branch protection already present"
body = resp_body.trim(), );
) Ok(())
}
Err(check_err) => anyhow::bail!(
"branch protection for {CONFIG_ORG}/{repo} not applied: create failed \
({create_err}); GET main rule failed ({check_err}), no `main` rule present"
),
} }
} }
@ -614,7 +772,14 @@ async fn apply_config_repo_branch_protection(repo: &str, token: &str) -> Result<
/// create repos directly (`max_repo_creation = 0`). Idempotent. /// create repos directly (`max_repo_creation = 0`). Idempotent.
pub async fn create_agent_repo(agent: &str, repo: &str, core_token: &str) -> Result<String> { pub async fn create_agent_repo(agent: &str, repo: &str, core_token: &str) -> Result<String> {
ensure_org_repo(AGENTS_ORG, repo, core_token).await?; ensure_org_repo(AGENTS_ORG, repo, core_token).await?;
add_collaborator(AGENTS_ORG, repo, agent, "write", core_token).await?; add_collaborator(
AGENTS_ORG,
repo,
agent,
AddCollaboratorOptionPermission::Write,
core_token,
)
.await?;
apply_operator_branch_protection(repo, core_token).await?; apply_operator_branch_protection(repo, core_token).await?;
tracing::info!(%agent, %repo, "forge: created agent repo in {AGENTS_ORG} with operator merge gate"); tracing::info!(%agent, %repo, "forge: created agent repo in {AGENTS_ORG} with operator merge gate");
Ok(format!("{AGENTS_ORG}/{repo}")) Ok(format!("{AGENTS_ORG}/{repo}"))

Some files were not shown because too many files have changed in this diff Show more