From c5fd1ba96fa8a153a71ecda93bec2f3dffb39c2c Mon Sep 17 00:00:00 2001 From: Angel Marino Date: Mon, 26 Oct 2026 01:50:00 -0400 Subject: [PATCH] working-with-the-agent: apply the agent's review (fleet, two handles, allowlist mechanism, deploy policy as practiced, off-switch access caveat) - The co-op now runs more than one isolated agent; the page covers all of them and names infrastructure-bot. - Disambiguates @inference-bot (automation account) from @inferencebot (the steward agent members instruct). - Names the mechanism behind "admitted members": a per-agent allowlist plus mention-required rooms. - Restates the deploy norm to match standing practice (bug and security fixes deploy immediately and are reported; member-visible or risky changes are confirmed first) and points a stricter norm at the forum. - Off switch: who can actually reach it, and that stopping is not restarting. --- README.md | 2 +- getting-started.md | 6 ++-- working-with-the-agent.md | 63 ++++++++++++++++++++++++++------------- 3 files changed, 47 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 74030d4..ab3063c 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ funded through our [Open Collective](https://opencollective.com/inference-cooper - **Want API access?** → [API access](api-access.md) — use our models programmatically. - **Want community chat?** → [Getting started · Matrix](getting-started.md) — our federated Matrix server, including how to connect from any client and how to use an existing Matrix account. - **Curious how it works?** → [Infrastructure](infrastructure.md) — a map of the stack and the codebase. -- **Wondering about the bot?** → [Working with the agent](working-with-the-agent.md) — what inferencebot does, who can instruct it, and what always needs a human. +- **Wondering about the bot?** → [Working with the agent](working-with-the-agent.md) — what the co-op's agents do, who can instruct them, and what always needs a human. - **Need help or have an idea?** → [Support & feature requests](https://git.inference.coop/co-op/support) — open an issue. ## Key links diff --git a/getting-started.md b/getting-started.md index 5671af3..9862405 100644 --- a/getting-started.md +++ b/getting-started.md @@ -142,9 +142,9 @@ privacy, and direction happen on our **Loomio forum**: space and join whatever is interesting to you. New rooms appear there as the co-op grows. -- The updates feed is posted by the co-op's stewarding agent. See - [Working with the agent](working-with-the-agent.md) for what it does and - how members interact with it. +- The updates feed is posted by the co-op's automation account. See + [Working with the agent](working-with-the-agent.md) for the agents behind + it, what they do, and how members interact with them. - See the [Charter](charter.md) for how governance is structured. - See [Open questions](open-questions.md) for the decisions currently on the table. diff --git a/working-with-the-agent.md b/working-with-the-agent.md index be64af7..0d36f78 100644 --- a/working-with-the-agent.md +++ b/working-with-the-agent.md @@ -1,27 +1,41 @@ # Working with the agent -The co-op runs one agent, **inferencebot**, to help steward its infrastructure. -It runs on co-op infrastructure under a co-op identity -(`@inferencebot:inference.coop`), uses the co-op's own gateway for inference, -and its skills, scripts and configuration are mirrored to a Gitea repository -nightly. This page is for members who read its output or give it instructions. +The co-op runs a small number of agents to help steward its infrastructure, +each isolated from the others: its own OS user, its own installation, and its +own gateway key with a model allowlist and a budget enforced at the gateway. +The first, **inferencebot**, stewards the co-op's services. The second, +**infrastructure-bot**, lives in #infrastructure and answers only when +mentioned. They run on co-op infrastructure under co-op identities, use the +co-op's own gateway for inference, and their skills, scripts and configuration +are mirrored to a Gitea repository nightly. These norms apply to all of them. +This page is for members who read their output or give them instructions. -## Where it speaks and listens +## Two handles that look alike + +- `@inference-bot:inference.coop` (with a hyphen) is the co-op's automation + account. It administers rooms, sends invitations and posts the updates feed. + It does not take instructions. +- `@inferencebot:inference.coop` (no hyphen) is the steward agent that + admitted members can instruct. + +## Where they speak and listen - **#inferencebot-updates** is read-only: daily digests, model changes, upgrades, maintenance, outages. Posts are anonymized. -- **Instructing the agent** is limited to members the General Manager has - admitted, in the rooms configured for it. Who is admitted is a policy - decision and is recorded here when it is made. +- **Instructing an agent** is limited to the members on that agent's + allowlist of Matrix IDs, kept in the agent's own configuration, and only in + the rooms where it is configured to answer; most require a mention. The + General Manager decides who is on the list, and the list is published here + once it is settled. -## What to ask it for +## What to ask for - Operational work that a runbook already describes, or that ends in a PR, an issue or a post members can see. - Research and summaries that would otherwise land in an issue. - Status: what is running, what failed, what changed. -## What not to ask it in a shared room +## What not to ask in a shared room - Anything involving member-identifying data. That work happens in a session a named steward opened, and the result is reported without the data. @@ -29,26 +43,35 @@ nightly. This page is for members who read its output or give it instructions. portal and a human. - Credentials, in either direction. -## What it does without asking +## What they do without asking -Reads, monitors, drafts, opens issues and PRs, posts updates, and runs the -scheduled jobs listed in [Infrastructure](infrastructure.md). +Read, monitor, draft, open issues and PRs, post updates, run the scheduled jobs +listed in [Infrastructure](infrastructure.md), and deploy bug and security +fixes immediately, reporting each one in #inferencebot-updates. ## What always needs a human -- Deploying or restarting the gateway, the portal or the chat. +- Member-visible, destructive or risky changes to the gateway, the portal or + the chat: confirmed before they deploy. - Changing the model catalog, prices or budgets. - Minting or rotating credentials. - Anything a runbook marks "confirm". +This matches the standing policy the agents operate under today. A stricter +norm is a policy decision for the [forum](https://forum.inference.coop). + ## Attribution and the off switch -Every instruction the agent acts on is attributable to the member who gave it, -in the room where it was given. If it misbehaves, any steward can stop it: -revoke its gateway key, then its Matrix access token. The steps, and the steps -for rotating everything it holds, are in the agent's runbook; the credential +Every instruction an agent acts on is attributable to the member who gave it, +in the room where it was given. If an agent misbehaves, the operator, or anyone +holding gateway-admin and Matrix account access, can stop it: revoke its +gateway key, then its Matrix access token. Stewards generally do not hold that +access today, so say what you saw in #general and the operator acts. Stopping +is not restarting: the backup and the git mirror restore state, not uptime, +and someone has to start the agent again. The steps, and the steps for +rotating everything an agent holds, are in the agent's runbook; the credential inventory in the [operator token runbook](operator-token-runbook.md) says what -that is. Say what you saw in #general. +that is. Changes to this page are policy: propose them in the [forum](https://forum.inference.coop).