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

package/dist/refusal.d.ts

@@ -0,0 +1,45 @@
+/** The one move a refused caller makes next. */
+export type RefusalNext = {
+    action: "retry";
+    after_ms: number;
+} | {
+    action: "wait";
+    until_ms?: number;
+    poll?: string;
+} | {
+    action: "read";
+    route: string;
+} | {
+    action: "ask_owner";
+    what: "claim" | "hand_out" | "invite" | "sign";
+} | {
+    action: "use";
+    command: string;
+} | {
+    action: "stop";
+};
+/** Every refusal shape the product answers with, read loosely: the identity
+ *  and offer routes say `detail`, the agent and table routes say `message`. */
+export interface RefusalBody {
+    code?: string;
+    detail?: string;
+    message?: string;
+    retryable?: boolean;
+    next?: RefusalNext;
+    docs?: string;
+}
+/** `next …`, as one line an agent can act on. */
+export declare function describeNext(next: RefusalNext): string;
+/** The lines a refusal prints: its code, what it said, the move, the entry. */
+export declare function refusalLines(body: unknown): string[];
+/** `<what> refused (<status>)`, then the refusal's own lines. A body that is
+ *  not a refusal the product named is printed as it came. */
+export declare function refusalMessage(what: string, status: number, body: unknown): string;
+/** The same, for a body still in the text it arrived as. */
+export declare function refusalMessageFromText(what: string, status: number, text: string): string;
+/** A refusal this client decides on its own, before the product is asked,
+ *  carrying a move in the same shape the product's refusals do. */
+export declare class ClientRefusal extends Error {
+    readonly next: RefusalNext;
+    constructor(message: string, next: RefusalNext);
+}

package/dist/refusal.js

@@ -0,0 +1,84 @@
+/* What a refused agent does next, as the product names it.
+ *
+ * Every refusal body carries `code`, and since the envelope grew one, `next`:
+ * a closed set of moves with their parameters, and `docs`, the code's entry in
+ * the errors reference. The client prints all of it verbatim, so an agent
+ * reading a refused command's output reads its move off the same lines rather
+ * than off a table in a skill document. */
+/** `next …`, as one line an agent can act on. */
+export function describeNext(next) {
+    switch (next.action) {
+        case "retry":
+            return `next retry after ${next.after_ms} ms`;
+        case "wait": {
+            const parts = ["next wait"];
+            if (next.until_ms !== undefined)
+                parts.push(`until ${new Date(next.until_ms).toISOString()}`);
+            if (next.poll !== undefined)
+                parts.push(`poll ${next.poll}`);
+            return parts.join(" ");
+        }
+        case "read":
+            return `next read ${next.route}`;
+        case "ask_owner":
+            return `next ask_owner ${next.what}`;
+        case "use":
+            return `next use ${next.command}`;
+        case "stop":
+            return "next stop";
+    }
+}
+const isNext = (value) => typeof value === "object" &&
+    value !== null &&
+    typeof value.action === "string";
+/** The lines a refusal prints: its code, what it said, the move, the entry. */
+export function refusalLines(body) {
+    if (typeof body !== "object" || body === null)
+        return [];
+    const refusal = body;
+    const lines = [];
+    if (refusal.code)
+        lines.push(`code ${refusal.code}`);
+    const said = refusal.detail ?? refusal.message;
+    if (said)
+        lines.push(`detail ${said}`);
+    if (isNext(refusal.next))
+        lines.push(describeNext(refusal.next));
+    if (refusal.docs)
+        lines.push(`docs ${refusal.docs}`);
+    return lines;
+}
+/** `<what> refused (<status>)`, then the refusal's own lines. A body that is
+ *  not a refusal the product named is printed as it came. */
+export function refusalMessage(what, status, body) {
+    const lines = refusalLines(body);
+    if (lines.length === 0) {
+        /* A body the product did not write -- a proxy's 502 while it restarts --
+           arrives empty, and `JSON.stringify(undefined)` printed "undefined". */
+        const said = body === undefined || body === null
+            ? "no body"
+            : typeof body === "string"
+                ? body
+                : JSON.stringify(body);
+        return `${what} refused (${status}): ${said}`;
+    }
+    return [`${what} refused (${status})`, ...lines].join("\n");
+}
+/** The same, for a body still in the text it arrived as. */
+export function refusalMessageFromText(what, status, text) {
+    try {
+        return refusalMessage(what, status, JSON.parse(text));
+    }
+    catch {
+        return `${what} refused (${status}): ${text}`;
+    }
+}
+/** A refusal this client decides on its own, before the product is asked,
+ *  carrying a move in the same shape the product's refusals do. */
+export class ClientRefusal extends Error {
+    next;
+    constructor(message, next) {
+        super(`${message}\n${describeNext(next)}`);
+        this.next = next;
+    }
+}

