playerthree/host#

playerthree/host: the in-process host (createPlayerThreeHost), replays, built-in stores and the JSON series store.

Classes#

SeriesStoreError#

Defined in: packages/playerthree/src/series-store.ts:9

Durable stores reject conflicts and quota failures; callers must stop scheduling on write failure.

Extends#

• Error

Constructors#

Constructor#

new SeriesStoreError(code, message): SeriesStoreError;

Defined in: packages/playerthree/src/series-store.ts:11

Parameters#

Returns#

SeriesStoreError

Overrides#

Error.constructor

Properties#

TokenBucket#

Defined in: packages/playerthree/src/host/util.ts:33

Rate limiter: burst tokens, refilled at perSecond; take() spends one or returns false.

Constructors#

Constructor#

new TokenBucket(perSecond, burst): TokenBucket;

Defined in: packages/playerthree/src/host/util.ts:38

Parameters#

Returns#

TokenBucket

Methods#

take()#

take(): boolean;

Defined in: packages/playerthree/src/host/util.ts:44

Returns#

boolean

Interfaces#

ReplayResult#

Defined in: packages/playerthree/src/host/replay.ts:10

The state a replay re-simulated to: the isolated adapter and the outcomes and pauses at that point.

Type Parameters#

Properties#

Variables#

HISTORY_DEFAULTS#

const HISTORY_DEFAULTS: object;

Defined in: packages/playerthree/src/host/history.ts:14

Default session history bounds (SessionHistoryOptions): 50 sessions, 24 h, 64 MiB of replays.

Type Declaration#

OWNER_RE#

const OWNER_RE: RegExp;

Defined in: packages/playerthree/src/host/store.ts:14

Owner ids the registry accepts (also safe as file names).

VIEW_MAX_BATCH#

const VIEW_MAX_BATCH: 20 = 20;

Defined in: packages/playerthree/src/host/views.ts:12

A reader further behind than this many versions gets one keyframe instead of the deltas it missed.

Functions#

callMethod()#

function callMethod(
   control, 
   method, 
   args
): Promise<unknown>;

Defined in: packages/playerthree/src/host/messages.ts:67

Map a protocol call onto the control plane. args is the method's named-parameter object (the same shape as the MCP tool input): briefing { topic?, page? }, act { intents }, observe { since?, detail? }, wait { seconds, until? }, skill { name, path, offset? }, policyDeploy { runtime, code, include? }, policyRollback { version }, practice = PracticeRequest, others {}.

Parameters#

Returns#

Promise<unknown>

createPlayerThreeHost()#

function createPlayerThreeHost<M>(opts): PlayerThreeHost<M>;

Defined in: packages/playerthree/src/host/host.ts:27

Create the in-process host for one game. Validates the manifest up front (throws on anything unsafe). Tokens are kept only as SHA-256 digests; lookups go by digest, so a guessed token never takes a timing-dependent string comparison against a real one.

Type Parameters#

Parameters#

Returns#

PlayerThreeHost<M>

jsonCommanderStore()#

function jsonCommanderStore(dir): CommanderStore;

Defined in: packages/playerthree/src/host/store.ts:60

JSON-file store: <dir>/commanders.json (key + rosters, written atomically) and one file per library version under <dir>/artifacts/<owner>/<commander-id>/<version>.json (runtime, code and surface hash). Owner and commander ids are pattern-checked before they become path components. commanders.json holds the host key every commander token is derived from, and artifacts are owners' private policy code: directories are created 0700 and files written 0600 so other local users cannot read either.

Parameters#

Returns#

CommanderStore

jsonHistoryStore()#

function jsonHistoryStore(dir): HistoryStore;

Defined in: packages/playerthree/src/host/store.ts:208

JSON-file history store: one <dir>/<session>.json per session ({format:"playerthree.session", version:1, record, replay}), written atomically (temp file + rename). Loading removes temp files left by an interrupted write and skips unreadable files. Use one directory per game.

