@playerthree/runner#

@playerthree/runner: play a seat with your own LLM key — the remote MCP seat client, the stdio bridge, LLM providers, the agent loop and browser sign-in. CLIs: playerthree-run, playerthree-mcp.

Classes#

BridgeError#

Defined in: packages/runner/src/bridge.ts:42

A bridge failure with a closed BridgeErrorCode.

Extends#

• Error

Constructors#

Constructor#

new BridgeError(code, remoteHash?): BridgeError;

Defined in: packages/runner/src/bridge.ts:46

Parameters#

Returns#

BridgeError

Overrides#

Error.constructor

Properties#

Budget#

Defined in: packages/runner/src/providers.ts:301

Hard spend limit with token accounting.

Constructors#

Constructor#

new Budget(
   maxUsd, 
   price, 
   maxTokens?
): Budget;

Defined in: packages/runner/src/providers.ts:308

Parameters#

Returns#

Budget

Properties#

Accessors#

spentUsd#

Get Signature#

get spentUsd(): number;

Defined in: packages/runner/src/providers.ts:316

Returns#

number

Methods#

add()#

add(usage): number;

Defined in: packages/runner/src/providers.ts:324

Parameters#

Returns#

number

canAfford()#

canAfford(estimatedInput, maxOutput): boolean;

Defined in: packages/runner/src/providers.ts:320

Whether a call with this many input tokens and up to maxOutput output tokens stays within the limit.

Parameters#

Returns#

boolean

cost()#

cost(usage): number;

Defined in: packages/runner/src/providers.ts:313

Parameters#

Returns#

number

PlayerThreeSeatError#

Defined in: packages/runner/src/remote.ts:36

A failed remote call. code is closed; no remote text is carried.

Extends#

• Error

Constructors#

Constructor#

new PlayerThreeSeatError(code): PlayerThreeSeatError;

Defined in: packages/runner/src/remote.ts:38

Parameters#

Returns#

PlayerThreeSeatError

Overrides#

Error.constructor

Properties#

ProviderError#

Defined in: packages/runner/src/providers.ts:86

A provider API call failed with HTTP status; the message carries at most 500 characters of the response.

Extends#

• Error

Constructors#

Constructor#

new ProviderError(
   provider, 
   status, 
   detail
): ProviderError;

Defined in: packages/runner/src/providers.ts:88

Parameters#

Returns#

ProviderError

Overrides#

Error.constructor

Properties#

SignInError#

Defined in: packages/runner/src/oauth.ts:35

Sign-in failed. code is closed; no remote text is carried.

Extends#

• Error

Constructors#

Constructor#

new SignInError(code): SignInError;

Defined in: packages/runner/src/oauth.ts:37

Parameters#

Returns#

SignInError

Overrides#

Error.constructor

Properties#

Interfaces#

Bridge#

Defined in: packages/runner/src/bridge.ts:70

A running bridge.

Properties#

Methods#

close()#

close(): Promise<void>;

Defined in: packages/runner/src/bridge.ts:73

Returns#

Promise<void>

BridgeOptions#

Defined in: packages/runner/src/bridge.ts:55

Options of startBridge: the remote endpoint, its credential and an optional expected surfaceHash.

Properties#

BrowserSignIn#

Defined in: packages/runner/src/oauth.ts:115

An OAuth client for one MCP endpoint with a loopback redirect listener.

Properties#

Methods#

callback()#

callback(): Promise<URLSearchParams>;

Defined in: packages/runner/src/oauth.ts:120

Resolves with the authorization callback's parameters (state checked) once the browser returns.

Returns#

Promise<URLSearchParams>

close()#

close(): void;

Defined in: packages/runner/src/oauth.ts:124

Stops the loopback listener.

Returns#

void

forget()#

forget(): void;

Defined in: packages/runner/src/oauth.ts:122

Forget the cached registration and tokens for this endpoint.

Returns#

void

BrowserSignInOptions#

Defined in: packages/runner/src/oauth.ts:99

Options of browserSignIn.

Properties#

Methods#

log()#

log(line): void;

Defined in: packages/runner/src/oauth.ts:111

Where the sign-in URL is printed (stderr in the CLIs).

Parameters#

Returns#

void

ConnectSeatOptions#

Defined in: packages/runner/src/remote.ts:64

Options of connectSeat: the endpoint URL and exactly one of token or signIn.

Properties#

LlmTool#

Defined in: packages/runner/src/providers.ts:7

Properties#

Price#

Defined in: packages/runner/src/providers.ts:265

USD per million tokens. Cached-input discounts are ignored, so spend is over- rather than under-counted.

Properties#

Provider#

Defined in: packages/runner/src/providers.ts:38

One model conversation: the provider owns its history; the agent loop adds user text and tool results and asks for turns.

Properties#

Methods#

addToolResults()#

