playerthree/control#

PlayerThree Control Plane v1 — the game-agnostic operations an agent can perform on a seat.

One contract, several bindings:

• in-process (built-in bots, practice, tests)
• WebSocket (protocol.ts: call / result, plus the stream push for tick-rate control)
• MCP (remote Streamable HTTP endpoint or local stdio bridge): one tool per method below

Trust rule for every output: game data is closed-vocabulary (schema-validated before it leaves the server). Free text is limited to the seat's own owner's messages and its own policy's log lines and engine errors. Owner messages carry the closed from: 'owner' label. Developer docs (briefing, skills) are static.

Interfaces#

Approval#

Defined in: packages/playerthree/src/control.ts:102

Properties#

Briefing#

Defined in: packages/playerthree/src/control.ts:116

The core briefing: small enough to read first (doc ≤ DOC_MAX, role doc ≤ ROLE_DOC_MAX, one-line topic index). Everything else (intent details, observation fields, match data, events, report, mandate, modes, policy ABI, JSON Schemas, game topics) is fetched on demand with briefing(topic, page?).

Properties#

LobbyStart#

Defined in: packages/playerthree/src/control.ts:29

When a pre-match seat's match starts. seat: nothing seats the agent yet; host: the lobby's host (or the game) starts it; ready: once every seat is ready, or at the ready deadline; countdown: the start countdown runs. inSeconds: wall-clock seconds left until the deadline or the countdown's end, when known.

Properties#

LobbyState#

Defined in: packages/playerthree/src/control.ts:40

The pre-match state of an agent (phase lobby): what wait, observe and ready report before the match starts. seat is the reserved or held seat (null while nothing seats the agent), match the game's guarded pre-match summary (manifest.lobby; absent when the game declares none or nothing seats the agent), you.ready whether the agent marked itself ready for this seat, and instruction the next step (static host text).

Properties#

Mandate#

Defined in: packages/playerthree/src/control.ts:68

Owner intent for a seat; directive and limits follow the game's schemas.

Properties#

MatchReceipt#

Defined in: packages/playerthree/src/control.ts:335

Bounded, non-consuming receipt for this role only; never includes observations or other teams' results.

Properties#

MatchWait#

Defined in: packages/playerthree/src/control.ts:322

Properties#

OwnerMessage#

Defined in: packages/playerthree/src/control.ts:288

A message from the seat's own owner (the player this agent works for). Owner-authored text: same trust as the player typing into their own harness. Never from opponents, teammates or spectators.

Properties#

PauseInfo#

Defined in: packages/playerthree/src/control.ts:91

A paused session: who holds it (every seat listed), and since when it has stood still.

Properties#

PolicyArtifact#

Defined in: packages/playerthree/src/control.ts:185

A policy as submitted to policyDeploy or practice.

Properties#

PolicyError#

Defined in: packages/playerthree/src/control.ts:209

A policy load or call failure: a closed code plus, at most, the engine's message about the caller's own artifact.

Properties#

PolicyStats#

Defined in: packages/playerthree/src/control.ts:216

Running statistics of one deployed policy version.

Properties#

PracticeRequest#

Defined in: packages/playerthree/src/control.ts:246

practice arguments: a headless match against a built-in opponent (SPEC §13).

Properties#

Said#

Defined in: packages/playerthree/src/control.ts:298

An agent's reply to its owner (say), as delivered to the owner's clients only.

Extended by#

• CommanderSaid

Properties#

SayResult#

Defined in: packages/playerthree/src/control.ts:389

Properties#

SeatControl#

Defined in: packages/playerthree/src/control.ts:363

The control plane for one seat. Every binding implements or forwards exactly this.

Extended by#

• RemoteSeat

Methods#

act()#

act(intents): Promise<IntentAck[]>;

Defined in: packages/playerthree/src/control.ts:373

Parameters#

Returns#

Promise<IntentAck[]>

briefing()#

Call Signature#

briefing(): Promise<Briefing>;

Defined in: packages/playerthree/src/control.ts:365

The core briefing.

Returns#

Promise<Briefing>

Call Signature#

briefing(topic, page?): Promise<TopicPage>;

Defined in: packages/playerthree/src/control.ts:367

One page (default 1) of a topic from the briefing's index; unknown topic or page → invalid.

Parameters#

Returns#

Promise<TopicPage>

observe()#

observe(since?, detail?): Promise<unknown>;

Defined in: packages/playerthree/src/control.ts:372

Returns manifest.observation. since: last tick already seen, for events. detail: observation sections to render in full besides the role's defaults, or 'all' (games declaring observationScope; unknown section → invalid).

Parameters#

Returns#

Promise<unknown>

policyDeploy()#

