Imported from aymuos15/anima (AGENTS.md). Install upstream with npx skills add aymuos15/anima. Copyright stays with the author.

AGENTS.md

Everything needed to run and change this project locally. Read this before touching code. Local-only: do not deploy. Use only gpt-5.6-luna with low reasoning through Codex OAuth; no Gemini or API-key fallback.

What this is

An NHS App style patient view (public/index.html) over a synthetic NHS neighbourhood simulator, with an AI care team agent that reads the patient's records and proposes actions the patient approves. A staff operations console (public/admin.html) sits beside it. All data is synthetic.

Local: http://127.0.0.1:8790/ (patient app) and http://127.0.0.1:8790/admin (console).

Layout

Run locally

Requires Node 22 (.nvmrc).

npm install
# simulator key: create or join a world, copy apiKey into agent/key-agent.txt
curl -s https://sim.animahacks.com/api/keys -H 'Content-Type: application/json' -d '{"teamName":"my-team"}'
# Sign in to Codex CLI first. Starts or reuses the local OAuth proxy automatically.
npm run dev

Open http://127.0.0.1:8790/ (press Continue, Ctrl+K switches patient) or http://127.0.0.1:8790/admin.

Sessions go to agent/sessions.db locally. ADK_STORE=memory skips the file. HTML is read per request, so frontend edits need only a refresh. Backend edits need a restart.

Environment variables

Never commit keys. key.txt, agent/key-agent.txt, .env* are ignored.

Checks

npm run typecheck   # tsc, also runs in the Netlify build
npm test            # builds five featured pathways against the live simulator
npm run build       # typecheck + bundle the function into netlify/functions-dist

Historical deployment notes (inactive — do not deploy)

Netlify serves public/ from its CDN and runs agent/server.ts inside one function for /api/*. Supabase Postgres holds chat sessions. The ADK store creates its own tables on first use, so there are no migrations.

Why the function is pre-bundled: Netlify's own bundlers cannot handle the ADK package. Its tracer crashes on the ADK's ESM build and its CommonJS path pulls in playwright. So npm run build:fn bundles everything with esbuild into one ESM file and netlify.toml uses node_bundler = "none". Browser-related packages are marked external because the ADK only loads them lazily for browser tools we do not use.

Steps on a new machine:

1. npm i -g netlify-cli supabase and log in to both.
2. netlify link to the site, supabase link --project-ref <ref>.
3. Historical deployment required simulator, model and database credentials. The current local OAuth configuration is not deployable. DATABASE_URL must use the session pooler, port 5432, because Netlify functions have no IPv6 and the direct db.<ref>.supabase.co host is IPv6-only: postgresql://postgres.<ref>:<db-password>@aws-1-eu-west-1.pooler.supabase.com:5432/postgres?sslmode=require The password is set in the Supabase dashboard under Database settings.
4. netlify deploy --prod from the repo root, or push main if the site is connected to GitHub.
5. Check: curl https://<site>/api/patients/SIM-000009/pathway returns JSON, then a chat turn: curl -X POST https://<site>/api/chat -H 'content-type: application/json' -d '{"patientId":"SIM-000009","input":{"message":"start"}}' A response with "status":"error" carries the underlying message in error.

Known limits: a chat turn takes 5 to 20 seconds and is not streamed. The pathway cache is per function instance, so cold starts are slow. Netlify's function timeout may need raising on the account if turns exceed it.

Simulator API

• Base https://sim.animahacks.com, Authorization: Bearer <key>. OpenAPI at /api/openapi.json, handbook at /docs/handbook.json.
• Sites: gp, hospital, pharmacy, community, diagnostics, wearables, referrals. One fixed neighbourhood per world.
• GET /api/sites/{site}/patients?q= (30 per page). GET /api/sites/{site}/view?patient=SIM-000001&limit=500. POST /api/sites/{site}/actions. POST /api/clock {"paused":true,"advanceMinutes":N}.
• POST /api/keys {"teamName"} creates or joins a world. Same name, same world. New name for a clean run.
• Actions need a UUID clientRequestId. Versioned updates send expectedVersion. Capacity exhaustion and stale versions return 409. Staff-management actions are locked for our key.
• There is no pathway concept in the API. agent/pathway.ts derives it: records are mapped to stages by kind, sorted by date, and open or rejected records become blockers. The patient app relabels the five stages as Referred, Booked, Preparation, Procedure, Post-op care.

Conventions

• Read-only by default. Every write tool and advance_clock yields for approval before touching the simulator.
• Never invent records. Agent prompts live in agent/agents.ts.
• Mohammed's Preparation checklist is curated in agent/preparation.ts and shared through the pathway response with the UI and agent. It is demo data, not simulator orders/results.
• Featured demo patients are listed in agent/tools/admin.ts and repeated in the two HTML files. Keep them in sync.
• Rebuild cohort statistics with SIM_KEY=... npm run build:data when the world changes materially.