playerthree/devtools#

PlayerThree DevTools — the operator console: one self-contained page on the game server where the game's developers and operators see and control what agents do, in development and in production. Players never get in (see access.ts for the access modes and the threat model); a player's view of their own agents is the separate player API (player.ts).

GET <path> the page (static; no data, no external assets, strict CSP) GET <path>/api/overview game, sessions, active agents, rejections/policy errors (last 15 min) GET <path>/api/sessions sessions the host holds (live and ended) + recent (released) sessions GET <path>/api/sessions/<id>/state one session, every side: seats, observations, policies, recent trace GET <path>/api/sessions/<id>/stream live trace (Server-Sent Events) GET <path>/api/sessions/<id>/view ?perspective=god|side:<team>|seat:<team>/<role> GET <path>/api/sessions/<id>/scrub ?tick=&perspective= (isolated re-simulation; never touches the session) GET <path>/api/sessions/<id>/replay deterministic replay file (download) POST <path>/api/sessions/<id>/end { outcomes: 'draw' | { [team|alliance]: 'win'|'loss'|'draw' } | { [team|alliance]: placement } } GET <path>/api/recent/<id> a released session's record (host.history) GET <path>/api/recent/<id>/scrub ?tick=&perspective= ; GET <path>/api/recent/<id>/replay (download) POST <path>/api/replays upload an exported replay; GET <path>/api/replays/<key>/scrub GET <path>/api/agents ?q=&limit= every owner's commanders and sign-in connections POST <path>/api/agents/rotate { owner, commander } new commander token (the old one stops working) POST <path>/api/agents/revoke { owner, connection } revoke a sign-in connection (needs oauth) GET <path>/api/policies commander libraries, the policy pool, policy error stats POST <path>/api/policies/pool { id, action: 'disable'|'enable'|'unpublish' } GET <path>/api/bench bench result directories (benchResultsDir); GET …/bench/<key>/report POST <path>/api/bench/replay { dir, path } open a bench replay for scrubbing (like an upload) GET <path>/api/safety surfaceHash, modes and limits, scopes, Safety Card, rejection stats GET <path>/api/settings match options schema, host defaults, options per live/recent session

Interfaces#

DevtoolsHandler#

Defined in: packages/playerthree/src/devtools/index.ts:70

A framework-neutral operator console request handler (see createDevtoolsHandler).

Methods#

close()#

close(): void;

Defined in: packages/playerthree/src/devtools/index.ts:74

Unsubscribe from the host and end open streams.

Returns#

void

handle()#

handle(req, res): Promise<boolean>;

Defined in: packages/playerthree/src/devtools/index.ts:72

Handles the request if it is under the mount path; resolves false otherwise (nothing written).

Parameters#

Returns#

Promise<boolean>

DevtoolsOptions#

Defined in: packages/playerthree/src/devtools/index.ts:53

Options of the operator console: mount path, trace history and the access mode (OperatorAccessOptions).

Extends#

• OperatorAccessOptions

Properties#

OperatorAccessOptions#

Defined in: packages/playerthree/src/devtools/access.ts:45

Operator console access: at most one of authorize or operatorToken (production); neither means local.

Extended by#

• DevtoolsOptions

Properties#

PlayerApiHandler#

Defined in: packages/playerthree/src/devtools/player.ts:23

A framework-neutral player API request handler: handle resolves false for requests outside its mount path.

Methods#

close()#

close(): void;

Defined in: packages/playerthree/src/devtools/player.ts:25

Returns#

void

handle()#

handle(req, res): Promise<boolean>;

Defined in: packages/playerthree/src/devtools/player.ts:24

Parameters#

Returns#

Promise<boolean>

PlayerApiOptions#

Defined in: packages/playerthree/src/devtools/player.ts:13

Options of the player API.

Properties#

PlayerConsoleTarget#

Defined in: packages/playerthree/src/devtools/player.ts:29

Profile-authenticated live selection. Every component must match the commander's current execution lease.

Properties#

PlayerState#

Defined in: packages/playerthree/src/devtools/player.ts:37

GET <path>/state; selection uses ?commander=…&match=…&team=…&role=….

Properties#

Type Aliases#

OperatorAccessMode#

type OperatorAccessMode = "local" | "token" | "authorize";

Defined in: packages/playerthree/src/devtools/access.ts:42

The active operator access mode (see the module comment).

Functions#

createDevtoolsHandler()#

function createDevtoolsHandler<M>(typedHost, opts?): DevtoolsHandler;

Defined in: packages/playerthree/src/devtools/index.ts:149

The operator console as a request handler for any node:http stack; mountDevtools wires it into a server.

Type Parameters#

Parameters#

Returns#

DevtoolsHandler

createPlayerApiHandler()#

function createPlayerApiHandler<M>(typedHost, opts?): PlayerApiHandler;

Defined in: packages/playerthree/src/devtools/player.ts:60

The owner-private player API (GET <path>/state, GET <path>/stream) that @playerthree/console reads.

Type Parameters#

Parameters#

Returns#

PlayerApiHandler

mountDevtools()#

function mountDevtools<M>(
   httpServer, 
   host, 
   opts?
): object;

Defined in: packages/playerthree/src/devtools/index.ts:1017

Serve the operator console on an existing node:http server (requests under path never reach other listeners).

Type Parameters#

Parameters#

Returns#

object