@playerthree/connect#

Headless connection setup: the catalog of agent harnesses a player can attach to a game's MCP endpoint, the exact copy-paste command or config for each one, and the wire types games use for connections and consent requests. DOM-free and UI-free: games render their own buttons, icons and pages from this.

With MCP authorization (OAuth 2.1, see docs/MCP.md) nothing here carries a secret: one static URL for everyone, and the harness signs the player in through the browser. token (a per-match seat token or a persistent commander token) is the bearer fallback for harnesses or hosts without OAuth; it is embedded only when it has the opaque PlayerThree token format. Output is only built from a well-formed http(s) URL and a [a-z0-9-] server name, so no command line is ever assembled from unexpected input.

Interfaces#

ConnectionClient#

Defined in: packages/connect/src/index.ts:254

The OAuth client behind a connection, as the host describes it. Name and URI come from the client: show as text.

Properties#

ConnectionInfo#

Defined in: packages/connect/src/index.ts:265

One independently authorised harness connection to one named commander.

Properties#

ConsentAnswer#

Defined in: packages/connect/src/index.ts:292

The owner's answer to a ConsentRequestInfo: approve or deny, binding the connection to one commander and its roles.

Properties#

ConsentCommander#

Defined in: packages/connect/src/index.ts:313

Safe named commander details returned after pairing; never includes profile or commander secrets.

Properties#

ConsentRequestInfo#

Defined in: packages/connect/src/index.ts:281

A pending authorization request the owner is asked to approve.

Properties#

ConsentResult#

Defined in: packages/connect/src/index.ts:302

Where to send the browser next (the client's redirect URI with the code, or with error=access_denied).

Properties#

Harness#

Defined in: packages/connect/src/index.ts:25

Catalog entry of one harness family.

Properties#

HarnessSetup#

Defined in: packages/connect/src/index.ts:63

The copy-paste setup for one harness.

Extends#

• SetupText

Properties#

KickoffOptions#

Defined in: packages/connect/src/index.ts:228

Inputs of kickoffPrompt: the game title, the seat roles and their mandate.

Properties#

PairingCode#

Defined in: packages/connect/src/index.ts:307

A single-use code minted in the owner's browser; expires after ten minutes.

Properties#

PairingResult#

Defined in: packages/connect/src/index.ts:327

A capability for one consent request, not a profile login. Keep it only in the consent page's memory.

Properties#

SetupOptions#

Defined in: packages/connect/src/index.ts:72

Inputs of harnessSetup.

Properties#

SetupText#

Defined in: packages/connect/src/index.ts:56

Where a setup goes: sh runs in a terminal, slash is typed into the harness's own session; otherwise it is pasted into file (or the client's MCP settings when no file).

Extended by#

• HarnessSetup

Properties#

Type Aliases#

ClientKind#

type ClientKind = typeof CLIENT_KINDS[number];

Defined in: packages/connect/src/index.ts:17

Variables#

CLIENT_KINDS#

const CLIENT_KINDS: readonly ["claude-code", "claude-api", "codex", "opencode", "pi", "oh-my-pi", "hermes", "generic", "playerthree-runner", "playerthree-bridge"];

Defined in: packages/connect/src/index.ts:16

Harness families a connection can come from (detected by the host from the OAuth client's metadata).

HARNESSES#

const HARNESSES: readonly Harness[];

Defined in: packages/connect/src/index.ts:36

Every harness with a setup recipe, in the order games should offer them.

MANDATE_PRESETS#

const MANDATE_PRESETS: object;

Defined in: packages/connect/src/index.ts:221

UI shortcuts; intersect their scopes with the modes supported by the game's manifest.

Type Declaration#

Functions#

harness()#

function harness(kind): Harness;

Defined in: packages/connect/src/index.ts:50

The catalog entry of kind.

Parameters#

Returns#

Harness

harnessSetup()#

function harnessSetup(kind, opts): HarnessSetup | undefined;

Defined in: packages/connect/src/index.ts:105

Setup for kind, or undefined when the URL is not http(s), the server name is not [a-z0-9-] or the token is malformed (callers render nothing rather than a broken command).

Parameters#

Returns#

HarnessSetup | undefined

isClientKind()#

function isClientKind(v): v is "claude-code" | "claude-api" | "codex" | "opencode" | "pi" | "oh-my-pi" | "hermes" | "generic" | "playerthree-runner" | "playerthree-bridge";

Defined in: packages/connect/src/index.ts:20

Narrows an untrusted value to a known ClientKind.

Parameters#

Returns#

v is "claude-code" | "claude-api" | "codex" | "opencode" | "pi" | "oh-my-pi" | "hermes" | "generic" | "playerthree-runner" | "playerthree-bridge"

kickoffPrompt()#

function kickoffPrompt(__namedParameters): string;

Defined in: packages/connect/src/index.ts:235

The player-pasted first message for a turn-based harness; live briefing remains authoritative.

Parameters#

Returns#

string

serverName()#

function serverName(...parts): string;

Defined in: packages/connect/src/index.ts:84

MCP server name from identifiers: lower-case, [a-z0-9-], joined with -, ≤ 64 chars.

Parameters#

Returns#

string