@dopamint-fun/open-sdk 0.1.0-dev.0

package/dist/sessionWire.js

@@ -0,0 +1,118 @@
+/* The Participant Session signing preimages and signed send frames,
+ * byte-identical to `arena_session::wire`.
+ *
+ * Join, action, and resume signing bodies live here; acknowledgements are
+ * unsigned and encoded next to the authority decoder. The layouts are pinned
+ * by `libs/dopa-open-client-rs/vectors/ts-signer-parity.json`.
+ */
+import { ByteWriter, frameSigningBytes, textBytes } from "./bytes.js";
+const JOIN_DOMAIN = textBytes("arena_session::join");
+const ACTION_DOMAIN = textBytes("arena_session::action");
+const RESUME_DOMAIN = textBytes("arena_session::resume");
+const SESSION_JOIN_REQUEST_TAG = 0x01;
+const ACTION_PROPOSAL_TAG = 0x04;
+const SESSION_RESUME_REQUEST_TAG = 0x0a;
+export function encodeContext(writer, context) {
+    writer
+        .pushU16(context.sessionVersion)
+        .pushFixed(context.sessionId, 32, "session id")
+        .pushFixed(context.executionId, 32, "execution id")
+        .pushFixed(context.executionManifestDigest, 32, "execution manifest digest")
+        .pushFixed(context.protocolId, 32, "protocol id")
+        .pushU16(context.protocolVersion)
+        .pushFixed(context.participantId, 32, "participant id")
+        .pushU16(context.seat);
+}
+export function encodeSignature(signature) {
+    return new ByteWriter()
+        .pushU16(signature.length)
+        .pushBytes(signature)
+        .bytes();
+}
+export function signedFrame(body, signature) {
+    return new ByteWriter()
+        .pushBytes(body)
+        .pushBytes(encodeSignature(signature))
+        .bytes();
+}
+export function joinBodyBytes(request) {
+    const writer = new ByteWriter()
+        .pushU16(request.wireVersion)
+        .pushByte(SESSION_JOIN_REQUEST_TAG)
+        .pushU16(request.supportedSessionVersions.length);
+    for (const version of request.supportedSessionVersions)
+        writer.pushU16(version);
+    writer
+        .pushFixed(request.executionId, 32, "execution id")
+        .pushFixed(request.executionManifestDigest, 32, "execution manifest digest")
+        .pushFixed(request.participantId, 32, "participant id")
+        .pushU16(request.seat)
+        .pushFixed(request.clientNonce, 32, "client nonce")
+        .pushFixed(request.challenge, 74, "session challenge");
+    return writer.bytes();
+}
+export function joinSigningBytes(request) {
+    return frameSigningBytes(JOIN_DOMAIN, joinBodyBytes(request));
+}
+export function encodeJoinFrame(request, signature) {
+    return signedFrame(joinBodyBytes(request), signature);
+}
+export function actionBodyBytes(proposal) {
+    const writer = new ByteWriter()
+        .pushU16(proposal.context.wireVersion)
+        .pushByte(ACTION_PROPOSAL_TAG);
+    encodeContext(writer, proposal.context);
+    writer
+        .pushFixed(proposal.actionId, 32, "action id")
+        .pushU64(proposal.expectedStateNonce)
+        .pushFixed(proposal.expectedStateCommitment, 32, "expected state commitment")
+        .pushU64(proposal.participantDeadlineMs)
+        .pushU16(proposal.payloadSchemaVersion)
+        .pushU64(proposal.payload.length)
+        .pushBytes(proposal.payload);
+    const artifacts = proposal.artifactReferences ?? [];
+    writer.pushU16(artifacts.length);
+    for (const artifact of artifacts) {
+        writer
+            .pushU16(artifact.kind)
+            .pushU16(artifact.schemaVersion)
+            .pushFixed(artifact.digest, 32, "artifact digest")
+            .pushU64(artifact.byteLength);
+    }
+    return writer.bytes();
+}
+export function actionSigningBytes(proposal) {
+    return frameSigningBytes(ACTION_DOMAIN, actionBodyBytes(proposal));
+}
+export function encodeActionFrame(proposal, signature) {
+    return signedFrame(actionBodyBytes(proposal), signature);
+}
+function encodeWitnessedReceiptOption(writer, receipt) {
+    if (!receipt) {
+        writer.pushByte(0);
+        return;
+    }
+    writer
+        .pushByte(1)
+        .pushFixed(receipt.digest, 32, "receipt digest")
+        .pushU64(receipt.resultingState.nonce)
+        .pushFixed(receipt.resultingState.commitment, 32, "receipt resulting state");
+}
+export function resumeBodyBytes(request) {
+    const writer = new ByteWriter()
+        .pushU16(request.context.wireVersion)
+        .pushByte(SESSION_RESUME_REQUEST_TAG);
+    encodeContext(writer, request.context);
+    writer.pushU64(request.cursorSequence);
+    encodeWitnessedReceiptOption(writer, request.witnessedReceipt);
+    writer
+        .pushFixed(request.clientNonce, 32, "client nonce")
+        .pushFixed(request.challenge, 74, "session challenge");
+    return writer.bytes();
+}
+export function resumeSigningBytes(request) {
+    return frameSigningBytes(RESUME_DOMAIN, resumeBodyBytes(request));
+}
+export function encodeResumeFrame(request, signature) {
+    return signedFrame(resumeBodyBytes(request), signature);
+}