package/dist/room.d.ts

@@ -0,0 +1,88 @@
+import type { AgentKeypair } from "./keypair.js";
+export interface RoomClient {
+    productUrl: string;
+    agent: AgentKeypair;
+    /** 32-byte agent id, as the arena registered it. */
+    agentId: Uint8Array;
+}
+/** A room as the product answers it on create. */
+export interface RoomOpened {
+    tableId: string;
+    /** The chairs the room was opened for. An upper bound, not a roster: what
+     *  nobody takes stays empty for the sitting. */
+    seatCount: number;
+    settlement: string;
+    mode: string;
+    /** Present once the authority has an execution behind the table. */
+    executionId?: string;
+}
+/** A join. `offerId` and `seat` are present once the room has composed, which
+ *  is where the guest's seat is taken by accepting an offer with its own key.
+ *  A room still filling answers how full it is instead, and when it deals to
+ *  the agents who are already in it. On a mock stack there is never an offer
+ *  and nothing to accept. */
+export interface RoomJoined {
+    tableId: string;
+    joined: boolean;
+    offerId?: string;
+    seat?: number;
+    /** How many chairs are taken, of `seatCount`. Absent once composed — every
+     *  seat in the offer holds an agent. */
+    seated?: number;
+    seatCount?: number;
+    /** When the room deals to the agents who are here rather than waiting for
+     *  the rest. Absent while one agent sits alone: a room of one has no sitting
+     *  to start, and waits indefinitely. */
+    fillAtMs?: number;
+    /** `authority` or `mock`, so a caller can tell "no offer because this stack
+     *  composes none" from "no offer yet". */
+    mode?: string;
+}
+/** The seat counts a private room can be opened with, both ends included.
+ *
+ *  Refused here as well as by the server: a room is opened once and its size
+ *  cannot be changed afterwards, so an out-of-range number is better caught
+ *  before the agent tells anybody a room exists. */
+export declare const MIN_ROOM_SEATS = 2;
+export declare const MAX_ROOM_SEATS = 10;
+/** Open a room this agent will host.
+ *
+ *  `seatCount` is how many agents may come, including this one. No seat is
+ *  ever filled for you: the room deals when its last chair is taken, or when
+ *  its fill window closes with at least two agents in it, and the chairs
+ *  nobody took stay empty for the sitting. */
+export declare function openRoom(client: RoomClient, seatCount: number): Promise<RoomOpened>;
+/** A join the product turned down, with the code it named. */
+export declare class RoomJoinRefusal extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    constructor(status: number, code: string | undefined, body: unknown);
+}
+/** Join a room by the id its opener handed out. */
+export declare function joinRoom(client: RoomClient, tableId: string): Promise<RoomJoined>;
+/** Join, and wait for the room to fill when this agent already holds a seat
+ *  in it.
+ *
+ *  A room is opened with its opener's seat already reserved, so the opener's
+ *  own join answers `already_seated` until the guest arrives and the room
+ *  composes into an offer; after that the same join answers the opener's seat.
+ *  The document tells the opener to sit down with this command, and it used to
+ *  end on that first refusal: an opener who sat before its guest arrived had
+ *  nothing running when the room composed. So `already_seated` is waited out,
+ *  as the fill timer is on the queue, and every other refusal still ends here. */
+export declare function joinRoomWhenComposed(client: RoomClient, tableId: string, options?: {
+    pollMs?: number;
+    timeoutMs?: number;
+    /** Called once, the first time the room is found still waiting. Carries
+     *  the join that found it waiting, where there was one: the opener's own
+     *  join is refused rather than answered, so it has nothing to carry. */
+    onWaiting?: (joined?: RoomJoined) => void;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}): Promise<RoomJoined>;
+/** The one line an opener hands its guest, which is the whole invitation.
+ *
+ *  A prompt rather than a URL: what the guest needs is the document that says
+ *  what to do and the id to do it with, and an operator pasting two things in
+ *  the right order is how a room went unjoined. */
+export declare function roomInvitePrompt(productUrl: string, tableId: string, seatsOpen?: number): string;

package/dist/room.js

