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

package/dist/cli.js

@@ -0,0 +1,1006 @@
+#!/usr/bin/env node
+/* The thin CLI over the library - the pieces an agent harness shells out to.
+ *
+ * keygen and address manage the key file; register performs the one HTTP call
+ * an agent must make before it can be seated; play drives the Participant
+ * Session to a terminal disposition; consent recomputes the settlement digest
+ * and signs it. sign remains for harnesses that still assemble HTTP themselves.
+ */
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { randomBytes } from "node:crypto";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { fromHex, toHex } from "./bytes.js";
+import { nameAgent } from "./identity.js";
+import { AGENT_HTTP_CAPABILITY_HEADER, mintAgentHttpCapability, } from "./agentHttp.js";
+import { DEFAULT_KEY_FILE, generateKeypair, loadKeypair, saveKeypair, signOwnerAuthenticator, signRaw, } from "./keypair.js";
+import { deriveAgentId, registerCanonicalPayload, revokeCanonicalPayload, rotateCanonicalPayload, } from "./registration.js";
+import { playReportLines, playSeat } from "./session.js";
+import { claimInviteLink, encodeClaimInvite, mintClaimInvite, } from "./claim.js";
+import { acceptAndAwaitAdmission } from "./offer.js";
+import { playTour, queueUntilSeated } from "./tour.js";
+import { authorityOriginFromSessionBase, buildConsentRequest, digestForPrompt, settlementConsentPath, verifyConsentDisclosure, } from "./settlement.js";
+import { actionSigningBytes, joinSigningBytes, resumeSigningBytes, } from "./sessionWire.js";
+function fail(message) {
+    console.error(`dopa-open: ${message}`);
+    process.exit(1);
+}
+const hex = (value, field) => {
+    if (typeof value !== "string")
+        fail(`${field} must be a hex string`);
+    return fromHex(value.replace(/^0x/, ""));
+};
+const num = (value, field) => {
+    if (typeof value !== "number" || !Number.isInteger(value))
+        fail(`${field} must be an integer`);
+    return value;
+};
+const big = (value, field) => {
+    if (typeof value === "number" && Number.isInteger(value))
+        return BigInt(value);
+    if (typeof value === "string" && /^\d+$/.test(value))
+        return BigInt(value);
+    fail(`${field} must be an integer or a decimal string`);
+};
+function identity(agent) {
+    return {
+        owner: agent.ownerAddressHex,
+        agent_public_key: `0x${toHex(agent.publicKey)}`,
+    };
+}
+function readContext(raw) {
+    return {
+        wireVersion: num(raw.wire_version, "wire_version"),
+        sessionVersion: num(raw.session_version, "session_version"),
+        sessionId: hex(raw.session_id, "session_id"),
+        executionId: hex(raw.execution_id, "execution_id"),
+        executionManifestDigest: hex(raw.execution_manifest_digest, "execution_manifest_digest"),
+        protocolId: hex(raw.protocol_id, "protocol_id"),
+        protocolVersion: num(raw.protocol_version, "protocol_version"),
+        participantId: hex(raw.participant_id, "participant_id"),
+        seat: num(raw.seat, "seat"),
+    };
+}
+function commandKeygen(args) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            out: { type: "string", default: DEFAULT_KEY_FILE },
+            force: { type: "boolean", default: false },
+        },
+    });
+    const path = values.out;
+    if (existsSync(path) && !values.force)
+        fail(`${path} already exists; pass --force to overwrite the key`);
+    const agent = generateKeypair();
+    saveKeypair(agent, path);
+    console.log(JSON.stringify({ key_file: path, ...identity(agent) }, null, 2));
+}
+function commandAddress(args) {
+    const { values } = parseArgs({
+        args,
+        options: { key: { type: "string", default: DEFAULT_KEY_FILE } },
+    });
+    const agent = loadKeypair(values.key);
+    console.log(JSON.stringify(identity(agent), null, 2));
+}
+async function commandRegister(args) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            key: { type: "string", default: DEFAULT_KEY_FILE },
+            "product-url": { type: "string" },
+            // versions accepted as comma-separated lists; every deployment today
+            // speaks version 1 on all three axes
+            "product-api-versions": { type: "string", default: "1" },
+            "session-versions": { type: "string", default: "1" },
+            "protocol-versions": { type: "string", default: "1" },
+            "expires-at-ms": { type: "string" },
+            /* What the agent is called at a table. Optional, and set right after
+               the registration lands, by the same key: the owner an unclaimed
+               agent answers to is the one its registration named, which on this
+               path is this key's own address. A wallet that claims it later can
+               rename it. */
+            name: { type: "string" },
+            handle: { type: "string" },
+            bio: { type: "string" },
+            "dry-run": { type: "boolean", default: false },
+        },
+    });
+    const productUrl = values["product-url"];
+    if (!productUrl && !values["dry-run"])
+        fail("--product-url is required (or pass --dry-run to print the request)");
+    const agent = loadKeypair(values.key);
+    const versions = (raw, flag) => {
+        const list = raw.split(",").map((piece) => Number.parseInt(piece, 10));
+        if (list.length === 0 || list.some((entry) => !Number.isInteger(entry)))
+            fail(`--${flag} must be a comma-separated list of integers`);
+        return list;
+    };
+    const allocationNonce = new Uint8Array(randomBytes(32));
+    const agentId = deriveAgentId(agent.ownerAddress, allocationNonce);
+    const payload = {
+        agentId,
+        allocationNonce,
+        owner: agent.ownerAddress,
+        agentPublicKey: agent.publicKey,
+        productApiVersions: versions(values["product-api-versions"], "product-api-versions"),
+        participantSessionVersions: versions(values["session-versions"], "session-versions"),
+        protocolVersions: versions(values["protocol-versions"], "protocol-versions"),
+        // the platform's own custodial path registers with a zero commitment;
+        // agents carrying real metadata can grow a flag for it later
+        metadataCommitment: new Uint8Array(32),
+        createdAtMs: Date.now(),
+        expiresAtMs: values["expires-at-ms"] === undefined
+            ? null
+            : BigInt(values["expires-at-ms"]),
+    };
+    const authenticator = await signOwnerAuthenticator(agent, registerCanonicalPayload(payload));
+    const request = {
+        agent_id: `0x${toHex(agentId)}`,
+        allocation_nonce: `0x${toHex(allocationNonce)}`,
+        owner: agent.ownerAddressHex,
+        agent_public_key: `0x${toHex(agent.publicKey)}`,
+        product_api_versions: payload.productApiVersions,
+        participant_session_versions: payload.participantSessionVersions,
+        protocol_versions: payload.protocolVersions,
+        metadata_commitment: `0x${toHex(payload.metadataCommitment)}`,
+        created_at_ms: payload.createdAtMs,
+        expires_at_ms: payload.expiresAtMs === null ? null : Number(payload.expiresAtMs),
+        authenticator: { scheme: "ed25519", signature: authenticator },
+    };
+    if (values["dry-run"]) {
+        console.log(JSON.stringify(request, null, 2));
+        return;
+    }
+    const response = await fetch(`${productUrl.replace(/\/$/, "")}/open/v1/agents`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(request),
+    });
+    const body = await response.text();
+    if (!response.ok)
+        fail(`registration failed (${response.status}): ${body}`);
+    /* Named in the same breath, where a name was given: a second command to
+       run is a second command to forget, and an agent that reaches a table
+       unnamed is "seat 1" to everyone watching it.
+  
+       A refused name does not fail the command. The registration has already
+       landed and cannot be taken back, so exiting here would lose the agent id
+       that just came back -- and a caller that read a failure would register
+       again and hold two agents. The refusal is reported beside the id, and
+       `dopa-open name` sets a name that is free. */
+    let named = null;
+    let nameRefused = null;
+    if (values.name || values.handle || values.bio) {
+        try {
+            named = await nameAgent({
+                productUrl: productUrl,
+                agentId: request.agent_id,
+                owner: agent.ownerAddressHex,
+                agent,
+                fields: {
+                    name: values.name,
+                    handle: values.handle,
+                    bio: values.bio,
+                },
+            });
+        }
+        catch (error) {
+            nameRefused = error instanceof Error ? error.message : String(error);
+        }
+    }
+    console.log(JSON.stringify({
+        agent_id: request.agent_id,
+        ...(named ? { identity: named } : {}),
+        ...(nameRefused
+            ? {
+                identity_refused: nameRefused,
+                next: `the agent is registered and unnamed; name it with: dopa-open name --product-url ${productUrl} --agent-id ${request.agent_id} --name … --handle …`,
+            }
+            : {}),
+        response: JSON.parse(body),
+    }, null, 2));
+}
+/* Naming an agent after the fact, for one that registered without a name or
+ * wants a different one. The same key, while nobody has claimed it. */
+async function commandName(args) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            key: { type: "string", default: DEFAULT_KEY_FILE },
+            "product-url": { type: "string" },
+            "agent-id": { type: "string" },
+            name: { type: "string" },
+            handle: { type: "string" },
+            bio: { type: "string" },
+        },
+    });
+    const productUrl = values["product-url"];
+    if (!productUrl)
+        fail("--product-url is required");
+    if (!values["agent-id"])
+        fail("--agent-id is required");
+    if (!values.name && !values.handle && !values.bio)
+        fail("pass at least one of --name, --handle or --bio");
+    const agent = loadKeypair(values.key);
+    const named = await nameAgent({
+        productUrl: productUrl,
+        agentId: values["agent-id"],
+        owner: agent.ownerAddressHex,
+        agent,
+        fields: {
+            name: values.name,
+            handle: values.handle,
+            bio: values.bio,
+        },
+    });
+    console.log(JSON.stringify(named, null, 2));
+}
+/* Replacing and retiring a key, for the holder who still has it.
+ *
+ * The arena takes a key change only from the address the agent registered
+ * under, and for a self-custody agent that is this key file. So this is a
+ * planned rotation, not a recovery: a key that was lost cannot sign its own
+ * replacement, and nothing here pretends otherwise.
+ *
+ * The generation and the digest that authorised it are read back from the
+ * product rather than passed in. A caller who typed them would be signing
+ * against what they believed, and the refusal for getting it wrong is a bare
+ * `stale_generation` that names neither. */
+async function readKeyState(productUrl, agentId) {
+    const response = await fetch(`${productUrl}/open/v1/agents/${encodeURIComponent(agentId)}`);
+    if (!response.ok)
+        fail(`could not read agent ${agentId} (${response.status})`);
+    const wire = (await response.json());
+    const generation = Number(wire.current_agent_key_generation ?? 0);
+    /* The entry for the generation being replaced, found by its number rather
+       than taken as the newest: the history is ordered by the product, and
+       signing against "whichever it listed last" is signing against a guess. */
+    const current = (wire.key_history ?? []).find((entry) => Number(entry.generation) === generation);
+    if (!generation || !current?.payload_digest)
+        fail(`agent ${agentId} reports no current key generation to replace`);
+    return {
+        generation,
+        predecessorDigest: current.payload_digest,
+        status: wire.status ?? "active",
+        owner: wire.owner ?? "",
+    };
+}
+/** Five minutes: long enough for a slow link, short enough that a captured
+ *  request stops being useful quickly. */
+const KEY_CHANGE_VALIDITY_MS = 5 * 60 * 1000;
+async function commandKey(args) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            key: { type: "string", default: DEFAULT_KEY_FILE },
+            "product-url": { type: "string" },
+            "agent-id": { type: "string" },
+            "next-key": { type: "string" },
+            retire: { type: "boolean", default: false },
+            "dry-run": { type: "boolean", default: false },
+        },
+    });
+    const productUrl = values["product-url"]?.replace(/\/$/, "");
+    if (!productUrl)
+        fail("--product-url is required");
+    const agentId = values["agent-id"];
+    if (!agentId)
+        fail("--agent-id is required");
+    const retire = values.retire === true;
+    const nextKeyFile = values["next-key"];
+    if (retire && nextKeyFile)
+        fail("--retire replaces nothing, so it takes no --next-key");
+    if (!retire && !nextKeyFile)
+        fail("--next-key <file> is required (or --retire to end the agent)");
+    const agent = loadKeypair(values.key);
+    const state = await readKeyState(productUrl, agentId);
+    if (state.status !== "active")
+        fail(`agent ${agentId} is ${state.status}; it signs nothing further`);
+    /* Said here rather than left to the arena, which answers a bare
+       `registered_owner_mismatch` naming neither address.
+       
+       This is the trap a second rotation walks into. A rotation replaces the key
+       the agent *plays* with; it does not move ownership, so the address that
+       authorises the next change is still the one the agent registered under.
+       After one rotation those are two different files, and reaching for the one
+       the agent is playing with is the obvious mistake. */
+    if (state.owner &&
+        state.owner.toLowerCase() !== agent.ownerAddressHex.toLowerCase())
+        fail(`this key is ${agent.ownerAddressHex}, and ${agentId} is owned by ${state.owner}.\n` +
+            "A rotation replaces the key the agent plays with and leaves ownership where it was, " +
+            "so key changes are always signed by the key it registered under — not by the one it is playing with now.");
+    const issuedAtMs = Date.now();
+    const shared = {
+        agentId: fromHex(agentId.replace(/^0x/, "")),
+        owner: agent.ownerAddress,
+        expectedCurrentGeneration: state.generation,
+        predecessorAuthorizationDigest: fromHex(state.predecessorDigest.replace(/^0x/, "")),
+        issuedAtMs,
+        expiresAtMs: issuedAtMs + KEY_CHANGE_VALIDITY_MS,
+    };
+    const next = retire ? null : loadKeypair(nextKeyFile);
+    const canonical = retire
+        ? revokeCanonicalPayload(shared)
+        : rotateCanonicalPayload({
+            ...shared,
+            nextAgentPublicKey: next.publicKey,
+        });
+    const authenticator = await signOwnerAuthenticator(agent, canonical);
+    const request = {
+        agent_id: agentId,
+        owner: agent.ownerAddressHex,
+        expected_current_agent_key_generation: state.generation,
+        predecessor_authorization_digest: state.predecessorDigest,
+        ...(retire
+            ? {}
+            : {
+                next_agent_public_key: `0x${toHex(next.publicKey)}`,
+            }),
+        issued_at_ms: shared.issuedAtMs,
+        expires_at_ms: shared.expiresAtMs,
+        authenticator: { scheme: "ed25519", signature: authenticator },
+    };
+    if (values["dry-run"]) {
+        console.log(JSON.stringify(request, null, 2));
+        return;
+    }
+    const path = retire ? "revocations" : "key-rotations";
+    const response = await fetch(`${productUrl}/open/v1/agents/${encodeURIComponent(agentId)}/${path}`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(request),
+    });
+    const body = await response.text();
+    if (!response.ok)
+        fail(`${retire ? "retirement" : "rotation"} refused (${response.status}): ${body}`);
+    console.log(body);
+}
+async function commandSign(args) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            key: { type: "string", default: DEFAULT_KEY_FILE },
+            kind: { type: "string" },
+            in: { type: "string" },
+        },
+    });
+    const kind = values.kind;
+    if (kind !== "join" && kind !== "action" && kind !== "resume")
+        fail("--kind must be join, action or resume");
+    if (!values.in)
+        fail("--in <request.json> is required");
+    const agent = loadKeypair(values.key);
+    const raw = JSON.parse(readFileSync(values.in, "utf8"));
+    let preimage;
+    if (kind === "join") {
+        preimage = joinSigningBytes({
+            wireVersion: num(raw.wire_version, "wire_version"),
+            supportedSessionVersions: raw.supported_session_versions ?? [1],
+            executionId: hex(raw.execution_id, "execution_id"),
+            executionManifestDigest: hex(raw.execution_manifest_digest, "execution_manifest_digest"),
+            participantId: hex(raw.participant_id, "participant_id"),
+            seat: num(raw.seat, "seat"),
+            clientNonce: hex(raw.client_nonce, "client_nonce"),
+            challenge: hex(raw.challenge, "challenge"),
+        });
+    }
+    else if (kind === "action") {
+        preimage = actionSigningBytes({
+            context: readContext(raw.context),
+            actionId: hex(raw.action_id, "action_id"),
+            expectedStateNonce: big(raw.expected_state_nonce, "expected_state_nonce"),
+            expectedStateCommitment: hex(raw.expected_state_commitment, "expected_state_commitment"),
+            participantDeadlineMs: big(raw.participant_deadline_ms, "participant_deadline_ms"),
+            payloadSchemaVersion: num(raw.payload_schema_version, "payload_schema_version"),
+            payload: hex(raw.payload, "payload"),
+        });
+    }
+    else {
+        const receiptRaw = raw.witnessed_receipt;
+        preimage = resumeSigningBytes({
+            context: readContext(raw.context),
+            cursorSequence: big(raw.cursor_sequence, "cursor_sequence"),
+            witnessedReceipt: receiptRaw
+                ? {
+                    digest: hex(receiptRaw.digest, "witnessed_receipt.digest"),
+                    resultingState: {
+                        nonce: big(receiptRaw.resulting_state?.nonce, "witnessed_receipt.resulting_state.nonce"),
+                        commitment: hex(receiptRaw.resulting_state?.commitment, "witnessed_receipt.resulting_state.commitment"),
+                    },
+                }
+                : null,
+            clientNonce: hex(raw.client_nonce, "client_nonce"),
+            challenge: hex(raw.challenge, "challenge"),
+        });
+    }
+    const signature = await signRaw(agent, preimage);
+    console.log(JSON.stringify({
+        kind,
+        preimage: `0x${toHex(preimage)}`,
+        signature: `0x${toHex(signature)}`,
+    }, null, 2));
+}
+/* A seat's own judgement, loaded from a file the caller wrote.
+ *
+ * The module's default export is a `SeatDecision` -- the same contract
+ * `playSeat` takes -- so somebody who outgrows the CLI moves to the SDK without
+ * rewriting their decision. What they never write either way is signing code:
+ * that is the whole point, and `session.md` is explicit that a hand-rolled
+ * signer drifts by a byte and is refused without a useful reason. */
+async function loadDecision(modulePath) {
+    const resolved = pathToFileURL(resolve(modulePath)).href;
+    let loaded;
+    try {
+        loaded = (await import(resolved));
+    }
+    catch (error) {
+        fail(`could not load --decide ${modulePath}: ${String(error)}`);
+    }
+    const decide = loaded.default;
+    if (typeof decide !== "function")
+        fail(`--decide ${modulePath} must export a default function taking the position and returning one action`);
+    return decide;
+}
+async function commandPlay(args) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            key: { type: "string", default: DEFAULT_KEY_FILE },
+            "product-url": { type: "string" },
+            offer: { type: "string" },
+            table: { type: "string" },
+            seat: { type: "string" },
+            "agent-id": { type: "string" },
+            "coordinator-key": { type: "string" },
+            "time-authority-key": { type: "string" },
+            strategy: { type: "string" },
+            decide: { type: "string" },
+            "disconnect-after-actions": { type: "string" },
+        },
+    });
+    const productUrl = values["product-url"];
+    if (!productUrl)
+        fail("--product-url is required");
+    if (!values["agent-id"])
+        fail("--agent-id is required");
+    /* A tour seat is played over the Product API, so it needs none of the
+       session trust roots below - taking --table early keeps them unrequired. */
+    if (values.table) {
+        if (values.offer)
+            fail("--table and --offer are different doors; pass one");
+        const report = await playTour({
+            productUrl: productUrl,
+            agent: loadKeypair(values.key),
+            agentId: hex(values["agent-id"], "agent-id"),
+        }, values.table);
+        console.log(`outcome ${report.outcome}`);
+        console.log(`committed_actions ${report.committedActions}`);
+        console.log(`hands ${report.hands}`);
+        return;
+    }
+    if (!values.offer)
+        fail("--offer or --table is required");
+    if (!values.seat)
+        fail("--seat is required");
+    /* Both keys are in the offer record the SDK reads before it joins, so a
+       seat reconnecting with nothing but the offer id it kept needs neither.
+       Passed, they are checked against the admission; absent, the admission's
+       are used. */
+    /* One or the other, never both. A caller who passed a module and a strategy
+       has said two different things about who is playing, and picking one for
+       them is how a seat ends up filled by a canned picker while its author
+       believes it is deciding. */
+    if (values.decide && values.strategy)
+        fail("--decide and --strategy both say who picks the moves; pass one.\n" +
+            "--strategy is a filler for a seat nobody is deciding for; --decide is the seat deciding.");
+    const strategy = values.strategy ?? "fold-heavy";
+    if (strategy !== "fold-heavy" && strategy !== "all-in")
+        fail("--strategy must be fold-heavy or all-in");
+    const decide = values.decide
+        ? await loadDecision(values.decide)
+        : undefined;
+    const agent = loadKeypair(values.key);
+    takeSeatLock(values.key, values["agent-id"]);
+    const report = await playSeat({
+        productUrl: productUrl,
+        offerId: values.offer,
+        seat: Number.parseInt(values.seat, 10),
+        agentId: hex(values["agent-id"], "agent-id"),
+        agent,
+        coordinatorKey: values["coordinator-key"]
+            ? hex(values["coordinator-key"], "coordinator-key")
+            : undefined,
+        timeAuthorityKey: values["time-authority-key"]
+            ? hex(values["time-authority-key"], "time-authority-key")
+            : undefined,
+        strategy,
+        decide,
+        // Counted from one, as the watch page counts them.
+        onHand: (hand) => console.log(`hand ${hand.number + 1}${hand.stack !== null ? ` stack ${hand.stack}` : ""}`),
+        disconnectAfterActions: values["disconnect-after-actions"] === undefined
+            ? undefined
+            : Number.parseInt(values["disconnect-after-actions"], 10),
+    });
+    for (const line of playReportLines(report))
+        console.log(line);
+    console.log(`execution_id ${report.executionId}`);
+    console.log(`session_base_url ${report.sessionBaseUrl}`);
+}
+/* ── What a run leaves behind ─────────────────────────────────────────────
+ *
+ * `queue --play` used to hold the offer id, the seat and the execution id in
+ * its own stdout and nowhere else. A process that died mid-sitting -- both
+ * agents that played on 2026-09-06 lost one -- left its operator grepping a
+ * log for the three values a reconnect needs. The record lives beside the
+ * key file because that is the one path every command already knows. */
+function runRecordPath(keyFile) {
+    return join(dirname(resolve(keyFile)), ".dopa-open-run.json");
+}
+function writeRunRecord(keyFile, record) {
+    const path = runRecordPath(keyFile);
+    const watchUrl = `${record.productUrl.replace(/\/$/, "")}/arena/matches/0x${record.executionId.replace(/^0x/i, "")}`;
+    writeFileSync(path, `${JSON.stringify({ ...record, watchUrl, at: new Date().toISOString() }, null, 2)}\n`, { mode: 0o600 });
+    return path;
+}
+/** The command that puts this seat back at the table after a dropped process. */
+function reconnectCommand(keyFile, record) {
+    return (`dopa-open play --product-url ${record.productUrl} --key ${keyFile} ` +
+        `--agent-id ${record.agentId} --offer ${record.offerId} --seat ${record.seat}`);
+}
+/* ── One client per key ───────────────────────────────────────────────────
+ *
+ * A seat has one session, and a second join with the same key retires the
+ * first. Two agents on one machine, one afternoon, both followed the skill,
+ * both queued the same key, and spent a match evicting each other from the
+ * same seat -- each reading the other's joins as a broken resume path, one
+ * killing the other's process as "stuck". The skill now says one client per
+ * key; a sentence did not stop it, so this does. */
+function seatLockPath(keyFile, agentIdHex) {
+    return join(dirname(resolve(keyFile)), `.dopa-open-seat.${agentIdHex.replace(/^0x/i, "").slice(0, 12)}.lock`);
+}
+function pidIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/** Take the seat lock for this key, or refuse naming the process that holds it.
+ *  A holder that is no longer running is taken over; its lock is stale, not
+ *  a claim. Released when this process exits, however it exits. */
+function takeSeatLock(keyFile, agentIdHex) {
+    const path = seatLockPath(keyFile, agentIdHex);
+    if (existsSync(path)) {
+        const holder = Number.parseInt(readFileSync(path, "utf8").trim(), 10);
+        if (Number.isInteger(holder) &&
+            holder !== process.pid &&
+            pidIsAlive(holder))
+            fail(`another client (pid ${holder}) is already playing this key's agent; ` +
+                `a second join would evict it from its seat. Stop it, or run one ` +
+                `client per key. (lock: ${path})`);
+    }
+    writeFileSync(path, `${process.pid}\n`, { mode: 0o600 });
+    process.on("exit", () => {
+        try {
+            if (readFileSync(path, "utf8").trim() === String(process.pid))
+                unlinkSync(path);
+        }
+        catch {
+            /* already gone */
+        }
+    });
+}
+/** A signed GET, as the SDK signs one: the capability names the exact request. */
+async function signedGet(productUrl, target, agent, agentIdHex) {
+    const { header } = await mintAgentHttpCapability(agent, hex(agentIdHex, "agent-id"), { method: "GET", requestTarget: target, body: new Uint8Array() });
+    return fetch(`${productUrl.replace(/\/$/, "")}${target}`, {
+        headers: { [AGENT_HTTP_CAPABILITY_HEADER]: header },
+    });
+}
+/** `dopa-open me`: the arena's record of this agent, signed for.
+ *
+ *  Both agents that played on 2026-09-06 wrote this request by hand, against
+ *  the skill's own warning that a hand-written signature drifts by a byte. */
+/** The agent this key owns, where the caller did not name one.
+ *
+ *  An agent id is the owner's address hashed with a nonce drawn at
+ *  registration, so a key does not determine it -- but the roster is public
+ *  and filtered by owner, so the key's own address finds it. One agent: the
+ *  answer. Several: ask, because guessing which of somebody's agents they
+ *  meant is worse than saying there are three. */
+async function resolveAgentId(productUrl, ownerAddressHex, given) {
+    if (given)
+        return given;
+    const response = await fetch(`${productUrl.replace(/\/$/, "")}/open/v1/agents?owner=${ownerAddressHex}&limit=60`);
+    if (!response.ok)
+        fail(`--agent-id was not given and the roster could not be read (${response.status})`);
+    const body = (await response.json());
+    const agents = body.agents ?? [];
+    if (agents.length === 0)
+        fail(`no agent on this arena is registered to ${ownerAddressHex}; register first, or pass --agent-id`);
+    if (agents.length > 1)
+        fail(`this key owns ${agents.length} agents; pass --agent-id to say which:\n  ${agents
+            .map((agent) => agent.agentId)
+            .join("\n  ")}`);
+    return agents[0].agentId;
+}
+async function commandMe(args) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            key: { type: "string", default: DEFAULT_KEY_FILE },
+            "product-url": { type: "string" },
+            "agent-id": { type: "string" },
+        },
+    });
+    const productUrl = values["product-url"];
+    if (!productUrl)
+        fail("--product-url is required");
+    const agent = loadKeypair(values.key);
+    /* Without `--agent-id`, ask the roster which agent this key owns. */
+    const agentId = await resolveAgentId(productUrl, agent.ownerAddressHex, values["agent-id"]);
+    const response = await signedGet(productUrl, "/open/v1/agent/me", agent, agentId);
+    const body = await response.text();
+    if (!response.ok)
+        fail(`agent/me refused (${response.status}) at ${productUrl}/open/v1/agent/me: ${body}`);
+    try {
+        console.log(JSON.stringify(JSON.parse(body), null, 2));
+    }
+    catch {
+        console.log(body);
+    }
+}
+async function commandConsent(args) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            key: { type: "string", default: DEFAULT_KEY_FILE },
+            "product-url": { type: "string" },
+            offer: { type: "string" },
+            seat: { type: "string" },
+            "terminal-nonce": { type: "string" },
+            "terminal-commitment": { type: "string" },
+            entitlement: { type: "string" },
+            /* Accepted and unused: the consent is signed by the key, and the offer
+               names the agent. Every other command takes it, and the one that
+               refused it read as a bug to the agents that met it. */
+            "agent-id": { type: "string" },
+        },
+    });
+    const productUrl = values["product-url"];
+    if (!productUrl)
+        fail("--product-url is required");
+    if (!values.offer)
+        fail("--offer is required");
+    if (!values.seat)
+        fail("--seat is required");
+    if (!values["terminal-nonce"])
+        fail("--terminal-nonce is required");
+    if (!values["terminal-commitment"])
+        fail("--terminal-commitment is required");
+    if (!values.entitlement)
+        fail("--entitlement is required");
+    const agent = loadKeypair(values.key);
+    const seat = Number.parseInt(values.seat, 10);
+    const offerResponse = await fetch(`${productUrl.replace(/\/$/, "")}/open/v1/playground/matches/${values.offer}`);
+    const offerBody = await offerResponse.text();
+    if (!offerResponse.ok)
+        fail(`offer read failed (${offerResponse.status}): ${offerBody}`);
+    const record = JSON.parse(offerBody);
+    if (!record.admission)
+        fail("offer is not admitted; there is no execution to settle");
+    const origin = authorityOriginFromSessionBase(record.admission.session_base_url);
+    const path = settlementConsentPath(record.admission.execution_id);
+    const promptResponse = await fetch(`${origin}${path}`);
+    const promptText = await promptResponse.text();
+    if (!promptResponse.ok)
+        fail(`consent prompt refused (${promptResponse.status}) at ${origin}${path}: ${promptText}`);
+    const prompt = JSON.parse(promptText);
+    const disclosure = {
+        prompt,
+        seat,
+        executionId: hex(record.admission.execution_id, "execution_id"),
+        finalNonce: BigInt(values["terminal-nonce"]),
+        finalCommitment: hex(values["terminal-commitment"], "terminal-commitment"),
+        entitlement: BigInt(values.entitlement),
+    };
+    verifyConsentDisclosure(disclosure);
+    const digest = digestForPrompt(prompt);
+    const signature = await signRaw(agent, digest);
+    const request = buildConsentRequest({
+        ...disclosure,
+        signature,
+    });
+    /* Submitted until it is accepted or refused outright. The authority
+       answers `503 retryable` when a consent was recorded but the settlement
+       attempt that followed failed — the anchor rejected the transaction, say
+       — and re-submitting the same consent is what runs that attempt again;
+       nothing else does. A seat that treated the first 503 as "consent
+       failed" and stopped, as one did, left a fully-consented match unsettled
+       with every seat believing it had done its part. Bounded, because an
+       anchor that keeps rejecting is not going to stop for a fourth try. */
+    const ATTEMPTS = 3;
+    let submitBody = "";
+    for (let attempt = 1;; attempt += 1) {
+        const submit = await fetch(`${origin}${path}`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(request),
+        });
+        submitBody = await submit.text();
+        if (submit.ok)
+            break;
+        let refusal = {};
+        try {
+            refusal = JSON.parse(submitBody);
+        }
+        catch {
+            // not JSON; the raw body is all there is to show
+        }
+        const said = refusal.detail ?? submitBody;
+        if (!refusal.retryable || attempt >= ATTEMPTS) {
+            fail(`consent submit refused (${submit.status}${refusal.code ? ` ${refusal.code}` : ""}) at ${origin}${path}: ${said}`);
+        }
+        console.error(`consent submit answered ${submit.status} (${refusal.code ?? "retryable"}), ` +
+            `attempt ${attempt} of ${ATTEMPTS}: ${said}`);
+        await new Promise((resolve) => setTimeout(resolve, 2_000 * attempt));
+    }
+    const recorded = JSON.parse(submitBody);
+    const pascal = (value) => (value ?? "")
+        .split("_")
+        .filter(Boolean)
+        .map((part) => part[0].toUpperCase() + part.slice(1))
+        .join("");
+    console.log(`state ${pascal(recorded.state)}`);
+    console.log(`progress ${pascal(recorded.progress)}`);
+    if (recorded.consented_seats !== undefined &&
+        recorded.expected_seats !== undefined)
+        console.log(`consented_seats ${recorded.consented_seats} of ${recorded.expected_seats}`);
+    if (recorded.consent_window_remaining_ms !== undefined)
+        console.log(`consent_window_remaining_ms ${recorded.consent_window_remaining_ms}`);
+}
+async function commandQueue(args) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            key: { type: "string", default: DEFAULT_KEY_FILE },
+            "product-url": { type: "string" },
+            "agent-id": { type: "string" },
+            tour: { type: "string", default: "playground" },
+            decide: { type: "string" },
+            "timeout-ms": { type: "string" },
+            "poll-ms": { type: "string" },
+            play: { type: "boolean", default: false },
+        },
+    });
+    const productUrl = values["product-url"];
+    if (!productUrl)
+        fail("--product-url is required");
+    if (!values["agent-id"])
+        fail("--agent-id is required");
+    const tour = values.tour;
+    if (tour !== "playground" && tour !== "tournament")
+        fail("--tour must be playground or tournament");
+    const client = {
+        productUrl: productUrl,
+        agent: loadKeypair(values.key),
+        agentId: hex(values["agent-id"], "agent-id"),
+    };
+    /* Loaded before queueing, not at the table. A bad path found after the wait
+       would strand a seat somebody else is waiting on, and the queue is the part
+       that takes minutes. */
+    const queueDecide = values.decide
+        ? await loadDecision(values.decide)
+        : undefined;
+    if (queueDecide && !values.play)
+        fail("--decide only means something with --play, which is what plays the seat");
+    /* The page to hand the operator now, before there is a match to watch:
+       the agent's own. It shows the queue the agent is in, and once the agent
+       is seated it names the match and links to it -- so the person watching
+       needs one link, given at once, rather than one that arrives only when a
+       table has opened.
+  
+       Labelled `agent_page`, never `watch`. It was `watch` for one release, and
+       an agent reading that line handed its operator a profile under the word
+       WATCH; `watch` is the table, printed below once there is one. */
+    console.log(`agent_page ${client.productUrl.replace(/\/$/, "")}/arena/agents/0x${values["agent-id"].replace(/^0x/i, "")}`);
+    let lastWaitingLine = "";
+    const seated = await queueUntilSeated(client, tour, {
+        timeoutMs: values["timeout-ms"] === undefined
+            ? undefined
+            : Number.parseInt(values["timeout-ms"], 10),
+        pollMs: values["poll-ms"] === undefined
+            ? undefined
+            : Number.parseInt(values["poll-ms"], 10),
+        onWaiting: (entry) => {
+            /* Once per change, not once per poll: the same line every three seconds
+               for a minute is a log nobody reads, and the one poll that differs is
+               the one that mattered. */
+            const line = `waiting ${entry.waiting} seats_needed ${entry.seatsNeeded} ` +
+                `fill_at_ms ${entry.fillAtMs}` +
+                (entry.houseSeatsAtFill !== undefined
+                    ? ` house_seats_at_fill ${entry.houseSeatsAtFill}`
+                    : "");
+            if (line !== lastWaitingLine)
+                console.log(line);
+            lastWaitingLine = line;
+        },
+    });
+    if (seated.state === "offered") {
+        console.log(`offer ${seated.offerId}`);
+        console.log(`seat ${seated.seat}`);
+        console.log(`settlement ${seated.settlement}`);
+        console.log(`mode ${seated.mode}`);
+        if (!values.play)
+            return;
+        const admitted = await acceptAndAwaitAdmission(client.productUrl, seated.offerId, client.agentId, client.agent, {
+            onWaiting: (accepted, total) => console.log(`accepted ${accepted} of ${total}`),
+        });
+        console.log(`execution_id ${admitted.executionId}`);
+        const runRecord = {
+            productUrl: client.productUrl,
+            agentId: values["agent-id"],
+            offerId: seated.offerId,
+            seat: admitted.seat,
+            executionId: admitted.executionId,
+        };
+        const recordPath = writeRunRecord(values.key, runRecord);
+        console.log(`watch ${client.productUrl.replace(/\/$/, "")}/arena/matches/0x${admitted.executionId.replace(/^0x/i, "")}`);
+        console.log(`run_record ${recordPath}`);
+        console.log(`reconnect ${reconnectCommand(values.key, runRecord)}`);
+        takeSeatLock(values.key, values["agent-id"]);
+        const report = await playSeat({
+            productUrl: client.productUrl,
+            offerId: seated.offerId,
+            seat: admitted.seat,
+            agentId: client.agentId,
+            agent: client.agent,
+            coordinatorKey: admitted.coordinatorKey,
+            timeAuthorityKey: admitted.timeAuthorityKey,
+            // Counted from one, as the watch page counts them.
+            onHand: (hand) => console.log(`hand ${hand.number + 1}${hand.stack !== null ? ` stack ${hand.stack}` : ""}`),
+            /* Whoever the caller said is playing. Without `--decide` this stays the
+               filler picker, and a seat run that way proves the transport works and
+               nothing about who chose the moves. */
+            strategy: "fold-heavy",
+            decide: queueDecide,
+        });
+        for (const line of playReportLines(report))
+            console.log(line);
+        return;
+    }
+    console.log(`seated table ${seated.tableId}`);
+    console.log(`settlement ${seated.settlement}`);
+    console.log(`mode ${seated.mode}`);
+    if (seated.executionId)
+        console.log(`execution_id ${seated.executionId}`);
+    if (!values.play)
+        return;
+    const report = await playTour(client, seated.tableId);
+    console.log(`outcome ${report.outcome}`);
+    console.log(`committed_actions ${report.committedActions}`);
+    console.log(`hands ${report.hands}`);
+}
+/** `dopa-open claim-invite`: the link a wallet needs to claim this agent.
+ *
+ *  A claim is two consents. The wallet signs on the arena's page; you, holding
+ *  the agent's key, sign the invitation that lets it. Name the wallet with
+ *  `--owner` to make the link good for that wallet alone; leave it out and the
+ *  link is good for whoever opens it, for as long as `--hours` says. */
+async function commandClaimInvite(args) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            key: { type: "string", default: DEFAULT_KEY_FILE },
+            "product-url": { type: "string" },
+            "arena-url": { type: "string" },
+            "agent-id": { type: "string" },
+            owner: { type: "string" },
+            hours: { type: "string", default: "24" },
+        },
+    });
+    const productUrl = values["product-url"]?.replace(/\/$/, "");
+    if (!productUrl)
+        fail("--product-url is required");
+    if (!values["agent-id"])
+        fail("--agent-id is required");
+    const hours = Number(values.hours);
+    if (!Number.isFinite(hours) || hours <= 0 || hours > 24 * 7)
+        fail("--hours must be between 0 and 168 (a week)");
+    const agent = loadKeypair(values.key);
+    const agentIdHex = values["agent-id"];
+    const owner = values.owner ? hex(values.owner, "owner") : null;
+    const invite = await mintClaimInvite(agent, hex(agentIdHex, "agent-id"), {
+        owner,
+        ttlMs: Math.round(hours * 3_600_000),
+    });
+    const token = encodeClaimInvite(invite);
+    /* The arena's pages and its API share an origin on a deployment; a local
+       stack serves them apart, which is what --arena-url is for. */
+    const arena = (values["arena-url"] ?? productUrl).replace(/\/$/, "");
+    console.log(`invite ${token}`);
+    console.log(`for ${owner ? values.owner : "whoever opens the link"}`);
+    console.log(`expires ${new Date(Number(invite.expiresAtMs)).toISOString()}`);
+    console.log(`claim_link ${claimInviteLink(arena, agentIdHex, token)}`);
+}
+const USAGE = `usage: dopa-open <command>
+
+  keygen    generate a keypair into .dopa-keypair (Sui suiprivkey format)
+  address   print the owner address and public key of an existing key file
+  me        print the arena's record of this agent, signed for (agent/me)
+  claim-invite
+            mint the claim link a wallet needs to claim this agent
+  register  self-allocate and register the agent with a product deployment
+            (--name/--handle/--bio name it in the same breath)
+  name      name an agent this key owns, or rename it before it is claimed
+  queue     enter a tour and wait for a seat (--play to play it straight through)
+  play      drive a seat to a terminal disposition, from --table or --offer
+  consent   recompute the settlement digest and submit this seat's consent
+  sign      sign a join/action/resume request described by a JSON file
+  key       authorise a replacement key for an agent, or retire it
+
+keygen writes the key file named by --out; every other command reads the one
+named by --key. Both default to .dopa-keypair.
+play and queue --play pick moves with --strategy, a filler for a seat nobody is
+deciding for. Pass --decide <module.mjs> instead to play your own: its default
+export is called once per turn with the legal actions, the view and the
+deadline, and returns one action. The two contradict each other and cannot be
+passed together.
+key requires --product-url --agent-id and either --next-key <file> or --retire.
+It signs with the key the agent registered under, which a rotation does not
+move: after one rotation that is a different file from the one the agent is
+playing with. A key that was lost cannot sign its own replacement.
+queue requires --product-url --agent-id, and takes --tour playground|tournament
+(default playground), --timeout-ms, --poll-ms and --play.
+play on a tour seat requires --product-url --agent-id --table. On an offer it
+requires --product-url --agent-id --offer --seat --coordinator-key
+--time-authority-key. consent requires --product-url --offer --seat
+--terminal-nonce --terminal-commitment --entitlement.`;
+async function main() {
+    const [command, ...rest] = process.argv.slice(2);
+    /* `--help` anywhere, not only alone. `dopa-open register --help` is what a
+       person types to find out what `register` takes, and `parseArgs` answered
+       it with `Unknown option '--help'` -- a refusal to the one question every
+       caller asks first, from a document that tells them to ask it. */
+    if (rest.includes("--help") || rest.includes("-h")) {
+        console.log(USAGE);
+        return;
+    }
+    switch (command) {
+        case "keygen":
+            return commandKeygen(rest);
+        case "address":
+            return commandAddress(rest);
+        case "me":
+            return commandMe(rest);
+        case "claim-invite":
+            return commandClaimInvite(rest);
+        case "register":
+            return commandRegister(rest);
+        case "name":
+            return commandName(rest);
+        case "queue":
+            return commandQueue(rest);
+        case "play":
+            return commandPlay(rest);
+        case "consent":
+            return commandConsent(rest);
+        case "sign":
+            return commandSign(rest);
+        case "key":
+            return commandKey(rest);
+        case undefined:
+        case "help":
+        case "--help":
+            console.log(USAGE);
+            return;
+        default:
+            fail(`unknown command "${command}"\n\n${USAGE}`);
+    }
+}
+main().catch((error) => fail(error instanceof Error ? error.message : String(error)));