Parameters#

Returns#

HistoryStore

jsonlCommanderLogStore()#

function jsonlCommanderLogStore(file): CommanderLogStore;

Defined in: packages/playerthree/src/host/store.ts:333

JSONL log store: one line per entry ({"entry":…}) or verdict row ({"verdict":…}), appended (0600). A privacy tombstone rewrites the file atomically without the commander's sealed parts (the only rewrite). Use one file per game.

Parameters#

Returns#

CommanderLogStore

jsonPoolStore()#

function jsonPoolStore(dir): PoolStore;

Defined in: packages/playerthree/src/host/store.ts:150

JSON-file pool store: <dir>/pool.json ({version:1, entries}, written atomically) and one artifact file per entry, <dir>/<id>.json (runtime, code and surface hash). Every write re-reads pool.json, so entries of other games sharing the directory are kept. Entry ids are pattern-checked before they become file names.

Parameters#

Returns#

PoolStore

jsonSeriesStore()#

function jsonSeriesStore(dir): SeriesStore;

Defined in: packages/playerthree/src/series-store.ts:372

Explicit local fallback, one process per directory. Journal replay finishes interrupted atomic commits.

Parameters#

Returns#

SeriesStore

memoryCommanderLogStore()#

function memoryCommanderLogStore(): CommanderLogStore;

Defined in: packages/playerthree/src/host/store.ts:315

In-memory commander log store (the default without dataDir or commanderLog.store): lost on restart.

Returns#

CommanderLogStore

memoryCommanderStore()#

function memoryCommanderStore(): CommanderStore;

Defined in: packages/playerthree/src/host/store.ts:23

In-memory commander roster store (the default without dataDir or commanderStore): lost on restart.

Returns#

CommanderStore

memoryPoolStore()#

function memoryPoolStore(): PoolStore;

Defined in: packages/playerthree/src/host/store.ts:123

In-memory policy pool store (the default without poolDir or poolStore): lost on restart.

Returns#

PoolStore

policyArtifactHash()#

function policyArtifactHash(artifact): string;

Defined in: packages/playerthree/src/host/pipeline.ts:377

SHA-256 hex of an artifact's module bytes (the composed JS source as UTF-8, or the decoded WASM module).

Parameters#

Returns#

string

replayMatch()#

function replayMatch<M>(
   definition, 
   replay, 
   tick?, 
   position?
): ReplayResult<M>;

Defined in: packages/playerthree/src/host/replay.ts:22

Re-simulate through tick (including recorded inputs at that tick), defaulting to the entire replay.

Type Parameters#

Parameters#

Returns#

ReplayResult<M>

seriesChunkJson()#

function seriesChunkJson(rows): string;

Defined in: packages/playerthree/src/series-store.ts:51

Canonical JSON used for raw chunk byte counts and SHA-256 checksums.

Parameters#

Returns#

string

References#

AgentSession#

Re-exports AgentSession

AuthorizationLease#

Re-exports AuthorizationLease

ChatEntry#

Re-exports ChatEntry

COMMANDER_LOG_FORMAT#

Re-exports COMMANDER_LOG_FORMAT

COMMANDER_LOG_VERSION#

Re-exports COMMANDER_LOG_VERSION

CommanderAgent#

Re-exports CommanderAgent

CommanderIdentity#

Re-exports CommanderIdentity

CommanderLogAssist#

Re-exports CommanderLogAssist

CommanderLogContext#

Re-exports CommanderLogContext

CommanderLogDisposition#

Re-exports CommanderLogDisposition

CommanderLogEntry#

Re-exports CommanderLogEntry

CommanderLogHead#

Re-exports CommanderLogHead

CommanderLogOptions#

Re-exports CommanderLogOptions

CommanderLogOutcome#

Re-exports CommanderLogOutcome

CommanderLogReader#

Re-exports CommanderLogReader

CommanderLogSealed#

