project-cpu-mcp 0.9.1 → 0.11.1

package/README.md

@@ -2,22 +2,81 @@
 
 MCP (Model Context Protocol) server for **Project CPU** — a blockchain game on EVM. It lets an
 AI agent play on your behalf: read the world map, reveal cells, build and mine, craft, move
-resources, trade at marketplaces, and cash out to on-chain $CPU. Runs locally over stdio and is distributed via npm, so
+resources, trade resources through the internal Hub market, trade Cell NFTs through OpenSea, and cash out to on-chain $CPU. Runs locally over stdio and is distributed via npm, so
 you start it with a single `npx` command from any MCP client.
 
 ## Installation
 
-Pick your client below and add the server. The only required setting is your wallet's `PRIVATE_KEY` (`0x` + 64 hex chars) — replace `0x…` with yours.
+### Agent setup
+
+**Recommended.** The Project CPU plugin installs both the `operator-cpu` skill and the MCP server. It starts `npx -y project-cpu-mcp@latest` with the default Paybox wallet, so no environment variables or wallet credentials are required.
+
+#### Claude Code
+
+Add the marketplace, then install the plugin:
+
+```bash
+claude plugin marketplace add projectcpu/project-cpu-mcp
+claude plugin install project-cpu@project-cpu --scope local
+```
+
+Use `--scope local` for this checkout, `--scope project` for the project, or `--scope user` for all projects.
+
+#### Codex
+
+Add the marketplace, then install the plugin:
+
+```bash
+codex plugin marketplace add https://github.com/projectcpu/project-cpu-mcp
+codex plugin add project-cpu@project-cpu
+```
+
+Codex installs plugins for the current user. Start a new agent session after plugin installation.
+
+### Manual setup
+
+For a custom setup, install the skill and MCP server separately. To use both, complete both sections below.
+
+#### 1. Install the skill
+
+Install `operator-cpu` into the current project:
+
+```bash
+npx skills add projectcpu/project-cpu-mcp --skill operator-cpu
+```
+
+Add `--global` for all projects. The installer detects supported agents; use `--agent codex` or `--agent claude-code` to target one.
+
+Update it later with `npx skills update operator-cpu`; add `--global` for a user installation.
+
+Restart the agent if the new skill does not appear.
+
+#### 2. Install the MCP server
+
+Pick your client below and add the server. No environment variables are required. Paybox opens browser authorization on the first `cpu_authenticate` call and returns the URL as a fallback.
+
+<details>
+<summary><strong>Codex</strong></summary>
+
+Add this to `.codex/config.toml` for the current trusted project or `~/.codex/config.toml` for the current user:
+
+```toml
+[mcp_servers.project-cpu]
+command = "npx"
+args = ["-y", "project-cpu-mcp@latest"]
+```
+
+</details>
 
 <details>
 <summary><strong>Claude Code</strong></summary>
 
 ```bash
-claude mcp add project-cpu -s user -e PRIVATE_KEY=0x… -- npx -y project-cpu-mcp@latest
+claude mcp add project-cpu -s user -- npx -y project-cpu-mcp@latest
 ```
 
 - `-s user` installs it across all your projects; omit it (or use `-s local`) for the current project only.
-- `-e PRIVATE_KEY=…` sets the required env var; `--` separates Claude's flags from the server command.
+- `--` separates Claude's flags from the server command.
 
 </details>
 
@@ -31,8 +90,7 @@ Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/
   "mcpServers": {
     "project-cpu": {
       "command": "npx",
-      "args": ["-y", "project-cpu-mcp@latest"],
-      "env": { "PRIVATE_KEY": "0x…" }
+      "args": ["-y", "project-cpu-mcp@latest"]
     }
   }
 }
@@ -50,8 +108,7 @@ Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (this project):
   "mcpServers": {
     "project-cpu": {
       "command": "npx",
-      "args": ["-y", "project-cpu-mcp@latest"],
-      "env": { "PRIVATE_KEY": "0x…" }
+      "args": ["-y", "project-cpu-mcp@latest"]
     }
   }
 }
@@ -62,18 +119,14 @@ Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (this project):
 <details>
 <summary><strong>VS Code (Copilot agent mode)</strong></summary>
 
