Jeeves — AI Governance Gateway (Demo)

This is a fictional demo. "Meridian Health" is not a real company and has no affiliation with any real healthcare payer, insurer, or health system (including Optum/UHC). Every initiative, actor, approval, control, and telemetry series in this repository is synthetic, generated by a deterministic seed script. No real PHI, PII, or production data is used anywhere in this codebase — live LLM calls, when enabled, only ever see synthetic seed data.

Jeeves is a demo of an AI governance gateway for a fictional healthcare payer, "Meridian Health": a single place to submit an AI project or agent request, triage its risk deterministically, route it through the right governance reviews, get agent-drafted reviews that a human signs, issue a named accountable approval, generate versioned controls for the deployment, and keep monitoring it afterward — with a structured, evidence-linked audit trail throughout.

The core idea it demonstrates: agents draft, humans decide. No agent in this system ever holds approval authority.

Jeeves models the full lifecycle of an AI initiative moving through governance, end to end:

1. Intake — a structured form (not a chat) captures what the initiative is, plus a healthcare risk overlay (PHI access? member-facing? influences care/coverage? vendor-hosted? human-in-the-loop? individual impact?). A completeness check flags missing answers without blocking submission.
2. Deterministic risk triage — the overlay answers are run through fixed rules (lib/triage/rules.ts) to assign a tier: Low / Medium / High / Critical. No LLM is involved in the tier decision itself.
3. All-8-domain agent-drafted review — the tier determines which governance domains are required (up to all 8: Legal, Procurement, Tech Architecture, Responsible AI, Security, Privacy/HIPAA, Clinical Safety, Data Governance). A bounded-concurrency workflow fans a draft-review request out to every required domain in parallel, with per-domain retry, resumability, and progress visibility.
4. Human sign-off — a domain-scoped reviewer edits and signs (or returns) each draft. Agents never sign.
5. Conditional approval — a named, accountable human approver decides: approve, conditionally approve (with conditions linked to controls), or reject. Low-risk initiatives can instead take a deterministic fast lane under a pre-approved policy — which still names an accountable approver, never an agent.
6. Versioned effective controls — approval generates a versioned set of effective controls for the deployment, drawn from a per-domain control catalog (owner, cadence, evidence, enforcement mode).
7. Post-deploy monitoring — synthetic eval-quality telemetry is evaluated against a threshold; a sustained breach pauses the deployment and opens a reassessment review cycle, recording an incident. Re-running the monitor is idempotent — no duplicate incidents.
8. Structured, evidence-linked audit queries — canned queries (e.g. "member-facing initiatives touching PHI, with approver and current control status") return rows that link back to the decisions, signatures, and audit events that produced them.

• Governance operations console — a left-nav ops shell (Inbox, Portfolio, Reviews, Monitoring, Controls, Audit, Promotions, Administration) in a restrained enterprise UI, not a marketing site.
• 3-column Review Workbench as the central review-signing experience, and each initiative renders as a case file (overview, evidence/blockers rail, evals & telemetry, deployments/release ledger, decisions, audit).
• Role-aware, persona-specific screens — logging in as a persona doesn't just flip a label, it changes what you see: requesters see their own initiatives, reviewers see a queue scoped to their domain (e.g. Sofia Grant, Responsible AI, is the only persona who sees eval-quality/fairness signals), the approver sees decisions awaiting sign-off, admin sees operations/paused deployments, and program office sees a portfolio-wide view.
• Public read-only mode + passcode-gated live mode — anyone can browse the seeded portfolio with no login. A demo passcode unlocks a live, mutable workspace with per-browser workspace isolation (a cookie-scoped demo playground, not a fresh empty workspace per login, so a requester → reviewer → approver walkthrough in one browser sees the same data).
• Two live conversational surfaces — a grounded, cited ask-the-auditor chat and a conversational intake assistant, both hardened with role checks and payload limits.
• Honest synthetic telemetry — every synthetic panel is labeled "Synthetic data — demo" with a connector-status chip (e.g. "Arize: not connected"); no imitation third-party panels, no dead deep links.