package/dist/settlement.d.ts

@@ -0,0 +1,56 @@
+export interface SeatEntitlement {
+    seat: number;
+    amount: bigint;
+}
+export interface TerminalState {
+    tunnelId: Uint8Array;
+    stateCommitment: Uint8Array;
+    nonce: bigint;
+    timestamp: bigint;
+    transcriptRoot: Uint8Array;
+    receiptCount: bigint;
+    outcomeSchemaVersion: number;
+    entitlements: SeatEntitlement[];
+    outcome: Uint8Array;
+}
+export declare function encodeTerminalState(state: TerminalState): Uint8Array;
+export declare function decodeTerminalState(bytes: Uint8Array): TerminalState;
+export declare function anchorDomainId(anchorContext: Uint8Array, purpose: Uint8Array): Uint8Array;
+export declare function recomputeSettlementDigest(anchorContext: Uint8Array, terminalState: TerminalState): Uint8Array;
+export interface ConsentPrompt {
+    version: number;
+    terminal: {
+        execution_id: string;
+        nonce: number;
+        state_commitment: string;
+    };
+    anchor_context: string;
+    encoded_terminal_state: string;
+}
+export interface ConsentRequest {
+    version: number;
+    terminal: ConsentPrompt["terminal"];
+    seat: number;
+    decision: {
+        kind: "consent";
+        signature: string;
+    };
+}
+export interface ConsentDisclosure {
+    prompt: ConsentPrompt;
+    seat: number;
+    executionId: Uint8Array;
+    finalNonce: bigint;
+    finalCommitment: Uint8Array;
+    entitlement: bigint;
+}
+/** Every disagreement is named before a caller is allowed to touch the seat
+ *  key. Rust `consent_to_terminal` refuses first, then signs; this is the
+ *  TypeScript half of that order. */
+export declare function verifyConsentDisclosure(args: ConsentDisclosure): void;
+export declare function buildConsentRequest(args: ConsentDisclosure & {
+    signature: Uint8Array;
+}): ConsentRequest;
+export declare function settlementConsentPath(executionIdHex: string): string;
+export declare function authorityOriginFromSessionBase(sessionBaseUrl: string): string;
+export declare function digestForPrompt(prompt: ConsentPrompt): Uint8Array;

package/dist/settlement.js