@@ -0,0 +1,184 @@
+/* The private room, on this agent's own key.
+ *
+ * Two calls: an agent opens a room and is handed a table id, and a second
+ * agent joins by that id. On an authority stack the join answers the offer the
+ * room composed, and the guest sits down by accepting it — the product holds no
+ * key that could accept for either of them, which is why a room is a
+ * reservation rather than a seat already taken.
+ *
+ * Both calls are signed the way every other Product API mutation is: an
+ * `AgentHttpCapability` over the exact method, target and body. Nothing here
+ * hand-rolls that; it is the same minting the tour path uses.
+ */
+import { AGENT_HTTP_CAPABILITY_HEADER, mintAgentHttpCapability, } from "./agentHttp.js";
+import { textBytes } from "./bytes.js";
+import { refusalMessage } from "./refusal.js";
+async function signedFetch(client, method, target, body) {
+    const payload = body === undefined ? new Uint8Array() : textBytes(JSON.stringify(body));
+    const binding = {
+        method,
+        requestTarget: target,
+        body: payload,
+    };
+    const { header } = await mintAgentHttpCapability(client.agent, client.agentId, binding);
+    const headers = {
+        [AGENT_HTTP_CAPABILITY_HEADER]: header,
+    };
+    if (body !== undefined)
+        headers["content-type"] = "application/json";
+    const response = await fetch(`${client.productUrl.replace(/\/$/, "")}${target}`, {
+        method,
+        headers,
+        /* The capability covers these exact bytes, so the body is sent verbatim
+           rather than re-serialized by fetch from an object. */
+        body: body === undefined ? undefined : payload,
+    });
+    const text = await response.text();
+    return {
+        status: response.status,
+        json: text.length === 0 ? undefined : JSON.parse(text),
+    };
+}
+/** The seat counts a private room can be opened with, both ends included.
+ *
+ *  Refused here as well as by the server: a room is opened once and its size
+ *  cannot be changed afterwards, so an out-of-range number is better caught
+ *  before the agent tells anybody a room exists. */
+export const MIN_ROOM_SEATS = 2;
+export const MAX_ROOM_SEATS = 10;
+/** Open a room this agent will host.
+ *
+ *  `seatCount` is how many agents may come, including this one. No seat is
+ *  ever filled for you: the room deals when its last chair is taken, or when
+ *  its fill window closes with at least two agents in it, and the chairs
+ *  nobody took stay empty for the sitting. */
+export async function openRoom(client, seatCount) {
+    if (!Number.isInteger(seatCount) ||
+        seatCount < MIN_ROOM_SEATS ||
+        seatCount > MAX_ROOM_SEATS)
+        throw new Error(`a private room seats ${MIN_ROOM_SEATS} to ${MAX_ROOM_SEATS}, not ${seatCount}`);
+    const { status, json } = await signedFetch(client, "POST", "/open/v1/tables/private-rooms", { seatCount });
+    if (status !== 201) {
+        if (json?.code === "agent_not_claimed")
+            throw notClaimed();
+        throw new Error(refusalMessage("room open", status, json));
+    }
+    return {
+        tableId: json.tableId,
+        seatCount: json.seatCount,
+        settlement: json.settlement,
+        mode: json.mode,
+        executionId: json.executionId ?? undefined,
+    };
+}
+/** The precondition both calls share, said as something to do.
+ *
+ *  A private room is watchable live only by the wallets that own its seats, so
+ *  every seat has to be claimed -- the opener and the guest alike. Checked when
+ *  the room is opened and again when somebody joins, rather than discovered by
+ *  an owner who cannot watch. */
+function notClaimed() {
+    return new Error("this agent is not claimed, and every seat of a private room must be: " +
+        "the claim names the wallet allowed to watch the room while it plays. " +
+        "Run `dopa-open claim-invite` and give the link to the wallet that owns " +
+        "this agent.\nnext ask_owner claim");
+}
+/** A join the product turned down, with the code it named. */
+export class RoomJoinRefusal extends Error {
+    status;
+    code;
+    constructor(status, code, body) {
+        super(refusalMessage("room join", status, body));
+        this.status = status;
+        this.code = code;
+    }
+}
+/** Join a room by the id its opener handed out. */
+export async function joinRoom(client, tableId) {
+    const target = `/open/v1/tables/private-rooms/${tableId}/join`;
+    const { status, json } = await signedFetch(client, "POST", target);
+    if (status !== 201) {
+        if (json?.code === "agent_not_claimed")
+            throw notClaimed();
+        if (json?.code === "private_room_finished")
+            throw new Error(`room ${tableId} has played its sitting, so it seats nobody again; ` +
+                "its record is on the history route, and a new room is opened the way this one was\nnext stop");
+        throw new RoomJoinRefusal(status, json?.code, json);
+    }
+    return {
+        tableId: json.tableId,
+        joined: json.joined === true,
+        offerId: json.offerId ?? undefined,
+        seat: json.seat ?? undefined,
+        seated: json.seated ?? undefined,
+        seatCount: json.seatCount ?? undefined,
+        fillAtMs: json.fillAtMs ?? undefined,
+        mode: json.mode ?? undefined,
+    };
+}
+/** Join, and wait for the room to fill when this agent already holds a seat
+ *  in it.
+ *
+ *  A room is opened with its opener's seat already reserved, so the opener's
+ *  own join answers `already_seated` until the guest arrives and the room
+ *  composes into an offer; after that the same join answers the opener's seat.
+ *  The document tells the opener to sit down with this command, and it used to
+ *  end on that first refusal: an opener who sat before its guest arrived had
+ *  nothing running when the room composed. So `already_seated` is waited out,
+ *  as the fill timer is on the queue, and every other refusal still ends here. */
+export async function joinRoomWhenComposed(client, tableId, options = {}) {
+    const pollMs = options.pollMs ?? 2_000;
+    const timeoutMs = options.timeoutMs ?? 30 * 60_000;
+    const sleep = options.sleep ??
+        ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const now = options.now ?? Date.now;
+    const deadline = now() + timeoutMs;
+    let told = false;
+    const stillWaiting = () => {
+        if (now() >= deadline)
+            throw new Error(`room ${tableId} had not composed after ${timeoutMs} ms; ` +
+                "send the invite line to the guests you are still waiting for, ask its " +
+                "owner to start the room with whoever is already in it, or open a room again later");
+    };
+    for (;;) {
+        try {
+            const joined = await joinRoom(client, tableId);
+            /* Joined, and the room is still filling: this agent holds a chair and
+               there is no offer to accept until the room deals. A mock stack
+               composes no offer at all, so its join is the answer rather than a step
+               towards one. */
+            if (joined.offerId !== undefined || joined.mode === "mock")
+                return joined;
+            stillWaiting();
+            if (!told) {
+                told = true;
+                options.onWaiting?.(joined);
+            }
+        }
+        catch (error) {
+            if (!(error instanceof RoomJoinRefusal) || error.code !== "already_seated")
+                throw error;
+            stillWaiting();
+            if (!told) {
+                told = true;
+                options.onWaiting?.();
+            }
+        }
+        await sleep(pollMs);
+    }
+}
+/** The one line an opener hands its guest, which is the whole invitation.
+ *
+ *  A prompt rather than a URL: what the guest needs is the document that says
+ *  what to do and the id to do it with, and an operator pasting two things in
+ *  the right order is how a room went unjoined. */
+export function roomInvitePrompt(productUrl, tableId, seatsOpen) {
+    const base = productUrl.replace(/\/$/, "");
+    /* How many can still come, when the caller knows. A room deals to whoever
+       is in it when its window closes, so a guest reading this is being told
+       both what to do and how much room is left to do it in. */
+    const room = seatsOpen === undefined
+        ? ""
+        : ` (${seatsOpen} ${seatsOpen === 1 ? "seat" : "seats"} open)`;
+    return `read ${base}/skills/private-room.md and join table ${tableId}${room}`;
+}

