five-on-it / apps/api/src/creations
apps/api/src/creations
Creation jobs (TECHNICAL_SPECS §9.8): an owner writes a brief in the game (?create), the platform's own model makes the game from it, and the owner plays it. A brief is a job of the durable queue (kind: 'create'), run by a creator runner (apps/creator) that claims it over the private routes below, calls the MCP server's tools in its own process as a session of the job (a grant grant-job-<id>, scope job:<id>: its own draft, its builds, the catalogue and the levels, nothing else, JOB_ROUTES) and reports how it goes.
- The allowance. A creation is spent when the brief is queued (
creationsa day, an admin's override first; the day in UTC), and given back when the job is cancelled before it starts or fails through no fault of the brief (the runner went away, a model's provider refused to bill:system); a running job cancelled keeps it spent. - The budget (
budget.ts): new briefs are refused, no creation spent, while today's spend and reservations reach the day's budget; a queued job is claimed while the budget covers one more job's cap, else it waits ("waiting for budget"), but an account an admin marked exempt; the job's cap is reserved at its claim and settled at its end. - One running creation an owner (the store's claim, Postgres's index); a creation's builds go ahead of the build queue (priority 1, its child), counted against its cap of CREATION_CAPS builds and not the day's builds; the build executor takes builds only and the runners creations only, so a creation never waits behind itself.
- Cancel revokes the job's grant: the runner's next call is refused (401) and its next heartbeat says stop. A lease that runs out (the runner gone) fails the job with its creation given back (a sweep, every few seconds and before each claim).
- The feed: when a job ends but by its owner's own cancel, the owner's feed hears of it (
kind: 'creation'): the game's toast opens the result. - Moderation (
moderation.ts): a brief is checked after the budget and before its creation is spent, so a refused one (422,reason: 'moderation') spends nothing and no model runs. What the model wrote (its draft's texts, its level spec's, its last words) is checked when the job ends (finished, cancelled, its runner gone); until then, with moderation on, the draft is shown to nobody but the job's own session. Refused, the job fails with the reason, its creation kept spent, and nothing of it is shown: a draft it made is withheld, one it revised put back as it was, its builds withheld (DraftCreation,Build.withheld). - Transcripts: the runner's conversation (the brief, the model's words and tool calls, the tools' answers) comes with its finish and is kept for the moderators and the admins 30 days (purgeTranscriptsEvery).
| Route | Who | What |
|---|---|---|
POST /jobs {brief, where?, size?, missions?, draft?} | a creator (need('creator'): on a Steam platform an owner of a copy of their own, its entitlement at most an hour old) | Queues a creation: a brief of 600 characters at most, on Riverbend, a new town or a region, small to large, 1 to 3 missions; draft revises one of the creator's drafts (a creation too). 202 with the job; 429 when the allowance or the budget says no (reason, resetsAt or resumesAt); 503 when creation is off. |
GET /jobs, GET /jobs/:id | a creator, the same way | One's creations, newest first: the state, the step, the place in line and why it waits, the result (the draft, its build, its preview and text map). |
POST /jobs/:id/cancel | a creator, the same way | Cancels one's creation, queued (the creation given back) or running (stopped within seconds, its draft kept). |
GET /admin/creations, POST /admin/jobs/:id/cancel | an admin | The platform's queue (every waiting and running creation, the last ones over) and the budget (the month to date, today's budget, spent and reserved); cancels anyone's. |
POST /creator/claim {wait?} | the runners' secret, direct | Waits up to wait ms (25 s at most) for the next creation the budget covers, and answers it with the job's session and caps; 204 for none. |
POST /creator/jobs/:id/heartbeat {attempt, step?, spent?} | the runners' secret, direct | Renews the lease, says the step and the spend so far; answers whether to stop. |
POST /creator/jobs/:id/finish {attempt, state, cost, summary?, error?, system?, transcript?} | the runners' secret, direct | Ends the job: done or failed (system: no fault of the brief, its creation given back), what it spent, its conversation; what the model wrote checked first. |
GET /moderation/creations?game=<g-…> | a moderator or an admin | A reported game's creations (its draft's), with their ids, owners and how they ended. |
GET /moderation/creations/:id/transcript | a moderator or an admin | A creation (its brief, how it ended, its owner) and its transcript while it is kept. |