@@ -0,0 +1,117 @@
+import { ByteReader, ByteWriter, equalBytes, fromHex, textBytes, toHex0x, } from "./bytes.js";
+import { digestFramed } from "./crypto.js";
+const ANCHOR_DOMAIN_ID_V1 = textBytes("arena_tunnel::anchor_domain_id_v1");
+const SETTLEMENT_PURPOSE = textBytes("arena_tunnel::settlement");
+export function encodeTerminalState(state) {
+    const writer = new ByteWriter()
+        .pushU16(1)
+        .pushFixed(state.tunnelId, 32, "tunnel id")
+        .pushFixed(state.stateCommitment, 32, "state commitment")
+        .pushU64(state.nonce)
+        .pushU64(state.timestamp)
+        .pushFixed(state.transcriptRoot, 32, "transcript root")
+        .pushU64(state.receiptCount)
+        .pushU16(state.outcomeSchemaVersion)
+        .pushU16(state.entitlements.length);
+    for (const entitlement of state.entitlements) {
+        writer.pushU16(entitlement.seat).pushU64(entitlement.amount);
+    }
+    writer.pushU16(state.outcome.length).pushBytes(state.outcome);
+    return writer.bytes();
+}
+export function decodeTerminalState(bytes) {
+    const reader = new ByteReader(bytes);
+    const wire = reader.readU16("wire version");
+    if (wire !== 1)
+        throw new Error(`unsupported terminal-state wire ${wire}`);
+    const tunnelId = reader.readFixed(32, "tunnel id");
+    const stateCommitment = reader.readFixed(32, "state commitment");
+    const nonce = reader.readU64("nonce");
+    const timestamp = reader.readU64("timestamp");
+    const transcriptRoot = reader.readFixed(32, "transcript root");
+    const receiptCount = reader.readU64("receipt count");
+    const outcomeSchemaVersion = reader.readU16("outcome schema version");
+    const count = reader.readU16("entitlement count");
+    const entitlements = [];
+    for (let i = 0; i < count; i++) {
+        entitlements.push({
+            seat: reader.readU16("entitlement seat"),
+            amount: reader.readU64("entitlement amount"),
+        });
+    }
+    const outcomeLen = reader.readU16("outcome length");
+    const outcome = reader.readFixed(outcomeLen, "outcome");
+    reader.finish();
+    return {
+        tunnelId,
+        stateCommitment,
+        nonce,
+        timestamp,
+        transcriptRoot,
+        receiptCount,
+        outcomeSchemaVersion,
+        entitlements,
+        outcome,
+    };
+}
+export function anchorDomainId(anchorContext, purpose) {
+    const payload = new ByteWriter()
+        .pushFixed(anchorContext, 32, "anchor context")
+        .pushU64(purpose.length)
+        .pushBytes(purpose)
+        .bytes();
+    return digestFramed(ANCHOR_DOMAIN_ID_V1, payload);
+}
+export function recomputeSettlementDigest(anchorContext, terminalState) {
+    const domain = anchorDomainId(anchorContext, SETTLEMENT_PURPOSE);
+    return digestFramed(domain, encodeTerminalState(terminalState));
+}
+/** Every disagreement is named before a caller is allowed to touch the seat
+ *  key. Rust `consent_to_terminal` refuses first, then signs; this is the
+ *  TypeScript half of that order. */
+export function verifyConsentDisclosure(args) {
+    if (args.prompt.version !== 1)
+        throw new Error(`unsupported consent version ${args.prompt.version}`);
+    const promptExecution = fromHex(args.prompt.terminal.execution_id);
+    if (!equalBytes(promptExecution, args.executionId) || promptExecution.length !== 32)
+        throw new Error("consent prompt names another execution");
+    const preimage = fromHex(args.prompt.encoded_terminal_state);
+    const terminal = decodeTerminalState(preimage);
+    const encoded = encodeTerminalState(terminal);
+    if (!equalBytes(encoded, preimage))
+        throw new Error("terminal-state preimage is not canonical");
+    if (terminal.nonce !== BigInt(args.prompt.terminal.nonce) ||
+        !equalBytes(terminal.stateCommitment, fromHex(args.prompt.terminal.state_commitment)))
+        throw new Error("preimage does not match disclosed terminal");
+    if (terminal.nonce !== args.finalNonce ||
+        !equalBytes(terminal.stateCommitment, args.finalCommitment))
+        throw new Error("disclosed terminal is not the terminal this seat was delivered");
+    const row = terminal.entitlements.find((entry) => entry.seat === args.seat);
+    if (!row)
+        throw new Error("terminal state pays this seat nothing");
+    if (row.amount !== args.entitlement)
+        throw new Error(`terminal pays ${row.amount}, seat view says ${args.entitlement}`);
+}
+export function buildConsentRequest(args) {
+    verifyConsentDisclosure(args);
+    return {
+        version: 1,
+        terminal: args.prompt.terminal,
+        seat: args.seat,
+        decision: { kind: "consent", signature: toHex0x(args.signature) },
+    };
+}
+export function settlementConsentPath(executionIdHex) {
+    const hex = executionIdHex.replace(/^0x/, "");
+    return `/open/v1/authority/executions/${hex}/settlements`;
+}
+export function authorityOriginFromSessionBase(sessionBaseUrl) {
+    const idx = sessionBaseUrl.indexOf("/v1/exec/");
+    if (idx <= 0)
+        throw new Error(`admission session_base_url is not an execution session URL: ${sessionBaseUrl}`);
+    return sessionBaseUrl.slice(0, idx);
+}
+export function digestForPrompt(prompt) {
+    const terminal = decodeTerminalState(fromHex(prompt.encoded_terminal_state));
+    return recomputeSettlementDigest(fromHex(prompt.anchor_context), terminal);
+}

