@playerthree/console

@playerthree/console: the player console. A headless client over the game's player API (the owner's own seats only: status, mandate, scopes, limits, approvals, recent intents and ack codes, policy errors and logs, practice, observation size and token estimate) plus an optional drop-in panel. Browser-safe: no Node built-ins.

Classes

PlayerConsole

Defined in: packages/console/src/client.ts:295

Headless player-console client: polls /state, follows /stream while a match runs and publishes ConsoleSnapshots.

Constructors

Constructor

new PlayerConsole(opts): PlayerConsole;

Defined in: packages/console/src/client.ts:320

Parameters

Parameter	Type
`opts`	`PlayerConsoleOptions`

Returns

PlayerConsole

Accessors

snapshot

Get Signature

get snapshot(): ConsoleSnapshot;

Defined in: packages/console/src/client.ts:338

The latest normalized snapshot.

Returns

ConsoleSnapshot

started

Get Signature

get started(): boolean;

Defined in: packages/console/src/client.ts:363

Returns

boolean

Methods

refresh()

refresh(): Promise<void>;

Defined in: packages/console/src/client.ts:368

Fetch /state now.

Returns

Promise<void>

start()

start(): void;

Defined in: packages/console/src/client.ts:349

Start polling (and streaming while a match runs). Idempotent.

Returns

void

stop()

stop(): void;

Defined in: packages/console/src/client.ts:357

Stop all network activity; the last snapshot stays readable.

Returns

void

subscribe(listener): () => void;

Defined in: packages/console/src/client.ts:343

Called with every new snapshot. Returns unsubscribe.

Parameters

Parameter	Type
`listener`	`Listener`

Returns

() => void

Interfaces

CommanderInfo

Defined in: packages/console/src/client.ts:41

An owner's persistent commander (owner credential only).

Properties

Property	Type	Defined in
`approvals`	`object`[]	packages/console/src/client.ts:54
`botLevel`	`string`	packages/console/src/client.ts:48
`connected`	`boolean`	packages/console/src/client.ts:55
`id`	`string`	packages/console/src/client.ts:42
`isolation`	`object`	packages/console/src/client.ts:46
`isolation.independentSessions`	`boolean`	packages/console/src/client.ts:46
`kind`	`"policy"` \| `"agent"`	packages/console/src/client.ts:44
`lastPractice`	\| { `allies`: `string`; `at`: `number`; `opponent`: `string`; `outcome`: `Outcome`; `report`: `unknown`; `role`: `string`; `seed`: `number`; `ticks`: `number`; `version`: `number`; } \| `null`	packages/console/src/client.ts:53
`lastSeenAt`	`number` \| `null`	packages/console/src/client.ts:56
`mandate`	`Mandate`	packages/console/src/client.ts:50
`metadata?`	`object`	packages/console/src/client.ts:47
`metadata.model?`	`string`	packages/console/src/client.ts:47
`metadata.provider?`	`string`	packages/console/src/client.ts:47
`metadata.scaffoldVersion?`	`string`	packages/console/src/client.ts:47
`name`	`string`	packages/console/src/client.ts:43
`policy`	`object`	packages/console/src/client.ts:51
`policy.activeByRole`	`Record`<`string`, `number` \| `null`>	packages/console/src/client.ts:51
`policy.versions`	`object`[]	packages/console/src/client.ts:51
`record`	`object`	packages/console/src/client.ts:52
`record.draws`	`number`	packages/console/src/client.ts:52
`record.losses`	`number`	packages/console/src/client.ts:52
`record.wins`	`number`	packages/console/src/client.ts:52
`reservations`	`object`[]	packages/console/src/client.ts:58
`roles`	`string`[]	packages/console/src/client.ts:45
`scopes`	(`"act"` \| `"policy"` \| `"practice"` \| `"publish"` \| `"say"`)[]	packages/console/src/client.ts:49
`seated`	\| { `match`: `string`; `roles`: `string`[]; `team`: `string`; } \| `null`	packages/console/src/client.ts:57

ConsoleIntent

Defined in: packages/console/src/client.ts:94