addToolResults(results): void;

Defined in: packages/runner/src/providers.ts:42

Parameters#

Returns#

void

addUser()#

addUser(text): void;

Defined in: packages/runner/src/providers.ts:41

Parameters#

Returns#

void

compact()#

compact(keep): void;

Defined in: packages/runner/src/providers.ts:47

Replace tool outputs older than the last keep with a short marker to bound context growth.

Parameters#

Returns#

void

estimateInputTokens()#

estimateInputTokens(): number;

Defined in: packages/runner/src/providers.ts:45

Conservative estimate of the next turn's input tokens.

Returns#

number

turn()#

turn(signal?): Promise<Turn>;

Defined in: packages/runner/src/providers.ts:43

Parameters#

Returns#

Promise<Turn>

ProviderOptions#

Defined in: packages/runner/src/providers.ts:51

Options shared by the OpenAI and Anthropic providers.

Properties#

RemoteSeat#

Defined in: packages/runner/src/remote.ts:54

A SeatControl over a remote MCP endpoint, plus its pinned surface.

Extends#

• SeatControl

Properties#

Methods#

act()#

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

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

Parameters#

Returns#

Promise<IntentAck[]>

Inherited from#

SeatControl.act

briefing()#

Call Signature#

briefing(): Promise<Briefing>;

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

The core briefing.

Returns#

Promise<Briefing>

Inherited from#

SeatControl.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>

Inherited from#

SeatControl.briefing

call()#

call(
   name, 
   args, 
   opts?
): Promise<ToolOutcome>;

Defined in: packages/runner/src/remote.ts:59

Raw tool call (for agents that drive the MCP tools directly). Throws only on transport failure or surface change.

Parameters#

Returns#

Promise<ToolOutcome>

close()#

close(): Promise<void>;

Defined in: packages/runner/src/remote.ts:60

Returns#

Promise<void>

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>

Inherited from#

SeatControl.observe

policyDeploy()#

policyDeploy(artifact): Promise<DeployResult>;

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

Parameters#

Returns#

Promise<DeployResult>

Inherited from#

SeatControl.policyDeploy

policyRollback()#

policyRollback(version): Promise<DeployResult>;

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

Parameters#

Returns#

Promise<DeployResult>

Inherited from#

SeatControl.policyRollback

policyStatus()#

policyStatus(): Promise<PolicyStatus | null>;

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

Returns#

Promise<PolicyStatus | null>

Inherited from#

SeatControl.policyStatus

practice()#

practice(req): Promise<PracticeResult>;

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

Parameters#

Returns#

Promise<PracticeResult>

Inherited from#

SeatControl.practice

publish()#

publish(): Promise<PublishResult>;

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

Returns#

Promise<PublishResult>

Inherited from#

SeatControl.publish

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>

Inherited from#

SeatControl.ready

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>

Inherited from#

SeatControl.say

sequence()#

sequence(req): Promise<SequenceResult>;

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

Parameters#

Returns#

Promise<SequenceResult>

Inherited from#

SeatControl.sequence

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>

Inherited from#

SeatControl.skill

wait()#

wait(req): Promise<WaitResult>;

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

Parameters#

Returns#

Promise<WaitResult>

Inherited from#

SeatControl.wait

RunAgentOptions#

Defined in: packages/runner/src/agent.ts:30

Inputs of runAgent: the connected seat, the model provider and the spending budget.

Properties#

RunSummary#

Defined in: packages/runner/src/agent.ts:19

What one runAgent run did and spent.

Properties#

ToolCall#

Defined in: packages/runner/src/providers.ts:18

Properties#

ToolOutcome#

Defined in: packages/runner/src/remote.ts:46

A tool call result as the runner sees it.

Properties#

ToolResultInput#

Defined in: packages/runner/src/providers.ts:31

Properties#

Turn#

Defined in: packages/runner/src/providers.ts:25

Properties#

Usage#

Defined in: packages/runner/src/providers.ts:13

Properties#

Type Aliases#

BridgeErrorCode#

type BridgeErrorCode = 
  | "bad_token"
  | "transport"
  | "surface_mismatch"
  | "skills"
  | "sign_in"
  | "protocol";

Defined in: packages/runner/src/bridge.ts:39

EndpointAuth#

type EndpointAuth = 
  | {
  token: string;
}
  | {
  signIn: BrowserSignIn;
};

Defined in: packages/runner/src/oauth.ts:263

How a client authenticates to the endpoint: a pasted seat/commander token, or browser sign-in.

SeatErrorCode#

type SeatErrorCode = 
  | ToolErrorCode
  | "surface_mismatch"
  | "transport"
  | "protocol";

Defined in: packages/runner/src/remote.ts:33

@playerthree/runner: play a seat with your own LLM key — the remote MCP seat client, the stdio bridge, LLM providers, the agent loop and browser sign-in. CLIs: playerthree-run, playerthree-mcp.

