recflare/apps/ai/README.md

ai

AI worker served on the ai subdomain (ai.recflare.net). The client checks here before offering any of its AI features — Game AI in a room, the Roomie assistant, and Maker AI's usage meter.

No model runs behind this worker, so every answer is static. They are not all refusals, though, because the features fail at different points:

• Game AI is a server-side feature this server cannot provide, so both of its reads refuse and the client hides it.

• Roomie runs on the client and only asks this service what it may spend, so the budget reads grant everything. The refusal lands instead on POST /realtime-session/create — the one call whose real answer is a working credential rather than a description of one.

• Maker AI meters model usage in dollars. Nothing here bills, so every figure is zero.

• GET / — service status { "service": "ai", "status": "ok" }. No auth.

• GET /gameai/user/access?roomId=<id> — [Authorize]. Whether the caller may use Game AI in a room. Always refused:

  {
    "success": false,
    "error_id": "AI.RoomDoesNotSupportGameAI",
    "error": "This room does not support Rec Room Game AI"
  }
  

  No model runs behind this worker, so every room gets that answer. Two things about it are deliberate: it is a 200, not a 4xx (the client branches on success in the body; an error status would surface as a failed request rather than the "not available here" state this is), and roomId is ignored while the token is still validated first, as the reference server does — so an unauthenticated caller gets a 401 rather than the refusal.

• GET /gameai/room/<roomId>/spendsummary — [Authorize]. What a room has spent of its Game AI budget. Refused for the same reason, but the body is not identical to the access check's:

  {
    "success": false,
    "error_id": "AI.RoomDoesNotSupportGameAI",
    "error": "This room does not support Rec Room Game AI",
    "value": null
  }
  

  It carries value: null where the access check omits the key entirely — that one answers a yes/no and has nothing to carry, while this endpoint's payload slot exists and is simply empty. Reproduced as the reference server sends it; don't unify the two.

• GET /roomieai/user/access — [Authorize]. Roomie AI's energy budget, granted in full:

  {
    "success": true,
    "error_id": null,
    "error": null,
    "value": {
      "MaxEnergyFromSubscriptions": 2147483647,
      "EnergyLeft": 2147483647,
      "NextSubscriptionEnergyRechargeAt": null,
      "OutputAudioEnabled": true
    }
  }
  

  Granted rather than refused because Roomie runs on the CLIENT and only asks this service how much energy it may spend — so for a server that meters nothing, "as much as you can count" is the honest answer. That number is int.MaxValue: the client's field is a signed 32-bit int, and anything larger overflows on the way in and reads as negative, i.e. no energy at all. Nothing depletes, so nothing recharges — hence the null NextSubscriptionEnergyRechargeAt.

  Note the envelope: { success, error_id, error, value }, not the flat body the Game AI check answers with. The two shapes are different on purpose; don't unify them.

• GET /roomieai/user/facts — [Authorize]. What Roomie has been told about the caller:

  { "UserContext": "", "UserFacts": [] }
  

  Live, UserContext is a prose profile written from past conversations and UserFacts holds the discrete (Predicate, Object) claims behind it — things the player told Roomie about themselves. Nothing on this server observes a conversation, so there is nothing to remember and Roomie starts every session knowing nothing about who it's talking to. A flat body, like the Maker AI balances below.

• GET /makerai/user/balances — [Authorize]. What Maker AI has cost the caller, metered live in dollars against a per-user ceiling and a separate RR+ allowance, and rendered by the client as a usage bar with a status word:

  {
    "UsageDollars": 0,
    "UsersMaxUsageDollars": 0,
    "RRPlusUsageDollars": 0,
    "UsersMaxRRPlusUsageDollars": 0,
    "TimeBalanceStatus": "Empty",
    "TimeExpiresAt": "0001-01-01T00:00:00",
    "UsageBalanceStatus": "Good",
    "UsagePercent": 0,
    "RRPlusUsageBalanceStatus": "Good",
    "RRPlusUsagePercent": 0
  }
  

  Zeroed rather than refused: nothing here bills for model usage, so the caller has spent nothing. Both usage buckets report Good — an untouched allowance, not an exhausted one. The time bucket is Empty at DateTime.MinValue, this server selling no timed access for it to hold. Flat body, no envelope.

• POST /realtime-session/create — [Authorize]. Posted when the player actually pulls out an assistant. Live, this mints a short-lived credential ({ SessionId, ClientSecret } in value) that the client then uses to talk to the model provider directly. Refused:

  {
    "success": false,
    "error": "Realtime AI sessions are not available on this server",
    "error_id": "",
    "value": null
  }
  

  This is the one endpoint here whose real answer is a working key rather than a description of one, so there is nothing static to serve — which is why the budget reads above grant everything and the stop lands here instead: the client offers the feature, and the session it opens is what fails. Note error_id is an empty string, not a code — the reference server sends no id for this refusal. The posted body (AIType) is ignored; the answer is the same either way, and a missing or malformed body still gets the refusal rather than a 500.

The worker exists so the client gets a definite answer on the host its endpoints document already names (AI → ai, see apps/ns), instead of a failed request to a host with nothing behind it.

Not served here: GET /api/makerai/checkfreetrialeligibility, which despite the name lives on the api host in the reference server and belongs to apps/api.

API documentation

GET /openapi.json serves a spec generated from describeRoute blocks that sit alongside each handler, with the schemas in src/openapi.ts. It's also aggregated into the docs page www serves at /docs. A test asserts every route appears in it.

The spec is descriptive, not enforced — same rationale as the other workers: a reverse-engineered protocol, lenient handlers, no runtime validation.

Development

Run in dev mode

pnpm dev

Run tests

pnpm test

Deploy

pnpm turbo deploy