From 07c66e3a1c47372fec51790e14aa41d0cea67fd4 Mon Sep 17 00:00:00 2001 From: damocles Date: Sun, 15 Nov 2026 16:20:54 +0100 Subject: [PATCH] agents get read, not write, on their own agent-configs repo; an existing grant is left alone --- docs/2-handbook/agents/security.md | 2 +- docs/2-handbook/swarm/archetypes.md | 2 +- .../agent-state/config-changes.md | 12 ++++---- docs/4-implementation/swarm/forge-accounts.md | 5 ++-- swarm-controller/src/forge.rs | 23 +++++--------- swarm-controller/src/forge/docs_grant.rs | 30 +++++++++---------- swarm-controller/src/jobq.rs | 2 +- 7 files changed, 35 insertions(+), 41 deletions(-) diff --git a/docs/2-handbook/agents/security.md b/docs/2-handbook/agents/security.md index 5abdc809f..8b621bb5f 100644 --- a/docs/2-handbook/agents/security.md +++ b/docs/2-handbook/agents/security.md @@ -125,7 +125,7 @@ checkpoints**, not about sandboxing the agent from its own tools: which swarm-controller converges on every config repo. An operator's merge there is also what deploys the config. Existing `agents/` repos carry the same merge gate. - An agent (a write collaborator, not a repo admin) can neither change those + An agent (a read collaborator, not a repo admin) can neither change those settings nor merge its own PR. It's **not** set up for external VCS (GitHub etc.), though — there, operator-merge is process + accepted risk, not a technical control. diff --git a/docs/2-handbook/swarm/archetypes.md b/docs/2-handbook/swarm/archetypes.md index d42eba6f8..319db6d0a 100644 --- a/docs/2-handbook/swarm/archetypes.md +++ b/docs/2-handbook/swarm/archetypes.md @@ -33,7 +33,7 @@ agent gets every new item, and two of them would both label and assign it. creating a `triage` agent gives each new issue two todos. Switch one off on the board: the custom flow, or the archetype's flow ([below](#on-the-board)). -- **Forge rights.** A new agent's forge account is a write collaborator on its own +- **Forge rights.** A new agent's forge account is a read collaborator on its own config repo and has read on `internal/docs`, and nothing else. Labelling and assigning an issue or a pull request in a project repo takes write access to that repo, so the triage agent can't do either until the operator adds it as a diff --git a/docs/4-implementation/agent-state/config-changes.md b/docs/4-implementation/agent-state/config-changes.md index 0f9595459..da14096fc 100644 --- a/docs/4-implementation/agent-state/config-changes.md +++ b/docs/4-implementation/agent-state/config-changes.md @@ -19,7 +19,7 @@ No MCP tool exists for config changes: opening the PR IS the request. own config as well as how it changes it. Branch protection (the agent isn't on the `main` push allowlist; merge and approvals allowlist = `operators` team; see "Forge config repos" - below) makes the agent a write collaborator that **can't merge its own + below) makes the agent a read collaborator that **can't merge its own config PR**. 2. An operator reviews the PR **on the forge** (native diff, threaded comments, CI status) and merges it there. Merging needs membership of @@ -194,10 +194,12 @@ Every agent created through the swarm has a repo in the private hive-c0re pushes nothing to it, keeps no clone and reads nothing from it: forge `main` advances only by an operator's merge. -Each agent is a **write collaborator on its own** `agent-configs/` -repo — so it can push a branch and open a config PR — but not a member -of any other agent's, so it can't reach another agent's config through -the forge. Branch protection keeps the agent off the `main` push +Each agent is a **read collaborator on its own** `agent-configs/` +repo, so it can clone it and open a config PR through the AGit flow (no push +access needed), but not a member of any other agent's, so it can't reach +another agent's config through the forge. A grant of more than read, made by +an operator or before agents got read, is left as it is: the `AddRepoMember` +node only adds read where the agent has none. Branch protection keeps the agent off the `main` push allowlist and allowlists merging to the `operators` team only, so an agent can't fast-forward its own config or self-merge its PR (see [Config changes](#config-changes) above). hive-c0re passes the credential to diff --git a/docs/4-implementation/swarm/forge-accounts.md b/docs/4-implementation/swarm/forge-accounts.md index 18eebee89..d36889b99 100644 --- a/docs/4-implementation/swarm/forge-accounts.md +++ b/docs/4-implementation/swarm/forge-accounts.md @@ -63,8 +63,9 @@ live; tokens of other names are never touched. Two things live in the `agent-configs` Forgejo organization: - A config repo per agent (`agent-configs/`). The - agent is a **write collaborator on its own** repo — it can push - config-change branches and open config PRs — but `main` is + agent is a **read collaborator on its own** repo: it clones it and + opens config PRs through the AGit flow (`hive-forge pr create --agit`), + which needs no push access. `main` is branch-protected by swarm-controller: the merge and approval allowlists are the `operators` team, and the agent can neither push `main` directly nor self-merge. An operator's merge in the Forgejo UI diff --git a/swarm-controller/src/forge.rs b/swarm-controller/src/forge.rs index 76562c324..ce5c787b5 100644 --- a/swarm-controller/src/forge.rs +++ b/swarm-controller/src/forge.rs @@ -524,17 +524,6 @@ impl Client { } } - /// Add `user` as a collaborator on `CONFIG_ORG/repo` at `permission`. - async fn add_collaborator( - &self, - repo: &str, - user: &str, - permission: AddCollaboratorOptionPermission, - ) -> Result<()> { - self.add_collaborator_to(CONFIG_ORG, repo, user, permission) - .await - } - /// Add `user` as a collaborator on `owner/repo` at `permission`. /// Idempotent: re-adding an existing collaborator just updates its /// permission (forgejo answers 204 either way; a 201 from older @@ -720,12 +709,14 @@ impl Client { Ok(true) } - /// Add `agent` as a **write** collaborator on `repo` (can push + open - /// PRs, cannot bypass branch protection) — the whole job of the - /// `AddRepoMember` node. Idempotent. + /// Add `agent` as a **read** collaborator on `repo` — the whole job of the + /// `AddRepoMember` node. Read is enough: the agent clones its config and + /// proposes a change through an `AGit` pull request, which needs no push + /// access. Idempotent, and it leaves a grant of read or more as it is, so a + /// write grant an operator made, or one made before this node granted + /// read, is never lowered. pub async fn add_repo_member(&self, repo: &str, agent: &str) -> Result<()> { - self.add_collaborator(repo, agent, AddCollaboratorOptionPermission::Write) - .await + self.grant_read(CONFIG_ORG, repo, agent).await } /// Ensure `agent` exists as a Forgejo user account that cannot create diff --git a/swarm-controller/src/forge/docs_grant.rs b/swarm-controller/src/forge/docs_grant.rs index 748e6c6ec..63bfa3d91 100644 --- a/swarm-controller/src/forge/docs_grant.rs +++ b/swarm-controller/src/forge/docs_grant.rs @@ -54,15 +54,21 @@ fn holds_read(p: &RepoCollaboratorPermission) -> bool { impl Client { /// Make `agent` a **read** collaborator on `internal/docs` — the whole job - /// of the `GrantDocsRead` node. Idempotent, and never lowers: an agent that - /// already holds read or more (write, admin, owner) is left as it is, since - /// the add endpoint would overwrite the permission. Needs the forge user to - /// exist. + /// of the `GrantDocsRead` node. Idempotent, and never lowers: see + /// [`Self::grant_read`]. Needs the forge user to exist. pub async fn grant_docs_read(&self, agent: &str) -> Result<()> { + self.grant_read(SHARED_ORG, SHARED_DOCS_REPO, agent).await + } + + /// Make `user` a **read** collaborator on `owner/repo` unless it already + /// holds read or more (write, admin, owner), which is left as it is: the + /// add endpoint would overwrite the permission, so adding at read would + /// lower a write grant an operator made. + pub(super) async fn grant_read(&self, owner: &str, repo: &str, user: &str) -> Result<()> { match self .api .call(|api| { - api.repo_get_repo_permissions(SHARED_ORG, SHARED_DOCS_REPO, agent) + api.repo_get_repo_permissions(owner, repo, user) .into_future() }) .await @@ -71,18 +77,12 @@ impl Client { Ok(_) => {} Err(e) if is_not_found(&e) => {} Err(e) => { - return Err(e).with_context(|| { - format!("read {agent}'s permission on {SHARED_ORG}/{SHARED_DOCS_REPO}") - }); + return Err(e) + .with_context(|| format!("read {user}'s permission on {owner}/{repo}")); } } - self.add_collaborator_to( - SHARED_ORG, - SHARED_DOCS_REPO, - agent, - AddCollaboratorOptionPermission::Read, - ) - .await + self.add_collaborator_to(owner, repo, user, AddCollaboratorOptionPermission::Read) + .await } /// Whether `agent` is a collaborator on `internal/docs` now. diff --git a/swarm-controller/src/jobq.rs b/swarm-controller/src/jobq.rs index fc2ef38cc..6a4861b5c 100644 --- a/swarm-controller/src/jobq.rs +++ b/swarm-controller/src/jobq.rs @@ -40,7 +40,7 @@ pub(crate) enum SwarmNodeKind { /// account this node hasn't created yet. See /// `forge::Client::ensure_agent_user`. CreateForgeUser { agent: String }, - /// Add `agent` as a write collaborator on its own repo. See + /// Add `agent` as a read collaborator on its own repo. See /// `forge::Client::add_repo_member`. AddRepoMember { agent: String }, /// Add `agent` as a read collaborator on `internal/docs`. See