From 9b5eff63fb27b8b32618abcaba787353388d5433 Mon Sep 17 00:00:00 2001 From: Angel Marino Date: Mon, 26 Oct 2026 01:06:33 -0400 Subject: [PATCH 1/3] docs: add "Working with the agent" (norms for reading and instructing inferencebot) A first draft of the member-facing norms listed as a design goal on co-op/support#17: where the agent speaks and listens, what to ask it for, what not to ask it in a shared room, what it does without confirmation, what always needs a human, and how it is stopped. Linked from the README index and the Matrix section of getting-started. Nothing here changes how the agent is configured. --- README.md | 1 + getting-started.md | 4 +++ working-with-the-agent.md | 54 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 59 insertions(+) create mode 100644 working-with-the-agent.md diff --git a/README.md b/README.md index a2cd0ae..74030d4 100644 --- a/README.md +++ b/README.md @@ -16,6 +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. - **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 efb04eb..5671af3 100644 --- a/getting-started.md +++ b/getting-started.md @@ -142,6 +142,10 @@ 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. + - 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 new file mode 100644 index 0000000..be64af7 --- /dev/null +++ b/working-with-the-agent.md @@ -0,0 +1,54 @@ +# 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. + +## Where it speaks and listens + +- **#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. + +## What to ask it 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 + +- Anything involving member-identifying data. That work happens in a session a + named steward opened, and the result is reported without the data. +- Anything that moves money or changes who is a member. Those go through the + portal and a human. +- Credentials, in either direction. + +## What it does without asking + +Reads, monitors, drafts, opens issues and PRs, posts updates, and runs the +scheduled jobs listed in [Infrastructure](infrastructure.md). + +## What always needs a human + +- Deploying or restarting the gateway, the portal or the chat. +- Changing the model catalog, prices or budgets. +- Minting or rotating credentials. +- Anything a runbook marks "confirm". + +## 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 +inventory in the [operator token runbook](operator-token-runbook.md) says what +that is. Say what you saw in #general. + +Changes to this page are policy: propose them in the +[forum](https://forum.inference.coop). -- 2.53.0 From c5fd1ba96fa8a153a71ecda93bec2f3dffb39c2c Mon Sep 17 00:00:00 2001 From: Angel Marino Date: Mon, 26 Oct 2026 01:50:00 -0400 Subject: [PATCH 2/3] 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). -- 2.53.0 From 98cd517b8ae580f71c7cd91523a8b48bc9ba80c9 Mon Sep 17 00:00:00 2001 From: inference-bot Date: Wed, 4 Nov 2026 01:17:47 +0000 Subject: [PATCH 3/3] docs: rebase onto current main -- add the page to the nav and repoint the operator-runbook link - mkdocs.yml: list 'Working with the agent' in the nav (a page not in the nav is hard to find). - working-with-the-agent.md: the operator token runbook moved out of the published site into the git-only co-op/ops-docs, so the relative link (operator-token-runbook.md) would 404; point it at the runbook's new home in ops-docs, as infrastructure.md already does. Wording unchanged. --- mkdocs.yml | 1 + working-with-the-agent.md | 5 +++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 234e31a..9f0d9b4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -74,6 +74,7 @@ nav: - Energy & carbon: energy.md - Infrastructure: infrastructure.md - Background: background.md + - Working with the agent: working-with-the-agent.md - Governance: - Charter: charter.md - Code of conduct: code-of-conduct.md diff --git a/working-with-the-agent.md b/working-with-the-agent.md index 0d36f78..87f507a 100644 --- a/working-with-the-agent.md +++ b/working-with-the-agent.md @@ -70,8 +70,9 @@ 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. +inventory in the [operator token +runbook](https://git.inference.coop/co-op/ops-docs/src/branch/main/operator-token-runbook.md) +says what that is. Changes to this page are policy: propose them in the [forum](https://forum.inference.coop). -- 2.53.0