Thirteen fictional actors (lib/services/actors.ts, mirrored client-side in lib/client/personas.ts; see docs/seed-spec.md §1) drive every storyline. Reviewers are domain-scoped — each of the eight owns exactly one governance domain, covering all 8 required review domains.

• Next.js (App Router) + TypeScript, Tailwind + shadcn/ui, Recharts
• Neon Postgres + Drizzle ORM — the pooled neon-serverless driver in production, or a persistent local PGlite instance as a zero-setup fallback for local dev and tests (same schema, same Drizzle API either way)
• Vercel AI SDK + Workflow SDK behind app-owned capability ports — AgentPort (draft review, triage assist, completeness check via generateText + Output.object) and a WorkflowPort-shaped bounded- concurrency fan-out for multi-domain drafts. Authoritative state transitions live in application code + Postgres, never inside an adapter.
• OpenAI GPT-5.x as the runtime LLM (OPENAI_MODEL) — used only if OPENAI_API_KEY is set; otherwise a deterministic, keyless mock adapter is the default, so nothing ever calls a live provider without that key. All LLM calls are mocked in tests.

Prerequisites: Node.js (see package.json/next 16 for the supported range) and npm. No Docker, no external services required for local dev.

npm install

npm run db:seed   # seeds a persistent local PGlite store at ./.pglite
npm run dev       # http://localhost:3000

http://localhost:3000 (/) is the public marketing landing page; click through (or go straight to /inbox) for the governance operations console — a read-only portfolio board of 12 seeded initiatives with no further configuration.

DATA_PROVIDER=db DEMO_PASSCODE=<choose-a-passcode> npm run dev

Then, in the browser, click the "Read-only (public)" chip in the top bar and enter the passcode to unlock the live workspace (intake, triage, draft-run, sign, decide, monitor, admin actions). Point DATABASE_URL at a real Neon Postgres connection string to run against Neon instead of PGlite; set OPENAI_API_KEY (+ optionally OPENAI_MODEL) only if you want genuinely live-generated draft text — see .env.example for the full variable list.

Note: scripts/seed.ts refuses to run when NODE_ENV=production unless ALLOW_SEED=1 is explicitly set, to prevent an accidental reseed of a live hosted demo.

Optional env vars (all default to a safe, honest fallback):

All LLM capability enters the app through a single app-owned interface, AgentPort (lib/agents/ports.ts). Three implementations sit behind it, and which one you get is decided in one place (lib/agents/index.ts):

• Mock (no OPENAI_API_KEY) — deterministic, offline, keyless. This is the default and what the test suite and the Playwright golden path run against. A provider outage cannot break the demo.
• ai-sdk (default when a key is present) — Vercel AI SDK, one structured round trip per call.
• agents-sdk (JEEVES_AGENT_RUNTIME=agents-sdk) — OpenAI Agents SDK, with per-method model routing: Luna (gpt-5.6-luna) handles completeness checks, intake turns, triage narration, and grounded audit answers — high-volume, latency-sensitive work — while Terra (gpt-5.6-terra) drafts domain reviews, where policy-grounded nuance matters more than time-to-first-token.

Setting JEEVES_DEEP_REVIEW=1 on the agents-sdk runtime turns review drafting into a tool-using loop: the reviewer agent consults the governance policy corpus (docs/policies/, agents/reviewer/) through read-only, sandboxed tools before it drafts, and the Review Workbench shows which policies it read. The tools cannot write, and cannot escape the corpus. A deep draft costs many model calls, so the draft-run endpoint reserves a 10× budget multiplier when it is enabled — the daily cap stays honest.

Whichever runtime is selected, the hard rule is unchanged: agents draft, recommend, route, and flag missing evidence — they never approve.

Demo reset ritual — before a live walkthrough, run:

DEMO_PASSCODE=<passcode> npm run reset:demo

It re-seeds to the canonical state, clears live session + budget state, and prints a pre-flight checklist (passcode, agent/telemetry connector status, cron secret, build SHA, and a 12-initiative smoke count).