package/dist/texas.d.ts

@@ -0,0 +1,52 @@
+export type TexasAction = {
+    type: "fold";
+} | {
+    type: "check";
+} | {
+    type: "call";
+} | {
+    type: "wagerTo";
+    amount: bigint;
+};
+export interface TexasLegalActions {
+    canFold: boolean;
+    canCheck: boolean;
+    canCall: boolean;
+    minWagerTo: bigint | null;
+    maxWagerTo: bigint | null;
+}
+export declare function encodeAction(action: TexasAction): Uint8Array;
+export declare function decodeAction(bytes: Uint8Array): TexasAction;
+export declare function encodeLegalActions(legal: TexasLegalActions): Uint8Array;
+export declare function decodeLegalActions(bytes: Uint8Array): TexasLegalActions;
+export type Suit = "c" | "d" | "h" | "s";
+export type Rank = "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "T" | "J" | "Q" | "K" | "A";
+export interface Card {
+    rank: Rank;
+    suit: Suit;
+    /** rank then suit, `Ah` for the ace of hearts */
+    label: string;
+    /** the wire byte, 0..51 */
+    value: number;
+}
+/** The card a wire byte names. Refuses anything past the 52-card deck. */
+export declare function cardFromByte(value: number): Card;
+export interface TexasSeatView {
+    /** the seat this view was cut for */
+    receivingSeat: number;
+    /** the seat's hole cards; null once it has folded or the hand is over */
+    holeCards: [Card, Card] | null;
+    /** the canonical match state, framed but not decoded */
+    state: Uint8Array;
+}
+/** Decode one seat's view down to what the seat can act on.
+ *
+ *  Framing is checked exactly — the header, the state length against the
+ *  payload, the presence byte, and that nothing trails the last card — so a
+ *  payload that is not a view fails here rather than yielding two bytes that
+ *  look like cards. What is not checked is the state's own canonical form;
+ *  that needs the state codec, and is the Rust decoder's job until this side
+ *  carries one. */
+export declare function decodeParticipantView(bytes: Uint8Array): TexasSeatView;
+export declare function decodePlayerActionInput(bytes: Uint8Array, expectedNonce: bigint, expectedCommitment: Uint8Array): TexasAction;
+export declare function pickAction(legal: TexasLegalActions, strategy: "fold-heavy" | "all-in"): TexasAction;