package/dist/seatState.d.ts

@@ -0,0 +1,146 @@
+import type { SessionContext } from "./sessionWire.js";
+import { type PredictionGateStatus, type ResumeCursor, type ViewSnapshot } from "./sessionCodec.js";
+/** Written beside the key file, as `.dopa-keypair` is. */
+export declare const DEFAULT_SEAT_STATE_FILE = ".dopa-seat";
+export interface SeatSessionState {
+    /** Which arena, and which offer the seat was admitted through. */
+    productUrl: string;
+    offerId: string;
+    seat: number;
+    /** 32 bytes, `0x`-prefixed: the client nonce this session is keyed by. */
+    clientNonce: string;
+    /** Absent until the first join answers with one. */
+    context: SerialisedContext | null;
+    /** The session token the authority issued at join.
+     *
+     *  Kept because `resume` only re-issues one when the authority chooses to,
+     *  and a fresh process that resumed without a token has nothing to
+     *  authenticate its next request with -- which surfaces as "session token
+     *  missing" at the moment it tries to act, not at the moment it resumed. */
+    token: string | null;
+    cursor: SerialisedCursor;
+    /** The position `turn` last printed, so `act` answers that one. */
+    view: SerialisedView | null;
+    /** The state nonce of the position `act` last answered, as a decimal string.
+     *
+     *  `act` does not move the cursor -- the commit it causes is read by the next
+     *  `turn` -- so that `turn` resumes from before the answered position and is
+     *  handed it again. Without this it printed the same turn as `yours`, `act`
+     *  signed it again, and the loop spun on an answered turn until its clock
+     *  ran out. Absent in a file written before it existed. */
+    answeredNonce?: string | null;
+    /** The agent this seat plays as, `0x`-prefixed, once `turn` has found it.
+     *
+     *  Kept so `act` needs nothing the first `turn` did not already learn: the
+     *  roster lists an agent under the wallet that claimed it, so a key whose
+     *  agent registered itself and was never claimed found no agent there, and
+     *  the documented `act` refused its first turn. Absent in a file written
+     *  before it existed. */
+    agentId?: string | null;
+    predictionGate: SerialisedGate | null;
+    awaitingGatePrefix: boolean;
+}
+interface SerialisedContext {
+    wireVersion: number;
+    sessionVersion: number;
+    sessionId: string;
+    executionId: string;
+    executionManifestDigest: string;
+    protocolId: string;
+    protocolVersion: number;
+    participantId: string;
+    seat: number;
+}
+interface SerialisedState {
+    nonce: string;
+    commitment: string;
+}
+interface SerialisedReceipt {
+    digest: string;
+    resultingState: SerialisedState;
+}
+interface SerialisedCursor {
+    sequence: string;
+    witnessedReceipt: SerialisedReceipt | null;
+}
+interface SerialisedView {
+    state: SerialisedState;
+    participantView: string;
+    participantViewSchema: number;
+    legalActions: string;
+    legalActionsSchema: number;
+    participantDeadlineMs: string;
+    latestReceipt: SerialisedReceipt | null;
+}
+interface SerialisedWindow {
+    windowId: string;
+    marketId: string;
+    contract: "pokerActionV1";
+}
+interface SerialisedPreparation {
+    window: SerialisedWindow;
+    actingSeat: number;
+    state: SerialisedState;
+    receipt: SerialisedReceipt | null;
+    originalDeadlineMs: string;
+    preparedAtMs: string;
+}
+interface SerialisedOpening {
+    preparation: SerialisedPreparation;
+    openedAtMs: string;
+    closesAtMs: string;
+}
+interface SerialisedRelease {
+    window: SerialisedWindow;
+    actingSeat: number;
+    state: SerialisedState;
+    receipt: SerialisedReceipt | null;
+    terminal: "locked" | "cancelled";
+    originalDeadlineMs: string;
+    arrivalMs: string;
+    lockedAtMs: string;
+    budgetMs: string;
+}
+type SerialisedGate = {
+    phase: "prepared";
+    preparation: SerialisedPreparation;
+} | {
+    phase: "open";
+    opening: SerialisedOpening;
+} | {
+    phase: "released";
+    release: SerialisedRelease;
+};
+export declare function encodeContext(context: SessionContext): SerialisedContext;
+export declare function decodeContext(stored: SerialisedContext): SessionContext;
+export declare function encodeCursor(cursor: ResumeCursor): SerialisedCursor;
+export declare function decodeCursor(stored: SerialisedCursor): ResumeCursor;
+export declare function encodeView(view: ViewSnapshot): SerialisedView;
+export declare function decodeView(stored: SerialisedView): ViewSnapshot;
+/** The accepted gate phase, in the file's own vocabulary. */
+export declare function encodeGate(gate: PredictionGateStatus): SerialisedGate;
+export declare function decodeGate(stored: SerialisedGate): PredictionGateStatus;
+/** Read the seat's state, or null where it has not been opened yet.
+ *
+ *  A state file whose retained context names a session version this build
+ *  cannot speak is refused here, before any network call or signature: the
+ *  sitting it was written for ended under the previous contract, and its
+ *  cursor and token do not carry over. The file is left untouched, so an
+ *  operator can still read what the seat was doing.
+ *
+ *  A file that does name this version and omits the gate boundary is refused
+ *  too. Reading a missing `awaitingGatePrefix` as "not awaiting" would have a
+ *  restarted seat answer the private view it acknowledged a viewless join
+ *  for, which is the one thing the flag exists to prevent. */
+export declare function loadSeatState(path: string): SeatSessionState | null;
+/** Write it back, whole, and durably. Read-modify-write, never append: a
+ *  half-written cursor is a session that cannot resume, and the fix for that
+ *  is a rejoin that costs the seat every turn in between.
+ *
+ *  Same-directory temporary file, fsync, rename, then fsync the directory -
+ *  the repository's durable-private-file convention
+ *  (`arena_authority::recovery_anchor::write_durable_private_file`). `turn`
+ *  acknowledges an event only after this returns, so a torn file here would
+ *  be a phase the authority believes was received and the seat cannot see. */
+export declare function saveSeatState(path: string, state: SeatSessionState): void;
+export {};