grain.social/grain-support-agent
grain's support agent: triages mentions and reports, investigates bugs, proposes fixes
grain-support-agent
An always-on support agent for 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 withcom.atproto.admin.updateSubjectStatus, a label withsocial.grain.admin.applyLabel, and every open report on the subject closed withsocial.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 withgrain 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 towardINVESTIGATIONS_PER_DAY. - Triage runs on 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()inapps/server/src/triage.ts. - Investigation runs in opencode 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
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:
- Fill in the support agent section of
secrets.envand runscripts/push-secrets.sh. - Set
agent_enabled = trueinterraform.tfvarsand push the rendered config withscripts/push-config.sh. - Point
agent.grain.socialat the host in Cloudflare. grain-deployon 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, 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.