See docs/deploy.md for the full Vercel + Neon deployment runbook, known gaps, and a demo-day checklist.

npm test              # Vitest — unit/integration tests against in-memory PGlite
npm run test:e2e      # Playwright — golden-path.spec.ts (needs DEMO_PASSCODE in the runner env)
npm run lint          # eslint
npm run typecheck     # tsc --noEmit

The full suite runs several hundred Vitest unit/integration tests (targeting

80% coverage on lib/) plus 8 Playwright end-to-end tests. The Playwright suite is the required golden path: it walks the read-only portfolio and audit views, then a full live loop across requester, reviewer, and approver personas — intake, triage, an all-8-domain drafted review, sign-off, and conditional approval — against a real (mocked-LLM) run.

• Public visitors are strictly read-only. There is no unauthenticated mutation endpoint anywhere in the app.
• Every mutation is passcode-gated and bearer-authenticated with DB-backed sessions (not in-memory) issued only after the demo passcode is verified.
• Atomic per-day token budget — LLM usage is capped per day via a conditional INSERT ... ON CONFLICT DO UPDATE reservation, so concurrent requests can't race past the cap.
• Requester-ownership and reviewer-domain authorization — a reviewer can only sign/return reviews in their own assigned domain; a requester can only submit/edit their own initiatives.
• Per-browser workspace isolation for the live demo, so a passcode session doesn't leak into or collide with another visitor's session or the seeded baseline.
• Security headers set at the framework level, and input-length caps on every mutating request.
• DB-level append-only audit log — AuditEvent rows cannot be updated or deleted at the database level (revoked privileges + trigger, not just application-code discipline), and every synthetic telemetry panel is explicitly labeled as synthetic.

See docs/deploy.md §3 for the current, explicitly-documented gaps (e.g. Neon driver transaction semantics, rate-limiter scope) before relying on this for anything beyond a controlled demo.

app/                    Next.js App Router — pages (Inbox, Portfolio, Reviews,
                        Monitoring, Controls, Audit, Promotions, Admin,
                        initiative case-file pages) + app/api/** route handlers
lib/
  domain/               Shared value types (tiers, roles, lifecycle states, domains)
  triage/               Deterministic risk-tier + domain-routing rules
  approval/             Fast-lane eligibility logic
  lifecycle/            The single source of truth for legal state transitions
  controls/             Control-evaluation logic (threshold/sustained-window breaches)
  intake/               Intake completeness engine
  agents/               AgentPort type + OpenAI adapter + deterministic mock adapter
  workflow/             Bounded-concurrency, resumable multi-domain draft fan-out
  services/             Transactional use cases + the route-guard pipeline
                        (session -> rate-limit -> budget -> authz)
  security/             Passcode/session, rate limiting, token budget, input caps
  data/                 The DataProvider swap point (db vs mock), env-selected
  db/                   Drizzle schema + the Neon-or-PGlite client factory
  client/               Client-safe persona/session mirrors for UI components
components/jeeves/      App-specific UI: workbench, case-file tabs, chats,
                        portfolio table, audit console, admin controls, etc.
drizzle/                Generated SQL migrations, incl. the append-only audit trigger
docs/                   plan.md-adjacent specs: seed-spec, intake-spec, ui-spec,
                        demo-script, deploy runbook, per-domain policy corpus
tests/                  Component tests, port compile-tripwire tests, and the
                        required Playwright golden-path spec
scripts/                seed.ts — the deterministic seed script

Jeeves is an actively evolving demo build; plan.md is the authoritative product/engineering spec — domain model, phases, hard rules, and milestone map — and agents-build-log.md is the chronological record of everything built, including architecture decisions and review findings.

To restate the disclaimer at the top of this file: Jeeves is a fictional demo. "Meridian Health," all thirteen personas, all seeded initiatives, approvals, controls, and telemetry are synthetic and generated by a deterministic seed script. Nothing in this repository represents a real organization, a real patient, or real PHI/PII, and no real integration (Arize, ServiceNow, Ariba, etc.) is wired up anywhere in the code.