@seriousgaming/sdk-tools 0.0.0-stage → 1.0.0-alpha.2

package/dist/docs/guides/endpoints.md

@@ -0,0 +1,335 @@
+# Endpoints
+
+An endpoint is a named, server-side handler that a caller invokes by identifier: one of the game's own user interfaces, or a caller outside the game, such as a facilitator's AI agent or a platform API, when the endpoint allows it. It is how a caller runs code you wrote: you own the request and response shapes, the runtime validates both, and the handler works strictly within the bounds it declares.
+
+## The model
+
+### Why endpoints exist
+
+A user interface runs in an iframe the runtime does not trust. Handing it `generateText`, `extractText` or `generateSpeech` directly would let a hijacked or buggy iframe send any prompt it liked, draining quota and producing unaudited LLM traffic. So a UI reaches those services only through an endpoint, which shrinks what can happen from 'whatever prompt the iframe can construct' to 'whatever prompts you have written'.
+
+The caller passes structured parameters, and the handler builds the prompt and shapes the answer. Anything the caller sends outside `requestSchema` is refused before the handler runs, and anything the handler returns outside `responseSchema` is refused before it reaches the caller.
+
+The same holds for state. An endpoint changes nothing it has not declared: it writes only the capabilities in its `writes`, and carries out only the session operations in its `actions`.
+
+### Anatomy
+
+```
+endpoints/summarise_report/
+├── endpoint.sdk.json     # Request and response schemas, reads, writes, uses
+├── logic/
+│   ├── logic.ts          # Exports Handle, or Plan and Respond
+│   └── logic.test.ts
+└── types.ts              # Generated: Request, Response, Context, Handler
+```
+
+The endpoint's identifier is its directory name and is never authored. `endpoint.sdk.json` declares:
+
+| Field                        | Required                      | What it says                                                                                                                         |
+| ---------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `requestSchema`              | Yes                           | The request, as a full JSON Schema 7 object                                                                                          |
+| `responseSchema`             | Yes                           | The response, as a full JSON Schema 7 object                                                                                         |
+| `displayName`, `description` | `description` when `external` | What the endpoint does, for author-time tools and, when external, for an outside caller to read                                      |
+| `scope`                      | No, defaults to `team`        | Whether the call acts on one team or the session ([Scope](#scope))                                                                   |
+| `reads`                      | No                            | The capabilities the handler sees                                                                                                    |
+| `writes`                     | No                            | The capabilities the handler may change ([Changing state](#changing-state))                                                          |
+| `uses`                       | No                            | The gated callbacks the handler may call ([Declare the APIs a resource uses](./llm-integration.md#declare-the-apis-a-resource-uses)) |
+| `settings`                   | No                            | The [settings resources](./settings.md) the handler reads                                                                            |
+| `actions`                    | No                            | The session operations it may return ([Acting on the session](#acting-on-the-session))                                               |
+| `roster`                     | No, defaults to `false`       | Whether `session` lists each team's participants                                                                                     |
+| `visibility`                 | No, defaults to `internal`    | Who may call it ([Calling from outside the game](#calling-from-outside-the-game))                                                    |
+
+To scaffold one, follow [Create an endpoint](../recipes/create-endpoint.md).
+
+## Scope
+
+`scope` says what a call acts on. A team-scoped endpoint receives that team's board and a `team` naming it (`teamId`, `index` and `name`), whoever calls it. A session-scoped one has neither, because there is no single team for them to mean anything against.
+
+The surface calling an endpoint has to be able to supply what its scope needs. A session UI, setup screen or scenario editor has no team of its own, so one that calls a team-scoped endpoint fails the build, which tells you to declare the endpoint `"scope": "session"`.
+
+The scenario editor has no session either, so an endpoint it lists may declare no `reads`, `writes` or `actions`, and the build fails with `EDITOR_ENDPOINT_STATEFUL` if it does. See [Calls from the scenario editor](#calls-from-the-scenario-editor).
+
+Do not put a team in a request schema. A caller outside the game names the team it means through the platform, which hands it to your handler on `team`, so a team the caller typed can never be a team it invented.
+
+### What each scope may write
+
+| Endpoint `scope`     | May write                                                                            | Must not write |
+| -------------------- | ------------------------------------------------------------------------------------ | -------------- |
+| `team` (the default) | `team`, `team-readable` and `private` capabilities, under `capabilities`             | `shared`       |
+| `session`            | `shared` capabilities under `capabilities`; any other scope, per team, under `teams` | Nothing        |
+
+The build fails when a team-scoped endpoint writes a shared capability, naming both. A team-scoped endpoint has one board, and a shared capability does not live on a board, so the write would have nowhere to go. To change one team, call a team-scoped endpoint against it.
+
+A session-scoped endpoint's `capabilities` go to the shared store and reach every team at once, exactly as a facilitator's shared write does. Its own `writes` array is what authorises the write, which matters because a caller outside the game has no bundle to borrow permission from.
+
+A session-scoped endpoint has no board of its own, so it names the boards it changes. Its per-team writes go under `teams`, keyed by team id, and every team changes or none does:
+
+```typescript
+export const Handle: Handler = async ({ request, teams }) => ({
+    response: { granted: request.workers },
+    teams: Object.fromEntries(
+        (teams ?? []).map((team) => [
+            team.teamId,
+            { workers: { WorkerCount: team.context.workers.WorkerCount + request.workers } },
+        ])
+    ),
+});
+```
+
+'Give every team two more workers' is then one call rather than one per team, each able to fail on its own.
+
+### What a session-scoped endpoint reads
+
+With no board of its own, a session-scoped endpoint receives its declared capabilities split by their scope:
+
+- A `shared` capability arrives on `context`, as the single value it is
+- A `team`, `team-readable` or `private` capability arrives on `teams`, one entry per team in stable index order
+
+```typescript
+export const Handle: Handler = async ({ context, teams }) => ({
+    average: context.market.AveragePrice, // shared: one value
+    behind: (teams ?? [])
+        .filter((team) => team.context.decisions.Price > context.market.AveragePrice)
+        .map((team) => team.name),
+});
+```
+
+Each entry carries `teamId`, `index`, `name` and that team's `context`. The generated `types.ts` splits to match, so `Context` holds only what genuinely has one value and `TeamContext` holds the rest.
+
+**Read wide, answer narrow.** Assembling every team's board is the cheapest shape the SDK has for a cross-team question: it is pulled when the caller asks rather than pushed on every write, and it goes to one caller rather than to every participant's screen. The answer still crosses back to the caller, though, and at a hundred teams a raw dump of every board is both slow and useless to a model. Summarise in the handler, and declare the narrowest `reads` that answer the request.
+
+## Writing the handler
+
+```typescript
+import type { Handler } from '../types';
+
+export const Handle: Handler = async ({ request, context, settings, callbacks, caller, meta }) => {
+    return { summary: '...' };
+};
+```
+
+The handler receives:
+
+- `request`: validated against `requestSchema` before the handler runs
+- `context`: the capabilities listed in `reads` and `writes`, and nothing else. On a session-scoped endpoint, only the shared ones (see above)
+- `team`: on a team-scoped endpoint, the team the call acts on. `teams`: on a session-scoped one, every team's declared values
+- `settings`: exactly the settings resources listed in `settings`, keyed by identifier, read-only
+- `callbacks`: the callbacks named in `uses`, plus the ungated `readAsset` and `getPastState`. An undeclared gated callback throws
+- `caller`: who is calling, issued by the host and never by the iframe (see below)
+- `meta`: the facts true of the whole run: `meta.locale` (the session locale), `meta.seed`, `meta.runKind` and `meta.now`, the instant the call started
+- `participants`: a read-only copy of the roster the call covers, the addressed team's on a team-scoped endpoint and every participant on a session-scoped one
+- `session`: where the session stands ([Acting on the session](#acting-on-the-session))
+
+`caller` carries `role`, and, where they apply, `sessionId`, `teamId`, `playerId`, `userInterfaceIdentifier` and `principal`. `sessionId` is absent only on a call from the scenario editor, which has no session. `role` is `'participant'`, `'observer'`, `'facilitator'`, `'author'` or `'external'`: a session UI and a setup screen report `'facilitator'`, a scenario editor reports `'author'`, and a caller outside the game reports `'external'` with no `userInterfaceIdentifier`. An author is whoever is creating a scenario, who on the platform may not be a facilitator, so an endpoint that trusts a facilitator further than other callers should not extend that to an author. `principal` is the platform's account of which agent or API key made an external call, so an endpoint can answer one caller differently from another.
+
+`caller.teamId` is the caller's own team, set for a participant or an observer and absent for a facilitator, an author or an outside caller. It is not the team the call acts on: read that from `team`. A facilitator calling a team-scoped endpoint has `team` and no `caller.teamId`; a participant has both, and they are equal.
+
+### Calls from the scenario editor
+
+The scenario editor edits a scenario rather than a session, and runs whether or not one exists, so an endpoint it calls is answered with no session, even in a dev server running one beside it:
+
+- `settings`: the settings the endpoint declares, as the scenario being edited resolves them, with the editor's unsaved changes over it. An assistant advising on a draft sees the draft, so declare `settings` rather than passing the values in the request
+- `context`: empty, with no `team` or `teams`
+- `participants`: empty
+- `session`: the game's `mode` and the scenario's tick limit, with nothing played and no teams
+- `caller`: `role: 'author'` and `userInterfaceIdentifier: 'scenario_editor'`, with no `sessionId`, `teamId` or `playerId`
+
+The full argument and result types are in the API reference: [`EndpointBaseArgs`](../api/sdk.md#endpointbaseargs), [`EndpointCaller`](../api/sdk.md#endpointcaller) and [`EndpointSession`](../api/sdk.md#endpointsession).
+
+### Changing state
+
+An endpoint that declares no `writes` cannot change state at all, and returns its response bare. One that declares `writes` returns its response and its change together, and its generated `Handler` type says so:
+
+```typescript
+export const Handle: Handler = async ({ request, context }) => ({
+    response: { previous: context.price.Price, current: request.price },
+    capabilities: { price: { ...context.price, Price: request.price } },
+});
+```
+
+The two are separate because they are held to different contracts. `response` is validated against `responseSchema`. `capabilities` is held to `writes`, and naming a capability outside that set is a fault rather than a silent drop, because the alternative leaves the response describing a change the board never received. Any other top-level key is refused, and so is a writing endpoint that returns a bare value.
+
+To remove a key, such as one entry of a map, name its path in `deletes` beside `capabilities`. It is removed from the same board once `capabilities` has merged, and is held to `writes` the same way: a path under a capability the endpoint only reads is an `invalid-response` fault that applies nothing. A session-scoped endpoint's `deletes` remove paths from shared capabilities; its per-team `teams` patches carry no deletes.
+
+```typescript
+export const Handle: Handler = async ({ request, context }) => ({
+    response: { closed: request.orderId },
+    capabilities: { orders: context.orders },
+    deletes: [['orders', 'Open', request.orderId]],
+});
+```
+
+The change goes through the same queue as every other write, and lands on the board the call was made against. It is refused outright if a tick commits while the handler is still running, since it was computed against a board that no longer exists. That is a reason to keep a writing endpoint fast rather than to build a retry loop: a handler that calls a model can easily outlive the tick it was called in.
+
+### Reading past ticks
+
+`callbacks.getPastState` reads any tick that has already closed, projected onto the capabilities the endpoint declared:
+
+```typescript
+const rounds = await callbacks.getPastState<Context>({
+    fromTick: 0,
+    toTick: Number.MAX_SAFE_INTEGER,
+    capabilityIds: ['profit'],
+});
+```
+
+It is not gated by `uses`, because it reads state the endpoint already declared, one tick further back. A team-scoped endpoint reads its own team's ticks; a session-scoped one reads every team's.
+
+A range that runs past the last completed tick comes back short rather than failing, so treat a short result as normal. Before the first tick there is nothing to read and the answer is empty.
+
+The same callback reaches your engine, hooks and tick controller. That lets a game stop keeping a capability purely to carry last tick's figure forward: a value in context rides every push to every participant for the rest of the session, and the snapshot it was copied from is already recorded.
+
+## Acting on the session
+
+An endpoint that declares `actions` can return session operations beside its response, and the runtime carries them out after its write:
+
+```json
+"actions": ["setWaitingRoom", "tick"]
+```
+
+```typescript
+export const Handle: Handler = async ({ session }) => {
+    if (session.complete) throw new Error('The game is complete');
+    return {
+        response: { fromRound: session.completedTicks },
+        actions: [
+            ...(session.waitingRoomOpen ? [{ type: 'setWaitingRoom' as const, open: false }] : []),
+            { type: 'tick' },
+        ],
+    };
+};
+```
+
+The actions are the facilitator's own operations, held to the same rules as when the session UI performs them: `tick`, `pauseTimer`, `resumeTimer`, `extendTick`, `setWaitingRoom`, `renameTeam`, `addTeam`, `moveParticipant` and `setLocale` (see [`EndpointAction`](../api/sdk.md#endpointaction) for each one's fields). A `teamId` left off means the call's own team on a team-scoped endpoint, and the whole session on a session-scoped one.
+
+The runtime applies the write, the per-team writes and the actions as one step, so nothing else lands in between, and it checks everything it can before applying anything. A step that can only fail once applied, such as a tick the engine fails, stops the sequence there: what came before it stays applied, and the caller is told which step failed.
+
+Anyone who can call the endpoint can trigger its actions: a participant's game UI as well as the session UI. That is how a game lets a participant end their own turn under its own rules. An endpoint that should act only for the facilitator checks `caller.role` and refuses the rest.
+
+`session` tells the handler where things stand when it is called: the ticks completed (`completedTicks`), the tick limit (`maxTicks`), whether the waiting room is open, whether the game is complete, and each team's `completedTicks`, completion and timer (a [`TimerState`](../api/sdk.md#timerstate), or `null` without a tick controller). Declare `roster: true` to have each team's participants listed as well. That list grows with the cohort, which is why it is off by default.
+
+### Reporting what the actions did
+
+`Handle` runs before any of its effects land, so its response cannot say what they did: an endpoint that ticks cannot name the round it started. When that matters, answer in two phases. Export `Plan` in place of `Handle`, returning the effects alone, and `Respond`, which writes the response once they have landed:
+
+```typescript
+import type { Planner, Responder } from '../types';
+
+export const Plan: Planner = async ({ session }) => ({
+    actions: [{ type: 'tick' }],
+});
+
+export const Respond: Responder = async ({ session, plan, outcomes }) => ({
+    round: session.completedTicks, // read after the tick
+});
+```
+
+`Handle` always returns the response, `Plan` never does, and the build refuses any other mix of the three. `Respond` receives the same arguments as `Plan`, read afresh, plus `plan` (what `Plan` returned) and `outcomes` (what each action came to, such as the tick a `tick` committed). It changes nothing. It runs outside the session's queue, so a slow one, such as one that calls a model, holds up nobody else's writes, and the state it sees is the state when it runs. `meta.now` is the same for both phases.
+
+If `Respond` fails, the effects have still landed, and the caller is told so. See [Act on the session from an endpoint](../recipes/act-on-the-session-from-an-endpoint.md).
+
+## Files in and out
+
+A request field can be a file. Mark a string property with `blob`, saying which types it takes and how large:
+
+```json
+"document": {
+    "type": "string",
+    "description": "The research, as a PDF.",
+    "blob": { "accept": ["application/pdf"], "maxBytes": 5242880 }
+}
+```
+
+The handler always receives a `blob:` reference, typed `` `blob:${string}` ``, already checked against the declaration. It reads the file with `callbacks.readAsset`, passes it to `extractText`, or stores the reference in a capability for a screen to show with `getAssetUrl`.
+
+The caller sends one of two things:
+
+- **A `blob:` reference**, for a file it has already uploaded. A game UI gets one from `uploadBlob`; a script or an agent gets one from the platform's upload route (locally, `POST /api/blobs` or `pnpm run sdk blob upload`)
+- **A `data:` URI**, such as `data:application/pdf;name=research.pdf;base64,...`, carrying the file inline in the one call. Good for small files: a model writing base64 spends its context on it, so past a few megabytes, upload first
+
+The runtime refuses anything else before your handler runs: a type the field does not take, bytes that are not the type they claim, a file over the size, a reference to a blob that does not exist, and a URL. See [Take a file in an endpoint](../recipes/take-a-file-in-an-endpoint.md).
+
+Going the other way, an endpoint that produces binary data (audio, an image, a generated document) declares `writeBlob` in `uses` and calls `callbacks.writeBlob(bytes, { name, mimeType })`, which returns a `blob:<id>` reference. It returns the reference in its JSON response, and the UI fetches the bytes with `getAssetUrl` or `readAsset`. A caller outside the game is given a URL to fetch it from. The call itself stays JSON only, so a new kind of binary output needs no protocol change.
+
+## Calling from a UI
+
+A UI's bundle lists the endpoints it may call:
+
+```json
+{
+    "definition": {
+        "endpoints": ["summarise_report"]
+    }
+}
+```
+
+The UI's generated `types.ts` produces a typed `Endpoints` interface and merges it into the UI's `Callbacks` type. Calling an undeclared endpoint is a TypeScript error, and the host refuses the call at run time as a second line of defence.
+
+```typescript
+const { summary } = await callbacks.endpoints['summarise_report']({
+    fileBlobId,
+});
+```
+
+A UI has no `uses` of its own. It reaches `generateText` and the other gated services by calling an endpoint that declares them. See [Call an endpoint from a UI](../recipes/call-endpoint-from-ui.md).
+
+## Calling from outside the game
+
+An endpoint is `internal` unless it says otherwise, and only the game's own user interfaces reach it. Setting `visibility` to `external` publishes it to callers outside the game as well: a facilitator's AI agent, a platform API, or another integration. A caller outside the game is refused an internal endpoint before its request is validated.
+
+```json
+{
+    "definition": {
+        "description": "Sets a team's unit price, in pounds per unit. Use when a facilitator asks to change what a team charges.",
+        "visibility": "external"
+    }
+}
+```
+
+An external endpoint must carry a `description`, because it is what an outside caller, a model most of all, reads to decide whether to call it.
+
+Its `requestSchema` must also be an object at the top, `"type": "object"`, since an outside caller passes its request as named arguments, as an agent passes a tool's input. The build fails with `EXTERNAL_REQUEST_NOT_OBJECT` on a bare string, number or array. An external endpoint that takes no input declares an empty object:
+
+```json
+{ "type": "object", "properties": {}, "additionalProperties": false }
+```
+
+An internal endpoint's request may take any shape. Which outside callers may use it, and how they sign in, is up to the platform. An outside caller works against the endpoints of the session it addresses, for that session's life. `pnpm run sdk endpoint call --external` makes a call the way an outside caller does. See [Make an endpoint callable from outside the game](../recipes/make-an-endpoint-external.md) and, for writing descriptions a model can act on, [Structuring a game for AI facilitation](./ai-facilitation.md).
+
+## When a call fails
+
+A failed call is never a bare message, because a caller has to tell a call that changed nothing from one whose writes landed before an action failed. A UI's call rejects with an [`EndpointError`](../api/sdk-ui.md#endpointerror), `pnpm run sdk endpoint call --json` prints the same thing, and a `createTestSession` call answers `{ type: 'endpointFailure', failure }`. Each carries:
+
+- `outcome`: why, as `outcome.kind` and usually `outcome.message`. The kinds are those of a refused write (`denied`, `conflict`, `tick-failed` and the rest) plus three only an endpoint has: `invalid-request` (the request failed `requestSchema`, so the handler did not run), `handler-error` (the handler threw or overran its time limit), and `invalid-response` (what it returned broke its declaration)
+- `applied`: the steps that committed before the failure, in order: `{ kind: 'capabilities' }`, `{ kind: 'teams', teamId }`, or `{ kind: 'action', index, type }`. Empty when nothing changed
+- `failedStep`: the step that failed, when one failed once applied
+
+Most failures happen before anything is applied: a refusal, a bad request, a handler that throws, an undeclared write or action, or a round starting while the handler ran. Only two leave `applied` non-empty: an action that fails once applied (a `tick` on a game that has just completed, say), and `Respond` failing after the effects landed. See [Call an endpoint from a UI](../recipes/call-endpoint-from-ui.md) for handling one.
+
+## Endpoints and validators
+
+An endpoint's write, and its actions, are not put to the game's [validators](./validators.md), whoever called it, including a participant's own game UI.
+
+This is deliberate rather than a gap. A validator exists so a game can refuse a change a participant submits **directly**, the one route where the game has no code in the path. An endpoint is the game's code in the path, and checks its own request before it writes.
+
+Keeping the two apart buys something. A validator can refuse a change outright while a strict endpoint remains the one sanctioned way to make it:
+
+- The validator refuses any direct write to `price` from a participant
+- An endpoint sets `price`, having checked whatever conditions you decide
+
+The rule lives in the validator, the one sanctioned exception lives in the endpoint, and no participant can reach the exception except through the code you wrote.
+
+## The language environment
+
+Endpoints run in the same language environment as the engine: the ECMAScript intrinsics, plus the `console` shim and byte helpers the SDK compiles into the bundle (see [the language environment your logic runs in](./engine.md#the-language-environment-your-logic-runs-in)). `process`, `fs`, `fetch`, timers and the other host globals are absent, and the dev server evaluates logic in a bare V8 context, so reaching for one throws in dev exactly as it does in production. Importing a Node built-in (`node:fs`, `crypto`, `path` and the rest) is refused when the endpoint is built or loaded, with `LOGIC_NODE_BUILTIN` naming the file and the import.
+
+## Related
+
+- [Create an endpoint](../recipes/create-endpoint.md)
+- [Call an endpoint from a UI](../recipes/call-endpoint-from-ui.md)
+- [Act on the session from an endpoint](../recipes/act-on-the-session-from-an-endpoint.md)
+- [Take a file in an endpoint](../recipes/take-a-file-in-an-endpoint.md)
+- [Make an endpoint callable from outside the game](../recipes/make-an-endpoint-external.md)
+- [Declare API uses](../recipes/declare-api-uses.md)
+- [Structuring a game for AI facilitation](./ai-facilitation.md)
+- [Capabilities](./capabilities.md)