policyDeploy(artifact): Promise<DeployResult>;

Defined in: packages/playerthree/src/control.ts:375

Parameters#

Returns#

Promise<DeployResult>

policyRollback()#

policyRollback(version): Promise<DeployResult>;

Defined in: packages/playerthree/src/control.ts:377

Parameters#

Returns#

Promise<DeployResult>

policyStatus()#

policyStatus(): Promise<PolicyStatus | null>;

Defined in: packages/playerthree/src/control.ts:376

Returns#

Promise<PolicyStatus | null>

practice()#

practice(req): Promise<PracticeResult>;

Defined in: packages/playerthree/src/control.ts:378

Parameters#

Returns#

Promise<PracticeResult>

publish()#

publish(): Promise<PublishResult>;

Defined in: packages/playerthree/src/control.ts:379

Returns#

Promise<PublishResult>

ready()#

ready(): Promise<ReadyResult>;

Defined in: packages/playerthree/src/control.ts:382

Mark this agent ready for its pre-match seat (no-op once the match runs).

Returns#

Promise<ReadyResult>

say()#

say(text, disclosure?): Promise<SayResult>;

Defined in: packages/playerthree/src/control.ts:386

Agent-authored owner reply; observer disclosure is a separate explicit opt-in emission.

Parameters#

Returns#

Promise<SayResult>

sequence()#

sequence(req): Promise<SequenceResult>;

Defined in: packages/playerthree/src/control.ts:374

Parameters#

Returns#

Promise<SequenceResult>

skill()#

skill(
   name, 
   path, 
   offset?
): Promise<SkillPage>;

Defined in: packages/playerthree/src/control.ts:384

A window of a skill file (developer text) starting at offset (default 0); unknown file or offset → invalid.

Parameters#

Returns#

Promise<SkillPage>

wait()#

wait(req): Promise<WaitResult>;

Defined in: packages/playerthree/src/control.ts:380

Parameters#

Returns#

Promise<WaitResult>

SeatPause#

Defined in: packages/playerthree/src/control.ts:80

One seat holding a pausable session still: controller agent, mandate whenAbsent: 'pause', agent absent. reason is a closed code (agent_absent is the only reason today).

Properties#

SeatStatus#

Defined in: packages/playerthree/src/control.ts:348

Non-consuming lifecycle snapshot. No owner text, policy text, or game observations.

Properties#

SequenceRequest#

Defined in: packages/playerthree/src/control.ts:175

Properties#

SkillPage#

Defined in: packages/playerthree/src/control.ts:156

A window of one skill file: text ≤ SKILL_PAGE_MAX, cut after a newline; next is the offset to continue at.

Properties#

TopicPage#

Defined in: packages/playerthree/src/control.ts:146

One page of a briefing topic. text ≤ TOPIC_TEXT_MAX; next names the following page while there is one.

Properties#

WaitRequest#

Defined in: packages/playerthree/src/control.ts:277

Properties#

WaitWake#

Defined in: packages/playerthree/src/control.ts:306

What ended a wait early, and unread owner messages; shared by both phases' results.

Properties#

Type Aliases#

ApprovalRequest#

type ApprovalRequest = Pick<Approval, "id" | "kind" | "version">;

Defined in: packages/playerthree/src/control.ts:109

ControlMethod#

type ControlMethod = keyof SeatControl;

Defined in: packages/playerthree/src/control.ts:395

Names of the control-plane methods (SeatControl keys); each maps to one MCP tool.

DeployResult#

type DeployResult = 
  | {
  ok: true;
  probe: PolicyStats;
  version: number;
}
  | {
  error: PolicyError;
  ok: false;
}
  | {
  approval: ApprovalRequest;
  ok: false;
};

Defined in: packages/playerthree/src/control.ts:240

policyDeploy result: the new version with its probe call's stats, a load error, or (supervised) an approval request.

IntentAck#

type IntentAck = 
  | {
  ok: true;
}
  | {
  code: "invalid";
  ok: false;
  path: SchemaPath;
  schemaCode: SchemaErrorCode;
}
  | {
  code:   | "forbidden_role"
     | "rate_limited"
     | "not_controller"
     | "game_over"
     | "out_of_scope";
  ok: false;
}
  | {
  code: "game";
  gameCode: string;
  ok: false;
}
  | {
  code: "signal";
  ok: false;
  signalCode: SignalCode;
};

Defined in: packages/playerthree/src/control.ts:168

Result of one intent. Never echoes input.

PolicyErrorCode#

type PolicyErrorCode = 
  | "runtime_not_allowed"
  | "too_large"
  | "compile"
  | "missing_export"
  | "bad_module"
  | "imports_not_allowed"
  | "memory_limit"
  | "timeout"
  | "threw"
  | "bad_output";

