Watch
0
0
Fork
You've already forked hyperhive
0

Compare commits

..
61 changed files with 1914 additions and 2740 deletions

View file

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

93
Cargo.lock generated
View file

@ -630,16 +630,6 @@ version = "0.4.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
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]]
name = "core-foundation"
version = "0.10.1"
@ -872,7 +862,6 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7cd812cc2bc1d69d4764bd80df88b4317eaef9e773c75226407d9bc0876b211c"
dependencies = [
"powerfmt",
"serde_core",
]
[[package]]
@ -935,15 +924,6 @@ version = "1.16.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
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]]
name = "equivalent"
version = "1.0.2"
@ -1077,27 +1057,6 @@ version = "0.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
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]]
name = "form_urlencoded"
version = "1.2.2"
@ -1379,7 +1338,6 @@ dependencies = [
"anyhow",
"axum",
"clap",
"forgejo-api",
"futures-util",
"hive-claude",
"hive-sh4re",
@ -1390,13 +1348,11 @@ dependencies = [
"serde",
"serde_json",
"tempfile",
"time",
"tokio",
"tokio-stream",
"tower-http",
"tracing",
"tracing-subscriber",
"url",
]
[[package]]
@ -1428,7 +1384,6 @@ dependencies = [
"clap",
"clap-markdown",
"clap_complete",
"forgejo-api",
"hive-sh4re",
"libc",
"listenfd",
@ -1443,7 +1398,6 @@ dependencies = [
"tokio-stream",
"tracing",
"tracing-subscriber",
"url",
]
[[package]]
@ -1463,12 +1417,9 @@ version = "0.1.0"
dependencies = [
"anyhow",
"clap",
"forgejo-api",
"reqwest",
"serde",
"serde_json",
"time",
"url",
]
[[package]]
@ -1680,11 +1631,9 @@ dependencies = [
"percent-encoding",
"pin-project-lite",
"socket2",
"system-configuration",
"tokio",
"tower-service",
"tracing",
"windows-registry",
]
[[package]]
@ -3069,7 +3018,6 @@ checksum = "eddd3ca559203180a307f12d114c268abf583f59b03cb906fd0b3ff8646c1147"
dependencies = [
"base64",
"bytes",
"encoding_rs",
"futures-channel",
"futures-core",
"futures-util",
@ -3082,7 +3030,6 @@ dependencies = [
"hyper-util",
"js-sys",
"log",
"mime",
"mime_guess",
"percent-encoding",
"pin-project-lite",
@ -3510,7 +3457,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b7f4bc775c73d9a02cde8bf7b2ec4c9d12743edf609006c7facc23998404cd1d"
dependencies = [
"bitflags",
"core-foundation 0.10.1",
"core-foundation",
"core-foundation-sys",
"libc",
"security-framework-sys",
@ -3742,12 +3689,6 @@ dependencies = [
"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]]
name = "spki"
version = "0.7.3"
@ -3845,27 +3786,6 @@ dependencies = [
"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]]
name = "tempfile"
version = "3.27.0"
@ -4676,17 +4596,6 @@ version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
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]]
name = "windows-result"
version = "0.4.1"

View file

@ -68,14 +68,6 @@ reqwest = { version = "0.12", default-features = false, features = [
"json",
"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"] }
matrix-sdk = { version = "0.14", default-features = false, features = [
"rustls-tls",

View file

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

View file

@ -71,12 +71,7 @@ Two things live in the `agent-configs` Forgejo organization:
The `hive-forge` CLI (separate workspace crate, see
[`README.md`](../README.md) file map) wraps the Forgejo REST API
with the per-agent token; agents call it for issue / PR / comment
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.
ops as if it were a peer.
## Notification poller (`hive-ag3nt/src/forge_notify.rs`)
@ -151,14 +146,11 @@ one path still marked-read directly (no read-before-comment value).
The poller starts disabled and stays that way for any of:
- `HIVE_FORGE_URL` not set (no forge configured for this hive), or
not parseable as a URL.
- `HIVE_FORGE_URL` not set (no forge configured for this hive).
- `<state>/forge-token` missing or empty (agent has no forge
account — pre-provisioning or destroy-without-purge race).
- Initial client construction fails (the typed `forgejo-api` client
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).
- Initial `reqwest::Client::builder` fails (extremely unlikely;
treated as fatal-to-the-task only).
Disabled = the spawned task returns immediately. All other failure
modes (HTTP errors, parse errors, mark-read failures) are

View file

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

View file

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

View file

@ -1,43 +0,0 @@
//! 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

@ -1,60 +0,0 @@
//! 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:?}"),
}
}

735
hive-ag3nt/src/bin/hive.rs Normal file
View file

@ -0,0 +1,735 @@
//! Unified hyperhive harness binary. Dispatches one of three subcommands
//! (`serve` / `mcp` / `wake`). There is one role: agent. The `Surface`
//! trait + `AgentSurface` zero-sized type tag keeps the turn loop
//! generic and testable. Architecture lives in
//! [`docs/turn-loop.md::Harness binary shape`](../../../docs/turn-loop.md).
use std::path::{Path, PathBuf};
use std::sync::{Arc, Mutex};
use std::time::Duration;
use anyhow::Result;
use clap::{Parser, Subcommand};
use hive_ag3nt::events::{Bus, LiveEvent, TurnState};
use hive_ag3nt::login::{self, LoginState};
use hive_ag3nt::turn_stats::TurnStats;
use hive_ag3nt::{
DEFAULT_SOCKET, DEFAULT_WEB_PORT, client, mcp, plugins, serve_common, turn, web_ui,
};
use hive_sh4re::{AgentRequest, AgentResponse, HelperEvent, SYSTEM_SENDER};
#[derive(Parser)]
#[command(name = "hive", about = "hyperhive harness")]
struct Cli {
/// Path to the per-agent MCP socket (bind-mounted from the host).
#[arg(long, global = true, default_value = DEFAULT_SOCKET)]
socket: PathBuf,
#[command(subcommand)]
cmd: Cmd,
}
#[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]
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.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 ----------
/// Surface a `SYSTEM_SENDER` message in the live event bus + tracing
/// log. Both agents and the manager receive `QuestionAnswered`,
/// `ContainerCrash`, reparent notifications, and friends; the parse
/// and log path is identical. Quiet no-op when `from` isn't
/// `SYSTEM_SENDER`.
fn log_system_event(bus: &Bus, from: &str, body: &str) {
if from != SYSTEM_SENDER {
return;
}
let parsed = serde_json::from_str::<HelperEvent>(body).ok();
if let Some(event) = parsed {
tracing::info!(?event, "helper event");
} else {
tracing::info!(%from, %body, "system message");
}
bus.emit(LiveEvent::Note {
text: format!("[system] {body}"),
});
}
/// Body string for the turn-failure notification we route to
/// `<parent>` on `TurnError::Failed`. Reads the hive-qualified
/// identity so the receiver sees `agent@hive` rather than relying on
/// the caller threading a `label` through every turn-handling layer.
/// Falls back to `<unknown>` when `HIVE_LABEL` is missing so a
/// misconfigured harness still produces a parseable line.
fn format_turn_failure(err: &anyhow::Error) -> String {
let who = hive_ag3nt::identity::qualified_label();
let who = if who.is_empty() {
"<unknown>".to_owned()
} else {
who
};
format!("[system] `{who}` claude turn failed:\n{err:#}")
}
/// Check for the `hyperhive-continue` sentinel under the state dir
/// (dropped by the `request_next_turn` MCP tool). Returns true and
/// consumes the file when present; false otherwise. Caller fires
/// the role-specific `Wake` request — the sentinel itself is wire-
/// agnostic so this helper lives outside both surfaces.
fn consume_continue_sentinel() -> bool {
let sentinel = hive_ag3nt::paths::state_dir().join("hyperhive-continue");
if !sentinel.exists() {
return false;
}
if let Err(e) = std::fs::remove_file(&sentinel) {
tracing::warn!(error = %e, "consume_continue_sentinel: remove sentinel failed");
return false;
}
true
}
/// What a finished turn tells the serve loop to do next. Replaces the
/// bare `auth_failed` bool so the loop can also act on a pending
/// `request_next_turn` without round-tripping a synthetic message
/// through the broker.
struct TurnControl {
/// The turn ended in `AuthFailed` — caller parks on login.
auth_failed: bool,
/// `request_next_turn` was called during the turn (the
/// `hyperhive-continue` sentinel was dropped + consumed).
continue_requested: bool,
/// Inbox unread count observed right after the turn. Used to
/// decide whether a self-continue is actually needed.
pending: u64,
}
/// Decide whether the serve loop should drive a self-continue turn
/// in-process. A continue is only "needed" when nothing else will
/// wake the agent: if real messages are already pending they drive
/// the next turn(s) and the continue is dropped (matches the
/// `request_next_turn` contract — "no effect if a new inbox message
/// arrives before this turn ends"). Auth-failed parks the loop on
/// login, so it suppresses the continue too.
fn should_self_continue(ctrl: &TurnControl) -> bool {
ctrl.continue_requested && !ctrl.auth_failed && ctrl.pending == 0
}
/// Synthesize the `from: "self"` / `body: "continue"` message that a
/// `request_next_turn` self-continue drives. Built in-process rather
/// than fetched from the broker — it never touches the send/recv
/// path, so it doesn't persist to sqlite or pollute the inbox.
/// `id = 0` is a non-broker sentinel: the synthetic message
/// has no DB row, and `AckTurn` keys off the recipient's in-flight
/// list (which is empty here) rather than this id.
fn synthetic_continue() -> hive_sh4re::DeliveredMessage {
hive_sh4re::DeliveredMessage {
from: "self".into(),
body: "continue".into(),
id: 0,
redelivered: false,
in_reply_to: None,
}
}
/// Synthetic message that drives the single stop-checkpoint turn when c0re
/// signals a graceful stop. The agent gets one final turn to flush durable
/// `/state` before the container is stopped; new inbound is already fenced.
fn graceful_stop_message() -> hive_sh4re::DeliveredMessage {
hive_sh4re::DeliveredMessage {
from: "graceful-stop".into(),
body: "You are being gracefully stopped — the container will shut down after this turn, \
and new inbound messages are already fenced. This is your one checkpoint turn: \
flush anything worth keeping into your durable /state files now — update your \
notes / CLAUDE.md / TODO.md with in-flight task state, decisions made, important \
file paths, and whatever you'd need to resume cleanly later with only a summary \
of this conversation to go on. Do not start new work or reply to anyone; just \
write your notes and end your turn. The session may be compacted after this turn \
so a later cold start resumes cheaply."
.into(),
id: 0,
redelivered: false,
in_reply_to: None,
}
}
// ---------- surface trait ----------
/// What a `Recv` long-poll returned. Decoupled from the per-role
/// Response enum so `serve_loop` can pattern-match without seeing
/// either `AgentResponse` or `ManagerResponse` directly.
enum RecvOutcome {
/// Long-poll returned at least one message; first one is detached.
Message(hive_sh4re::DeliveredMessage),
/// Long-poll timed out cleanly (empty `Messages` response). Caller
/// sleeps then retries.
Empty,
/// Wire returned an error / unexpected variant. Caller logs +
/// retries; the surface impl is responsible for tracing the
/// detail before returning this.
TransportError,
/// c0re signalled a graceful stop for this agent. The serve loop runs
/// one stop-checkpoint turn (flush durable `/state`), reports
/// `GracefulStopComplete`, and exits so the container can be stopped.
GracefulStop,
}
/// Wire surface abstraction. `AgentSurface` is the only impl — the trait
/// exists to keep the turn loop generic and testable. Every function that
/// talks to the broker goes through this so there are zero hard-coded
/// `AgentRequest` / `AgentResponse` references in the turn loop itself.
trait Surface {
/// Ack the in-flight turn. Logs warnings on transport/broker
/// errors but never propagates — turn loop continues either way.
fn ack_turn(socket: &Path) -> impl Future<Output = ()>;
/// Requeue any messages that were "in-flight" (delivered but not
/// ack'd) — fires on harness boot to recover from a crash mid-turn.
fn requeue_inflight(socket: &Path) -> impl Future<Output = ()>;
/// Current inbox unread count via `Status`. Returns 0 on any
/// transport/wire error so the caller falls through cleanly.
fn inbox_unread(socket: &Path) -> impl Future<Output = u64>;
/// `(open_threads, open_reminders)` for the post-turn stats row.
/// Either field is `None` when the underlying request errors.
fn post_turn_counts(socket: &Path) -> impl Future<Output = (Option<u64>, Option<u64>)>;
/// Tell c0re the graceful-stop checkpoint is done and the harness is
/// exiting its serve loop (fire-and-forget; logs on error). Lets the
/// `GracefulStop` orchestration stop the container without waiting out
/// its timeout fallback.
fn graceful_stop_complete(socket: &Path) -> impl Future<Output = ()>;
/// Send a message addressed to `<parent>` (broker resolves the
/// sentinel via `topology::parent_of` at delivery time; root
/// agents/manager fall through to operator).
fn send_to_parent(socket: &Path, body: String) -> impl Future<Output = ()>;
/// Long-poll the broker for the next message. Wraps the
/// `Messages`/empty/error trichotomy in `RecvOutcome` so the
/// generic `serve_loop` doesn't need the per-role Response enum
/// at all.
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 ----------
/// Zero-sized type tag for the agent wire surface.
/// Talks `AgentRequest` / `AgentResponse`.
struct AgentSurface;
/// Issue an `Ok`-expecting fire-and-forget broker request, logging any
/// rejection / unexpected response / transport error under `label`. Shared by
/// the `Surface` methods that don't need the reply (`ack_turn`,
/// `requeue_inflight`, `graceful_stop_complete`).
async fn fire_and_forget(socket: &Path, req: AgentRequest, label: &str) {
match client::request::<_, AgentResponse>(socket, &req).await {
Ok(AgentResponse::Ok) => {}
Ok(AgentResponse::Err { message }) => {
tracing::warn!(%message, "{label} rejected by broker");
}
Ok(other) => tracing::warn!(?other, "{label} unexpected response"),
Err(e) => tracing::warn!(error = ?e, "{label} transport error"),
}
}
impl Surface for AgentSurface {
async fn ack_turn(socket: &Path) {
fire_and_forget(socket, AgentRequest::AckTurn, "ack_turn").await;
}
async fn requeue_inflight(socket: &Path) {
fire_and_forget(socket, AgentRequest::RequeueInflight, "requeue_inflight").await;
}
async fn graceful_stop_complete(socket: &Path) {
fire_and_forget(
socket,
AgentRequest::GracefulStopComplete,
"graceful_stop_complete",
)
.await;
}
async fn inbox_unread(socket: &Path) -> u64 {
match client::request::<_, AgentResponse>(socket, &AgentRequest::Status).await {
Ok(AgentResponse::Status { unread }) => unread,
_ => 0,
}
}
async fn post_turn_counts(socket: &Path) -> (Option<u64>, Option<u64>) {
let threads = match client::request::<_, AgentResponse>(
socket,
&AgentRequest::GetLooseEnds { agent: None },
)
.await
{
Ok(AgentResponse::LooseEnds { loose_ends }) => u64::try_from(loose_ends.len()).ok(),
_ => None,
};
let reminders = match client::request::<_, AgentResponse>(
socket,
&AgentRequest::CountPendingReminders { agent: None },
)
.await
{
Ok(AgentResponse::PendingRemindersCount { count }) => Some(count),
_ => None,
};
(threads, reminders)
}
async fn send_to_parent(socket: &Path, body: String) {
let res = client::request::<_, AgentResponse>(
socket,
&AgentRequest::Send {
to: hive_sh4re::PARENT_RECIPIENT.into(),
body,
in_reply_to: None,
},
)
.await;
if let Err(e) = res {
tracing::warn!(error = ?e, "failed to notify parent of turn failure");
}
}
async fn recv_next(socket: &Path) -> RecvOutcome {
let recv: Result<AgentResponse> = client::request(
socket,
&AgentRequest::Recv {
wait_seconds: Some(180),
max: None,
},
)
.await;
match recv {
Ok(AgentResponse::Messages { messages }) if !messages.is_empty() => {
let first = messages.into_iter().next().expect("checked non-empty");
RecvOutcome::Message(first)
}
Ok(AgentResponse::Messages { .. }) => RecvOutcome::Empty,
Ok(AgentResponse::GracefulStop) => RecvOutcome::GracefulStop,
Ok(AgentResponse::Err { message }) => {
tracing::warn!(%message, "recv error");
RecvOutcome::TransportError
}
Ok(other) => {
tracing::warn!(?other, "recv produced unexpected response kind");
RecvOutcome::TransportError
}
Err(e) => {
tracing::warn!(error = ?e, "recv failed; retrying");
RecvOutcome::TransportError
}
}
}
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 ----------
/// Boot — wires up the web UI, login state, stats, plugins, forge
/// notifier, and either drops into `serve_loop` directly (`Online`) or
/// parks on the login flow first (`NeedsLogin`). See
/// `docs/turn-loop.md::Boot wiring`.
async fn serve_main<S: Surface>(socket: &Path, poll_ms: u64) -> Result<()> {
let port = std::env::var("HIVE_PORT")
.ok()
.and_then(|s| s.parse::<u16>().ok())
.unwrap_or(DEFAULT_WEB_PORT);
// `HIVE_LABEL` is set unconditionally by the meta-flake envelope
// for any container-deployed agent; the `"hive"` fallback here
// covers standalone `nix run .#hive` invocations and pre-meta
// dev shells. Role-independent: no semantic reason for the
// fallback to differ when the env var is missing.
let label = std::env::var("HIVE_LABEL").unwrap_or_else(|_| "hive".into());
let claude_dir = login::default_dir();
let initial = LoginState::from_dir(&claude_dir);
tracing::info!(state = ?initial, claude_dir = %claude_dir.display(), "harness boot");
let login_state = Arc::new(Mutex::new(initial));
let bus = Bus::new();
let stats = TurnStats::open_default();
if let Some(s) = &stats {
let (ctx, cost) = s.last_usage();
if ctx.is_some() || cost.is_some() {
bus.seed_usage(ctx, cost);
}
}
let files = turn::TurnFiles::prepare(socket, &label).await?;
// Plugin install failures come back as a Vec<String> — route each
// through `<parent>` via the `send_to_parent` failure-notify path.
// The broker resolves `<parent>` per `topology::parent_of`;
// root agents fall through to operator.
for failure in plugins::install_configured().await {
S::send_to_parent(socket, failure).await;
}
tokio::spawn(hive_ag3nt::forge_notify::run(socket.to_path_buf()));
// Agent-side cleanup of this agent's own harness artifacts (completed
// bash-task files + verbose event rows). Runs here, not host-side in
// hive-c0re, because the files are agent-owned — see `vacuum` module docs.
tokio::spawn(hive_ag3nt::vacuum::run());
// Log web_ui::serve's error instead of dropping it. A bare
// `tokio::spawn(web_ui::serve(...))` discards the JoinHandle, so
// any Err (e.g. EACCES from `bind_unix` when HIVE_WEB_SOCKET points
// at a dir the agent user can't write) vanishes — leaving an
// operator with no log line and no socket, debuggable only by
// staring at lifecycle.rs.
let web_ui_args = (
label.clone(),
port,
login_state.clone(),
bus.clone(),
socket.to_path_buf(),
);
tokio::spawn(async move {
let (label, port, login_state, bus, socket) = web_ui_args;
if let Err(e) = web_ui::serve(label, port, login_state, bus, socket).await {
tracing::error!(error = %e, "web_ui::serve exited with error");
}
});
if matches!(initial, LoginState::NeedsLogin) {
login::wait_for_login(&claude_dir, login_state.clone(), &bus, poll_ms).await;
} else {
// Clear any stale `hyperhive-needs-login` sentinel left over
// from a prior boot — `online` status writes the sentinel
// cleanup in `Bus::emit_status`.
bus.emit_status("online");
}
serve_loop::<S>(
socket,
Duration::from_millis(poll_ms),
login_state,
claude_dir,
bus,
stats,
&files,
)
.await
}
/// The long-running message loop. Long-polls the broker via
/// `S::recv_next`, drives a turn per message, parks on auth-failed,
/// otherwise retries.
#[allow(
clippy::too_many_arguments,
reason = "the harness's long-lived deps threaded into one serve loop, \
wired once from main; bundling into a struct would just move the \
same fields one level out (cf. Coordinator::open)"
)]
async fn serve_loop<S: Surface>(
socket: &Path,
interval: Duration,
login_state: Arc<Mutex<LoginState>>,
claude_dir: std::path::PathBuf,
bus: Bus,
stats: Option<TurnStats>,
files: &turn::TurnFiles,
) -> Result<()> {
tracing::info!(socket = %socket.display(), "harness serve");
S::requeue_inflight(socket).await;
// The durable claude session, built once and reused for every turn +
// idle compaction below (it's effectively stateless).
let session = turn::make_session(&bus);
// Set when a turn calls `request_next_turn` and no real work is
// pending — the next iteration drives this synthetic message
// in-process instead of long-polling the broker. Never
// persisted: it lives entirely in this loop's stack.
let mut self_continue: Option<hive_sh4re::DeliveredMessage> = None;
loop {
let next = match self_continue.take() {
Some(msg) => msg,
None => match S::recv_next(socket).await {
RecvOutcome::Message(first) => first,
RecvOutcome::Empty => {
// Idle: no message this poll. Service a queued operator
// `/compact` here so it runs even when no turn is driving
// (the in-flight case is handled at the end of drive_turn).
let compacted = turn::run_pending_compact(files, &bus, &session).await;
if !compacted {
tokio::time::sleep(interval).await;
}
continue;
}
RecvOutcome::TransportError => {
// `recv_next` already logged the detail; just retry.
// No backoff: the long-poll wait is itself the throttle.
continue;
}
RecvOutcome::GracefulStop => {
// c0re fenced our inbox and wants a clean stop. Run one
// checkpoint turn so the agent flushes durable /state,
// report completion, then exit the loop → the harness
// process ends and the container can be stopped.
tracing::info!(
"graceful stop signalled — running stop-checkpoint turn, then exiting"
);
let _ = handle_turn::<S>(
socket,
&bus,
stats.as_ref(),
files,
&session,
graceful_stop_message(),
)
.await;
S::graceful_stop_complete(socket).await;
return Ok(());
}
},
};
let ctrl = handle_turn::<S>(socket, &bus, stats.as_ref(), files, &session, next).await;
if ctrl.auth_failed {
*login_state.lock().unwrap() = LoginState::NeedsLogin;
login::wait_for_login(
&claude_dir,
login_state.clone(),
&bus,
u64::try_from(interval.as_millis()).unwrap_or(2000),
)
.await;
} else if should_self_continue(&ctrl) {
tracing::info!("request_next_turn: driving self-continue turn in-process");
self_continue = Some(synthetic_continue());
}
}
}
/// Drive a single turn: emit boot-of-turn events, run claude, ack on
/// success / requeue on rate-limit-or-401 / notify parent on failure,
/// record stats, then pick up the `request_next_turn` sentinel if it's
/// been dropped during the turn. Returns a `TurnControl` carrying the
/// auth-failed flag, whether a self-continue was requested, and the
/// post-turn inbox count — the serve loop decides what to do next.
async fn handle_turn<S: Surface>(
socket: &Path,
bus: &Bus,
stats: Option<&TurnStats>,
files: &turn::TurnFiles,
session: &turn::AgentSession,
first: hive_sh4re::DeliveredMessage,
) -> TurnControl {
let from = first.from;
let body = first.body;
let redelivered = first.redelivered;
let msg_id = first.id;
log_system_event(bus, &from, &body);
tracing::info!(%from, %body, %redelivered, "inbox");
let unread = S::inbox_unread(socket).await;
bus.emit(LiveEvent::TurnStart {
from: from.clone(),
body: body.clone(),
unread,
});
bus.set_state(TurnState::Thinking);
let started_at = serve_common::now_unix();
let started_instant = std::time::Instant::now();
let model_at_start = bus.model();
let prompt = serve_common::format_wake_prompt(msg_id, &from, &body, unread, redelivered);
let outcome = turn::drive_turn(&prompt, files, bus, session).await;
turn::emit_turn_end(bus, &outcome);
bus.set_state(TurnState::Idle);
if outcome.is_ok() {
S::ack_turn(socket).await;
}
if matches!(outcome, Err(turn::TurnError::RateLimited)) {
let secs = turn::rate_limit_sleep_secs();
bus.emit_status("rate_limited");
bus.emit(LiveEvent::Note {
text: format!("API rate-limited — sleeping {secs}s before retry"),
});
tracing::warn!(sleep_secs = secs, "rate-limited; parking");
tokio::time::sleep(Duration::from_secs(secs)).await;
S::requeue_inflight(socket).await;
bus.emit_status("online");
}
if matches!(outcome, Err(turn::TurnError::AuthFailed)) {
bus.emit_status("needs_login_idle");
bus.emit(LiveEvent::Note {
text: "API 401 — waiting for re-login via web UI".into(),
});
tracing::warn!("auth-failed; parking until re-login");
S::requeue_inflight(socket).await;
}
if matches!(outcome, Err(turn::TurnError::PromptTooLong)) {
// `drive_turn` already archived the session; requeue the message so it
// redelivers into the fresh session (which fits — the wake prompt is
// tiny, the overflow was the now-cleared context). No status park: the
// agent is healthy, it just needs one more delivery.
tracing::warn!("prompt-too-long; session archived, requeueing message for a fresh turn");
S::requeue_inflight(socket).await;
}
if matches!(outcome, Err(turn::TurnError::SessionNotFound)) {
// "Shouldn't happen": resume missed and the lib's create self-heal
// didn't resolve it. Requeue rather than ack-and-drop so the wake
// message isn't silently lost; the next turn creates the session fresh.
tracing::warn!("session-not-found; requeueing message for a fresh turn");
S::requeue_inflight(socket).await;
}
if let Err(turn::TurnError::Failed(e)) = &outcome {
S::send_to_parent(socket, format_turn_failure(e)).await;
}
if let Some(stats) = stats {
// Fresh session this turn → mint a `sessions` row and set its id on
// the bus so this turn (and subsequent ones until the next fresh
// start) stamp `turn_stats.session_id`. Takes the one-shot flag
// `run_claude` set when it suppressed `--continue`.
if bus.take_fresh_session() {
let sid = stats.start_session(started_at, &model_at_start);
bus.set_session_id(sid);
}
let ended_at = serve_common::now_unix();
let duration_ms = i64::try_from(started_instant.elapsed().as_millis()).unwrap_or(i64::MAX);
let (open_threads, open_reminders) = S::post_turn_counts(socket).await;
let row = serve_common::build_row(serve_common::TurnRowArgs {
started_at,
ended_at,
duration_ms,
model: model_at_start,
wake_from: from.clone(),
outcome: &outcome,
bus,
open_threads_count: open_threads,
open_reminders_count: open_reminders,
});
stats.record(&row);
}
let pending = S::inbox_unread(socket).await;
if pending > 0 {
tracing::info!(%pending, "pending messages after turn; fetching next");
}
TurnControl {
auth_failed: matches!(outcome, Err(turn::TurnError::AuthFailed)),
continue_requested: consume_continue_sentinel(),
pending,
}
}
/// 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)]
mod continue_tests {
use super::{TurnControl, should_self_continue, synthetic_continue};
fn ctrl(auth_failed: bool, continue_requested: bool, pending: u64) -> TurnControl {
TurnControl {
auth_failed,
continue_requested,
pending,
}
}
#[test]
fn self_continue_when_requested_and_inbox_empty() {
assert!(should_self_continue(&ctrl(false, true, 0)));
}
#[test]
fn no_self_continue_when_not_requested() {
assert!(!should_self_continue(&ctrl(false, false, 0)));
}
#[test]
fn no_self_continue_when_real_messages_pending() {
// A real message will drive the next turn via recv — the
// continue is superseded, not needed (request_next_turn contract).
assert!(!should_self_continue(&ctrl(false, true, 3)));
}
#[test]
fn no_self_continue_when_auth_failed() {
// Auth-failed parks the loop on login; a queued continue must
// not jump the gate.
assert!(!should_self_continue(&ctrl(true, true, 0)));
}
#[test]
fn synthetic_continue_shape() {
let m = synthetic_continue();
assert_eq!(m.from, "self");
assert_eq!(m.body, "continue");
assert_eq!(m.id, 0);
assert!(!m.redelivered);
assert!(m.in_reply_to.is_none());
}
}

View file

@ -24,18 +24,9 @@ use std::fmt::Write as _;
use std::path::{Path, PathBuf};
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};
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;
/// Page size of the unread-notifications fetch. This is also the hard
/// bound on the persisted delivery-dedupe cursor: each poll prunes the
@ -61,7 +52,7 @@ const TOKEN_RETRY_MAX: u32 = 20;
/// claim it's "new" — see docs/forge.md, "new vs activity on".
const NEW_ITEM_TOLERANCE_SECS: i64 = 120;
/// Spawn point: called once from the `hive-agent` serve loop. Returns immediately if the forge is not
/// Spawn point: called once from `hive serve`. Returns immediately if the forge is not
/// configured. Otherwise loops forever, polling every
/// `POLL_INTERVAL_SECS` seconds. Errors are never fatal.
///
@ -106,27 +97,6 @@ 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()
.timeout(Duration::from_secs(HTTP_TIMEOUT_SECS))
.build()
@ -141,15 +111,13 @@ pub async fn run(socket: PathBuf) {
// Fetch own login once for self-notification filtering. Falls back
// to empty string on failure — no filtering (safe degradation; see
// `docs/forge.md::Self-notification filtering`).
let own_login = tokio::time::timeout(
Duration::from_secs(HTTP_TIMEOUT_SECS),
forge.user_get_current().send(),
)
.await
.ok()
.and_then(Result::ok)
.and_then(|u| u.login)
.unwrap_or_default();
let own_login = {
let url = format!("{forge_url}/api/v1/user");
fetch_json(&client, &url, &token)
.await
.and_then(|v| v["login"].as_str().map(std::borrow::ToOwned::to_owned))
.unwrap_or_default()
};
if own_login.is_empty() {
warn!("forge_notify: could not resolve own login — self-notification filtering disabled");
} else {
@ -192,7 +160,15 @@ pub async fn run(socket: PathBuf) {
loop {
interval.tick().await;
poll_once(&forge, &client, &token, &socket, &mut delivered, &own_login).await;
poll_once(
&client,
&forge_url,
&token,
&socket,
&mut delivered,
&own_login,
)
.await;
}
}
@ -212,16 +188,14 @@ async fn fetch_json(client: &reqwest::Client, url: &str, token: &str) -> Option<
}
/// Map a Forgejo notification `subject.type` to a human-readable label.
/// `Commit` / `Repository` keep their API names, matching the old raw
/// pass-through of types we don't relabel; a missing type degrades to
/// `?` like every other absent field.
fn notif_type_label(t: Option<NotifySubjectType>) -> &'static str {
/// Known values: "Pull", "Issue", "Commit", "Repository". Any unknown
/// type is passed through as-is so new Forgejo types degrade gracefully
/// rather than silently collapsing into a generic label.
fn notif_type_label(t: &str) -> &str {
match t {
Some(NotifySubjectType::Pull) => "PR",
Some(NotifySubjectType::Issue) => "issue",
Some(NotifySubjectType::Commit) => "Commit",
Some(NotifySubjectType::Repository) => "Repository",
None => "?",
"Pull" => "PR",
"Issue" => "issue",
other => other,
}
}
@ -375,19 +349,14 @@ fn review_state_label(state: &str) -> Option<&str> {
async fn format_notification(
client: &reqwest::Client,
token: &str,
notif: &PolledNotification,
notif: &serde_json::Value,
own_login: &str,
) -> Option<String> {
let subj = notif.thread.subject.as_ref();
let title = subj.and_then(|s| s.title.as_deref()).unwrap_or("?");
let subject_type = subj.and_then(|s| s.r#type);
// forgejo-api maps a blank `html_url` (Go marshals empty strings) to
// `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);
let title = notif["subject"]["title"].as_str().unwrap_or("?");
let notif_type = notif["subject"]["type"].as_str().unwrap_or("?");
let html_url = notif["subject"]["html_url"]
.as_str()
.unwrap_or_else(|| notif["subject"]["url"].as_str().unwrap_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.
@ -400,24 +369,19 @@ async fn format_notification(
.unwrap_or_default();
// Repo slug for multi-repo disambiguation. Falls back gracefully when absent.
let repo = notif
.thread
.repository
.as_ref()
.and_then(|r| r.full_name.as_deref())
let repo = notif["repository"]["full_name"]
.as_str()
.map(|r| format!(" {r}"))
.unwrap_or_default();
// API URLs for fetching content
let subject_api_url = subj
.and_then(|s| s.url.as_ref())
.map_or("", url::Url::as_str);
let comment_api_url = subj
.and_then(|s| s.latest_comment_url.as_ref())
.map_or("", url::Url::as_str);
let comment_html_url = subj
.and_then(|s| s.latest_comment_html_url.as_ref())
.map_or("", url::Url::as_str);
let subject_api_url = notif["subject"]["url"].as_str().unwrap_or("");
let comment_api_url = notif["subject"]["latest_comment_url"]
.as_str()
.unwrap_or("");
let comment_html_url = notif["subject"]["latest_comment_html_url"]
.as_str()
.unwrap_or("");
// Always fetch subject detail for assignee/reviewer metadata so
// the meta suffix can show current ownership without a follow-up
@ -430,7 +394,7 @@ async fn format_notification(
// Forgejo's notification `subject.type` is "Pull" / "Issue", never
// "Pull Request".
let is_pr = subject_type == Some(NotifySubjectType::Pull);
let is_pr = notif_type == "Pull";
let meta_suffix = build_meta_suffix(subject.as_ref(), is_pr);
// Determine whether this notification was triggered by a comment/review or
@ -439,7 +403,7 @@ async fn format_notification(
let meta = NotifMeta {
title,
subject_type,
notif_type,
html_url,
num,
repo,
@ -458,14 +422,14 @@ async fn format_notification(
)
.await
} else {
format_state_change_notification(notif.thread.updated_at, &notif.state, &meta, own_login)
format_state_change_notification(notif, &meta, own_login)
}
}
/// Shared notification metadata extracted from the polled notification.
/// Shared notification metadata extracted from the raw Forgejo JSON.
struct NotifMeta<'a> {
title: &'a str,
subject_type: Option<NotifySubjectType>,
notif_type: &'a str,
html_url: &'a str,
num: String,
repo: String,
@ -558,7 +522,7 @@ async fn format_comment_notification(
};
let NotifMeta {
title,
subject_type,
notif_type,
num,
repo,
meta_suffix,
@ -583,7 +547,7 @@ async fn format_comment_notification(
Some(out)
} else {
// Regular comment.
let kind = format!("comment on {}{num}{repo}", notif_type_label(*subject_type));
let kind = format!("comment on {}{num}{repo}", notif_type_label(notif_type));
let mut out = format!(
"[{kind}] {title}\nurl: {url}\n\n{author}: {body_for_embed}{truncated_mentions}"
);
@ -599,17 +563,17 @@ async fn format_comment_notification(
/// 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.
fn format_state_change_notification(
event_time: Option<OffsetDateTime>,
notif_state: &str,
notif: &serde_json::Value,
meta: &NotifMeta<'_>,
own_login: &str,
) -> Option<String> {
// Classification uses the raw `subject.state` string extracted in
// `parse_notification` — Forgejo returns "open" / "closed" / "merged"
// there. We do NOT rely on fetching the PR/issue detail for `merged`:
// Classification uses notif["subject"]["state"] directly — Forgejo
// returns "open" / "closed" / "merged" here. We do NOT rely on
// fetching the PR/issue detail for `merged`:
// - `subject.url` points to the *issues* endpoint, which returns
// `pull_request.merged`, not top-level `merged`.
// - 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
// the review-request override.
@ -617,7 +581,7 @@ fn format_state_change_notification(
let NotifMeta {
title,
subject_type,
notif_type,
html_url,
num,
repo,
@ -625,7 +589,7 @@ fn format_state_change_notification(
subject,
is_pr,
} = meta;
let label = notif_type_label(*subject_type);
let label = notif_type_label(notif_type);
// Only claim "new" when the notification actually fired at creation
// time. A review submitted with no body carries no
// `latest_comment_url`, so it lands here instead of on the comment
@ -634,7 +598,7 @@ fn format_state_change_notification(
// on"): agents dismiss it as a
// duplicate of the original open notification. When we can't confirm
// creation, fall back to a neutral "activity on" label.
let looks_new = notification_is_creation(event_time, subject.as_ref());
let looks_new = notification_is_creation(notif, subject.as_ref());
// Self-authored creation filter: skip an agent being woken by its own
// freshly-opened issue/PR. The subject payload is already fetched (for
@ -704,66 +668,81 @@ fn format_state_change_notification(
/// new item behind the neutral fallback. See docs/forge.md, "new vs
/// activity on".
fn notification_is_creation(
event: Option<OffsetDateTime>,
notif: &serde_json::Value,
subject: Option<&serde_json::Value>,
) -> bool {
let created = subject
.and_then(|s| s["created_at"].as_str())
.and_then(parse_rfc3339);
.and_then(parse_rfc3339_secs);
let event = notif["updated_at"].as_str().and_then(parse_rfc3339_secs);
match (created, event) {
(Some(c), Some(e)) => (e - c).whole_seconds().abs() <= NEW_ITEM_TOLERANCE_SECS,
(Some(c), Some(e)) => (e - c).abs() <= NEW_ITEM_TOLERANCE_SECS,
_ => true,
}
}
/// Parse an RFC 3339 timestamp as Forgejo emits them
/// (`2026-06-13T11:18:42+02:00` or `...Z`, optionally with fractional
/// seconds). Returns `None` on any shape `time` doesn't recognise so
/// callers can fall back gracefully.
fn parse_rfc3339(s: &str) -> Option<OffsetDateTime> {
OffsetDateTime::parse(s, &Rfc3339).ok()
}
/// One notification from the poll page: the typed thread plus two raw
/// fields the typed structs can't carry faithfully.
struct PolledNotification {
thread: NotificationThread,
/// Raw `subject.state`. Forgejo reports `"merged"` for merged PRs
/// (`services/convert/notification.go`), which forgejo-api's
/// `StateType` (open/closed only) rejects at deserialization — so
/// the state is extracted verbatim before the typed parse and
/// matched as a string, exactly like the pre-typed code.
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;
/// Minimal dependency-free RFC 3339 / ISO 8601 parser → Unix epoch
/// seconds. Forgejo emits timestamps like `2026-06-13T11:18:42+02:00`
/// or `...Z`, optionally with fractional seconds. We only need
/// second-granularity comparison, so the fractional part is skipped.
/// Returns `None` on any shape we don't recognise so callers can fall
/// back gracefully.
fn parse_rfc3339_secs(s: &str) -> Option<i64> {
if s.len() < 19 {
return None;
}
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
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`
/// (Howard Hinnant's `days_from_civil`). Valid for all dates Forgejo
/// can emit.
fn days_from_civil(y: i64, m: i64, d: i64) -> i64 {
let y = if m <= 2 { y - 1 } else { y };
let era = (if y >= 0 { y } else { y - 399 }) / 400;
let yoe = y - era * 400;
let doy = (153 * (if m > 2 { m - 3 } else { m + 9 }) + 2) / 5 + d - 1;
let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;
era * 146_097 + doe - 719_468
}
#[allow(
@ -773,45 +752,33 @@ fn parse_notification(mut value: serde_json::Value) -> Option<PolledNotification
functions for state shared across all three phases"
)]
async fn poll_once(
forge: &Forgejo,
client: &reqwest::Client,
forge_url: &str,
token: &str,
socket: &Path,
delivered: &mut HashMap<u64, String>,
own_login: &str,
) {
// Fetch the page as raw JSON (`response_type::<String>`) instead of the
// crate's `Vec<NotificationThread>`: one merged-PR notification
// (`subject.state = "merged"`, unrepresentable in `StateType`) would
// otherwise poison deserialization of the whole page. HTTP-level errors
// still surface as `ForgejoError` exactly like the fully-typed call;
// `parse_notification` below does the per-item typed parse.
let query = NotifyGetListQuery {
all: Some(false),
..NotifyGetListQuery::default()
let url = format!("{forge_url}/api/v1/notifications?all=false&limit={UNREAD_FETCH_LIMIT}");
let resp = match client
.get(&url)
.header("Authorization", format!("token {token}"))
.send()
.await
{
Ok(r) => r,
Err(e) => {
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;
}
};
let values: Vec<serde_json::Value> = match serde_json::from_str(&raw) {
if !resp.status().is_success() {
debug!("forge_notify: poll status {}", resp.status());
return;
}
let notifications: Vec<serde_json::Value> = match resp.json().await {
Ok(v) => v,
Err(e) => {
warn!("forge_notify: response parse error: {e}");
@ -819,25 +786,22 @@ async fn poll_once(
}
};
if values.is_empty() {
if notifications.is_empty() {
return;
}
debug!(
count = values.len(),
count = notifications.len(),
"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
// recorded, or the prune below dropped now-read threads) so we only
// rewrite the on-disk cursor when there's something to persist.
let mut cursor_dirty = false;
for notif in &notifications {
let Some(id) = notif.thread.id.and_then(|id| u64::try_from(id).ok()) else {
let Some(id) = notif["id"].as_u64() else {
continue;
};
@ -846,7 +810,7 @@ async fn poll_once(
// Skip it silently unless its `updated_at` advanced since the
// version we last delivered a wake for (i.e. genuinely new
// activity). See the `delivered` cursor note in `run`.
let updated_at = notif.updated_at.clone();
let updated_at = notif["updated_at"].as_str().unwrap_or("").to_owned();
if !should_deliver(delivered, id, &updated_at) {
debug!(%id, "forge_notify: skipping (already delivered this version)");
continue;
@ -856,7 +820,7 @@ async fn poll_once(
// None means self-echo — mark read silently, no delivery.
let Some(body) = body_opt else {
mark_read(forge, id).await;
mark_read(client, forge_url, token, id).await;
continue;
};
@ -900,7 +864,7 @@ async fn poll_once(
// loud in tests/dev if a future pagination change silently breaks it.
let current_ids: HashSet<u64> = notifications
.iter()
.filter_map(|n| n.thread.id.and_then(|id| u64::try_from(id).ok()))
.filter_map(|n| n["id"].as_u64())
.collect();
let before_prune = delivered.len();
delivered.retain(|id, _| current_ids.contains(id));
@ -935,31 +899,21 @@ fn should_deliver(delivered: &HashMap<u64, String>, id: u64, updated_at: &str) -
/// 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
/// next poll tick.
async fn mark_read(forge: &Forgejo, id: u64) {
let Ok(thread_id) = i64::try_from(id) else {
// Thread ids originate from `i64` in the poll parse, so an
// unrepresentable value can't actually reach here.
return;
};
// `to_status: None` → Forgejo's default transition (unread → read),
// matching the old bare PATCH. The 205 response body is the thread
// 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(_))) => {
async fn mark_read(client: &reqwest::Client, forge_url: &str, token: &str, id: u64) {
let mark_url = format!("{forge_url}/api/v1/notifications/threads/{id}");
match client
.patch(&mark_url)
.header("Authorization", format!("token {token}"))
.send()
.await
{
Err(e) => {
warn!(%id, error = ?e, "forge_notify: mark-read request failed — notification will resurface");
}
Ok(Err(e)) => {
warn!(%id, error = %e, "forge_notify: mark-read returned non-2xx — notification will resurface");
Ok(r) if !r.status().is_success() => {
warn!(%id, status = %r.status(), "forge_notify: mark-read returned non-2xx — notification will resurface");
}
Ok(Ok(_)) => {
Ok(_) => {
debug!(%id, "forge_notify: marked read");
}
}
@ -1175,98 +1129,39 @@ mod tests {
}
#[test]
fn parse_rfc3339_handles_offsets_and_z() {
// Same instant expressed three ways must parse equal
// (`OffsetDateTime` comparison is instant-based).
let utc = parse_rfc3339("2026-06-13T09:18:42Z").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();
fn parse_rfc3339_secs_handles_offsets_and_z() {
// Same instant expressed three ways must parse equal.
let utc = parse_rfc3339_secs("2026-06-13T09:18:42Z").unwrap();
let plus2 = parse_rfc3339_secs("2026-06-13T11:18:42+02:00").unwrap();
let minus5 = parse_rfc3339_secs("2026-06-13T04:18:42-05:00").unwrap();
assert_eq!(utc, plus2);
assert_eq!(utc, minus5);
// Fractional seconds parse; second-granularity comparison holds.
assert_eq!(
parse_rfc3339("2026-06-13T09:18:42.512Z")
.unwrap()
.unix_timestamp(),
utc.unix_timestamp(),
);
// Fractional seconds are skipped (second granularity).
assert_eq!(parse_rfc3339_secs("2026-06-13T09:18:42.512Z").unwrap(), utc);
}
#[test]
fn parse_rfc3339_rejects_garbage() {
assert!(parse_rfc3339("").is_none());
assert!(parse_rfc3339("not-a-date").is_none());
assert!(parse_rfc3339("2026-06-13").is_none());
fn parse_rfc3339_secs_rejects_garbage() {
assert!(parse_rfc3339_secs("").is_none());
assert!(parse_rfc3339_secs("not-a-date").is_none());
assert!(parse_rfc3339_secs("2026-06-13").is_none());
}
#[test]
fn notification_is_creation_flags_fresh_and_later_activity() {
let subject = serde_json::json!({ "created_at": "2026-06-13T11:18:40+02:00" });
// 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)));
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" });
assert!(notification_is_creation(&fresh, Some(&subject)));
// Review hours later on the same PR → not a creation.
let later = parse_rfc3339("2026-06-13T14:55:00+02:00");
assert!(!notification_is_creation(later, Some(&subject)));
let later = serde_json::json!({ "updated_at": "2026-06-13T14:55:00+02:00" });
assert!(!notification_is_creation(&later, Some(&subject)));
// Missing timestamps → default to creation (preserve prior behavior).
assert!(notification_is_creation(None, None));
assert!(notification_is_creation(None, 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());
let empty = serde_json::json!({});
assert!(notification_is_creation(&empty, None));
assert!(notification_is_creation(&empty, Some(&subject)));
}
/// Build a `NotifMeta` for the state-change formatter tests. The `&str`
@ -1274,7 +1169,7 @@ mod tests {
fn state_change_meta(subject: serde_json::Value) -> NotifMeta<'static> {
NotifMeta {
title: "subject title",
subject_type: Some(NotifySubjectType::Issue),
notif_type: "Issue",
html_url: "http://forge/issues/1",
num: " #1".to_owned(),
repo: " [agents/x]".to_owned(),
@ -1288,13 +1183,15 @@ mod tests {
fn state_change_drops_self_authored_creation() {
// No timestamps ⇒ treated as a creation; poster login == own_login.
let meta = state_change_meta(serde_json::json!({ "user": { "login": "damocles" } }));
assert!(format_state_change_notification(None, "open", &meta, "damocles").is_none());
let notif = serde_json::json!({ "subject": { "state": "open" } });
assert!(format_state_change_notification(&notif, &meta, "damocles").is_none());
}
#[test]
fn state_change_keeps_other_authored_creation() {
let meta = state_change_meta(serde_json::json!({ "user": { "login": "someone-else" } }));
assert!(format_state_change_notification(None, "open", &meta, "damocles").is_some());
let notif = serde_json::json!({ "subject": { "state": "open" } });
assert!(format_state_change_notification(&notif, &meta, "damocles").is_some());
}
#[test]
@ -1306,7 +1203,10 @@ mod tests {
"user": { "login": "damocles" },
"created_at": "2020-01-01T00:00:00Z",
}));
let event = parse_rfc3339("2026-06-22T16:00:00Z");
assert!(format_state_change_notification(event, "closed", &meta, "damocles").is_some());
let notif = serde_json::json!({
"subject": { "state": "closed" },
"updated_at": "2026-06-22T16:00:00Z",
});
assert!(format_state_change_notification(&notif, &meta, "damocles").is_some());
}
}

View file

@ -1,7 +1,6 @@
//! Shared in-container harness code for the sibling `hive-agent` /
//! `hive-agent-mcp` / `hive-agent-wake` binaries, which serve every
//! agent role (the manager is just an agent role, not a separate set
//! of binaries).
//! Shared in-container harness code for the single `hive` binary that
//! serves every agent role (the manager is just an agent role, not a
//! separate binary).
pub mod client;
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>`.
/// `mcp_binary` is the path (or PATH-resolvable name) of the
/// `hive-agent-mcp` bridge executable; `socket` is the hyperhive per-agent
/// socket bind-mounted into the container (forwarded to the child as
/// `--socket <path>`). Merges in any extra MCP servers declared via
/// `hyperhive.extraMcpServers` in the agent's NixOS config.
/// `agent_binary` is the path (or PATH-resolvable name) of the `hive-ag3nt`
/// executable; `socket` is the hyperhive per-agent socket bind-mounted into
/// the container (forwarded to the child as `--socket <path>`). Merges in
/// any extra MCP servers declared via `hyperhive.extraMcpServers` in the
/// agent's NixOS config.
#[must_use]
pub fn render_claude_config(mcp_binary: &str, socket: &std::path::Path) -> String {
pub fn render_claude_config(agent_binary: &str, socket: &std::path::Path) -> String {
let mut servers = serde_json::Map::new();
// When the harness is configured to run the built-in server as a
// persistent streamable-http daemon (loopback port in
@ -353,8 +353,8 @@ pub fn render_claude_config(mcp_binary: &str, socket: &std::path::Path) -> Strin
"url": format!("http://127.0.0.1:{port}/mcp"),
}),
None => serde_json::json!({
"command": mcp_binary,
"args": ["--socket", socket.display().to_string()],
"command": agent_binary,
"args": ["--socket", socket.display().to_string(), "mcp"],
"env": {}
}),
};

View file

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

View file

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

View file

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

View file

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

View file

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

View file

@ -1,190 +1,99 @@
//! Repo + org plumbing on the local Forgejo: org / repo creation,
//! the meta + shared-docs + knowledge repos, per-agent config-repo
//! mirroring (`push_config` / `push_meta`), collaborator grants,
//! pull-mirrors, and branch-protection rules. The typed API-client
//! constructor + org-name constants live in the module root (`super`).
//! pull-mirrors, and branch-protection rules. Shared HTTP helpers +
//! org-name constants live in the module root (`super`).
use std::path::Path;
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 crate::coordinator::Coordinator;
use super::{
AGENTS_ORG, CONFIG_ORG, FORGE_HTTP, KNOWLEDGE_REPO, OPERATORS_TEAM, SHARED_DOCS_REPO,
SHARED_ORG, api, core_token, is_present,
SHARED_ORG, core_token, forge_http, is_present,
};
/// Creation options for an empty repo defaulting to `main`.
fn repo_option(name: &str, private: bool) -> CreateRepoOption {
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 private, empty repo defaulting to `main`.
fn repo_body(name: &str) -> String {
format!(r#"{{"name":"{name}","auto_init":false,"private":true,"default_branch":"main"}}"#)
}
/// `EditRepoOption` with every field unset — repo edits only ever
/// change the one field the caller sets on top (Forgejo leaves `None`
/// 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}")),
}
/// JSON body for a public, empty repo defaulting to `main`.
fn repo_body_public(name: &str) -> String {
format!(r#"{{"name":"{name}","auto_init":false,"private":false,"default_branch":"main"}}"#)
}
/// Set an existing repo to public visibility. No-op if the repo is
/// already public. Used for `internal/knowledge` which may have been
/// created as private on an older deployment.
async fn set_repo_public(owner: &str, repo: &str, token: &str) -> Result<()> {
let mut edit = sparse_edit_repo_option();
edit.private = Some(false);
api(token)?
.repo_edit(owner, repo, edit)
.await
.with_context(|| format!("edit {owner}/{repo} (set public)"))?;
tracing::debug!(%owner, %repo, "forge: repo set to public");
Ok(())
let url = format!("{FORGE_HTTP}/api/v1/repos/{owner}/{repo}");
let (status, _) =
forge_http(reqwest::Method::PATCH, &url, token, r#"{"private":false}"#).await?;
match status.as_u16() {
200 => {
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.
async fn ensure_org_repo_public(org: &str, name: &str, token: &str) -> Result<()> {
let res = api(token)?
.create_org_repo(org, repo_option(name, false))
.await;
created_or_exists(res, &format!("{org}/{name}"))
create_repo(
&format!("{FORGE_HTTP}/api/v1/orgs/{org}/repos"),
&repo_body_public(name),
token,
&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
/// to the user we want the repo owned by (we use `core`'s token for
/// `core/meta`). Idempotent.
pub async fn ensure_repo(name: &str, token: &str) -> Result<()> {
let res = api(token)?
.create_current_user_repo(repo_option(name, true))
.await;
created_or_exists(res, &format!("core/{name}"))
create_repo(
&format!("{FORGE_HTTP}/api/v1/user/repos"),
&repo_body(name),
token,
&format!("core/{name}"),
)
.await
}
/// Create `name` inside org `org` (used for `agent-configs/<agent>`).
/// Idempotent.
async fn ensure_org_repo(org: &str, name: &str, token: &str) -> Result<()> {
let res = api(token)?
.create_org_repo(org, repo_option(name, true))
.await;
created_or_exists(res, &format!("{org}/{name}"))
create_repo(
&format!("{FORGE_HTTP}/api/v1/orgs/{org}/repos"),
&repo_body(name),
token,
&format!("{org}/{name}"),
)
.await
}
/// Push `dir` (the meta repo) to `core/meta` on the local forge.
@ -232,14 +141,7 @@ pub async fn ensure_config_repo(name: &str) -> Result<()> {
ensure_org_repo(CONFIG_ORG, name, &token).await?;
// Agent = write collaborator: it can push config-PR branches + open PRs,
// but the branch protection below keeps it off `main` directly.
add_collaborator(
CONFIG_ORG,
name,
name,
AddCollaboratorOptionPermission::Write,
&token,
)
.await?;
add_collaborator(CONFIG_ORG, name, name, "write", &token).await?;
// Protect `main` core-only, fast-forward-only (no auto force-push).
apply_config_repo_branch_protection(name, &token).await
}
@ -252,20 +154,43 @@ pub async fn ensure_shared_docs_repo(core_token: &str) -> Result<()> {
}
/// Grant agent `name` read-only collaborator access to `internal/docs`.
/// Idempotent: re-adding an existing collaborator succeeds (Forgejo
/// answers 204 either way). Mirrors `meta_read_access` so agents can
/// clone the shared docs repo without authentication hassle.
/// Idempotent: HTTP 204 (already a collaborator) is treated as success.
/// Mirrors `meta_read_access` so agents can clone the shared docs repo
/// without authentication hassle.
pub async fn shared_docs_access(name: &str, core_token: &str) -> Result<()> {
add_collaborator(
SHARED_ORG,
SHARED_DOCS_REPO,
name,
AddCollaboratorOptionPermission::Read,
core_token,
)
.await?;
tracing::info!(%name, "forge: granted shared-docs read access");
Ok(())
let url =
format!("{FORGE_HTTP}/api/v1/repos/{SHARED_ORG}/{SHARED_DOCS_REPO}/collaborators/{name}");
let body = r#"{"permission":"read"}"#;
let out = Command::new("curl")
.args([
"-sS",
"-o",
"/dev/null",
"-w",
"%{http_code}",
"-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.
@ -283,19 +208,38 @@ pub async fn ensure_knowledge_repo(core_token: &str) -> Result<()> {
/// Grant agent `name` read-only collaborator access to `core/meta` on
/// the forge so the agent can clone/fetch the meta flake. Idempotent:
/// re-adding an existing collaborator succeeds (Forgejo answers 204
/// either way).
/// HTTP 204 (already a collaborator) is treated as success.
pub async fn meta_read_access(name: &str, core_token: &str) -> Result<()> {
add_collaborator(
"core",
"meta",
name,
AddCollaboratorOptionPermission::Read,
core_token,
)
.await?;
tracing::info!(%name, "forge: granted meta read access");
Ok(())
let url = format!("{FORGE_HTTP}/api/v1/repos/core/meta/collaborators/{name}");
let body = r#"{"permission":"read"}"#;
let out = Command::new("curl")
.args([
"-sS",
"-o",
"/dev/null",
"-w",
"%{http_code}",
"-X",
"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
@ -395,29 +339,22 @@ pub async fn push_config(name: &str) -> Result<()> {
Ok(())
}
/// Create an org named `name` (`org_create`). Idempotent: HTTP 422
/// ("user already exists") / 409 is treated as success.
/// POST `/api/v1/orgs` to create an org named `name`. Idempotent:
/// HTTP 422 ("user already exists") is treated as success.
pub(super) async fn ensure_org(name: &str, admin_token: &str) -> Result<()> {
let org = CreateOrgOption {
description: None,
email: None,
full_name: None,
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(_) => {
let body = format!(r#"{{"username":"{name}"}}"#);
let url = format!("{FORGE_HTTP}/api/v1/orgs");
let (status, _) = forge_http(reqwest::Method::POST, &url, admin_token, &body).await?;
match status.as_u16() {
201 => {
tracing::info!(%name, "forge: created org");
Ok(())
}
Err(e) if is_already_exists(&e) => {
422 | 409 => {
tracing::debug!(%name, "forge: org already exists");
Ok(())
}
Err(e) => Err(e).with_context(|| format!("create org {name}")),
other => anyhow::bail!("POST /api/v1/orgs name={name} returned HTTP {other}"),
}
}
@ -477,82 +414,63 @@ const MIRROR_INTERVAL: &str = "8h0m0s";
/// Idempotent: if the repo already exists this function patches its
/// `mirror_interval` to ensure it matches (covers mirrors that were
/// created before the interval was introduced). A 409 on the migrate
/// call (a race between the existence check and the migrate) is also
/// success.
/// POST (a race between the GET check and the POST) is also success.
async fn ensure_mirror_repo(
upstream: &str,
owner: &str,
repo: &str,
admin_token: &str,
) -> Result<()> {
let client = api(admin_token)?;
match client.repo_get(owner, repo).await {
Ok(_) => {
// Mirror already present. Patch interval so mirrors seeded before
// this field was introduced (or with a different value) converge.
let mut edit = sparse_edit_repo_option();
edit.mirror_interval = Some(MIRROR_INTERVAL.to_owned());
match client.repo_edit(owner, repo, edit).await {
Ok(_) => {
tracing::debug!(%owner, %repo, interval = MIRROR_INTERVAL, "forge: pull-mirror interval updated");
}
Err(e) => {
tracing::warn!(
%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}"));
let repo_url = format!("{FORGE_HTTP}/api/v1/repos/{owner}/{repo}");
let (status, _) = forge_http(reqwest::Method::GET, &repo_url, admin_token, "").await?;
if status.is_success() {
// Mirror already present. Patch interval so mirrors seeded before
// this field was introduced (or with a different value) converge.
let patch_body = serde_json::json!({ "mirror_interval": MIRROR_INTERVAL }).to_string();
let (patch_status, patch_text) =
forge_http(reqwest::Method::PATCH, &repo_url, admin_token, &patch_body).await?;
if patch_status.is_success() {
tracing::debug!(%owner, %repo, interval = MIRROR_INTERVAL, "forge: pull-mirror interval updated");
} else {
tracing::warn!(
%owner, %repo, status = %patch_status, body = %patch_text,
"forge: failed to set mirror_interval on existing pull-mirror"
);
}
return Ok(());
}
let opts = MigrateRepoOptions {
auth_password: None,
auth_token: None,
auth_username: None,
clone_addr: upstream.to_owned(),
description: None,
issues: None,
labels: None,
lfs: None,
lfs_endpoint: None,
milestones: None,
mirror: Some(true),
// serde_json::json! → the upstream URL is escaped safely (no string
// interpolation into the JSON body).
let body = serde_json::json!({
"clone_addr": upstream,
"repo_owner": owner,
"repo_name": repo,
"mirror": true,
// Periodic refresh instead of on-access sync — keeps CI isolated
// from external DNS failures at clone time.
mirror_interval: Some(MIRROR_INTERVAL.to_owned()),
private: Some(false),
pull_requests: None,
releases: None,
repo_name: repo.to_owned(),
repo_owner: Some(owner.to_owned()),
service: Some(MigrateRepoOptionsService::Git),
uid: None,
wiki: None,
};
match client.repo_migrate(opts).await {
Ok(_) => {
"interval": MIRROR_INTERVAL,
"service": "git",
"private": false,
})
.to_string();
let url = format!("{FORGE_HTTP}/api/v1/repos/migrate");
let (status, text) = forge_http(reqwest::Method::POST, &url, admin_token, &body).await?;
match status.as_u16() {
201 => {
tracing::info!(%owner, %repo, %upstream, interval = MIRROR_INTERVAL, "forge: created pull-mirror");
Ok(())
}
// 409 = a race created it between our existence check and here (the
// check is the real idempotency guard). NOT 422: for the migrate
// endpoint 422 is a validation error (bad clone_addr / service), so
// it must surface via the error arm, not be swallowed as "already
// exists" — hence `is_conflict`, not `is_already_exists`.
Err(e) if is_conflict(&e) => {
// 409 = a race created it between our GET check and here (the GET
// is the real idempotency guard). NOT 422: for the migrate endpoint
// 422 is a validation error (bad clone_addr / service), so it must
// surface via the bail arm, not be swallowed as "already exists".
409 => {
tracing::debug!(%owner, %repo, "forge: pull-mirror already exists (race)");
Ok(())
}
Err(e) => Err(e).with_context(|| format!("migrate pull-mirror {owner}/{repo}")),
other => {
anyhow::bail!("POST /api/v1/repos/migrate {owner}/{repo} returned HTTP {other}: {text}")
}
}
}
@ -570,101 +488,48 @@ async fn ensure_mirror_repo(
/// repos unprotected — operator-merged config PRs then bypassed the deploy
/// pipeline and silently didn't apply.
pub(super) async fn ensure_operators_team(org: &str, token: &str) -> Result<()> {
let team = CreateTeamOption {
can_create_org_repo: Some(false),
description: Some("hyperhive operators — merge gate for agent repos".to_owned()),
includes_all_repositories: Some(true),
name: OPERATORS_TEAM.to_owned(),
permission: Some(CreateTeamOptionPermission::Write),
units: None,
units_map: None,
};
match api(token)?.org_create_team(org, team).await {
Ok(_) => {
let url = format!("{FORGE_HTTP}/api/v1/orgs/{org}/teams");
let body = format!(
r#"{{"name":"{OPERATORS_TEAM}","description":"hyperhive operators — merge gate for agent repos","permission":"write","includes_all_repositories":true,"can_create_org_repo":false}}"#
);
let (status, _) = forge_http(reqwest::Method::POST, &url, token, &body).await?;
match status.as_u16() {
201 => {
tracing::info!(%org, "forge: created {OPERATORS_TEAM} team");
Ok(())
}
Err(e) if is_already_exists(&e) => {
409 | 422 => {
tracing::debug!(%org, "forge: {OPERATORS_TEAM} team already exists");
Ok(())
}
Err(e) => Err(e).with_context(|| format!("create team {org}/{OPERATORS_TEAM}")),
other => {
anyhow::bail!("POST /orgs/{org}/teams ({OPERATORS_TEAM}) returned HTTP {other}")
}
}
}
/// Add `user` as a collaborator on `owner/repo` at `permission`.
/// Idempotent: adding an existing collaborator just updates its
/// permission (Forgejo answers 204 either way; a 201 from older
/// versions is tolerated defensively).
/// Add `user` as a collaborator on `owner/repo` at `permission`
/// (`read` / `write` / `admin`). Idempotent: 201 (added) and 204 (already a
/// collaborator / permission updated) both count as success.
async fn add_collaborator(
owner: &str,
repo: &str,
user: &str,
permission: AddCollaboratorOptionPermission,
permission: &str,
token: &str,
) -> Result<()> {
let res = api(token)?
.repo_add_collaborator(
owner,
repo,
user,
AddCollaboratorOption {
permission: Some(permission),
},
)
.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}"));
let url = format!("{FORGE_HTTP}/api/v1/repos/{owner}/{repo}/collaborators/{user}");
let body = format!(r#"{{"permission":"{permission}"}}"#);
let (status, _) = forge_http(reqwest::Method::PUT, &url, token, &body).await?;
match status.as_u16() {
201 | 204 => {
tracing::debug!(%owner, %repo, %user, %permission, "forge: collaborator set");
Ok(())
}
other => {
anyhow::bail!("PUT {owner}/{repo}/collaborators/{user} returned HTTP {other}")
}
}
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
@ -673,26 +538,21 @@ fn is_protection_already_present(e: &ForgejoError) -> bool {
/// agent, not in the team) cannot merge its own PR. Idempotent: an existing
/// rule for the branch (200/409/422) is treated as success.
async fn apply_operator_branch_protection(repo: &str, token: &str) -> Result<()> {
let mut rule = main_branch_protection_option();
rule.enable_merge_whitelist = Some(true);
rule.merge_whitelist_teams = Some(vec![OPERATORS_TEAM.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);
match api(token)?
.repo_create_branch_protection(AGENTS_ORG, repo, rule)
.await
{
Ok(_) => {
let url = format!("{FORGE_HTTP}/api/v1/repos/{AGENTS_ORG}/{repo}/branch_protections");
let body = format!(
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}}"#
);
let (status, _) = forge_http(reqwest::Method::POST, &url, token, &body).await?;
match status.as_u16() {
201 => {
tracing::info!(%repo, "forge: applied operator branch protection");
Ok(())
}
Err(e) if is_protection_already_present(&e) => {
200 | 409 | 422 => {
tracing::debug!(%repo, "forge: branch protection already present");
Ok(())
}
Err(e) => Err(e).with_context(|| format!("create branch protection {AGENTS_ORG}/{repo}")),
other => anyhow::bail!("POST {AGENTS_ORG}/{repo}/branch_protections returned HTTP {other}"),
}
}
@ -704,63 +564,45 @@ async fn apply_operator_branch_protection(repo: &str, token: &str) -> Result<()>
/// (`run_merge_config_pr`). The agent can never push `main` directly.
/// - **operator-team approval is required** to merge, and the author (not in
/// the team) cannot self-approve.
/// - **force-pushing `main` stays impossible** — `main` only ever advances by
/// - **`enable_force_push` is `false`** — `main` only ever advances by
/// 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
/// force-push (it re-points status tags and rewinds `main` on a failed-build
/// rollback), so the protection rejects those non-ff updates — that
/// rollback), so the protection now rejects those non-ff updates — that
/// mirror runs best-effort until the agent-opened PR-merge flow retires it.
/// (Auto force-push is intentionally not allowed: per operator directive a
/// 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.)
/// silent force-push is a bug, not a feature.)
///
/// Idempotent: an existing rule for the branch (200/409/422) is success.
async fn apply_config_repo_branch_protection(repo: &str, token: &str) -> Result<()> {
let client = api(token)?;
let mut rule = main_branch_protection_option();
rule.enable_push_whitelist = Some(true);
rule.push_whitelist_usernames = Some(vec!["core".to_owned()]);
rule.enable_merge_whitelist = Some(true);
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 {
let url = format!("{FORGE_HTTP}/api/v1/repos/{CONFIG_ORG}/{repo}/branch_protections");
let body = format!(
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}}"#
);
let (status, resp_body) = forge_http(reqwest::Method::POST, &url, token, &body).await?;
if status.as_u16() == 201 {
tracing::info!(%repo, "forge: applied config-repo branch protection");
return Ok(());
};
// A create failure is ambiguous: it can mean "rule already exists"
// (idempotent success) OR a silent rejection — e.g. a 422 where Forgejo
// refused the request and created NO rule. The old code treated
// 200/409/422 all as success, so a rejected POST left the repo
// unprotected with no error (the reported case: a new agent's config
// repo had no `main` rule and nothing was logged). Don't trust the
// status: verify the `main` rule actually exists, and on failure
// surface the create error (its Display carries Forgejo's validation
// message) so the real reason is in the journal.
match client
.repo_get_branch_protection(CONFIG_ORG, repo, "main")
.await
{
Ok(_) => {
tracing::debug!(
%repo, create_error = %create_err,
"forge: config-repo branch protection already present"
);
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"
),
}
// Non-201 is ambiguous: it can mean "rule already exists" (idempotent
// success) OR a silent rejection — e.g. a 422 where Forgejo refused
// the request and created NO rule. The old code treated 200/409/422
// all as success, so a rejected POST left the repo unprotected with
// no error (the reported case: a new agent's config repo had no
// `main` rule and nothing was logged). Don't trust the status code:
// verify the `main` rule actually exists, and on failure surface the
// POST's response body so the real reason is in the journal.
let main_url = format!("{url}/main");
let (check, _) = forge_http(reqwest::Method::GET, &main_url, token, "").await?;
if check.as_u16() == 200 {
tracing::debug!(%repo, %status, "forge: config-repo branch protection already present");
Ok(())
} else {
anyhow::bail!(
"branch protection for {CONFIG_ORG}/{repo} not applied: POST -> HTTP {status} \
(body: {body}); GET main -> HTTP {check}, no `main` rule present",
body = resp_body.trim(),
)
}
}
@ -772,14 +614,7 @@ async fn apply_config_repo_branch_protection(repo: &str, token: &str) -> Result<
/// create repos directly (`max_repo_creation = 0`). Idempotent.
pub async fn create_agent_repo(agent: &str, repo: &str, core_token: &str) -> Result<String> {
ensure_org_repo(AGENTS_ORG, repo, core_token).await?;
add_collaborator(
AGENTS_ORG,
repo,
agent,
AddCollaboratorOptionPermission::Write,
core_token,
)
.await?;
add_collaborator(AGENTS_ORG, repo, agent, "write", 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");
Ok(format!("{AGENTS_ORG}/{repo}"))

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