Properties

Property	Type	Description	Defined in
`ack`	`IntentAck`	-	packages/console/src/client.ts:101
`at`	`number`	-	packages/console/src/client.ts:95
`code`	`string`	`ok`, or the closed rejection code (a game code for `game` rejections). See ackCode.	packages/console/src/client.ts:103
`kind`	`string` \| `null`	The intent kind when it passed schema validation (rejected input is never stored).	packages/console/src/client.ts:100
`source`	`string`	Who produced it: `agent`, `policy`, `bot`, `owner` or `stream`.	packages/console/src/client.ts:98
`tick`	`number`	-	packages/console/src/client.ts:96

ConsoleObservation

Defined in: packages/console/src/client.ts:131

Properties

Property	Type	Description	Defined in
`at`	`number`	-	packages/console/src/client.ts:132
`bytes`	`number`	UTF-8 JSON bytes of the guarded observation the seat's agent last received.	packages/console/src/client.ts:135
`cost`	`number` \| `null`	Estimated cost of reading it once, in the price option's currency; null without a price.	packages/console/src/client.ts:139
`tick`	`number`	-	packages/console/src/client.ts:133
`tokens`	`number`	Estimated input tokens (`ceil(bytes / bytesPerToken)`).	packages/console/src/client.ts:137

ConsolePanel

Defined in: packages/console/src/panel.ts:45

A mounted panel.

Properties

Property	Modifier	Type	Defined in
`el`	`readonly`	`HTMLElement`	packages/console/src/panel.ts:46
`isOpen`	`readonly`	`boolean`	packages/console/src/panel.ts:47

Methods

close()

close(): void;

Defined in: packages/console/src/panel.ts:49

Returns

void

destroy()

destroy(): void;

Defined in: packages/console/src/panel.ts:52

Remove the panel, its key listener and its subscription (stops the client unless pollWhileHidden).

Returns

void

open()

open(): void;

Defined in: packages/console/src/panel.ts:48

Returns

void

toggle()

toggle(): void;

Defined in: packages/console/src/panel.ts:50

Returns

void

ConsolePanelOptions

Defined in: packages/console/src/panel.ts:19

Options of mountConsolePanel.

Properties

