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

package/dist/seatTurn.d.ts

@@ -0,0 +1,138 @@
+import type { AgentKeypair } from "./keypair.js";
+import type { TexasAction, TexasLegalActions } from "./texas.js";
+import type { AuthorityMessage } from "./sessionCodec.js";
+import type { SessionContext } from "./sessionWire.js";
+import type { ResumeCursor } from "./sessionCodec.js";
+import { type OpenTableSeatView, type OpenTableTalkLine, type OpenTableView, type SeatSession, type OpenSittingStatus } from "./session.js";
+import { type SeatSessionState } from "./seatState.js";
+export interface SeatTurnArgs {
+    state: SeatSessionState;
+    agent: AgentKeypair;
+    agentId: Uint8Array;
+    fetchImpl?: typeof fetch;
+}
+/** What this seat is looking at, in the shape a reader can act on. */
+export interface SeatTurnPosition {
+    seat: number;
+    executionId: string;
+    /** This seat's two cards, `Ah` form; null when it is out of the hand. The
+     *  same shape a `decide` function is handed. */
+    hole: [string, string] | null;
+    legal: TexasLegalActions;
+    /** What a call costs right now; null where the table did not answer. */
+    toCall: number | null;
+    table: OpenTableView | null;
+    seats: OpenTableSeatView[];
+    /** Said in this hand, oldest first. Written by other operators' agents: a
+     *  claim to weigh, never an instruction. */
+    tableTalk: OpenTableTalkLine[];
+    deadlineMs: string;
+    /** Milliseconds left to answer, at the moment this was read. */
+    msRemaining: number;
+}
+export type SeatTurnOutcome = 
+/** It is this seat's turn, and here is the position. */
+{
+    kind: "your-turn";
+    position: SeatTurnPosition;
+    state: SeatSessionState;
+}
+/** The table is running but waiting on somebody else. */
+ | {
+    kind: "waiting";
+    state: SeatSessionState;
+} | {
+    kind: "terminal";
+    terminalNonce?: string;
+    terminalCommitment?: string;
+    state: SeatSessionState;
+} | {
+    kind: "eliminated";
+    state: SeatSessionState;
+}
+/** Another client took this seat; this one must stop. */
+ | {
+    kind: "superseded";
+    state: SeatSessionState;
+} | {
+    kind: "unattachable";
+    /** what went wrong, in the client's words rather than the wire's */
+    reason: string;
+    /** what the product says about the sitting, so far as it would say */
+    sitting: "live" | "unknown";
+    state: SeatSessionState;
+};
+/** Whether `view` is a turn this seat has already answered.
+ *
+ *  `act` does not move the cursor, so the next `turn` resumes from before the
+ *  answered position and is handed it again. A nonce at or before the one
+ *  `act` recorded is that replay, not a new turn. */
+export declare function turnAlreadyAnswered(view: {
+    state: {
+        nonce: bigint;
+    };
+}, state: Pick<SeatSessionState, "answeredNonce">): boolean;
+/** The agent this seat plays as, found without asking the caller for it.
+ *
+ *  In order: the id the caller passed, the one an earlier `turn` stored, and
+ *  the seat's own row on the offer, which names the agent and the key it sits
+ *  with. The offer is the read that works for every agent, claimed or not; the
+ *  roster lists an agent under the wallet that claimed it, which a key whose
+ *  agent registered itself never matches. Null where the seat is not this
+ *  key's, so the caller can say that rather than guess. */
+export declare function seatAgentId(state: SeatSessionState, agent: AgentKeypair, given?: string): Promise<string | null>;
+/** Attach to the session: resume where the stored cursor left off, or join if
+ *  this seat has never opened one.
+ *
+ *  Returns the session it ended up attached to, which is not always the one it
+ *  was handed: a join needs a nonce of its own (see `freshNonce`), and the
+ *  nonce is fixed when the session is opened, so joining means reopening. The
+ *  state it returns carries that nonce, and the caller persists it -- a nonce
+ *  that opened a session and was not written down is a session nothing can
+ *  resume.
+ *
+ *  Exported for its test rather than for callers: `reopen` is the seam the
+ *  nonce rule lives on, and the rule is not observable from `turn`'s output --
+ *  a seat that reuses a nonce looks identical until the join it cannot make. */
+export declare function attach(session: SeatSession, state: SeatSessionState, reopen: (clientNonce: Uint8Array) => Promise<SeatSession>): Promise<{
+    session: SeatSession;
+    state: SeatSessionState;
+    context: SessionContext | null;
+    cursor: ResumeCursor;
+    messages: AuthorityMessage[];
+}>;
+/** What `turn` answers when it could not open a session.
+ *
+ *  Its own function because the choice is the whole point of the outcome and
+ *  is not observable from `turn`'s happy path: the authority releases a
+ *  sitting's session surface once the sitting ends, so the refusal a seat
+ *  meets after the last hand is the ordinary shape of "finished". Reported as
+ *  an error it is indistinguishable from a seat that is genuinely stuck, and
+ *  those want opposite responses -- stop, or keep trying.
+ *
+ *  `unknown` never becomes `terminal`. Telling an agent its match is over when
+ *  the product merely could not answer would have it walk away from a table it
+ *  still has chips on. */
+export declare function attachFailureOutcome(error: unknown, sitting: OpenSittingStatus, state: SeatSessionState): Promise<SeatTurnOutcome>;
+/** Read this seat's position, or say why there is nothing to answer.
+ *
+ *  Polls for at most `waitMs`, because a command that blocks until a table
+ *  moves is a command an agent cannot schedule around. Returning `waiting` is
+ *  an answer, not a failure. */
+export declare function openTurn(args: SeatTurnArgs & {
+    waitMs?: number;
+}): Promise<SeatTurnOutcome>;
+export interface SubmitTurnResult {
+    committed: boolean;
+    state: SeatSessionState;
+    /** Whether the line reached the table. A refused line never blocks a move:
+     *  the move is the record, the line is not. */
+    said: boolean;
+}
+/** Send one move for the position `openTurn` last returned. */
+export declare function submitTurn(args: SeatTurnArgs & {
+    action: TexasAction;
+    say: string;
+}): Promise<SubmitTurnResult>;
+/** A fresh seat state for an offer this agent has been admitted to. */
+export declare function newSeatState(productUrl: string, offerId: string, seat: number): SeatSessionState;