SignInErrorCode#

type SignInErrorCode = "declined" | "timeout" | "bad_callback" | "rejected";

Defined in: packages/runner/src/oauth.ts:32

StopReason#

type StopReason = 
  | "match_over"
  | "budget"
  | "aborted"
  | "surface_changed"
  | "provider_error"
  | "max_turns"
  | "prepared";

Defined in: packages/runner/src/agent.ts:16

Why runAgent stopped.

Variables#

MCP_PROTOCOL_VERSION#

const MCP_PROTOCOL_VERSION: "2026-07-28" = '2026-07-28';

Defined in: packages/runner/src/remote.ts:30

@playerthree/runner: play a seat with your own LLM key — the remote MCP seat client, the stdio bridge, LLM providers, the agent loop and browser sign-in. CLIs: playerthree-run, playerthree-mcp.

PRICES#

const PRICES: Readonly<Record<string, Price>>;

Defined in: packages/runner/src/providers.ts:271

List prices (standard tier) as of 2026-11. Override with --price-in/--price-out for anything else.

Functions#

browserSignIn()#

function browserSignIn(opts): Promise<BrowserSignIn>;

Defined in: packages/runner/src/oauth.ts:128

Prepares browser sign-in for one MCP endpoint: a cached OAuth client provider plus a loopback listener on 127.0.0.1 for the redirect.

Parameters#

Returns#

Promise<BrowserSignIn>

configDir()#

function configDir(): string;

Defined in: packages/runner/src/oauth.ts:45

The playerthree config dir: PLAYERTHREE_CONFIG_DIR, else the platform's user config dir.

Returns#

string

connectClient()#

function connectClient(
   url, 
   auth, 
   makeClient
): Promise<Client>;

Defined in: packages/runner/src/oauth.ts:319

Connects a fresh client from makeClient() to url. With browser sign-in, an endpoint answering 401 starts the sign-in (once): after the browser returns, the code is redeemed and a fresh client connects. Throws UnauthorizedError when the endpoint rejects the credential, SignInError when sign-in fails.

Parameters#

Returns#

Promise<Client>

connectSeat()#

function connectSeat(opts): Promise<RemoteSeat>;

Defined in: packages/runner/src/remote.ts:103

Connects to a remote seat over MCP (protocol revision pinned to MCP_PROTOCOL_VERSION).

Parameters#

Returns#

Promise<RemoteSeat>

createAnthropicProvider()#

function createAnthropicProvider(opts): Provider;

Defined in: packages/runner/src/providers.ts:212

Anthropic Messages API provider (tools).

Parameters#

Returns#

Provider

createOpenAiProvider()#

function createOpenAiProvider(opts): Provider;

Defined in: packages/runner/src/providers.ts:157

OpenAI Responses API provider (function tools).

Parameters#

Returns#

Provider

createScriptedProvider()#

function createScriptedProvider(turns, model?): Provider & object;

Defined in: packages/runner/src/providers.ts:62

Deterministic offline provider; each instance owns a fresh script cursor and records its inputs.

Parameters#

Returns#

Provider & object

joinStringOptions()#

function joinStringOptions(argv, options): string[];

Defined in: packages/runner/src/argv.ts:5

Seat tokens are base64url and may start with -, which node:util parseArgs rejects as an ambiguous option value in --token -abc…. Rewrite --name value to --name=value for string options so pasted commands work.

Parameters#

Returns#

string[]

llmTools()#

function llmTools(seat): object[];

Defined in: packages/runner/src/agent.ts:114

Tools offered to the model: the remote MCP tools as-is (names, descriptions, input schemas).

Parameters#

Returns#

object[]

priceFor()#

function priceFor(model): Price | undefined;

Defined in: packages/runner/src/providers.ts:294

Price for a model id, accepting dated snapshots (gpt-5-mini-2025-08-07).

Parameters#

Returns#

Price | undefined

runAgent()#

function runAgent(opts): Promise<RunSummary>;

Defined in: packages/runner/src/agent.ts:146

Drives one seat with one LLM until the match is over, the budget is spent, signal aborts or another StopReason.

Parameters#

Returns#

Promise<RunSummary>

startBridge()#

function startBridge(opts): Promise<Bridge>;

Defined in: packages/runner/src/bridge.ts:91

Serves local discovery immediately, without claiming a remote credential. Resolves with truthful remote tools/hash only after the first non-discovery request acquires the endpoint.

Parameters#

Returns#

Promise<Bridge>

systemPrompt()#

function systemPrompt(seat, game): string;

Defined in: packages/runner/src/agent.ts:67

Runner-authored system prompt. Embeds only static developer text: the game's manifest title and the first paragraph of its doc (from game_briefing game) and the server's instructions.

Parameters#

Returns#

string