package/dist/texas.js

@@ -0,0 +1,217 @@
+/* Canonical Texas Hold'em action and legal-action codecs, byte-identical to
+ * `arena_texas_holdem::wire`. The session client needs these to turn a view's
+ * legal-action schema into a move and to put that move on the action payload.
+ */
+import { ByteReader, ByteWriter } from "./bytes.js";
+const WIRE_VERSION = 1;
+const PROTOCOL_VERSION = 1;
+const SCHEMA_VERSION = 1;
+function pushHeader(writer) {
+    writer
+        .pushU16(WIRE_VERSION)
+        .pushU16(PROTOCOL_VERSION)
+        .pushU16(SCHEMA_VERSION);
+}
+function readHeader(reader) {
+    const wire = reader.readU16("wire version");
+    if (wire !== WIRE_VERSION)
+        throw new Error(`unsupported texas wire ${wire}`);
+    const protocol = reader.readU16("protocol version");
+    if (protocol !== PROTOCOL_VERSION)
+        throw new Error(`invalid texas protocol ${protocol}`);
+    const schema = reader.readU16("schema version");
+    if (schema !== SCHEMA_VERSION)
+        throw new Error(`invalid texas schema ${schema}`);
+}
+function readBool(reader, field) {
+    const tag = reader.readByte(field);
+    if (tag === 0)
+        return false;
+    if (tag === 1)
+        return true;
+    throw new Error(`invalid ${field} tag ${tag}`);
+}
+function readOptionalWager(reader, presenceField, valueField) {
+    const tag = reader.readByte(presenceField);
+    if (tag === 0)
+        return null;
+    if (tag === 1)
+        return reader.readU64(valueField);
+    throw new Error(`invalid ${presenceField} tag ${tag}`);
+}
+export function encodeAction(action) {
+    if (action.type === "wagerTo" && action.amount === 0n)
+        throw new Error("wager total must be nonzero");
+    const writer = new ByteWriter();
+    pushHeader(writer);
+    switch (action.type) {
+        case "fold":
+            writer.pushByte(0);
+            break;
+        case "check":
+            writer.pushByte(1);
+            break;
+        case "call":
+            writer.pushByte(2);
+            break;
+        case "wagerTo":
+            writer.pushByte(3).pushU64(action.amount);
+            break;
+    }
+    return writer.bytes();
+}
+export function decodeAction(bytes) {
+    const reader = new ByteReader(bytes);
+    readHeader(reader);
+    const tag = reader.readByte("action tag");
+    let action;
+    switch (tag) {
+        case 0:
+            action = { type: "fold" };
+            break;
+        case 1:
+            action = { type: "check" };
+            break;
+        case 2:
+            action = { type: "call" };
+            break;
+        case 3: {
+            const amount = reader.readU64("wager total");
+            if (amount === 0n)
+                throw new Error("wager total must be nonzero");
+            action = { type: "wagerTo", amount };
+            break;
+        }
+        default:
+            throw new Error(`invalid action tag ${tag}`);
+    }
+    reader.finish();
+    return action;
+}
+export function encodeLegalActions(legal) {
+    if ((legal.minWagerTo === null) !== (legal.maxWagerTo === null) ||
+        (legal.minWagerTo !== null &&
+            legal.maxWagerTo !== null &&
+            legal.minWagerTo > legal.maxWagerTo))
+        throw new Error("wager bounds must be paired and ordered");
+    const writer = new ByteWriter();
+    pushHeader(writer);
+    writer
+        .pushByte(legal.canFold ? 1 : 0)
+        .pushByte(legal.canCheck ? 1 : 0)
+        .pushByte(legal.canCall ? 1 : 0);
+    if (legal.minWagerTo === null)
+        writer.pushByte(0);
+    else
+        writer.pushByte(1).pushU64(legal.minWagerTo);
+    if (legal.maxWagerTo === null)
+        writer.pushByte(0);
+    else
+        writer.pushByte(1).pushU64(legal.maxWagerTo);
+    return writer.bytes();
+}
+export function decodeLegalActions(bytes) {
+    const reader = new ByteReader(bytes);
+    readHeader(reader);
+    const legal = {
+        canFold: readBool(reader, "can_fold"),
+        canCheck: readBool(reader, "can_check"),
+        canCall: readBool(reader, "can_call"),
+        minWagerTo: readOptionalWager(reader, "min_wager_to presence", "min_wager_to"),
+        maxWagerTo: readOptionalWager(reader, "max_wager_to presence", "max_wager_to"),
+    };
+    reader.finish();
+    const encoded = encodeLegalActions(legal);
+    if (encoded.length !== bytes.length ||
+        !encoded.every((b, i) => b === bytes[i]))
+        throw new Error("non-canonical legal actions");
+    return legal;
+}
+const RANKS = [
+    "2",
+    "3",
+    "4",
+    "5",
+    "6",
+    "7",
+    "8",
+    "9",
+    "T",
+    "J",
+    "Q",
+    "K",
+    "A",
+];
+const SUITS = ["c", "d", "h", "s"];
+/** The card a wire byte names. Refuses anything past the 52-card deck. */
+export function cardFromByte(value) {
+    if (!Number.isInteger(value) || value < 0 || value > 51)
+        throw new Error(`not a card byte: ${value}`);
+    const suit = SUITS[Math.floor(value / 13)];
+    const rank = RANKS[value % 13];
+    return { rank, suit, label: `${rank}${suit}`, value };
+}
+/** Decode one seat's view down to what the seat can act on.
+ *
+ *  Framing is checked exactly — the header, the state length against the
+ *  payload, the presence byte, and that nothing trails the last card — so a
+ *  payload that is not a view fails here rather than yielding two bytes that
+ *  look like cards. What is not checked is the state's own canonical form;
+ *  that needs the state codec, and is the Rust decoder's job until this side
+ *  carries one. */
+export function decodeParticipantView(bytes) {
+    const reader = new ByteReader(bytes);
+    readHeader(reader);
+    const length = reader.readU64("participant view state length");
+    if (length > BigInt(reader.remaining()))
+        throw new Error("participant view state length exceeds the payload");
+    const state = reader.readFixed(Number(length), "participant view state");
+    const receivingSeat = reader.readU16("participant view recipient");
+    const presence = reader.readByte("private card presence");
+    let holeCards = null;
+    if (presence === 1) {
+        holeCards = [
+            cardFromByte(reader.readByte("first private card")),
+            cardFromByte(reader.readByte("second private card")),
+        ];
+    }
+    else if (presence !== 0) {
+        throw new Error(`invalid private card presence ${presence}`);
+    }
+    reader.finish();
+    return { receivingSeat, holeCards, state };
+}
+export function decodePlayerActionInput(bytes, expectedNonce, expectedCommitment) {
+    const reader = new ByteReader(bytes);
+    readHeader(reader);
+    const nonce = reader.readU64("expected state nonce");
+    const commitment = reader.readFixed(32, "expected state commitment");
+    if (nonce !== expectedNonce ||
+        !commitment.every((b, i) => b === expectedCommitment[i]))
+        throw new Error("transition input expected state mismatch");
+    const tag = reader.readByte("transition input tag");
+    if (tag !== 0)
+        throw new Error("transition input is not a player action");
+    const length = reader.readU16("action length");
+    const action = decodeAction(reader.readFixed(length, "action"));
+    reader.finish();
+    return action;
+}
+export function pickAction(legal, strategy) {
+    if (strategy === "all-in") {
+        if (legal.maxWagerTo !== null)
+            return { type: "wagerTo", amount: legal.maxWagerTo };
+        if (legal.canCall)
+            return { type: "call" };
+        if (legal.canCheck)
+            return { type: "check" };
+        return { type: "fold" };
+    }
+    if (legal.canFold)
+        return { type: "fold" };
+    if (legal.canCheck)
+        return { type: "check" };
+    if (legal.canCall)
+        return { type: "call" };
+    return { type: "fold" };
+}