Defined in: packages/playerthree/src/control.ts:196

PolicyStatus#

type PolicyStatus = (
  | PolicyStats
  | {
  version: null;
}) & object;

Defined in: packages/playerthree/src/control.ts:237

Type Declaration#

PracticeResult#

type PracticeResult = 
  | {
  ok: true;
  outcome: "win" | "loss" | "draw" | "running";
  policy: PolicyStats;
  report: unknown;
  ticks: number;
  wallMs: number;
}
  | {
  code: "policy" | "guard";
  ok: false;
  policy: PolicyStats;
  wallMs: number;
};

Defined in: packages/playerthree/src/control.ts:260

practice result.

Union Members#

Type Literal#

{
  ok: true;
  outcome: "win" | "loss" | "draw" | "running";
  policy: PolicyStats;
  report: unknown;
  ticks: number;
  wallMs: number;
}

Type Literal#

{
  code: "policy" | "guard";
  ok: false;
  policy: PolicyStats;
  wallMs: number;
}

PublishResult#

type PublishResult = 
  | {
  policyId: string;
}
  | {
  approval: ApprovalRequest;
  ok: false;
};

Defined in: packages/playerthree/src/control.ts:360

ReadyResult#

type ReadyResult = 
  | LobbyState
  | {
  phase: "match";
  you: {
     ready: true;
  };
};

Defined in: packages/playerthree/src/control.ts:61

The result of marking a seat ready: the lobby state, or match once the match runs (ready is then implied).

ResumeReason#

type ResumeReason = "present" | "owner" | "timeout";

Defined in: packages/playerthree/src/control.ts:100

Why a seat stopped holding a paused session: its agent is present again, the owner changed the seat, or max pause ran out.

Scope#

type Scope = typeof SCOPES[number];

Defined in: packages/playerthree/src/control.ts:65

SequenceResult#

type SequenceResult = 
  | {
  acks: IntentAck[][];
  id: string;
  ok: true;
}
  | {
  acks: IntentAck[][];
  code: "invalid" | "out_of_scope" | "not_controller" | "game_over";
  ok: false;
};

Defined in: packages/playerthree/src/control.ts:180

SessionPhase#

type SessionPhase = "lobby" | "match";

Defined in: packages/playerthree/src/control.ts:22

Where a session is. lobby: before the match a seat is in starts — nothing seats the agent yet (commander tokens between matches), a game lobby reserved a seat for the next match, or the agent's match is held before its first tick (ready check, preparation, countdown). match: the match is running (or just ended for this seat).

WaitResult#

type WaitResult = 
  | LobbyState & WaitWake
  | MatchWait & WaitWake;

Defined in: packages/playerthree/src/control.ts:320

A wait result. Before the match starts it is the lobby state; a wait that sees the match start (or the seat handed to this agent mid-match) returns match at once with that first observation and an instruction.

Variables#

LOBBY_INSTRUCTIONS#

const LOBBY_INSTRUCTIONS: object;

Defined in: packages/playerthree/src/control.ts:51

Static next-step texts of the lobby state.

Type Declaration#

MATCH_INSTRUCTION#

const MATCH_INSTRUCTION: "The match is running and you command this seat: read game_briefing for it, then play from this observation." = 'The match is running and you command this seat: read game_briefing for it, then play from this observation.';

Defined in: packages/playerthree/src/control.ts:58

Static next-step text of the first result in a match (a held match started, or a seat handed over mid-match).

MCP_TOOL_NAMES#

const MCP_TOOL_NAMES: Record<ControlMethod, string>;

Defined in: packages/playerthree/src/control.ts:437

Stable MCP tool names. Same for every game.

METHOD_MODE#

const METHOD_MODE: Record<ControlMethod, "intents" | "sequence" | "policy" | "practice" | "pool" | "chat">;

Defined in: packages/playerthree/src/control.ts:398

Which control mode gates each method (intents is always available).

METHOD_SCOPE#

const METHOD_SCOPE: Record<ControlMethod, Scope | undefined>;

Defined in: packages/playerthree/src/control.ts:415

Reading never requires a scope.

SCOPES#

const SCOPES: readonly ["act", "policy", "practice", "publish", "say"];

Defined in: packages/playerthree/src/control.ts:64

Agent permission scopes an owner grants per seat (SPEC §6).

Functions#

defaultScopes()#

function defaultScopes(manifest): ("act" | "policy" | "practice" | "publish" | "say")[];

Defined in: packages/playerthree/src/control.ts:432

New seats receive each permission supported by the game.

Parameters#

Returns#

("act" | "policy" | "practice" | "publish" | "say")[]