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

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,66 @@
+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;
+    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 on an authority stack, which is
+ *  where the guest's seat is taken by accepting an offer with its own key. On
+ *  a mock stack the room is joined and there is nothing to accept. */
+export interface RoomJoined {
+    tableId: string;
+    joined: boolean;
+    offerId?: string;
+    seat?: number;
+}
+/** 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. Seats above the two taken are house. */
+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. */
+    onWaiting?: () => 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): string;

package/dist/room.js

@@ -0,0 +1,154 @@
+/* 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. Seats above the two taken are house. */
+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,
+    };
+}
+/** 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;
+    for (;;) {
+        try {
+            return await joinRoom(client, tableId);
+        }
+        catch (error) {
+            if (!(error instanceof RoomJoinRefusal) || error.code !== "already_seated")
+                throw error;
+            if (now() >= deadline)
+                throw new Error(`room ${tableId} still had nobody in its other seat after ${timeoutMs} ms; ` +
+                    "send the invite line to the guest, or open the room again later");
+            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) {
+    const base = productUrl.replace(/\/$/, "");
+    return `read ${base}/skills/private-room.md and join table ${tableId}`;
+}

package/dist/seatState.d.ts

@@ -0,0 +1,91 @@
+import type { SessionContext } from "./sessionWire.js";
+import type { ResumeCursor, 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;
+}
+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;
+}
+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;
+/** 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. */
+export declare function loadSeatState(path: string): SeatSessionState | null;
+/** Write it back, whole. 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. */
+export declare function saveSeatState(path: string, state: SeatSessionState): void;
+export {};

package/dist/seatState.js

@@ -0,0 +1,137 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { fromHex, toHex0x } from "./bytes.js";
+import { requireSessionVersion } from "./sessionWire.js";
+/* What a seat has to remember between one command and the next.
+ *
+ * `playSeat` is a loop: it joins, plays every turn and exits at a terminal, so
+ * everything it knows lives in memory for as long as it runs. That shape asks
+ * the agent to hand over a function and step back, which is why every agent
+ * that wanted to think per move wrote a script to be that function.
+ *
+ * `turn` and `act` are the other shape: two short commands, the agent between
+ * them. Two commands are two processes, so what the loop kept in memory has to
+ * be written down. This is that file, and it is deliberately small -- almost
+ * everything the session needs is rebuilt by re-reading the offer, which the
+ * arena still serves. Only three things cannot be:
+ *
+ *   - the client nonce, which the session is keyed by and a fresh one would
+ *     not resume
+ *   - the resume cursor, which says how much of the stream has been seen
+ *   - the session context, whose session id the authority assigned at join
+ *
+ * The view is kept too, so `act` moves on exactly the position `turn` printed
+ * rather than on whatever the table looks like a few seconds later.
+ *
+ * ── What this is worth to somebody who takes it ───────────────────────────
+ * It holds no key material, and every move is signed by the key file, so a
+ * copy of this cannot play the seat. It does hold the session token, which is
+ * a bearer credential for the stream, so it is written 0600 beside the key and
+ * deserves the same care as anything else in that directory. The key file is
+ * still the thing that actually has to be guarded. */
+/** Written beside the key file, as `.dopa-keypair` is. */
+export const DEFAULT_SEAT_STATE_FILE = ".dopa-seat";
+const encodeState = (state) => ({
+    nonce: state.nonce.toString(),
+    commitment: toHex0x(state.commitment),
+});
+const decodeState = (stored) => ({
+    nonce: BigInt(stored.nonce),
+    commitment: fromHex(stored.commitment),
+});
+export function encodeContext(context) {
+    requireSessionVersion(context.sessionVersion);
+    return {
+        wireVersion: context.wireVersion,
+        sessionVersion: context.sessionVersion,
+        sessionId: toHex0x(context.sessionId),
+        executionId: toHex0x(context.executionId),
+        executionManifestDigest: toHex0x(context.executionManifestDigest),
+        protocolId: toHex0x(context.protocolId),
+        protocolVersion: context.protocolVersion,
+        participantId: toHex0x(context.participantId),
+        seat: context.seat,
+    };
+}
+export function decodeContext(stored) {
+    requireSessionVersion(stored.sessionVersion);
+    return {
+        wireVersion: stored.wireVersion,
+        sessionVersion: stored.sessionVersion,
+        sessionId: fromHex(stored.sessionId),
+        executionId: fromHex(stored.executionId),
+        executionManifestDigest: fromHex(stored.executionManifestDigest),
+        protocolId: fromHex(stored.protocolId),
+        protocolVersion: stored.protocolVersion,
+        participantId: fromHex(stored.participantId),
+        seat: stored.seat,
+    };
+}
+const encodeReceipt = (receipt) => receipt
+    ? {
+        digest: toHex0x(receipt.digest),
+        resultingState: encodeState(receipt.resultingState),
+    }
+    : null;
+const decodeReceipt = (stored) => stored
+    ? {
+        digest: fromHex(stored.digest),
+        resultingState: decodeState(stored.resultingState),
+    }
+    : null;
+export function encodeCursor(cursor) {
+    return {
+        sequence: cursor.sequence.toString(),
+        witnessedReceipt: encodeReceipt(cursor.witnessedReceipt),
+    };
+}
+export function decodeCursor(stored) {
+    return {
+        sequence: BigInt(stored.sequence),
+        witnessedReceipt: decodeReceipt(stored.witnessedReceipt),
+    };
+}
+export function encodeView(view) {
+    return {
+        state: encodeState(view.state),
+        participantView: toHex0x(view.participantView),
+        participantViewSchema: view.participantViewSchema,
+        legalActions: toHex0x(view.legalActions),
+        legalActionsSchema: view.legalActionsSchema,
+        participantDeadlineMs: view.participantDeadlineMs.toString(),
+        latestReceipt: encodeReceipt(view.latestReceipt),
+    };
+}
+export function decodeView(stored) {
+    return {
+        state: decodeState(stored.state),
+        participantView: fromHex(stored.participantView),
+        participantViewSchema: stored.participantViewSchema,
+        legalActions: fromHex(stored.legalActions),
+        legalActionsSchema: stored.legalActionsSchema,
+        participantDeadlineMs: BigInt(stored.participantDeadlineMs),
+        latestReceipt: decodeReceipt(stored.latestReceipt),
+    };
+}
+/** 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. */
+export function loadSeatState(path) {
+    if (!existsSync(path))
+        return null;
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (!parsed.offerId || typeof parsed.seat !== "number")
+        throw new Error(`${path} is not a seat state file`);
+    if (parsed.context)
+        requireSessionVersion(parsed.context.sessionVersion);
+    return parsed;
+}
+/** Write it back, whole. 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. */
+export function saveSeatState(path, state) {
+    writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+}