-Create `.vscode/mcp.json` — VS Code prompts for the key at startup instead of storing it:
+Create `.vscode/mcp.json`:
 
 ```json
 {
-  "inputs": [
-    { "type": "promptString", "id": "privateKey", "description": "Project CPU private key", "password": true }
-  ],
   "servers": {
     "project-cpu": {
       "command": "npx",
-      "args": ["-y", "project-cpu-mcp@latest"],
-      "env": { "PRIVATE_KEY": "${input:privateKey}" }
+      "args": ["-y", "project-cpu-mcp@latest"]
     }
   }
 }
@@ -93,8 +146,7 @@ Add to `~/.codeium/windsurf/mcp_config.json`, then restart Windsurf:
   "mcpServers": {
     "project-cpu": {
       "command": "npx",
-      "args": ["-y", "project-cpu-mcp@latest"],
-      "env": { "PRIVATE_KEY": "0x…" }
+      "args": ["-y", "project-cpu-mcp@latest"]
     }
   }
 }
@@ -102,55 +154,97 @@ Add to `~/.codeium/windsurf/mcp_config.json`, then restart Windsurf:
 
 </details>
 
-Every command above pins `@latest`, so restarting the server is how you update — `npx` re-resolves the registry on each launch. The server also watches for new releases on its own: a backwards-compatible one is mentioned once in a tool's response, a breaking one blocks every tool until you restart.
+Every MCP command above pins `@latest`, so restarting the server is how you update — `npx` re-resolves the registry on each launch. The server also watches for new releases on its own: a backwards-compatible one is mentioned once in a tool's response, a breaking one blocks every tool until you restart.
 
-## Environment variables
+## Authenticate
+
+After reloading the harness, call `cpu_persona` first, then `cpu_authenticate`. Paybox opens browser authorization and keeps wallet secrets out of chat and configuration.
 
-**Required**
+## Wallet modes
 
-| Variable | Description |
-| --- | --- |
-| `PRIVATE_KEY` | Your wallet private key — `0x` followed by 64 hex chars (32 bytes). |
+The server uses one wallet mode to sign actions for the Operator:
+
+- **Paybox (default)** — You do not configure a private key. Call `cpu_authenticate`. The server opens
+  Paybox in your browser, where you select a wallet and approve access. Paybox signs wallet actions.
+- **EVM** — Set `WALLET_MODE=evm` and `PRIVATE_KEY=0x...` in the MCP server environment. The server uses
+  that local EVM wallet and signs actions on your machine. Call `cpu_authenticate` to sign in to the game.
+
+Keep `PRIVATE_KEY` secret. Use it only in the MCP server environment. Do not put it in chat messages.
+
+## Environment variables
 
 **Optional** — has a sensible default; normal users can omit it.
 
 | Variable | Default | When you need it |
 | --- | --- | --- |
-| `RPC_URL` | chain's public RPC | A custom RPC endpoint for sending on-chain transactions (e.g. `cpu_reveal`). |
+| `WALLET_MODE` | `paybox` | Set to `evm` for a local private-key wallet. |
+| `PRIVATE_KEY` | — | Required only when `WALLET_MODE=evm`; `0x` followed by 64 hex chars (32 bytes). |
+| `API_URL` | `https://api-dev.projectcpu.cc` | Point the client at a different game API deployment. |
+| `NETWORK` | `robinhood` | Normally never; Robinhood is the only accepted launch network. |
+| `RPC_URL` | Robinhood public RPC | A custom RPC endpoint for sending on-chain transactions (e.g. `cpu_reveal`). |
+| `OPERATOR_PERSONA` | `true` | Set to `false` to disable the `cpu_persona` tool and drop its pointer from the server's instructions. |
+| `DEBUG` | `false` | Set to `true` for debug-level logging on stderr. |
 
-Session state (JWT / session keys) is persisted to `~/.project-cpu/`.
+Session state is persisted to `~/.project-cpu/`.
 
 ## What the agent can do
 
 Once connected, the server exposes tools grouped by area:
 