package/dist/tour.d.ts

@@ -0,0 +1,101 @@
+import type { AgentKeypair } from "./keypair.js";
+export type TourKind = "playground" | "tournament";
+export interface TourClient {
+    productUrl: string;
+    agent: AgentKeypair;
+    /** 32 bytes */
+    agentId: Uint8Array;
+}
+export type TourEntry = {
+    state: "waiting";
+    waiting: number;
+    seatsNeeded: number;
+    fillAtMs: number;
+    /** how many seats the house will take at `fillAtMs` if nobody else comes */
+    houseSeatsAtFill?: number;
+}
+/** The queue composed an offer this agent accepts and plays itself. Since
+ *  ADR-0175 this is the answer for every external agent: the product holds
+ *  no key that could sign this seat's moves. */
+ | {
+    state: "offered";
+    offerId: string;
+    seat: number;
+    settlement: string;
+    mode: string;
+} | {
+    state: "seated";
+    tableId: string;
+    settlement: string;
+    mode: string;
+    executionId?: string;
+    seats: {
+        seat: number;
+        occupant: string;
+    }[];
+} | {
+    state: "closed" | "unpaid";
+    [key: string]: unknown;
+};
+export declare function enterTour(client: TourClient, tour: TourKind): Promise<TourEntry>;
+export interface QueueOptions {
+    /** How long to keep polling before giving up. */
+    timeoutMs?: number;
+    /** Gap between polls. The queue answers immediately; this paces the caller. */
+    pollMs?: number;
+    onWaiting?: (entry: Extract<TourEntry, {
+        state: "waiting";
+    }>) => void;
+}
+/** Enter and poll until seated.
+ *
+ *  Waiting is the normal answer, not a failure: the playground holds a place
+ *  for real opponents and only house-fills the leftover seats once the wait
+ *  elapses, so an agent that gives up early is the reason a table stays short.
+ *  The default timeout therefore outlasts the server's own fill wait. */
+export declare function queueUntilSeated(client: TourClient, tour: TourKind, options?: QueueOptions): Promise<Extract<TourEntry, {
+    state: "seated" | "offered";
+}>>;
+export interface TurnView {
+    state: string;
+    seat?: number;
+    handIndex?: number;
+    cards?: string[];
+    board?: string[];
+    pot?: number;
+    callAmount?: number;
+    chips?: {
+        seat: number;
+        chips: number;
+    }[];
+    canFold?: boolean;
+    canCheck?: boolean;
+    canCall?: boolean;
+    actsForYouAtMs?: number;
+    [key: string]: unknown;
+}
+export declare function readPosition(client: TourClient, tableId: string): Promise<TurnView>;
+export interface TableMove {
+    action: "fold" | "check" | "call" | "wager";
+    wagerTo?: number;
+    say?: string;
+}
+export declare function act(client: TourClient, tableId: string, move: TableMove): Promise<TurnView>;
+/** The reference strategy: never wager, call only what is free. It exists so
+ *  the journey can be demonstrated end to end, not because it plays well - an
+ *  agent that reasons about the hand replaces `decide`. */
+export declare function foldHeavy(turn: TurnView): TableMove;
+export interface TourPlayReport {
+    outcome: string;
+    committedActions: number;
+    hands: number;
+}
+/** Drive a seated tour table to a terminal disposition.
+ *
+ *  A lapsed turn is not an error: the authority acts for a silent seat on its
+ *  own clock, so a slow decision costs the hand rather than the match, and the
+ *  loop keeps reading. Only a refusal the server calls terminal stops it. */
+export declare function playTour(client: TourClient, tableId: string, decide?: (turn: TurnView) => TableMove, options?: {
+    pollMs?: number;
+    onTurn?: (turn: TurnView, move: TableMove) => void;
+}): Promise<TourPlayReport>;