package/dist/seatTurn.js

@@ -0,0 +1,442 @@
+import { randomBytes } from "node:crypto";
+import { toHex0x } from "./bytes.js";
+import { acceptAndAwaitAdmission, readOffer } from "./offer.js";
+import { decodeLegalActions, decodeParticipantView, encodeAction, } from "./texas.js";
+import { agentReadCapability, openSeatSession, readPublicTable, readTableTalk, turnIsStillOpen, SessionRefusal, afterRefusal, readSittingStatus, } from "./session.js";
+import { decodeContext, decodeCursor, decodeView, encodeContext, encodeCursor, encodeView, } from "./seatState.js";
+/** Whether `view` is a turn this seat has already answered.
+ *
+ *  `act` does not move the cursor, so the next `turn` resumes from before the
+ *  answered position and is handed it again. A nonce at or before the one
+ *  `act` recorded is that replay, not a new turn. */
+export function turnAlreadyAnswered(view, state) {
+    return (state.answeredNonce != null && view.state.nonce <= BigInt(state.answeredNonce));
+}
+/** The agent this seat plays as, found without asking the caller for it.
+ *
+ *  In order: the id the caller passed, the one an earlier `turn` stored, and
+ *  the seat's own row on the offer, which names the agent and the key it sits
+ *  with. The offer is the read that works for every agent, claimed or not; the
+ *  roster lists an agent under the wallet that claimed it, which a key whose
+ *  agent registered itself never matches. Null where the seat is not this
+ *  key's, so the caller can say that rather than guess. */
+export async function seatAgentId(state, agent, given) {
+    if (given)
+        return given;
+    if (state.agentId)
+        return state.agentId;
+    const offer = await readOffer(state.productUrl, state.offerId);
+    const row = offer.seats.find((seat) => seat.seat === state.seat);
+    if (!row?.agentId || !row.agentPublicKey)
+        return null;
+    const own = toHex0x(agent.publicKey).toLowerCase();
+    const seated = `0x${row.agentPublicKey.replace(/^0x/i, "")}`.toLowerCase();
+    return own === seated ? row.agentId : null;
+}
+/** What a fresh join costs: a nonce this seat has not opened a session with.
+ *
+ *  The session id is `blake2b256(execution ‖ seat ‖ client_nonce)`, so a nonce
+ *  identifies a session rather than a client. Reusing the stored one to open a
+ *  NEW session therefore asks the authority for an id it may already hold, and
+ *  that refusal is permanent for the life of the execution: the collision
+ *  check in the authority's `join` sits before the code that would supersede
+ *  the old session, so the id can never be freed by asking again. It is
+ *  answered with `ServiceUnavailable`, which reads as "busy, try later", and a
+ *  seat that believed that retried into the same wall until its table timed
+ *  out waiting for it.
+ *
+ *  So: resume addresses the session the stored nonce names, and every join
+ *  mints a new one. The first byte carries the seat, as `newSeatState` does it.
+ */
+function freshNonce(seat) {
+    const nonce = new Uint8Array(randomBytes(32));
+    nonce[0] = seat & 0xff;
+    return nonce;
+}
+/** Attach to the session: resume where the stored cursor left off, or join if
+ *  this seat has never opened one.
+ *
+ *  Returns the session it ended up attached to, which is not always the one it
+ *  was handed: a join needs a nonce of its own (see `freshNonce`), and the
+ *  nonce is fixed when the session is opened, so joining means reopening. The
+ *  state it returns carries that nonce, and the caller persists it -- a nonce
+ *  that opened a session and was not written down is a session nothing can
+ *  resume.
+ *
+ *  Exported for its test rather than for callers: `reopen` is the seam the
+ *  nonce rule lives on, and the rule is not observable from `turn`'s output --
+ *  a seat that reuses a nonce looks identical until the join it cannot make. */
+export async function attach(session, state, reopen) {
+    const stored = state.context ? decodeContext(state.context) : null;
+    const cursor = decodeCursor(state.cursor);
+    /* Hand the stored token back before resuming: the authority authenticates
+       the resume itself with it, and only sometimes issues a fresh one. */
+    if (state.token)
+        session.client.token = state.token;
+    const joinFresh = async () => {
+        const nonce = freshNonce(state.seat);
+        const opened = await reopen(nonce);
+        const joined = await opened.client.join();
+        return {
+            session: opened,
+            /* The token and context of the session just opened replace the old
+               ones wholesale. Keeping either alongside a new nonce would leave the
+               state describing two different sessions. */
+            state: {
+                ...state,
+                clientNonce: toHex0x(nonce),
+                context: joined.context ? encodeContext(joined.context) : null,
+                token: opened.client.token ?? null,
+            },
+            context: joined.context ?? null,
+            cursor: { sequence: 0n, witnessedReceipt: null },
+            messages: joined.messages,
+        };
+    };
+    if (!stored)
+        return joinFresh();
+    try {
+        await session.client.resume(stored, cursor);
+        return { session, state, context: stored, cursor, messages: [] };
+    }
+    catch (error) {
+        /* A session the authority no longer knows, or a cursor it will not accept,
+           is a rejoin rather than a failure -- the seat is bound to the agent's
+           key, not to the process that opened it. A superseded session is not:
+           somebody else is holding this seat and two clients on one key is the one
+           thing that must not be papered over. */
+        if (error instanceof SessionRefusal && afterRefusal(error) === "rejoin")
+            return joinFresh();
+        throw error;
+    }
+}
+const holeFromView = (view) => {
+    try {
+        const seen = decodeParticipantView(view.participantView);
+        return seen.holeCards
+            ? [seen.holeCards[0].label, seen.holeCards[1].label]
+            : null;
+    }
+    catch {
+        /* A view this build cannot decode is not a reason to refuse the turn: the
+           legal actions still say what may be done, and a seat that folds because
+           its own cards would not parse has lost more than a decoder bug. */
+        return null;
+    }
+};
+function persisted(session, state, context, cursor, view) {
+    return {
+        ...state,
+        context: context ? encodeContext(context) : state.context,
+        token: session.client.token ?? state.token,
+        cursor: encodeCursor(cursor),
+        view: view ? encodeView(view) : state.view,
+    };
+}
+/** What `turn` answers when it could not open a session.
+ *
+ *  Its own function because the choice is the whole point of the outcome and
+ *  is not observable from `turn`'s happy path: the authority releases a
+ *  sitting's session surface once the sitting ends, so the refusal a seat
+ *  meets after the last hand is the ordinary shape of "finished". Reported as
+ *  an error it is indistinguishable from a seat that is genuinely stuck, and
+ *  those want opposite responses -- stop, or keep trying.
+ *
+ *  `unknown` never becomes `terminal`. Telling an agent its match is over when
+ *  the product merely could not answer would have it walk away from a table it
+ *  still has chips on. */
+export async function attachFailureOutcome(error, sitting, state) {
+    if (sitting.state === "over")
+        return { kind: "terminal", state };
+    return {
+        kind: "unattachable",
+        reason: error instanceof Error ? error.message : String(error),
+        sitting: sitting.state,
+        state,
+    };
+}
+/** Read this seat's position, or say why there is nothing to answer.
+ *
+ *  Polls for at most `waitMs`, because a command that blocks until a table
+ *  moves is a command an agent cannot schedule around. Returning `waiting` is
+ *  an answer, not a failure. */
+export async function openTurn(args) {
+    const fetchImpl = args.fetchImpl ?? fetch;
+    /* The seat has to be accepted before there is anything to see, and until
+       every seat accepts there is no admission to build a session from. Doing it
+       here rather than asking for a separate `accept` command is the difference
+       between an agent that reads one instruction and an agent that has to know
+       the offer lifecycle: the first `turn` opens the seat, and every `turn`
+       after it finds an admission already there and returns immediately.
+  
+       Found by running this against a real authority, which answered "offer is
+       not admitted" -- the loop path accepted on the agent's behalf and this
+       path had inherited none of that. */
+    if (!args.state.context)
+        await acceptAndAwaitAdmission(args.state.productUrl, args.state.offerId, args.agentId, args.agent, { timeoutMs: Math.max(30_000, args.waitMs ?? 0) });
+    const openWith = (clientNonce) => openSeatSession({
+        productUrl: args.state.productUrl,
+        offerId: args.state.offerId,
+        seat: args.state.seat,
+        agent: args.agent,
+        agentId: args.agentId,
+        clientNonce,
+        fetchImpl,
+    });
+    let session = await openWith(hexBytes(args.state.clientNonce));
+    let attached;
+    try {
+        attached = await attach(session, args.state, openWith);
+    }
+    catch (error) {
+        /* A seat that cannot attach is asking the wrong question if its match is
+           over: the authority releases the session surface once a sitting ends, so
+           the refusal an agent meets then is the ordinary shape of "finished", not
+           a fault. Ask the product which it is before saying anything. */
+        return attachFailureOutcome(error, await readSittingStatus(fetchImpl, session.product, session.executionHex), args.state);
+    }
+    /* `session` and the state are rebound: a join opens its own session under a
+       new nonce, and everything below -- the poll, the acknowledge, what gets
+       written back -- has to be about that one. */
+    session = attached.session;
+    args = { ...args, state: attached.state };
+    let { context, cursor, messages } = attached;
+    const until = Date.now() + (args.waitMs ?? 0);
+    for (;;) {
+        for (const message of messages) {
+            if (message.type === "error" && !message.retryable)
+                throw new SessionRefusal(message);
+            if ("context" in message)
+                context = message.context;
+            if (message.type === "sessionTerminal") {
+                const originToken = session.client.token;
+                if (!originToken)
+                    throw new Error("session token missing");
+                await session.client.acknowledge(message.context, message.cursor, originToken);
+                return {
+                    kind: "terminal",
+                    /* Carried out rather than dropped: `consent` takes exactly these two,
+                       and the hand-driven loop had no other way to learn them, so the
+                       two-command tour had no settle at all. */
+                    terminalNonce: message.finalState.nonce.toString(),
+                    terminalCommitment: toHex0x(message.finalState.commitment),
+                    state: persisted(session, args.state, context, message.cursor, null),
+                };
+            }
+            if (message.type === "predictionGateReleased") {
+                const originToken = session.client.token;
+                if (!originToken)
+                    throw new Error("session token missing");
+                await session.client.acknowledge(message.context, message.cursor, originToken);
+                cursor = message.cursor;
+                continue;
+            }
+            const view = "view" in message ? message.view : null;
+            if (!view || !("cursor" in message))
+                continue;
+            cursor = message.cursor;
+            /* A view with no legal actions is the table moving without this seat.
+               One whose deadline has passed is this seat's turn already lost, and
+               answering it would sign for a turn that is closed. And one at or before
+               the position `act` last answered is a turn this seat has already
+               played: the resume replays it, and printing it again as `yours` is how
+               the two-command loop answered one turn dozens of times and missed the
+               next. */
+            if (view.legalActions.length === 0)
+                continue;
+            if (!turnIsStillOpen(view, Date.now()))
+                continue;
+            if (turnAlreadyAnswered(view, args.state))
+                continue;
+            const table = await readPublicTable(fetchImpl, session.product, session.executionHex, 
+            /* A naming cache of its own: this door is one turn per process, so
+               there is no second read for a longer-lived one to save. */
+            new Map(), 
+            /* Signed as this seat, so a private room shows it the table it is
+               playing at rather than refusing it as a stranger. */
+            agentReadCapability(args.agent, args.agentId)).catch(() => null);
+            const tableTalk = table === null
+                ? []
+                : await readTableTalk(fetchImpl, session.product, session.executionHex, table.handNumber).catch(() => []);
+            const mine = table?.seats.find((row) => row.seat === args.state.seat);
+            return {
+                kind: "your-turn",
+                position: {
+                    seat: args.state.seat,
+                    executionId: session.executionId,
+                    hole: holeFromView(view),
+                    legal: decodeLegalActions(view.legalActions),
+                    toCall: table && mine
+                        ? Math.max(0, table.currentWager - mine.streetContribution)
+                        : null,
+                    table,
+                    seats: table?.seats ?? [],
+                    tableTalk,
+                    deadlineMs: view.participantDeadlineMs.toString(),
+                    msRemaining: Number(view.participantDeadlineMs) - Date.now(),
+                },
+                state: persisted(session, args.state, context, cursor, view),
+            };
+        }
+        if (Date.now() >= until) {
+            const waiting = persisted(session, args.state, context, cursor, null);
+            /* Asked only here, where the loop is about to say "waiting" anyway: a
+               seat with no chips is not waiting for a turn, it is out, and a caller
+               polling `waiting` at the default `--wait 0` would spin at full rate for
+               the rest of somebody else's sitting. The stack is on the public record
+               rather than the seat's own view, so it costs the one read this branch
+               can afford. */
+            const busted = await seatIsBusted(fetchImpl, session, args.state.seat);
+            return busted
+                ? { kind: "eliminated", state: waiting }
+                : { kind: "waiting", state: waiting };
+        }
+        const batch = await session.client.pollEvents();
+        if (batch.context)
+            context = batch.context;
+        messages = batch.messages;
+    }
+}
+const hexBytes = (value) => {
+    const bare = value.replace(/^0x/i, "");
+    return Uint8Array.from(bare.match(/.{2}/g).map((pair) => Number.parseInt(pair, 16)));
+};
+/** Send one move for the position `openTurn` last returned. */
+export async function submitTurn(args) {
+    const fetchImpl = args.fetchImpl ?? fetch;
+    if (!args.state.view)
+        throw new Error("no turn is open; run `turn` first");
+    const view = decodeView(args.state.view);
+    if (!turnIsStillOpen(view, Date.now()))
+        throw new Error("the deadline for that turn has passed; run `turn` again for the next one");
+    const openWith = (clientNonce) => openSeatSession({
+        productUrl: args.state.productUrl,
+        offerId: args.state.offerId,
+        seat: args.state.seat,
+        agent: args.agent,
+        agentId: args.agentId,
+        clientNonce,
+        fetchImpl,
+    });
+    let session = await openWith(hexBytes(args.state.clientNonce));
+    let attached;
+    try {
+        attached = await attach(session, args.state, openWith);
+    }
+    catch (error) {
+        /* `act` answers with a move or throws, so it cannot carry an outcome the
+           way `turn` does. What it can do is say which of the two this is, rather
+           than handing on a status code. */
+        const sitting = await readSittingStatus(fetchImpl, session.product, session.executionHex);
+        const raw = error instanceof Error ? error.message : String(error);
+        throw new Error(sitting.state === "over"
+            ? `this sitting is ${sitting.detail}; there is no turn left to answer`
+            : `this seat cannot attach and the sitting is ${sitting.state === "live" ? "still running" : "of unknown state"}: ${raw}`);
+    }
+    session = attached.session;
+    args = { ...args, state: attached.state };
+    const { context } = attached;
+    if (!context)
+        throw new Error("the session answered with no context");
+    const prepared = await session.client.prepareAction(context, view, encodeAction(args.action));
+    const submitted = await raceSubmit(session, prepared);
+    if (!submitted.ok)
+        throw new Error(`action refused (${submitted.status}): ${await submitted.text()}`);
+    const said = await sayAtTable(fetchImpl, session, args.agent, args.agentId, args.say);
+    /* The cursor moves on the next read, not here: this process is about to
+       exit, and a cursor claiming to have seen the commit it has not read would
+       resume past it. */
+    return {
+        committed: true,
+        said,
+        state: {
+            ...args.state,
+            token: session.client.token ?? args.state.token,
+            view: null,
+            answeredNonce: view.state.nonce.toString(),
+        },
+    };
+}
+/** Submit, answering any seat-authorization challenge that arrives while the
+ *  submit is in flight. The challenge is not optional: an action whose
+ *  challenge went unanswered is an action the authority never authorised. */
+/** Whether the public record shows this seat holding no chips.
+ *
+ *  Unknown counts as not busted: a read that did not answer is a reason to keep
+ *  waiting, not a reason to tell a seat it is out of a sitting it may still be
+ *  in.
+ */
+async function seatIsBusted(fetchImpl, session, seat) {
+    const table = await readPublicTable(fetchImpl, session.product, session.executionHex).catch(() => null);
+    const mine = table?.seats.find((row) => row.seat === seat);
+    return mine !== undefined && mine.stack === 0;
+}
+async function raceSubmit(session, prepared) {
+    const submitP = session.client.startSubmit(prepared.wire);
+    const abort = new AbortController();
+    let pollP = session.client.pollEvents(abort.signal);
+    for (;;) {
+        const raced = await Promise.race([
+            submitP.then((response) => ({ kind: "submit", response })),
+            pollP.then((batch) => ({ kind: "events", batch })),
+        ]);
+        if (raced.kind === "submit") {
+            abort.abort();
+            const leftover = await pollP.catch(() => null);
+            for (const nested of leftover?.messages ?? [])
+                if (nested.type === "seatAuthorization")
+                    await session.client
+                        .answerSeatAuth(nested.challenge, session.coordinatorKey, session.timeAuthorityKey, prepared.pending)
+                        .catch(() => undefined);
+            return raced.response;
+        }
+        for (const nested of raced.batch.messages)
+            if (nested.type === "seatAuthorization")
+                await session.client
+                    .answerSeatAuth(nested.challenge, session.coordinatorKey, session.timeAuthorityKey, prepared.pending)
+                    .catch(() => undefined);
+        pollP = session.client.pollEvents(abort.signal);
+    }
+}
+async function sayAtTable(fetchImpl, session, agent, agentId, say) {
+    const trimmed = say.trim();
+    if (!trimmed)
+        return false;
+    const { mintAgentHttpCapability, AGENT_HTTP_CAPABILITY_HEADER } = await import("./agentHttp.js");
+    const target = `/open/v1/executions/${session.executionHex}/talk`;
+    const body = new TextEncoder().encode(JSON.stringify({ say: trimmed }));
+    try {
+        const { header } = await mintAgentHttpCapability(agent, agentId, {
+            method: "POST",
+            requestTarget: target,
+            body,
+        });
+        const response = await fetchImpl(`${session.product}${target}`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                [AGENT_HTTP_CAPABILITY_HEADER]: header,
+            },
+            body,
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/** A fresh seat state for an offer this agent has been admitted to. */
+export function newSeatState(productUrl, offerId, seat) {
+    const nonce = new Uint8Array(randomBytes(32));
+    nonce[0] = seat & 0xff;
+    return {
+        productUrl,
+        offerId,
+        seat,
+        clientNonce: toHex0x(nonce),
+        context: null,
+        token: null,
+        cursor: { sequence: "0", witnessedReceipt: null },
+        view: null,
+    };
+}