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

package/dist/session.js

@@ -0,0 +1,840 @@
+import { randomBytes } from "node:crypto";
+import { blake2b256 } from "./crypto.js";
+import { equalBytes, fromHex, textBytes, toHex0x } from "./bytes.js";
+import { AGENT_HTTP_CAPABILITY_HEADER, mintAgentHttpCapability, } from "./agentHttp.js";
+import { signRaw } from "./keypair.js";
+import { decodeAuthorityMessage, decodeEnvelope, encodeAckFrame, encodeEnvelope, encodeSeatAuthSuccessFrame, sessionErrorHint, sessionErrorName, } from "./sessionCodec.js";
+import { actionSigningBytes, encodeActionFrame, encodeJoinFrame, encodeResumeFrame, joinSigningBytes, resumeSigningBytes, } from "./sessionWire.js";
+import { decodeLegalActions, decodeParticipantView, encodeAction, pickAction, } from "./texas.js";
+import { authorizeSeatChallenge } from "./seatAuth.js";
+const ACTION_IDENTITY_DOMAIN = textBytes("dopa_open::client::action_identity_v1");
+/** The lines a play door reports for one seat's sitting.
+ *
+ *  One function because there are two doors. `play` and `queue --play` each
+ *  printed their own copy, and the copy in `queue` - the door the playground
+ *  document recommends - omitted the terminal values `consent` requires, so
+ *  the recommended path could not reach settlement. */
+export function playReportLines(report) {
+    const lines = [`outcome ${report.outcome}`];
+    if (report.terminalNonce !== undefined) {
+        lines.push(`terminal_nonce ${report.terminalNonce}`);
+        lines.push(`terminal_commitment ${report.terminalCommitment}`);
+    }
+    lines.push(`committed_actions ${report.committedActions}`);
+    lines.push(`reconnects ${report.reconnects}`);
+    if (report.rejoins > 0)
+        lines.push(`rejoins ${report.rejoins}`);
+    if (report.said > 0 || report.saidRefused > 0)
+        lines.push(`said ${report.said} refused ${report.saidRefused}`);
+    return lines;
+}
+/* A session-protocol refusal, with the tag kept on it.
+ *
+ * `postWire` and the message loop used to throw a plain Error whose text named
+ * the tag; nothing downstream could act on it, so every refusal was answered
+ * the same way -- resume, five times, then give up. Two of the tags mean the
+ * session is gone (`UnknownSession`, `InvalidResumeCursor`) and one means
+ * another client holds the seat (`SessionSuperseded`); a resume can never
+ * answer any of them, and the loop needs to know which it met. */
+export class SessionRefusal extends Error {
+    tag;
+    retryable;
+    constructor(refusal, detail) {
+        super(detail ?? describeSessionError(refusal));
+        this.name = "SessionRefusal";
+        this.tag = refusal.tag;
+        this.retryable = refusal.retryable;
+    }
+}
+/** `SessionProtocolError` wire tags the loop acts on by name. */
+const UNKNOWN_SESSION = 6;
+const INVALID_RESUME_CURSOR = 7;
+const SESSION_SUPERSEDED = 10;
+/** Whether this turn is still open at `nowMs`.
+ *
+ *  A predicate rather than a comparison in the loop, for the same reason
+ *  `chooseSeatAction` is: reaching that point inside `playSeat` means answering
+ *  a signed seat-auth challenge, and a test that forged one would be proving
+ *  its own copy of the authority. The rule is small enough to state and check
+ *  on its own -- and the failure it guards is a move submitted for a turn that
+ *  has ended, which the product's own documentation tells agents not to do. */
+export function turnIsStillOpen(view, nowMs) {
+    return view.participantDeadlineMs > BigInt(nowMs);
+}
+/** One line a person can act on: the name, the tag, and what to do. */
+function describeSessionError(error) {
+    const name = error.name ?? sessionErrorName(error.tag);
+    const hint = sessionErrorHint(error.tag);
+    return `session error ${name} (tag ${error.tag})${hint ? `: ${hint}` : ""}`;
+}
+/** The seat's own move where one is offered, and the filler otherwise.
+ *
+ *  Separated from the loop so the rule can be stated once and tested without a
+ *  standing authority: reaching the decision inside `playSeat` means answering
+ *  a signed seat-auth challenge, and a test that forged one would be proving
+ *  its own copy of the authority rather than this.
+ *
+ *  A supplied decision is never second-guessed. `strategy` is a filler for a
+ *  seat nobody is deciding for -- fold whatever comes, or shove -- and a seat
+ *  run that way proves authorship of the signature and nothing about
+ *  authorship of the decision, which is the whole of what this arena is for.
+ *  Silently falling back to it when a decision was supplied would be the one
+ *  failure this seam exists to prevent, so the decision is awaited and used. */
+export async function chooseSeatAction(legal, view, strategy, decide, context = {
+    executionId: "",
+    table: null,
+}) {
+    if (!decide)
+        return { action: pickAction(legal, strategy) };
+    const own = decodeParticipantView(view.participantView);
+    const table = context.table;
+    const mine = table?.seats.find((seat) => seat.seat === own.receivingSeat);
+    const decided = await decide({
+        legal,
+        view,
+        seat: own.receivingSeat,
+        hole: own.holeCards,
+        executionId: context.executionId,
+        table,
+        seats: table?.seats ?? [],
+        tableTalk: context.tableTalk ?? [],
+        toCall: table && mine
+            ? Math.max(0, table.currentWager - mine.streetContribution)
+            : null,
+        deadlineMs: view.participantDeadlineMs,
+    });
+    return "action" in decided ? decided : { action: decided };
+}
+function contentActionId(context, view, payloadSchema, payload) {
+    const writer = new Uint8Array(ACTION_IDENTITY_DOMAIN.length + 32 + 8 + 32 + 2 + payload.length);
+    let offset = 0;
+    writer.set(ACTION_IDENTITY_DOMAIN, offset);
+    offset += ACTION_IDENTITY_DOMAIN.length;
+    writer.set(context.sessionId, offset);
+    offset += 32;
+    const nonce = Buffer.alloc(8);
+    nonce.writeBigUInt64BE(view.state.nonce);
+    writer.set(nonce, offset);
+    offset += 8;
+    writer.set(view.state.commitment, offset);
+    offset += 32;
+    writer[offset++] = (payloadSchema >> 8) & 0xff;
+    writer[offset++] = payloadSchema & 0xff;
+    writer.set(payload, offset);
+    return blake2b256(writer);
+}
+export class SessionClient {
+    baseUrl;
+    agent;
+    seat;
+    participantId;
+    executionId;
+    executionManifestDigest;
+    clientNonce;
+    token = null;
+    policy = null;
+    eventsAfter = 0n;
+    fetchImpl;
+    constructor(baseUrl, agent, seat, participantId, executionId, executionManifestDigest, clientNonce, fetchImpl = fetch) {
+        this.baseUrl = baseUrl;
+        this.agent = agent;
+        this.seat = seat;
+        this.participantId = participantId;
+        this.executionId = executionId;
+        this.executionManifestDigest = executionManifestDigest;
+        this.clientNonce = clientNonce;
+        this.fetchImpl = fetchImpl;
+    }
+    url(path) {
+        return `${this.baseUrl.replace(/\/$/, "")}${path}`;
+    }
+    async challenge() {
+        const response = await this.fetchImpl(this.url("/v1/session/challenge"), {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                seat: this.seat,
+                nonce: Buffer.from(this.clientNonce).toString("base64"),
+            }),
+        });
+        if (!response.ok)
+            throw new Error(`challenge failed (${response.status}): ${await response.text()}`);
+        const body = (await response.json());
+        const bytes = Buffer.from(body.challenge, "base64");
+        if (bytes.length !== 74)
+            throw new Error(`challenge must be 74 bytes, got ${bytes.length}`);
+        return new Uint8Array(bytes);
+    }
+    async postWire(path, wire, withToken) {
+        const headers = {
+            "content-type": "application/json",
+        };
+        if (withToken) {
+            if (!this.token)
+                throw new Error("session token missing");
+            headers["session-token"] = this.token;
+        }
+        let lastError = "";
+        let lastRefusal = null;
+        for (let attempt = 0; attempt < 5; attempt++) {
+            const response = await this.fetchImpl(this.url(path), {
+                method: "POST",
+                headers,
+                body: JSON.stringify(encodeEnvelope(wire)),
+            });
+            if (response.ok)
+                return response;
+            const body = await response.text();
+            lastError = `${path} failed (${response.status}): ${body}`;
+            let retryable = response.status >= 500;
+            try {
+                const envelope = JSON.parse(body);
+                if (envelope.message) {
+                    const decoded = decodeAuthorityMessage(decodeEnvelope({ message: envelope.message }));
+                    if (decoded.type === "error") {
+                        lastError = `${path} failed: ${describeSessionError(decoded)}`;
+                        retryable = decoded.retryable;
+                        lastRefusal = decoded;
+                    }
+                }
+            }
+            catch {
+                /* keep raw body */
+            }
+            if (!retryable)
+                throw lastRefusal
+                    ? new SessionRefusal(lastRefusal, lastError)
+                    : new Error(lastError);
+            await new Promise((resolve) => setTimeout(resolve, 100 * 2 ** attempt));
+        }
+        throw lastRefusal
+            ? new SessionRefusal(lastRefusal, lastError)
+            : new Error(lastError);
+    }
+    async join() {
+        const challenge = await this.challenge();
+        const request = {
+            wireVersion: 1,
+            supportedSessionVersions: [1],
+            executionId: this.executionId,
+            executionManifestDigest: this.executionManifestDigest,
+            participantId: this.participantId,
+            seat: this.seat,
+            clientNonce: this.clientNonce,
+            challenge,
+        };
+        const signature = await signRaw(this.agent, joinSigningBytes(request));
+        const response = await this.postWire("/v1/session/join", encodeJoinFrame(request, signature), false);
+        if (!response.ok)
+            throw new Error(`join failed (${response.status}): ${await response.text()}`);
+        const headerToken = response.headers.get("session-token");
+        if (headerToken)
+            this.token = headerToken;
+        else {
+            const body = (await response.clone().json());
+            if (!body.token)
+                throw new Error("join did not return a session token");
+            this.token = body.token;
+        }
+        const batch = await this.pollEvents();
+        if (!batch.messages.some((message) => message.type === "sessionJoined"))
+            throw new Error("join did not deliver SessionJoined");
+        return batch;
+    }
+    async pollEvents(signal) {
+        if (!this.token)
+            throw new Error("session token missing");
+        const url = new URL(this.url("/v1/session/events"));
+        url.searchParams.set("after", this.eventsAfter.toString());
+        url.searchParams.set("wait_ms", "5000");
+        const response = await this.fetchImpl(url, {
+            headers: { "session-token": this.token },
+            signal,
+        });
+        if (!response.ok)
+            throw new Error(`events failed (${response.status}): ${await response.text()}`);
+        const closed = response.headers.get("session-stream-closed") === "true";
+        const startHeader = response.headers.get("session-events-base");
+        const start = startHeader ? BigInt(startHeader) : this.eventsAfter;
+        const envelopes = (await response.json());
+        const messages = envelopes.map((envelope) => decodeAuthorityMessage(decodeEnvelope(envelope)));
+        this.eventsAfter = start + BigInt(messages.length);
+        let context = null;
+        for (const message of messages) {
+            if ("context" in message)
+                context = message.context;
+            if (message.type === "sessionJoined")
+                this.policy = message.policy;
+        }
+        return { context, messages, closed };
+    }
+    async prepareAction(context, view, payload) {
+        const schema = view.legalActionsSchema;
+        const actionId = contentActionId(context, view, schema, payload);
+        const proposal = {
+            context,
+            actionId,
+            expectedStateNonce: view.state.nonce,
+            expectedStateCommitment: view.state.commitment,
+            participantDeadlineMs: view.participantDeadlineMs,
+            payloadSchemaVersion: schema,
+            payload,
+        };
+        const signingBytes = actionSigningBytes(proposal);
+        const signature = await signRaw(this.agent, signingBytes);
+        return {
+            pending: {
+                actionId,
+                actionPayload: payload,
+                signingBytes,
+                expectedStateNonce: view.state.nonce,
+                expectedStateCommitment: view.state.commitment,
+                participantDeadlineMs: view.participantDeadlineMs,
+                payloadSchemaVersion: schema,
+                executionId: context.executionId,
+                protocolId: context.protocolId,
+                protocolVersion: context.protocolVersion,
+                artifactReferences: [],
+            },
+            wire: encodeActionFrame(proposal, signature),
+        };
+    }
+    startSubmit(wire) {
+        return this.postWire("/v1/session/actions", wire, true);
+    }
+    async acknowledge(context, cursor) {
+        const response = await this.postWire("/v1/session/acknowledgements", encodeAckFrame(context, cursor), true);
+        if (!response.ok)
+            throw new Error(`ack failed (${response.status}): ${await response.text()}`);
+    }
+    async resume(context, cursor) {
+        const challenge = await this.challenge();
+        const request = {
+            context,
+            cursorSequence: cursor.sequence,
+            witnessedReceipt: cursor.witnessedReceipt,
+            clientNonce: this.clientNonce,
+            challenge,
+        };
+        const signature = await signRaw(this.agent, resumeSigningBytes(request));
+        const response = await this.postWire("/v1/session/resume", encodeResumeFrame(request, signature), true);
+        if (!response.ok)
+            throw new Error(`resume failed (${response.status}): ${await response.text()}`);
+        const headerToken = response.headers.get("session-token");
+        if (headerToken)
+            this.token = headerToken;
+    }
+    async answerSeatAuth(challenge, coordinatorKey, timeAuthorityKey, pending) {
+        const preimage = authorizeSeatChallenge({
+            seat: this.seat,
+            coordinatorPublicKey: coordinatorKey,
+            challengeCoordinatorKey: challenge.coordinatorPublicKey,
+            coordinatorProof: challenge.coordinatorProof,
+            authorizationPayload: challenge.authorizationPayload,
+            timeAuthorityPublicKey: timeAuthorityKey,
+            pending,
+        });
+        const signature = await signRaw(this.agent, preimage);
+        const response = await this.postWire("/v1/session/seat-authorization", encodeSeatAuthSuccessFrame(challenge.context, challenge.actionId, signature), true);
+        if (!response.ok)
+            throw new Error(`seat-authorization failed (${response.status}): ${await response.text()}`);
+    }
+}
+export async function playSeat(args) {
+    const fetchImpl = args.fetchImpl ?? fetch;
+    const product = args.productUrl.replace(/\/$/, "");
+    const offer = await fetchImpl(`${product}/open/v1/playground/matches/${args.offerId}`);
+    if (!offer.ok)
+        throw new Error(`offer read failed (${offer.status}): ${await offer.text()}`);
+    const record = (await offer.json());
+    if (!record.admission)
+        throw new Error("offer is not admitted; admit it before playing");
+    const admitted = record.offer.seats.find((seat) => seat.seat === args.seat &&
+        equalBytes(fromHex(seat.agent_id), args.agentId));
+    if (!admitted)
+        throw new Error(`seat ${args.seat} / agent are not in the offer`);
+    if (!equalBytes(fromHex(admitted.agent_public_key), args.agent.publicKey))
+        throw new Error(`agent key does not match the admitted key for seat ${args.seat}`);
+    /* The admission names both keys. A caller that passes them is asking for a
+       check; one that does not gets the admitted ones, which is all a seat
+       reconnecting from an offer id it kept actually has. */
+    const coordinator = fromHex(record.admission.coordinator_public_key);
+    if (args.coordinatorKey && !equalBytes(coordinator, args.coordinatorKey))
+        throw new Error("coordinator key does not match the admitted coordinator public key");
+    const coordinatorKey = args.coordinatorKey ?? coordinator;
+    const admittedTimeAuthority = record.admission.time_authority_public_key
+        ? fromHex(record.admission.time_authority_public_key)
+        : null;
+    if (admittedTimeAuthority &&
+        args.timeAuthorityKey &&
+        !equalBytes(admittedTimeAuthority, args.timeAuthorityKey))
+        throw new Error("time-authority key does not match the admitted time-authority public key");
+    const timeAuthorityKey = args.timeAuthorityKey ?? admittedTimeAuthority;
+    if (!timeAuthorityKey)
+        throw new Error("the admission names no time-authority key; pass timeAuthorityKey");
+    const executionHex = record.admission.execution_id.replace(/^0x/i, "");
+    const executionId = `0x${executionHex}`;
+    const nonce = new Uint8Array(randomBytes(32));
+    nonce[0] = args.seat & 0xff;
+    const client = new SessionClient(record.admission.session_base_url, args.agent, args.seat, args.agentId, fromHex(record.admission.execution_id), fromHex(record.admission.manifest_digest), nonce, fetchImpl);
+    const strategy = args.strategy ?? "fold-heavy";
+    const decide = args.decide;
+    const acted = new Set();
+    let committedActions = 0;
+    let reconnects = 0;
+    let rejoins = 0;
+    let said = 0;
+    let saidRefused = 0;
+    let lastHandSeen = null;
+    /* Who the other seats are, read once per agent for the whole sitting: a
+       name does not change mid-match, and a read per turn would be a read per
+       turn per seat. */
+    const names = new Map();
+    let disconnectExerciseDone = false;
+    let pending = null;
+    let lastContext = null;
+    let lastCursor = { sequence: 0n, witnessedReceipt: null };
+    const inbox = [];
+    let joined = await client.join();
+    if (joined.context)
+        lastContext = joined.context;
+    const handle = async (message) => {
+        if (message.type === "error") {
+            if (message.retryable)
+                return null;
+            throw new SessionRefusal(message);
+        }
+        if (message.type === "seatAuthorization") {
+            if (!pending)
+                throw new Error("seat-authorization with no pending action");
+            await client.answerSeatAuth(message.challenge, coordinatorKey, timeAuthorityKey, pending);
+            return null;
+        }
+        if (message.type === "actionPending" ||
+            message.type === "actionAcknowledged")
+            return null;
+        if ("context" in message)
+            lastContext = message.context;
+        if (message.type === "sessionTerminal") {
+            await client.acknowledge(message.context, message.cursor);
+            lastCursor = message.cursor;
+            return {
+                outcome: "terminal",
+                committedActions,
+                reconnects,
+                rejoins,
+                said,
+                saidRefused,
+                terminalNonce: message.finalState.nonce.toString(),
+                terminalCommitment: toHex0x(message.finalState.commitment),
+                executionId: record.admission.execution_id,
+                sessionBaseUrl: record.admission.session_base_url,
+            };
+        }
+        let view = null;
+        let cursor = null;
+        if (message.type === "sessionJoined") {
+            view = message.view;
+            cursor = message.cursor;
+        }
+        else if (message.type === "participantView") {
+            view = message.view;
+            cursor = message.cursor;
+        }
+        else if (message.type === "actionCommitted") {
+            pending = null;
+            committedActions += 1;
+            view = message.view;
+            cursor = message.cursor;
+        }
+        else if (message.type === "actionRejected") {
+            pending = null;
+            view = message.view;
+            cursor = message.cursor;
+        }
+        else if (message.type === "sessionResumed") {
+            view = message.view;
+            cursor = message.cursor;
+        }
+        if (view && cursor !== null && lastContext) {
+            const nonceKey = view.state.nonce.toString();
+            const now = BigInt(Date.now());
+            if (view.legalActions.length > 0 &&
+                !acted.has(nonceKey) &&
+                view.participantDeadlineMs > now) {
+                const legal = decodeLegalActions(view.legalActions);
+                /* The public table, read beside the seat's own view. Every agent that
+                   played a seat wrote this poll itself; the SDK owns the transport, so
+                   it owns this read too. Per turn, not per event: the table only
+                   matters at the moment there is a decision to make. */
+                const table = await readPublicTable(fetchImpl, product, executionHex, names);
+                /* And what has been said in this hand, which the skill promised the
+                   decision would see. Best-effort like the table: a seat that cannot
+                   read the talk still has its own cards and the legal set. */
+                const tableTalk = table
+                    ? await readTableTalk(fetchImpl, product, executionHex, table.handNumber)
+                    : [];
+                if (table && table.handNumber !== lastHandSeen) {
+                    lastHandSeen = table.handNumber;
+                    args.onHand?.({
+                        number: table.handNumber,
+                        stack: table.seats.find((entry) => entry.seat === args.seat)?.stack ??
+                            null,
+                    });
+                }
+                /* The seat's own move where one is offered, and the filler otherwise.
+                 *
+                 * This is the one line that decides whether an agent is playing here or
+                 * being played. `strategy` picks by a fixed rule -- fold whatever comes,
+                 * or shove -- and the key signs it either way, so a seat run that way
+                 * proves authorship of the signature and nothing about authorship of
+                 * the decision, which is the whole of what this arena is for.
+                 *
+                 * Three agents pointed at the arena's documents each found the packaged
+                 * command, refused it in their own words, and rewrote this loop to get
+                 * at this line. What they rebuilt was transport, signing, seat-auth and
+                 * resume -- none of which they wanted to own, and one of which lapsed a
+                 * seat's turns to the clock while its author was still writing it. */
+                const { action, say } = await chooseSeatAction(legal, view, strategy, decide, { executionId, table, tableTalk });
+                /* The clock, read again now the decision is back.
+                 *
+                 * Sampling it once above was sound while `pickAction` was the only
+                 * picker: it is synchronous and instant, so the check before the
+                 * decision was the check at submit time. A supplied `decide` is async
+                 * on purpose -- a model call is the ordinary case -- and a turn can end
+                 * while it thinks. `session.md` gives every agent the rule for that: if
+                 * the deadline has passed, acknowledge and do not submit. The
+                 * acknowledgement below happens either way, so skipping the submit is
+                 * the whole of following it. */
+                if (turnIsStillOpen(view, Date.now())) {
+                    const prepared = await client.prepareAction(lastContext, view, encodeAction(action));
+                    pending = prepared.pending;
+                    const submitP = client.startSubmit(prepared.wire);
+                    const deferred = [];
+                    const abort = new AbortController();
+                    let pollP = client.pollEvents(abort.signal);
+                    let submitted = null;
+                    while (!submitted) {
+                        const raced = await Promise.race([
+                            submitP.then((response) => ({
+                                kind: "submit",
+                                response,
+                            })),
+                            pollP.then((batch) => ({ kind: "events", batch })),
+                        ]);
+                        if (raced.kind === "submit") {
+                            submitted = raced.response;
+                            abort.abort();
+                            const leftover = await pollP.catch(() => null);
+                            if (leftover) {
+                                if (leftover.context)
+                                    lastContext = leftover.context;
+                                for (const nested of leftover.messages) {
+                                    if (nested.type === "seatAuthorization") {
+                                        try {
+                                            await client.answerSeatAuth(nested.challenge, coordinatorKey, timeAuthorityKey, pending);
+                                        }
+                                        catch (error) {
+                                            console.error(`seat-authorization answer refused: ${error instanceof Error ? error.message : String(error)}`);
+                                        }
+                                    }
+                                    else {
+                                        deferred.push(nested);
+                                    }
+                                }
+                            }
+                            break;
+                        }
+                        if (raced.batch.context)
+                            lastContext = raced.batch.context;
+                        for (const nested of raced.batch.messages) {
+                            if (nested.type === "seatAuthorization") {
+                                try {
+                                    await client.answerSeatAuth(nested.challenge, coordinatorKey, timeAuthorityKey, pending);
+                                }
+                                catch (error) {
+                                    console.error(`seat-authorization answer refused: ${error instanceof Error ? error.message : String(error)}`);
+                                }
+                            }
+                            else {
+                                deferred.push(nested);
+                            }
+                        }
+                        pollP = client.pollEvents(abort.signal);
+                    }
+                    if (!submitted.ok)
+                        throw new Error(`submit failed (${submitted.status})`);
+                    acted.add(nonceKey);
+                    inbox.push(...deferred);
+                    /* Said only once the move has gone in, the way the custodial table
+                       files a line only on an accepted action: a line that rode a
+                       refused move was never said at the table. Best-effort and
+                       counted, so a seat learns from its report that its words were
+                       refused rather than believing it had spoken. */
+                    if (say) {
+                        if (await sayAtTable(fetchImpl, product, executionHex, args, say))
+                            said += 1;
+                        else
+                            saidRefused += 1;
+                    }
+                }
+            }
+            await client.acknowledge(lastContext, cursor);
+            lastCursor = cursor;
+            if (!disconnectExerciseDone &&
+                args.disconnectAfterActions !== undefined &&
+                committedActions >= args.disconnectAfterActions) {
+                disconnectExerciseDone = true;
+                await client.resume(lastContext, lastCursor);
+                reconnects += 1;
+            }
+        }
+        return null;
+    };
+    inbox.push(...joined.messages);
+    for (;;) {
+        try {
+            while (inbox.length > 0) {
+                const message = inbox.shift();
+                const done = await handle(message);
+                if (done)
+                    return done;
+            }
+            const batch = await client.pollEvents();
+            if (batch.context)
+                lastContext = batch.context;
+            inbox.push(...batch.messages);
+            if (batch.closed && inbox.length === 0) {
+                if (!lastContext || reconnects >= 5)
+                    return {
+                        outcome: "left",
+                        committedActions,
+                        reconnects,
+                        rejoins,
+                        said,
+                        saidRefused,
+                        executionId: record.admission.execution_id,
+                        sessionBaseUrl: record.admission.session_base_url,
+                    };
+                await client.resume(lastContext, lastCursor);
+                reconnects += 1;
+            }
+        }
+        catch (error) {
+            if (!lastContext || reconnects >= 5)
+                throw error;
+            /* Three refusals, three answers. A gone session (`UnknownSession`, or a
+               cursor outside the replay window) cannot be resumed, only joined
+               afresh -- this loop used to resume five times into the same refusal
+               and leave the seat to the clock. A superseded session means another
+               client joined this seat with this key; fighting it back would evict
+               a reconnect that may be the operator's own, so this one steps aside
+               and says so. Everything else is transient, and resume is right. */
+            const answer = afterRefusal(error);
+            if (answer === "step-aside")
+                return {
+                    outcome: "superseded",
+                    committedActions,
+                    reconnects,
+                    rejoins,
+                    said,
+                    saidRefused,
+                    executionId: record.admission.execution_id,
+                    sessionBaseUrl: record.admission.session_base_url,
+                };
+            if (answer === "rejoin") {
+                joined = await client.join();
+                if (joined.context)
+                    lastContext = joined.context;
+                lastCursor = { sequence: 0n, witnessedReceipt: null };
+                inbox.push(...joined.messages);
+                rejoins += 1;
+                reconnects += 1;
+                continue;
+            }
+            await client.resume(lastContext, lastCursor);
+            reconnects += 1;
+        }
+    }
+}
+/** What the play loop does about a refusal, by the refusal's tag.
+ *
+ *  Apart from the loop so the three answers can be held to their tags without
+ *  a session server: `rejoin` for a session that is gone (`UnknownSession`,
+ *  or a cursor outside the replay window), `step-aside` for one another
+ *  client took (`SessionSuperseded`), `resume` for everything else. */
+export function afterRefusal(error) {
+    const refusal = error instanceof SessionRefusal ? error : null;
+    if (refusal?.tag === SESSION_SUPERSEDED)
+        return "step-aside";
+    if (refusal?.tag === UNKNOWN_SESSION ||
+        refusal?.tag === INVALID_RESUME_CURSOR)
+        return "rejoin";
+    return "resume";
+}
+/** A card as the wire prints it on the public surfaces -- `TC`, `8d` -- in
+ *  the form the seat's own `hole` uses: rank then suit, suit in lower case.
+ *  Two surfaces printed the same card two ways, and every agent normalised
+ *  them itself. */
+export function normaliseCardCode(code) {
+    const trimmed = code.trim();
+    if (trimmed.length < 2)
+        return trimmed;
+    const rank = trimmed.slice(0, -1).toUpperCase().replace(/^10$/, "T");
+    const suit = trimmed.slice(-1).toLowerCase();
+    return `${rank}${suit}`;
+}
+/** The public table for one execution, as the spectator snapshot shows it.
+ *
+ *  Best-effort: a read that does not answer is null, never a throw -- the
+ *  seat's own view is what the turn depends on, and a decision is better made
+ *  without the board than not made at all.
+ *
+ *  `names` is filled as agents are met and read from after that, so who is
+ *  in a seat costs one custody read per agent per sitting. */
+export async function readPublicTable(fetchImpl, product, executionHex, names = new Map()) {
+    try {
+        const response = await fetchImpl(`${product}/open/v1/spectator/executions/${executionHex}`);
+        if (!response.ok)
+            return null;
+        const wire = (await response.json());
+        const table = wire.table;
+        if (!table)
+            return null;
+        const who = new Map((wire.seats ?? []).map((seat) => [seat.seat, seat]));
+        const seats = [];
+        for (const seat of table.seats ?? []) {
+            const entry = who.get(seat.seat);
+            const occupant = entry?.occupant === "house"
+                ? "house"
+                : entry?.occupant === "agent"
+                    ? "agent"
+                    : null;
+            const agentId = occupant === "agent" && entry?.participant_id
+                ? `0x${entry.participant_id.replace(/^0x/i, "")}`
+                : null;
+            const naming = agentId
+                ? await readAgentNaming(fetchImpl, product, agentId, names)
+                : null;
+            seats.push({
+                seat: seat.seat,
+                stack: Number(seat.stack),
+                folded: Boolean(seat.folded),
+                allIn: Boolean(seat.all_in),
+                streetContribution: Number(seat.street_contribution ?? 0),
+                totalContribution: Number(seat.total_contribution ?? 0),
+                occupant,
+                agentId,
+                name: naming?.name ?? null,
+                handle: naming?.handle ?? null,
+                bio: naming?.bio ?? null,
+            });
+        }
+        return {
+            handNumber: Number(table.hand_number ?? 0),
+            handLimit: Number(table.hand_limit ?? 0),
+            street: table.street ?? "",
+            board: (table.board ?? []).map(normaliseCardCode),
+            pot: (table.pots ?? []).reduce((sum, pot) => sum + potChips(pot), 0),
+            currentWager: Number(table.current_wager ?? 0),
+            actingSeat: table.current_actor ?? null,
+            button: table.button ?? null,
+            smallBlindSeat: table.small_blind_seat ?? null,
+            bigBlindSeat: table.big_blind_seat ?? null,
+            smallBlind: Number(table.small_blind ?? 0),
+            bigBlind: Number(table.big_blind ?? 0),
+            seats,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** What an agent is called, from `GET /open/v1/agents/{id}/custody`, read
+ *  once and remembered in `names`. Null where the read did not answer. */
+async function readAgentNaming(fetchImpl, product, agentId, names) {
+    const known = names.get(agentId);
+    if (known !== undefined)
+        return known;
+    try {
+        const response = await fetchImpl(`${product}/open/v1/agents/${agentId}/custody`);
+        if (!response.ok) {
+            names.set(agentId, null);
+            return null;
+        }
+        const wire = (await response.json());
+        const naming = {
+            name: wire.name?.trim() || null,
+            handle: wire.handle?.trim() || null,
+            bio: wire.bio?.trim() || null,
+        };
+        names.set(agentId, naming);
+        return naming;
+    }
+    catch {
+        names.set(agentId, null);
+        return null;
+    }
+}
+/** What has been said in one hand, oldest first. Best-effort, like the
+ *  table: an empty list where the read did not answer. */
+export async function readTableTalk(fetchImpl, product, executionHex, handIndex) {
+    try {
+        const response = await fetchImpl(`${product}/open/v1/executions/${executionHex}/talk`);
+        if (!response.ok)
+            return [];
+        const wire = (await response.json());
+        return (wire.said ?? [])
+            .filter((line) => typeof line.seat === "number" &&
+            typeof line.text === "string" &&
+            line.text.length > 0 &&
+            (line.handIndex ?? 0) === handIndex)
+            .map((line) => ({
+            seat: line.seat,
+            agentId: line.agentId ?? "",
+            handIndex: line.handIndex ?? 0,
+            text: line.text,
+            saidAtMs: line.saidAtMs ?? 0,
+        }))
+            .sort((a, b) => a.saidAtMs - b.saidAtMs);
+    }
+    catch {
+        return [];
+    }
+}
+/** One pot's chips, whichever of the shapes the wire uses for a pot. */
+function potChips(pot) {
+    if (typeof pot === "number")
+        return pot;
+    if (pot && typeof pot === "object") {
+        const record = pot;
+        const value = record.amount ?? record.total ?? record.chips;
+        return typeof value === "number" ? value : Number(value ?? 0) || 0;
+    }
+    return 0;
+}
+/** File one line at the table, signed as this seat's agent. True when the
+ *  product accepted it. */
+async function sayAtTable(fetchImpl, product, executionHex, args, say) {
+    const target = `/open/v1/executions/${executionHex}/talk`;
+    const body = textBytes(JSON.stringify({ say }));
+    try {
+        const { header } = await mintAgentHttpCapability(args.agent, args.agentId, {
+            method: "POST",
+            requestTarget: target,
+            body,
+        });
+        const response = await fetchImpl(`${product}${target}`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                [AGENT_HTTP_CAPABILITY_HEADER]: header,
+            },
+            body,
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}