Re-exports CommanderLogSealed

CommanderLogSeatRef#

Re-exports CommanderLogSeatRef

CommanderLogStore#

Re-exports CommanderLogStore

CommanderLogUsage#

Re-exports CommanderLogUsage

CommanderLogVerdict#

Re-exports CommanderLogVerdict

CommanderLogVerdictRow#

Re-exports CommanderLogVerdictRow

CommanderPolicyVersion#

Re-exports CommanderPolicyVersion

CommanderPractice#

Re-exports CommanderPractice

CommanderPracticeRequest#

Re-exports CommanderPracticeRequest

CommanderRegistry#

Re-exports CommanderRegistry

CommanderSaid#

Re-exports CommanderSaid

CommanderSettings#

Re-exports CommanderSettings

CommanderSettingsPatch#

Re-exports CommanderSettingsPatch

CommanderStatus#

Re-exports CommanderStatus

CommanderStore#

Re-exports CommanderStore

CommanderStoreData#

Re-exports CommanderStoreData

CommentaryEvent#

Re-exports CommentaryEvent

compareLogEntries#

Re-exports compareLogEntries

CreateCommander#

Re-exports CreateCommander

CreateMatchOptions#

Re-exports CreateMatchOptions

DecisionUsage#

Re-exports DecisionUsage

GuardChannel#

Re-exports GuardChannel

HistoryStore#

Re-exports HistoryStore

LobbyReservation#

Re-exports LobbyReservation

MatchLogFacts#

Re-exports MatchLogFacts

MatchTokens#

Re-exports MatchTokens

ObserverFrame#

Re-exports ObserverFrame

ObserverGrant#

Re-exports ObserverGrant

ObserverMessage#

Re-exports ObserverMessage

ObserverPolicy#

Re-exports ObserverPolicy

PlayerThreeError#

Re-exports PlayerThreeError

PlayerThreeHost#

Re-exports PlayerThreeHost

PlayerThreeHostOptions#

Re-exports PlayerThreeHostOptions

PlayerThreeMatch#

Re-exports PlayerThreeMatch

PlayerThreeTraceEvent#

Re-exports PlayerThreeTraceEvent

PolicyPool#

Re-exports PolicyPool

PoolEntry#

Re-exports PoolEntry

PoolPublisher#

Re-exports PoolPublisher

PoolRecord#

Re-exports PoolRecord

PoolStore#

Re-exports PoolStore

PoolStoreData#

Re-exports PoolStoreData

PublicSeatCard#

Re-exports PublicSeatCard

ReadinessSnapshot#

Re-exports ReadinessSnapshot

ReadinessState#

Re-exports ReadinessState

ReadyCheck#

Re-exports ReadyCheck

Replay#

Re-exports Replay

ReplayEntry#

Re-exports ReplayEntry

ReplayPosition#

Re-exports ReplayPosition

ResultsKey#

Re-exports ResultsKey

ResultsSigner#

Re-exports ResultsSigner

SeatAssignment#

Re-exports SeatAssignment

SeatInfo#

Re-exports SeatInfo

SeatKind#

Re-exports SeatKind

SeatTicket#

Re-exports SeatTicket

SessionHistory#

Re-exports SessionHistory

SessionHistoryOptions#

Re-exports SessionHistoryOptions

SessionRecord#

Re-exports SessionRecord

SessionSeatRecord#

Re-exports SessionSeatRecord

StoredCommander#

Re-exports StoredCommander

StoredCommanderLogEntry#

Re-exports StoredCommanderLogEntry

StoredOwner#

Re-exports StoredOwner

StoredPolicyArtifact#

Re-exports StoredPolicyArtifact

StoredPoolEntry#

Re-exports StoredPoolEntry

TraceSource#

Re-exports TraceSource

UNRATED#

Re-exports UNRATED

UsageEvent#

Re-exports UsageEvent

ViewMessage#

Re-exports ViewMessage