~ 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. 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, 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 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

VariableDefault
OPENROUTER_API_KEYWithout it, nothing is investigated
INVESTIGATION_MODELz-ai/glm-5.3Any OpenRouter model id with tool calling
INVESTIGATIONS_PER_DAY20Spend ceiling, UTC day
INVESTIGATION_TIMEOUT_MS600000An investigation is aborted after this
CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_AI_TOKENWithout them, every item goes to review
CLEF_MODELclefclef-flash is faster and smaller
BSKY_IDENTIFIERgrain.social
BSKY_APP_PASSWORDWithout it, mentions are not polled
GRAIN_URLhttps://grain.socialgrain-serve, for its moderation methods and public reads; its host's did:web is the audience of the service tokens
GRAIN_MOD_IDENTIFIERThe moderating account's DID, which grain-serve's GRAIN_ADMIN_DIDS names
GRAIN_MOD_APP_PASSWORDIts app password. Without both, reports are neither read nor acted on
GRAIN_DB_PATHgrain-serve's index (index.db, with its -wal and -shm beside it), read-only. Without it, no SQL tool
REPOSgrain, grain-ios, grain-androidname=url#branch, space separated
GITHUB_APP_ID, GITHUB_APP_KEYThe GitHub App fixes become pull requests as; the key is the PEM, base64-encoded. Without them, fixes download as patches
STATE_DIR./stateQueue 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:

PathWhat
apps/serverThe 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/webThe dashboard: React, Vite, TanStack Router (file-based, src/routes) and TanStack Query, with shadcn components on Base UI.
apps/previewThe screenshot runner, its own image.
packages/typesThe 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/uiThe 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:

  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, 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.