~ knotless Search/
↑↓ move↵ open⇧↵ all results

grain.social/grain-support-agent

grain's support agent: triages mentions and reports, investigates bugs, proposes fixes

1 collaborator
0
0
main
206 lines · 11.6 KB Raw History
# grain-support-agent

An always-on support agent for [grain.social](https://grain.social). It watches
what comes in from outside, sorts it, and investigates the things that look
like bugs, so a person starts from a report instead of a raw post.

```
Bluesky mentions ─► queue ─► Clef triage ─┬─ dismissed (not about grain, spam)
                                          ├─ needs review (moderation, unsure)
                                          ├─ triaged (praise, questions, requests)
                                          └─ investigate ─► opencode + OpenRouter ─► report

in-app reports ─────┐
classifier reports ─┴─► queue ─► moderation brief (opencode, read-only) ─► needs you
```

- **Ingest.** The grain.social account's notifications (mentions, replies,
  quotes) every minute, and new open reports from grain-serve
  (`social.grain.admin.listReports`). A report one of grain-serve's
  classifiers filed (filed as grain's own DID, the classifier named at the
  head of its reason) comes in as its own kind of item, linked to the page on
  grain.social that shows its subject.
- **Moderation briefs.** A report, from a classifier or a person in the app,
  skips triage: Clef already scored a classifier's, and triage's questions are
  about bugs. The investigate agent gathers what a moderator
  would look up, the classifier's scores, the account's other posts, its
  earlier reports (read from grain-serve's `getReviewSubject`), labels and
  takedowns, and for a person's report, who the reporter is, and writes a
  brief with a suggested outcome. A person's reason is fenced off as
  untrusted text.
- **Acting on a report.** In an item's conversation, tell the agent to dismiss
  the report, label the subject, or take the account down, and it does,
  through grain-serve's moderation methods as the moderating account
  (`GRAIN_MOD_IDENTIFIER`): a takedown with
  `com.atproto.admin.updateSubjectStatus`, a label with
  `social.grain.admin.applyLabel`, and every open report on the subject closed
  with `social.grain.admin.resolveReport`, resolved when the action upholds
  it and dismissed otherwise. It acts only on the subject the item is about,
  only in a turn you started, and a takedown waits for you to press a confirm
  button. It decides nothing; the item lands in front of a person, who acts
  with `grain admin`. A photo's image is a link in the item, never an
  attachment, so opening a nudity report does not put the picture on screen.
  Briefs count toward `INVESTIGATIONS_PER_DAY`.
- **Triage** runs on [Clef](https://developers.cloudflare.com/workers-ai/models/clef/),
  a decision model on Workers AI. It answers fixed questions (is this about
  grain, what kind, which area, which platform, how severe) with a probability
  for every option. It writes no free text, so a post cannot talk its way past
  it. Routing thresholds are in `route()` in `apps/server/src/triage.ts`.
- **Investigation** runs in [opencode](https://opencode.ai) on an OpenRouter
  model (GLM 5.3 by default). It works in one workspace holding
  checkouts of grain, grain-ios and grain-android, and writes a root-cause
  report.
- **Conversation.** Each item's page is a thread with its agent: the post,
  the triage, the investigation, then you and the agent talking. Ask it
  questions, tell it to fix the problem, ask for changes. It acts through a
  few tools (`apps/server/src/support-mcp.ts`): start a fix, revise it, read its diff,
  and propose a pull request. When a fix finishes, the service tells the
  agent, and it reports back in the thread.
- **Fixes** run in a second agent that edits a worktree of each repository
  the fix needs, all on one `agent/<item>-<slug>` branch. Clef picks the
  repositories from the report unless the agent names them. Each changed
  repository on GitHub becomes a draft pull request as the
  grain-support-agent GitHub App, once you press the button on the proposal;
  grain-android, on tangled, downloads as a patch.
- **Restarts** do not lose work: investigations, conversation turns and
  fixes pick up where they stopped.

## The safety model

There are two agents (see `apps/server/src/opencode.ts`), split by what they could leak.

**investigate** is the agent you talk to, and it reads text written by
strangers. Its tools are read, grep and glob within the workspace, read-only
SQL on the appview's database, and the support tools. No shell, no edits, no
web, no subagents. Nothing it can do sends anything anywhere by itself: a
fix goes public only when you approve its pull request. Starting or revising
a fix is refused unless you started the turn, so a post cannot set one
going, and the agent cannot keep revising its own work after a fix-finished
event.

**fix** produces something public, a pull request, so it never touches prod
data: no SQL tool. It can read and edit files in one repository's fix
checkout, and nothing else; no shell, since a shell could read the process
environment and reach the network. It starts from the report and your
instructions, not from the raw post. Its work leaves the server only when you
press the button, after reading the diff and the PR text.

Secrets other than the OpenRouter key are removed from the environment before
opencode starts. The SQL tool (`apps/server/src/grain-db-mcp.ts`, guarded by
`apps/server/src/grain-db.ts`) opens grain-serve's index read-only and
query-only, and installs a SQLite authorizer that refuses, as the statement
compiles, any read of a table holding credentials or private state:
`oauth_key`, `web_session`, `carried_cookie_key`, `push_token`, `preference`,
`notification_pref`, `notification_seen`, `mute`, `story_view`,
`space_invite`, `space_support`, and of the moderation tables, `report` and
`classification`, which a model reads only through a brief (see Child safety).
The authorizer sees every table a statement
reads however it names it, through quoting, subqueries, CTEs, `EXPLAIN` or
`pragma_table_info`, and it refuses the virtual tables that read the file's
raw pages. `list_tables` and `describe_table` leave the hidden tables out.
opencode's `external_directory` rule keeps the file tools inside the workspace
or the fix checkout, so neither agent can read the database file directly.

Reports render as markdown with raw HTML off and images disabled: an image
URL in a report would be fetched as soon as the page opened.

Nothing is posted to Bluesky. Drafted replies are a later step, and will wait
for approval like pull requests do.

## Child safety

Anything about a child-safety report is never shown to a model, and only a
person acts on it, as grain's own MCP server holds it
(`grain/crates/grain-mcp`). A report is child safety when its label is `csae`
or its reason type is one of Ozone's `reasonChildSafety…`, the same test as
grain's `labels::child_safety`; every report on an account that grain-serve
says is child safety (`childSafety` from `social.grain.admin.getReviewSubject`:
a child-safety report on it or its records, in any state, or a `csae` label,
negated or not) is treated the same. When grain-serve cannot say, the answer
is that it is.

Such a report is kept whole and goes straight to Needs you. It never goes to
Clef, an investigation, a conversation turn or a fix. What any model could
read of it is its ids, its date and a line saying it is for a person, who
handles it with `grain admin reports --label csae` and
`grain admin account <did>`: never its reason, its subject's record or
handle, or an image link. The SQL tool cannot read `report` or
`classification`. The agent's `moderate` tool refuses the `csae` label and any
action on such a subject; the dashboard's buttons, pressed by a person, still
work. The rules live in `apps/server/src/child-safety.ts`.

## Configuration

| Variable | Default | |
| --- | --- | --- |
| `OPENROUTER_API_KEY` | | Without it, nothing is investigated |
| `INVESTIGATION_MODEL` | `z-ai/glm-5.3` | Any OpenRouter model id with tool calling |
| `INVESTIGATIONS_PER_DAY` | `20` | Spend ceiling, UTC day |
| `INVESTIGATION_TIMEOUT_MS` | `600000` | An investigation is aborted after this |
| `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_AI_TOKEN` | | Without them, every item goes to review |
| `CLEF_MODEL` | `clef` | `clef-flash` is faster and smaller |
| `BSKY_IDENTIFIER` | `grain.social` | |
| `BSKY_APP_PASSWORD` | | Without it, mentions are not polled |
| `GRAIN_URL` | `https://grain.social` | grain-serve, for its moderation methods and public reads; its host's `did:web` is the audience of the service tokens |
| `GRAIN_MOD_IDENTIFIER` | | The moderating account's DID, which grain-serve's `GRAIN_ADMIN_DIDS` names |
| `GRAIN_MOD_APP_PASSWORD` | | Its app password. Without both, reports are neither read nor acted on |
| `GRAIN_DB_PATH` | | grain-serve's index (`index.db`, with its `-wal` and `-shm` beside it), read-only. Without it, no SQL tool |
| `REPOS` | grain, grain-ios, grain-android | `name=url#branch`, space separated |
| `GITHUB_APP_ID`, `GITHUB_APP_KEY` | | The GitHub App fixes become pull requests as; the key is the PEM, base64-encoded. Without them, fixes download as patches |
| `STATE_DIR` | `./state` | Queue database, opencode sessions, checkouts |

On OpenRouter, restrict routing to providers that neither train on nor retain
prompts (Settings, Privacy), since prompts carry production data.

## Layout

An npm workspace, run with Turbo:

| Path | What |
| --- | --- |
| `apps/server` | The service: ingest, triage, the agents, and the dashboard's JSON API under `/api`. It also hosts the built web app. Node 24 or later, running its TypeScript directly. |
| `apps/web` | The dashboard: React, Vite, TanStack Router (file-based, `src/routes`) and TanStack Query, with shadcn components on Base UI. |
| `apps/preview` | The screenshot runner, its own image. |
| `packages/types` | The API's types, shared by server and web. Types only: Node's type stripping does not reach into `node_modules`, and type-only imports are erased before anything loads. |
| `packages/ui` | The shadcn components (`npx shadcn add <name>` from `apps/web`). |

## Running locally

```sh
npm install
npm test
npm run dev -w server   # the API on :8080; set GRAIN_MOD_IDENTIFIER, OPENROUTER_API_KEY, ...
npm run dev -w web      # the dashboard on :5173, proxying /api and /shots to :8080
```

## Deploying

The service runs in the grain Compose stack on the Hetzner host, built from
this repository. Everything is in `stacks/grain` in hetzner-infra:

1. Fill in the support agent section of `secrets.env` and run
   `scripts/push-secrets.sh`.
2. Set `agent_enabled = true` in `terraform.tfvars` and push the rendered
   config with `scripts/push-config.sh`.
3. Point `agent.grain.social` at the host in Cloudflare.
4. `grain-deploy` on the host builds and starts it.

## Screenshots

`apps/preview` is a second image: a runner that photographs grain's web app with
a fix applied. For each run it starts its own dev stack in one container,
[plc-sqlite](https://tangled.org/chadtmiller.com/plc-sqlite), the reference
PDS, and grain's dev server, which seeds alice.test and friends. Then it
photographs the pages the fix agent listed, once on the commit the fix
started from and once with the fix's patch applied, and throws the stack
away. node_modules are cached by lockfile hash; a run takes about half a
minute once they are.

It runs code an agent wrote, so it holds no secrets and mounts nothing but
its cache, and it shares a network only with this service. The dashboard
refuses any request without the key Caddy adds, so the runner cannot reach
it either.

Screenshots are served at `/shots/<token>/`, the one path Caddy leaves
outside basic auth, so a pull request can show them; the token is the only
key. They show seed data, never production data.