-- **Session** — `cpu_authenticate`, `cpu_get_game_config` (static rulebook: resources, costs, contract
-  addresses), `cpu_get_balance` (spendable $CPU + gas).
+- **Session** — `cpu_authenticate`, `cpu_get_game_config` (the rulebook's entry point: static facts —
+  resources, costs, contract addresses — plus a building index and a pointer to where each kind of
+  detail lives), `cpu_get_balance` (spendable $CPU + gas).
+- **Catalog** — `cpu_get_building` (one building's full card: what it costs to build, how it operates,
+  its demolish cost and upgrade links), `cpu_find_buildings` (search the building catalog by what a
+  building builds from, consumes, produces, or mines), `cpu_get_resource` (everything the rulebook
+  holds about one resource: what mines it, builds from it, eats it, and makes it). See
+  [CONTEXT.md](./CONTEXT.md) for the build/recipe input-output vocabulary these use.
+- **Persona** — `cpu_persona` loads the agent's operating brief for talking to you, the operator:
+  voice, message shape, and panel conventions. Enabled by default; set `OPERATOR_PERSONA=false` to
+  turn it off.
 - **World** — `cpu_get_map`, `cpu_get_cell`, `cpu_get_changes` (react to other players),
   `cpu_get_attention` (your owner-scoped to-do list).