Property	Type	Description	Defined in
`actions?`	`object`	Owner actions the panel may offer. Without `resolveApproval`, approvals are shown read-only.	packages/console/src/panel.ts:37
`actions.resolveApproval?`	(`target`, `id`, `approve`) => `Promise`<`void`>	-	packages/console/src/panel.ts:37
`className?`	`string`	Extra class names on the root (theme hooks).	packages/console/src/panel.ts:33
`console`	`PlayerConsole`	-	packages/console/src/panel.ts:20
`currency?`	`string`	Prefix for cost figures (the console's `pricePerMTok` currency), e.g. `$`. Default none.	packages/console/src/panel.ts:41
`mount?`	`HTMLElement`	Where the panel is appended. Default `document.body`.	packages/console/src/panel.ts:22
`onToggle?`	(`open`) => `void`	Called after the panel opens or closes.	packages/console/src/panel.ts:39
`pollWhileHidden?`	`boolean`	Keep the client polling while the panel is hidden. Default false: it runs only while open.	packages/console/src/panel.ts:35
`roleLabel?`	(`role`) => `string`	Display name of a role. Default: the role id.	packages/console/src/panel.ts:31
`title?`	`string`	Panel title. Default `Agent console`.	packages/console/src/panel.ts:29
`toggleKey?`	`string` \| `null`	Toggle key, matched against `KeyboardEvent.code` or `KeyboardEvent.key` (no Ctrl/Alt/Meta, never while typing in a field). Default `Backslash`; null: no keyboard toggle (call `toggle()` yourself).	packages/console/src/panel.ts:27

ConsolePolicy

Defined in: packages/console/src/client.ts:142

Properties

Property	Type	Description	Defined in
`calls?`	`number`	-	packages/console/src/client.ts:146
`errors?`	`number`	-	packages/console/src/client.ts:147
`intentsEmitted?`	`number`	-	packages/console/src/client.ts:151
`intentsRejected?`	`object`[]	-	packages/console/src/client.ts:152
`maxMs?`	`number`	-	packages/console/src/client.ts:150
`meanMs?`	`number`	-	packages/console/src/client.ts:149
`runtime?`	`string`	-	packages/console/src/client.ts:145
`timeouts?`	`number`	-	packages/console/src/client.ts:148
`version`	`number` \| `null`	Version playing in the live seat (or the active library version in the lobby); null: none.	packages/console/src/client.ts:144
`versions?`	`number`	Library versions (owner credential).	packages/console/src/client.ts:154

ConsolePolicyError

Defined in: packages/console/src/client.ts:106

Properties

Property	Type	Description	Defined in
`at`	`number`	-	packages/console/src/client.ts:107
`code`	`PolicyErrorCode`	-	packages/console/src/client.ts:111
`message?`	`string`	Own-authored engine text about the owner's own artifact (plain text).	packages/console/src/client.ts:113
`phase`	`"call"` \| `"deploy"`	A failed deploy/rollback, or a failed policy call at tick rate.	packages/console/src/client.ts:110
`tick`	`number`	-	packages/console/src/client.ts:108
`version?`	`number`	-	packages/console/src/client.ts:114

ConsolePractice

Defined in: packages/console/src/client.ts:117

Properties

Property	Type	Description	Defined in
`at`	`number`	-	packages/console/src/client.ts:118
`code?`	`"policy"` \| `"guard"`	-	packages/console/src/client.ts:126
`opponent`	`string`	-	packages/console/src/client.ts:121
`outcome`	`Outcome` \| `null`	Null when the run failed (`code`).	packages/console/src/client.ts:125
`role`	`string`	Compatible role selected for this practice run, not the commander's roster identity.	packages/console/src/client.ts:120
`seed`	`number`	-	packages/console/src/client.ts:123
`ticks`	`number`	-	packages/console/src/client.ts:122
`version?`	`number`	Policy version that played, when known.	packages/console/src/client.ts:128

ConsoleSeat

Defined in: packages/console/src/client.ts:157

Properties

Property	Type	Description	Defined in
`approvals`	`object`[]	Pending proposals, role-labelled; live consoles include only their exact selected lane.	packages/console/src/client.ts:184
`commander`	`string` \| `null`	Persistent roster identity, or null for a human/private-team seat console.	packages/console/src/client.ts:159
`controller`	`"human"` \| `"policy"` \| `"agent"` \| `"bot"` \| `"none"`	Runtime controller in a match; commander execution kind in the lobby.	packages/console/src/client.ts:168
`errors`	`ConsolePolicyError`[]	Newest first.	packages/console/src/client.ts:193
`intents`	`ConsoleIntent`[]	Newest first.	packages/console/src/client.ts:189
`lastSeenAt`	`number` \| `null`	Last agent call (owner credential), ms since epoch.	packages/console/src/client.ts:178
`limits`	`Record`<`string`, `unknown`> \| `null`	`mandate.limits` (house rules the game enforces).	packages/console/src/client.ts:182
`live`	`boolean`	True while a live match seats it.	packages/console/src/client.ts:170
`logs`	`string`[]	Policy `log()` tail (own-authored text; render as plain text).	packages/console/src/client.ts:187
`mandate`	`Mandate` \| `null`	-	packages/console/src/client.ts:179
`name`	`string` \| `null`	-	packages/console/src/client.ts:160
`observation`	`ConsoleObservation` \| `null`	-	packages/console/src/client.ts:196
`paused`	`boolean`	This seat holds a pausable session still while its agent is away (`whenAbsent: 'pause'`).	packages/console/src/client.ts:176
`policy`	`ConsolePolicy` \| `null`	-	packages/console/src/client.ts:185
`practice`	`ConsolePractice`[]	Newest first.	packages/console/src/client.ts:195
`present`	`boolean`	The seat's agent is active now (a recent or in-flight call, or a running sequence).	packages/console/src/client.ts:174
`readiness`	`ConsoleReadiness` \| `null`	Exact live preparation/probe/consent state; null for a reusable lobby connection.	packages/console/src/client.ts:172
`rejections`	`object`[]	Rejected intents among `intents`, by code, most frequent first.	packages/console/src/client.ts:191
`role`	`string` \| `null`	Exact runtime role, null for a reusable lobby commander.	packages/console/src/client.ts:164
`roles`	`string`[]	All compatible roles in the lobby; no arbitrary primary role is selected.	packages/console/src/client.ts:162
`scopes`	(`"act"` \| `"policy"` \| `"practice"` \| `"publish"` \| `"say"`)[]	-	packages/console/src/client.ts:180
`target`	`ConsoleActionTarget`	-	packages/console/src/client.ts:166
`team`	`string` \| `null`	-	packages/console/src/client.ts:165

ConsoleSnapshot

Defined in: packages/console/src/client.ts:203

One normalized view of the owner's own seats, rebuilt on every refresh and live trace event.

Properties

Property	Type	Description	Defined in
`error`	`string` \| `null`	Closed code when `status` is `error`: the API's `{ error }` (`bad_token`, `forbidden`…), `http_<n>` or `network`.	packages/console/src/client.ts:206
`estimate`	`object`	-	packages/console/src/client.ts:217
`estimate.bytesPerToken`	`number`	-	packages/console/src/client.ts:217
`estimate.pricePerMTok`	`number` \| `null`	-	packages/console/src/client.ts:217
`game`	\| { `id`: `string`; `tickRate`: `number`; `title`: `string`; `version`: `string`; } \| `null`	-	packages/console/src/client.ts:207
`match`	`string` \| `null`	-	packages/console/src/client.ts:210
`outcome`	`Outcome` \| `null`	-	packages/console/src/client.ts:213
`phase`	`"match"` \| `"lobby"`	`match` for an explicitly selected live lane or live owner capability, otherwise `lobby`.	packages/console/src/client.ts:209
`seats`	`ConsoleSeat`[]	-	packages/console/src/client.ts:216
`status`	`ConsoleStatus`	-	packages/console/src/client.ts:204
`streaming`	`boolean`	The live trace stream is connected.	packages/console/src/client.ts:215
`team`	`string` \| `null`	-	packages/console/src/client.ts:211
`tick`	`number`	-	packages/console/src/client.ts:212
`updatedAt`	`number`	ms since epoch of the last successful refresh; 0 before the first.	packages/console/src/client.ts:219

PlayerConsoleOptions

Defined in: packages/console/src/client.ts:223

Options of PlayerConsole.

Properties

Property	Type	Description	Defined in
`bytesPerToken?`	`number`	Bytes per token for the estimate. Default 4 (a rough average for JSON; real tokenizers vary by model).	packages/console/src/client.ts:240
`credential`	`string` \| (() => `string` \| `undefined`)	The game's authenticated profile credential, a live exact-seat human capability, or a trusted private team capability. Profile identity comes only from the host's `owner` resolver. Read before every request.	packages/console/src/client.ts:228
`fetch?`	{ (`input`, `init?`): `Promise`<`Response`>; (`input`, `init?`): `Promise`<`Response`>; }	`fetch` implementation (tests, custom transports). Default the global `fetch`.	packages/console/src/client.ts:244
`maxIntents?`	`number`	Recent intents kept per seat. Default 50.	packages/console/src/client.ts:242
`pollMs?`	`number`	`/state` refresh interval, ms (≥ 250). Default 2000.	packages/console/src/client.ts:234
`pricePerMTok?`	`number`	Price per million input tokens for the observation cost estimate (any currency). Default: no cost shown.	packages/console/src/client.ts:238
`stream?`	`boolean`	Follow `/stream` for live intents and observations while a match runs. Default true.	packages/console/src/client.ts:236
`target?`	\| `PlayerConsoleTarget` \| (() => `PlayerConsoleTarget` \| `undefined`)	Explicit live commander lane; undefined keeps profile authentication in roster-only mode.	packages/console/src/client.ts:232
`url?`	`string`	Player API base URL. Default `/playerthree/player`.	packages/console/src/client.ts:230

PlayerConsoleTarget

Defined in: packages/console/src/client.ts:62

Profile-authenticated live selection, checked against the current commander lease by the host.

Properties

Property	Type	Defined in
`commander`	`string`	packages/console/src/client.ts:63
`match`	`string`	packages/console/src/client.ts:64
`role`	`string`	packages/console/src/client.ts:66
`team`	`string`	packages/console/src/client.ts:65

PlayerStateWire

Defined in: packages/console/src/client.ts:75

GET <url>/state as the player API sends it.

Properties

Property	Type	Defined in
`calls`	`Record`<`string`, `PlayerTraceEvent`[]>	packages/console/src/client.ts:86
`commanders?`	`CommanderInfo`[]	packages/console/src/client.ts:89
`events`	`PlayerTraceEvent`[]	packages/console/src/client.ts:88
`game`	`object`	packages/console/src/client.ts:76
`game.id`	`string`	packages/console/src/client.ts:76
`game.policy`	`unknown`	packages/console/src/client.ts:76
`game.tickRate`	`number`	packages/console/src/client.ts:76
`game.title`	`string`	packages/console/src/client.ts:76
`game.version`	`string`	packages/console/src/client.ts:76
`match`	`string` \| `null`	packages/console/src/client.ts:77
`observations`	`Record`<`string`, `PlayerTraceEvent`>	packages/console/src/client.ts:84
`outcome`	`Outcome` \| `null`	packages/console/src/client.ts:81
`policies`	`Record`<`string`, `PolicyStatus` \| `null`>	packages/console/src/client.ts:85
`practice`	`PlayerTraceEvent`[]	packages/console/src/client.ts:87
`readiness`	`Record`<`string`, `ConsoleReadiness`>	packages/console/src/client.ts:83
`seats`	`SeatInfo`[]	packages/console/src/client.ts:82
`target`	`PlayerConsoleTarget` \| `null`	packages/console/src/client.ts:79
`team`	`string` \| `null`	packages/console/src/client.ts:78
`tick`	`number`	packages/console/src/client.ts:80

Type Aliases

ConsoleActionTarget

type ConsoleActionTarget = 
  | {
  commander: string;
  kind: "commander";
  seat?: {
     match: string;
     role: string;
     team: string;
  };
}
  | {
  kind: "seat";
  match: string;
  role: string;
  team: string;
};

Defined in: packages/console/src/client.ts:70

Approval routing never conflates a reusable commander with a live human seat.

ConsoleReadiness

type ConsoleReadiness = 
  | "ready"
  | "online"
  | "waiting"
  | "absent"
  | "stale_policy"
  | "policy_failed"
  | "consent_required";

Defined in: packages/console/src/client.ts:18

ConsoleStatus

type ConsoleStatus = "idle" | "connecting" | "live" | "error";

Defined in: packages/console/src/client.ts:200

Client state: live after a successful refresh, error after a failed one (see ConsoleSnapshot.error).

Controller

type Controller = SeatInfo["controller"];

Defined in: packages/console/src/client.ts:16

Outcome

type Outcome = "win" | "loss" | "draw" | "running";

Defined in: packages/console/src/client.ts:17

PlayerTraceEvent

type PlayerTraceEvent = 
  | SeatTrace & object
  | SeatTrace & object
  | SeatTrace & object
  | SeatTrace & object
  | SeatTrace & object;

Defined in: packages/console/src/client.ts:33

The trace events the console reads (the API may send others; they are ignored).

SeatInfo

type SeatInfo = Extract<ServerMsg, {
  op: "seats";
}>["seats"][number];

Defined in: packages/console/src/client.ts:15

One seat as the host reports it (playerthree SeatInfo).

Functions

ackCode()

function ackCode(ack): string;

Defined in: packages/console/src/client.ts:248

Closed rejection code of an ack: ok, the ack code, or the game's code for game rejections.

Parameters

Parameter	Type
`ack`	`IntentAck`

Returns

string

createPlayerConsole()

function createPlayerConsole(opts): PlayerConsole;

Defined in: packages/console/src/client.ts:654

Creates a stopped PlayerConsole; call start().

Parameters

Parameter	Type
`opts`	`PlayerConsoleOptions`

Returns

PlayerConsole

estimateTokens()

function estimateTokens(bytes, bytesPerToken?): number;

Defined in: packages/console/src/client.ts:254

Input tokens for bytes of JSON at bytesPerToken (default 4): an estimate, not a tokenizer.

Parameters

Parameter	Type	Default value
`bytes`	`number`	`undefined`
`bytesPerToken?`	`number`	`4`

Returns

number

mergeTrace()

function mergeTrace(snapshot, live): PlayerTraceEvent[];

Defined in: packages/console/src/client.ts:265

Server snapshot ∪ live events received since the snapshot was requested. Everything received before the request is in the snapshot; an event in both is counted once per occurrence (identical events can legitimately repeat).

Parameters

Parameter	Type
`snapshot`	readonly `PlayerTraceEvent`[]
`live`	readonly `PlayerTraceEvent`[]

Returns

PlayerTraceEvent[]

mountConsolePanel()

function mountConsolePanel(opts): ConsolePanel;

Defined in: packages/console/src/panel.ts:129

Mounts the panel (hidden) for opts.console, injecting its stylesheet once per document.

Parameters

Parameter	Type
`opts`	`ConsolePanelOptions`

Returns

ConsolePanel

@playerthree/console#

Classes#

PlayerConsole#

Constructors#

Constructor#

Parameters#

Returns#

Accessors#

snapshot#

Get Signature#

Returns#

started#

Get Signature#

Returns#

Methods#

refresh()#

Returns#

start()#

Returns#

stop()#

Returns#

subscribe()#

Parameters#

Returns#

Interfaces#

CommanderInfo#

Properties#

ConsoleIntent#

Properties#

ConsoleObservation#

Properties#

ConsolePanel#

Properties#

Methods#

close()#

Returns#

destroy()#

Returns#

open()#

Returns#

toggle()#

Returns#

ConsolePanelOptions#

Properties#

ConsolePolicy#

Properties#

ConsolePolicyError#

Properties#

ConsolePractice#

Properties#

ConsoleSeat#

Properties#

ConsoleSnapshot#

Properties#

PlayerConsoleOptions#

Properties#

PlayerConsoleTarget#

Properties#

PlayerStateWire#

Properties#

Type Aliases#

ConsoleActionTarget#

ConsoleReadiness#

ConsoleStatus#

Controller#

Outcome#

PlayerTraceEvent#

SeatInfo#

Functions#

ackCode()#

Parameters#

Returns#

createPlayerConsole()#

Parameters#

Returns#

estimateTokens()#

Parameters#

Returns#

mergeTrace()#

Parameters#

@playerthree/console

Classes

PlayerConsole

Constructors

Constructor

Parameters

Returns

Accessors

snapshot

Get Signature

Returns

started

Get Signature

Returns

Methods

refresh()

Returns

start()

Returns

stop()

Returns

subscribe()

Parameters

Returns

Interfaces

CommanderInfo

Properties

ConsoleIntent

Properties

ConsoleObservation

Properties

ConsolePanel

Properties

Methods

close()

Returns

destroy()

Returns

open()

Returns

toggle()

Returns

ConsolePanelOptions

Properties

ConsolePolicy

Properties

ConsolePolicyError

Properties

ConsolePractice

Properties

ConsoleSeat

Properties

ConsoleSnapshot

Properties

PlayerConsoleOptions

Properties

PlayerConsoleTarget

Properties

PlayerStateWire

Properties

Type Aliases

ConsoleActionTarget

ConsoleReadiness

ConsoleStatus

Controller

Outcome

PlayerTraceEvent

SeatInfo

Functions

ackCode()

Parameters

Returns

createPlayerConsole()

Parameters

Returns

estimateTokens()

Parameters

Returns

mergeTrace()

Parameters