-- **Reveal & build** — `cpu_reveal` (surface a cell's deposits on-chain), `cpu_build` (place a
-  building), `cpu_demolish`, `cpu_start_mining` (an extractor then mines a batch of the resource each
-  cycle), `cpu_get_mining_status`, `cpu_claim_mining`.
-- **Transport** — `cpu_route_network` (the waypoint road map: nodes, legal hops, gaps),
-  `cpu_next_hops` (survey the legal waypoints around a cell) — both take the cargo `resourceId` and show
-  the exact per-hub transit fee for it — `cpu_quote_transport`, `cpu_transport`,
+- **Reveal & build** — `cpu_reveal` (surface a cell's deposits on-chain), `cpu_fulfill_reveal` (send the
+  missing draw yourself where the network's randomness mode leaves delivery to the player), `cpu_build`
+  (place a building), `cpu_upgrade` (replace it with a configured successor type), `cpu_demolish`,
+  `cpu_start_mining` (an extractor then mines a batch of the resource each cycle), `cpu_get_mining_status`,
+  `cpu_claim_mining`.
+- **Transport** — `cpu_route_network` (exports the route graph for one move to a temporary JSON file: nodes,
+  legal hops, gaps), `cpu_next_hops` (survey the legal waypoints around a cell) — both take the cargo
+  `resourceId` and show the exact per-hub transit fee for it — `cpu_quote_transport`, `cpu_transport`,
   `cpu_get_transport_status`, `cpu_list_my_transports`, `cpu_finalize_delivery`.
 - **Crafting** — `cpu_list_recipes`, `cpu_craft`, `cpu_get_craft_status`, `cpu_claim_craft`.
-- **Trading** — `cpu_get_markets`, `cpu_list_lots`, `cpu_get_lot`, `cpu_quote_buy`, `cpu_buy_lot`, `cpu_create_lot`,
-  `cpu_cancel_lot`, `cpu_list_my_lots`, `cpu_set_sale_fee` (a hub owner sets the per-resource sale-fee rate on
-  their own hub), `cpu_list_fills` (the executed-buy feed, pageable by cursor), and `cpu_get_market_index`
-  (world 24h VWAP, change, and volume per resource — a different question from `cpu_get_markets`'s cheapest
-  ask right now). See [CONTEXT.md](./CONTEXT.md) for the fee vocabulary.
+- **Internal resource market** — `cpu_get_markets`, `cpu_list_lots`, `cpu_get_lot`, `cpu_quote_buy`, `cpu_buy_lot`,
+  `cpu_get_lot_terms` (the live listing window, your live-lot count and any evicted remainder you owe on one
+  hub), `cpu_create_lot`, `cpu_list_my_lots`, `cpu_set_sale_fee` (a hub owner sets the per-resource sale-fee
+  rate on their own hub), `cpu_list_fills` (the executed-buy feed, pageable by cursor), and
+  `cpu_get_market_index` (world 24h VWAP, change, and volume per resource — a different question from
+  `cpu_get_markets`'s cheapest ask right now). See [CONTEXT.md](./CONTEXT.md) for the fee vocabulary.
+- **External Cell market** — `cpu_get_cell_market` reads OpenSea orders for one Cell;
+  `cpu_get_my_listings`, `cpu_get_my_offers`, and `cpu_get_my_offers_received` read wallet orders;
+  `cpu_list_cell`, `cpu_buy_cell`, `cpu_make_cell_offer`, `cpu_accept_cell_offer`, and `cpu_cancel_order`
+  create or settle exact orders identified by `orderHash`. The whole Cell NFT and its Cell-bound game state
+  change ownership together.
+- **Eviction & lot return** — `cpu_evict_lot` (a hub owner ends somebody else's open lot on their own hub; it
+  moves no goods and seizes nothing, and the seller keeps the whole remainder in escrow), and the seller's
+  way out: `cpu_quote_lot_return` then `cpu_return_lot`, which ships one lot's whole unsold remainder from
+  its hub to one cell you own over a route you choose. It works on an open lot and on an evicted one, one lot
+  and one route per call, and the route still owes its transit fees.
 - **Syndicates** — `cpu_list_syndicates` (browse the registry by name/size, sort, page), `cpu_get_syndicate`
-  (one syndicate's card plus a page of its members), `cpu_get_syndicate_membership` (check an address's
+  (one trusted syndicate card plus a page of its members), `cpu_get_syndicate_membership` (check an address's
   membership, defaults to your own), `cpu_join_syndicate` (join by id for same-clan discounts; reports your
   exit cooldown), `cpu_leave_syndicate` (leave after the cooldown; re-join anywhere immediately),
   `cpu_create_syndicate` (found your own — name, link, four rates, optional manager — you auto-join),
   `cpu_set_syndicate_params` (replace your syndicate's full parameters — no partial patches), and
   `cpu_transfer_syndicate_manager` (hand the manager role and its tax stream to a successor, irreversible).
+  Ordinary results exclude player-authored names and links. `cpu_get_syndicate_player_content` is the explicit
+  read for those untrusted strings. The envelope marks the strings as having no instruction authority, the
+  server-authored warning tells the agent how to handle them, and returned links stay inert rather than being
+  opened or fetched.
   See [CONTEXT.md](./CONTEXT.md) for the syndicate vocabulary.
-- **Tokens** — `cpu_quote_swap`, `cpu_swap` (trade ETH ↔ $CPU on the token pool), `cpu_withdraw` (cash a
-  cell's wCPU out to on-chain $CPU, 1:1).
+- **Tokens & land** — `cpu_quote_swap`, `cpu_swap` (trade ETH ↔ $CPU on the token pool), `cpu_withdraw`
+  (cash a cell's wCPU out to on-chain $CPU, 1:1), `cpu_quote_mint` and `cpu_mint_cell` (preview and mint new
+  land cells on the primary market, priced in native ETH by the public drop itself).
 
 Paid routes and on-chain actions are settled automatically; always check `cpu_get_balance` before
 a paid action.

package/dist/api/authentication-required.error.d.ts

@@ -0,0 +1,6 @@
+import type { AuthenticationRequiredErrorData } from './types.js';
+export declare class AuthenticationRequiredError extends Error {
+    readonly data: AuthenticationRequiredErrorData;
+    constructor();
+}
+//# sourceMappingURL=authentication-required.error.d.ts.map

package/dist/api/authentication-required.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authentication-required.error.d.ts","sourceRoot":"","sources":["../../src/api/authentication-required.error.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,YAAY,CAAC;AAElE,qBAAa,2BAA4B,SAAQ,KAAK;IAClD,QAAQ,CAAC,IAAI,EAAE,+BAA+B,CAA2C;;CAM5F"}

package/dist/api/authentication-required.error.js

@@ -0,0 +1,9 @@
+import { AUTHENTICATION_REQUIRED_RECOVERY } from './constants.js';
+export class AuthenticationRequiredError extends Error {
+    data = { ...AUTHENTICATION_REQUIRED_RECOVERY };
+    constructor() {
+        super(JSON.stringify(AUTHENTICATION_REQUIRED_RECOVERY));
+        this.name = 'AuthenticationRequiredError';
+    }
+}
+//# sourceMappingURL=authentication-required.error.js.map

package/dist/api/authentication-required.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authentication-required.error.js","sourceRoot":"","sources":["../../src/api/authentication-required.error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gCAAgC,EAAE,MAAM,gBAAgB,CAAC;AAGlE,MAAM,OAAO,2BAA4B,SAAQ,KAAK;IACzC,IAAI,GAAoC,EAAE,GAAG,gCAAgC,EAAE,CAAC;IAEzF;QACI,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,gCAAgC,CAAC,CAAC,CAAC;QACxD,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;IAC9C,CAAC;CACJ"}

package/dist/api/client.d.ts

@@ -1,5 +1,5 @@
 import { type ApiClientOptions, type ApiResponse, type IAuthenticator, type ServerHealthView } from './types.js';
-import type { SessionManager } from '../session/manager.js';
+import type { IJwtSession } from '../session/types.js';
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 export interface RequestOptions {
     method: HttpMethod;
@@ -17,7 +17,7 @@ export declare class ApiClient {
     /**
      * Low-level request without auth. Use for public endpoints (SIWE nonce/verify, device flow).
      */
-    request<T>(path: string, options?: RequestOptions | null): Promise<ApiResponse<T>>;
+    request<T>(path: string, options?: RequestOptions | null, signal?: AbortSignal | null): Promise<ApiResponse<T>>;
     /**
      * The outcome is kept out of the reachability signal: this may target an endpoint an older server
      * does not serve at all, which says nothing about the API being up.
@@ -25,14 +25,16 @@ export declare class ApiClient {
     requestWithTimeout<T>(path: string, timeoutMs: number): Promise<ApiResponse<T>>;
     /**
      * Request with a `Authorization: Bearer <jwt>` header. The token is obtained from the
-     * authenticator (which (re-)logs in when missing/expired). On a 401 the authenticator is
-     * asked to re-authenticate and the request is retried exactly once.
+     * authenticator (which logs in when missing/expired). A 401 clears the game JWT and asks the
+     * caller to authenticate explicitly before choosing whether to retry the operation.
      */
     authenticatedRequest<T>(path: string, options?: RequestOptions | null): Promise<ApiResponse<T>>;
     private send;
+    private fetchResponse;
+    private parseResponse;
     private setReachable;
     getServerHealth(): ServerHealthView;
     getBaseUrl(): string;
-    getSession(): SessionManager;
+    getSession(): IJwtSession;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/api/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AACA,OAAO,EACH,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAEhB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACxB,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAG5D,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;AAErE,MAAM,WAAW,cAAc;IAC3B,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;CACxB;AAED,qBAAa,SAAS;IAClB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,aAAa,CAA+B;IACpD,OAAO,CAAC,eAAe,CAAQ;IAC/B,OAAO,CAAC,gBAAgB,CAAuB;gBAEnC,OAAO,EAAE,gBAAgB;IAMrC,gBAAgB,CAAC,aAAa,EAAE,cAAc,GAAG,IAAI;IAIrD;;OAEG;IACG,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAc,GAAG,IAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAI9F;;;OAGG;IACG,kBAAkB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAIrF;;;;OAIG;IACG,oBAAoB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAc,GAAG,IAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;YAoB7F,IAAI;IAyDlB,OAAO,CAAC,YAAY;IAapB,eAAe,IAAI,gBAAgB;IAInC,UAAU,IAAI,MAAM;IAIpB,UAAU,IAAI,cAAc;CAG/B"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAEA,OAAO,EACH,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAEhB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACxB,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGvD,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;AAErE,MAAM,WAAW,cAAc;IAC3B,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;CACxB;AAED,qBAAa,SAAS;IAClB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,aAAa,CAA+B;IACpD,OAAO,CAAC,eAAe,CAAQ;IAC/B,OAAO,CAAC,gBAAgB,CAAuB;gBAEnC,OAAO,EAAE,gBAAgB;IAMrC,gBAAgB,CAAC,aAAa,EAAE,cAAc,GAAG,IAAI;IAIrD;;OAEG;IACG,OAAO,CAAC,CAAC,EACX,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAc,GAAG,IAAW,EACrC,MAAM,GAAE,WAAW,GAAG,IAAW,GAClC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAI1B;;;OAGG;IACG,kBAAkB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAIrF;;;;OAIG;IACG,oBAAoB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAc,GAAG,IAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;YAsB7F,IAAI;YAcJ,aAAa;YA+Cb,aAAa;IAwB3B,OAAO,CAAC,YAAY;IAapB,eAAe,IAAI,gBAAgB;IAInC,UAAU,IAAI,MAAM;IAIpB,UAAU,IAAI,WAAW;CAG5B"}

package/dist/api/client.js

@@ -1,3 +1,4 @@
+import { AuthenticationRequiredError } from './authentication-required.error.js';
 import { parseJsonBody } from './response.utils.js';
 import { HttpStatus, } from './types.js';
 import { errorMessage } from '../utils/error.utils.js';
@@ -19,8 +20,8 @@ export class ApiClient {
     /**
      * Low-level request without auth. Use for public endpoints (SIWE nonce/verify, device flow).
      */
-    async request(path, options = null) {
-        return this.send(path, options?.method ?? 'GET', options?.body ?? null, null);
+    async request(path, options = null, signal = null) {
+        return this.send(path, options?.method ?? 'GET', options?.body ?? null, null, null, true, signal);
     }
     /**
      * The outcome is kept out of the reachability signal: this may target an endpoint an older server
@@ -31,8 +32,8 @@ export class ApiClient {
     }
     /**
      * Request with a `Authorization: Bearer <jwt>` header. The token is obtained from the
-     * authenticator (which (re-)logs in when missing/expired). On a 401 the authenticator is
-     * asked to re-authenticate and the request is retried exactly once.
+     * authenticator (which logs in when missing/expired). A 401 clears the game JWT and asks the
+     * caller to authenticate explicitly before choosing whether to retry the operation.
      */
     async authenticatedRequest(path, options = null) {
         if (!this.authenticator) {
@@ -41,24 +42,33 @@ export class ApiClient {
         const method = options?.method ?? 'GET';
         const body = options?.body ?? null;
         const token = await this.authenticator.getAccessToken();
-        const first = await this.send(path, method, body, { Authorization: `Bearer ${token}` });
-        if (first.status !== HttpStatus.Unauthorized) {
-            return first;
+        const response = await this.fetchResponse(path, method, body, { Authorization: `Bearer ${token}` });
+        if (response.status === HttpStatus.Unauthorized) {
+            this.setReachable(true, null);
+            this.logger.debug('api response', { method, path, status: response.status });
+            this.session.clearJwt();
+            this.logger.warn('authenticated request got 401 — game JWT cleared', { path });
+            throw new AuthenticationRequiredError();
         }
-        this.logger.warn('authenticated request got 401 — re-authenticating and retrying once', { path });
-        const fresh = await this.authenticator.reauthenticate();
-        return this.send(path, method, body, { Authorization: `Bearer ${fresh}` });
+        return this.parseResponse(response, method, path);
+    }
+    async send(path, method, body, extraHeaders, timeoutMs = null, trackHealth = true, signal = null) {
+        const response = await this.fetchResponse(path, method, body, extraHeaders, timeoutMs, trackHealth, signal);
+        return this.parseResponse(response, method, path, trackHealth);
     }
-    async send(path, method, body, extraHeaders, timeoutMs = null, trackHealth = true) {
+    async fetchResponse(path, method, body, extraHeaders, timeoutMs = null, trackHealth = true, signal = null) {
         const url = `${this.baseUrl}${path}`;
         const headers = {
             'Content-Type': 'application/json',
             ...(extraHeaders ?? {}),
         };
         const init = { method, headers };
-        if (timeoutMs !== null) {
-            init.signal = AbortSignal.timeout(timeoutMs);
-        }
+        const timeoutSignal = timeoutMs === null ? null : AbortSignal.timeout(timeoutMs);
+        const requestSignal = signal !== null && timeoutSignal !== null
+            ? AbortSignal.any([signal, timeoutSignal])
+            : (signal ?? timeoutSignal);
+        if (requestSignal !== null)
+            init.signal = requestSignal;
         if (body !== undefined && body !== null) {
             init.body = JSON.stringify(body);
         }
@@ -68,12 +78,17 @@ export class ApiClient {
             response = await fetch(url, init);
         }
         catch (error) {
+            if (signal?.aborted === true)
+                signal.throwIfAborted();
             if (trackHealth) {
                 this.setReachable(false, errorMessage(error));
             }
             throw new Error(`Cannot reach the game API at ${this.baseUrl} — the server is likely down or unreachable. ` +
                 `Retry shortly. (${errorMessage(error)})`);
         }
+        return response;
+    }
+    async parseResponse(response, method, path, trackHealth = true) {
         let data;
         try {
             data = await parseJsonBody(response);

package/dist/api/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"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"}

package/dist/api/constants.d.ts

@@ -1,5 +1,7 @@
+import { type AuthenticationRequiredErrorData } from './types.js';
 export declare const RESPONSE_BODY_SNIPPET_LENGTH = 200;
 export declare const HTTP_OK = 200;
 export declare const HTTP_MULTIPLE_CHOICES = 300;
 export declare const OPEN_REVEAL_REQUESTS_PATH = "/api/v1/reveal/requests";
+export declare const AUTHENTICATION_REQUIRED_RECOVERY: AuthenticationRequiredErrorData;
 //# sourceMappingURL=constants.d.ts.map

package/dist/api/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/api/constants.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAGhD,eAAO,MAAM,OAAO,MAAM,CAAC;AAC3B,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,eAAO,MAAM,yBAAyB,4BAA4B,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/api/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsD,KAAK,+BAA+B,EAAE,MAAM,YAAY,CAAC;AAItH,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAGhD,eAAO,MAAM,OAAO,MAAM,CAAC;AAC3B,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,eAAO,MAAM,yBAAyB,4BAA4B,CAAC;AAEnE,eAAO,MAAM,gCAAgC,EAAE,+BAI9C,CAAC"}

package/dist/api/constants.js

@@ -1,3 +1,4 @@
+import { ApiAuthenticationErrorCode, AuthenticationNextTool } from './types.js';
 // Max characters of a non-JSON response body echoed back in the error message — enough to identify
 // a gateway/error page without dumping a full HTML document into the agent's context.
 export const RESPONSE_BODY_SNIPPET_LENGTH = 200;
@@ -5,4 +6,9 @@ export const RESPONSE_BODY_SNIPPET_LENGTH = 200;
 export const HTTP_OK = 200;
 export const HTTP_MULTIPLE_CHOICES = 300;
 export const OPEN_REVEAL_REQUESTS_PATH = '/api/v1/reveal/requests';
+export const AUTHENTICATION_REQUIRED_RECOVERY = {
+    code: ApiAuthenticationErrorCode.AuthenticationRequired,
+    stateCleared: true,
+    nextTool: AuthenticationNextTool.Authenticate,
+};
 //# sourceMappingURL=constants.js.map

package/dist/api/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/api/constants.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,sFAAsF;AACtF,MAAM,CAAC,MAAM,4BAA4B,GAAG,GAAG,CAAC;AAEhD,qEAAqE;AACrE,MAAM,CAAC,MAAM,OAAO,GAAG,GAAG,CAAC;AAC3B,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAEzC,MAAM,CAAC,MAAM,yBAAyB,GAAG,yBAAyB,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/api/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,sBAAsB,EAAwC,MAAM,YAAY,CAAC;AAEtH,mGAAmG;AACnG,sFAAsF;AACtF,MAAM,CAAC,MAAM,4BAA4B,GAAG,GAAG,CAAC;AAEhD,qEAAqE;AACrE,MAAM,CAAC,MAAM,OAAO,GAAG,GAAG,CAAC;AAC3B,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAEzC,MAAM,CAAC,MAAM,yBAAyB,GAAG,yBAAyB,CAAC;AAEnE,MAAM,CAAC,MAAM,gCAAgC,GAAoC;IAC7E,IAAI,EAAE,0BAA0B,CAAC,sBAAsB;IACvD,YAAY,EAAE,IAAI;IAClB,QAAQ,EAAE,sBAAsB,CAAC,YAAY;CAChD,CAAC"}