constructor-research-mcp 0.3.2 → 0.4.0-beta.2

package/INSTALL.md

@@ -1,11 +1,11 @@
 # Install the Constructor Research MCP
 
-The MCP lets Claude Code, Codex or OpenCode deploy apps to Constructor Research: constructor.app, or your organisation's Constructor, such as acme.constructor.app. It runs on your machine as a local MCP server, installed from npm. Each tool signs in to Constructor once, with its own session.
+The MCP lets Claude Code, Codex or OpenCode deploy apps to Constructor Research: constructor.app, or your organisation's Constructor, such as acme.constructor.app. It runs on your machine as a local MCP server, installed from npm, and works with your personal Constructor access key.
 
 ## What you need
 
 - Node.js 22 or later ([nodejs.org](https://nodejs.org), or `nvm install 22`)
-- Chrome, Edge, Chromium or Brave, for signing in
+- a personal access key (`rk-…`) for your Constructor
 - macOS, Windows or Linux
 
 ## 1. Add it to your tool
@@ -13,19 +13,19 @@ The MCP lets Claude Code, Codex or OpenCode deploy apps to Constructor Research:
 **Claude Code**: run once:
 
 ```sh
-claude mcp add --scope user constructor-research -- npx -y constructor-research-mcp@latest
+claude mcp add --scope user constructor-research -- npx -y constructor-research-mcp@beta
 ```
 
 On Windows (not WSL), use this instead:
 
 ```bat
-claude mcp add --scope user constructor-research -- cmd /c npx -y constructor-research-mcp@latest
+claude mcp add --scope user constructor-research -- cmd /c npx -y constructor-research-mcp@beta
 ```
 
 **Codex**: run once:
 
 ```sh
-codex mcp add constructor-research -- npx -y constructor-research-mcp@latest
+codex mcp add constructor-research -- npx -y constructor-research-mcp@beta
 ```
 
 The first start downloads the package and can exceed Codex's 10-second start limit. If Codex reports a timeout, restart it once, or add `startup_timeout_sec = 60` under `[mcp_servers.constructor-research]` in `~/.codex/config.toml`. The full entry, if you prefer to write it by hand:
@@ -33,7 +33,7 @@ The first start downloads the package and can exceed Codex's 10-second start lim
 ```toml
 [mcp_servers.constructor-research]
 command = "npx"
-args = ["-y", "constructor-research-mcp@latest"]
+args = ["-y", "constructor-research-mcp@beta"]
 startup_timeout_sec = 60
 tool_timeout_sec = 30
 ```
@@ -41,13 +41,13 @@ tool_timeout_sec = 30
 **OpenCode**: run once; it adds the entry to your OpenCode config and keeps what is already there. Check your version with `opencode --version`. OpenCode 2.x:
 
 ```sh
-opencode mcp add --global constructor-research -- npx -y constructor-research-mcp@latest
+opencode mcp add --global constructor-research -- npx -y constructor-research-mcp@beta
 ```
 
 Without `--global`, OpenCode 2.x adds it to the current folder's project config instead. OpenCode 1.x has no `--global` and writes to your user config when run outside a project:
 
 ```sh
-opencode mcp add constructor-research -- npx -y constructor-research-mcp@latest
+opencode mcp add constructor-research -- npx -y constructor-research-mcp@beta
 ```
 
 Or add it by hand to `~/.config/opencode/opencode.json` (or a project's `opencode.json`). This is the 1.x layout; in 2.x the entry goes one level deeper, under `mcp.servers`, as in [examples/opencode-v2.json](examples/opencode-v2.json):
@@ -58,22 +58,25 @@ Or add it by hand to `~/.config/opencode/opencode.json` (or a project's `opencod
   "mcp": {
     "constructor-research": {
       "type": "local",
-      "command": ["npx", "-y", "constructor-research-mcp@latest"]
+      "command": ["npx", "-y", "constructor-research-mcp@beta"]
     }
   }
 }
 ```
 
-Do not put a token or cookie file in these settings; sign-in is handled by the MCP.
+Do not put the key in these settings unless you have to; the next step saves it where every tool finds it.
 
-## 2. Restart and sign in
+## 2. Save your access key
 
-1. Restart the tool, or run `/mcp` in Claude Code, so it starts the MCP. The first start downloads it and can take a minute.
-2. Ask the agent to sign in. If your Constructor is not constructor.app, give its address, for example "sign in to Constructor at https://acme.constructor.app". A desk link from it works too.
-3. The agent says a sign-in window will open and calls `sign_in`. A separate browser window opens at your Constructor's sign-in page.
-4. Sign in. The window closes by itself.
+In a terminal, run this with your Constructor's address and paste the key when asked (it is not shown):
 
-The MCP then works with the Constructor you signed in to; to switch, ask the agent to sign in to the other one. The session is saved for that tool only, in `~/.config/constructor-research/sessions/<tool>.txt`, and renewed automatically for 14 days. A day before it ends, the agent asks you to sign in again.
+```sh
+npx -y -p constructor-research-mcp@beta constructor-research-set-key https://acme.constructor.app
+```
+
+It checks the key with Constructor and saves it, with that address, to `~/.config/constructor-research/access-key.json` (readable only by you). Claude Code, Codex and OpenCode all use this one key, and the MCP works with that Constructor. To switch Constructor or replace a revoked key, run it again. Never paste the key into the chat.
+
+Then restart the tool, or run `/mcp` in Claude Code, so it starts the MCP. The first start downloads it and can take a minute.
 
 ## 3. Optional: get told when a deployment finishes
 
@@ -85,7 +88,7 @@ Builds can take many minutes. These add-ons wake the agent when a deployment it
 
 ## Update
 
-Restart the tool (or `/mcp` in Claude Code): `@latest` fetches the newest version on start. Your sign-in is kept.
+Restart the tool (or `/mcp` in Claude Code): `@beta` fetches the newest beta on start. Your key is kept.
 
 ## Troubleshooting
 
@@ -95,18 +98,14 @@ Restart the tool (or `/mcp` in Claude Code): `@latest` fetches the newest versio
 which npx
 ```
 
-**`sign_in` says no browser was found.** Set `CONSTRUCTOR_BROWSER` in the MCP settings to the browser's executable.
+**A tool returns `needs_key`.** No key is saved, or Constructor rejected it (revoked or expired). Save a new one with the command in step 2.
 
-**No screen (a remote Linux machine).** In the browser on your own machine, open Constructor, then DevTools → Network → right-click a request → Copy as cURL. Save it to a file and run (with `codex` or `opencode` in place of `claude-code` for those tools):
-
-```sh
-npx -y -p constructor-research-mcp constructor-research-set-token <file> --for claude-code
-```
+**`set-key` says the address answered an HTTP error.** That Constructor may not have the public API yet, or you are off the VPN it needs.
 
 **Check the MCP on its own.** Run the MCP Inspector, then turn on the server's toggle and open Tools:
 
 ```sh
-npx @modelcontextprotocol/inspector@2.11.0 -- npx -y constructor-research-mcp@latest
+npx @modelcontextprotocol/inspector@2.11.0 -- npx -y constructor-research-mcp@beta
 ```
 
 ## Uninstall
@@ -117,7 +116,7 @@ Remove `constructor-research` from your tool's settings. In Claude Code:
 claude mcp remove constructor-research --scope user
 ```
 
-To remove your data too, delete the sign-in sessions and deployment progress:
+To remove your data too, delete the saved key and deployment progress:
 
 ```sh
 rm -rf ~/.config/constructor-research ~/.local/state/constructor-research-mcp

package/README.md

@@ -1,5 +1,7 @@
 # Constructor Research MCP
 
+> **Beta (0.4.0-beta):** works only with Constructor's public API and a personal access key (`rk-…`); there is no browser sign-in. The public API is not yet on every Constructor. Install with `@beta`; `@latest` is still 0.3.x with browser sign-in.
+
 Local stdio MCP for Codex CLI, Claude Code and OpenCode. Submit the whole application once; the MCP builds images, connects services, configures them and starts them. The agent supplies missing configuration and reports the result.
 
 ## Install
@@ -9,76 +11,71 @@ You need Node.js 22+. Then add the MCP to your tool.
 **Claude Code**
 
 ```sh
-claude mcp add --scope user constructor-research -- npx -y constructor-research-mcp@latest
+claude mcp add --scope user constructor-research -- npx -y constructor-research-mcp@beta
 ```
 
 **Codex**
 
 ```sh
-codex mcp add constructor-research -- npx -y constructor-research-mcp@latest
+codex mcp add constructor-research -- npx -y constructor-research-mcp@beta
 ```
 
 **OpenCode 2.x**
 
 ```sh
-opencode mcp add --global constructor-research -- npx -y constructor-research-mcp@latest
+opencode mcp add --global constructor-research -- npx -y constructor-research-mcp@beta
 ```
 
 **OpenCode 1.x** (no `--global` there):
 
 ```sh
-opencode mcp add constructor-research -- npx -y constructor-research-mcp@latest
+opencode mcp add constructor-research -- npx -y constructor-research-mcp@beta
 ```
 
-Then restart the tool and ask the agent anything about Constructor; it signs you in through the `sign_in` tool on first use. Windows notes, the optional wake-up hooks and troubleshooting are in [INSTALL.md](INSTALL.md). Restarting the tool picks up a new version.
+Then save your personal access key (see below), restart the tool and ask the agent anything about Constructor. Windows notes, the optional wake-up hooks and troubleshooting are in [INSTALL.md](INSTALL.md). Restarting the tool picks up a new version.
 
-## Authentication and connection
+## Access key and connection
 
-Each harness signs in once and keeps its own Constructor session; nothing is stored centrally and nothing goes in the MCP settings. When a tool returns `needs_auth`, the agent tells the user a sign-in window is about to open and calls `sign_in`:
+The MCP uses only a personal access key (`rk-…`) from Constructor's public API; there is no browser sign-in. Every request carries it as `X-Research-AccessKey: Bearer rk-…`, to the account API (`/api/platform-account/v1`), the desk storage (WebDAV) and the logs alike. The key never goes through the chat: the user saves it in a terminal, where it is read hidden, checked against Constructor and saved:
 
-1. The MCP opens a separate browser window (Chrome, Edge, Chromium or Brave, on macOS, Windows or Linux; `CONSTRUCTOR_BROWSER` names another executable) with a fresh temporary profile at the Constructor sign-in page.
-2. The user signs in. The MCP reads the session cookies, closes the window itself and deletes the profile.
-3. It saves `ap_access_token`, `ap_id_token` and `ap_refresh_token` to that harness's session file and answers `signed_in`. No token is ever returned or printed.
+```sh
+npx -y -p constructor-research-mcp@beta constructor-research-set-key https://acme.constructor.app
+```
 
-The MCP works with one Constructor at a time: the one the user signed in to, recorded as a `host=` line in the session file. Before the first sign-in it is `https://constructor.app`, or the host of a desk link the user gave. For another Constructor (for example `https://acme.constructor.app`), the agent passes any link from it as `sign_in`'s `url`; the new sign-in replaces the old one, and the MCP works there from then on. A desk link from a different Constructor than the signed-in one returns `wrong_environment`, which tells the agent to sign in there with that link.
+It goes to `~/.config/constructor-research/access-key.json` (mode 600) together with the Constructor it belongs to, and the MCP works with that Constructor. All harnesses (Claude Code, Codex, OpenCode) and the wait command share this one file. Every request rereads it, so a new key needs no restart. A key is never sent to a Constructor other than the one it was saved for.
 
-`sign_in` waits up to `wait_seconds` (default 20, so it stays within short harness tool timeouts); while the user is still signing in it returns `sign_in_pending`, and calling it again waits on the same window. With a renewable session already saved it answers `signed_in` without opening anything (`force=true` signs in again).
+Instead of the file, `CONSTRUCTOR_ACCESS_KEY` (with `CONSTRUCTOR_BASE_URL`) can be set in the MCP settings; it takes precedence. The wait hooks do not see the MCP settings, so with this option they need the same variables in their own environment.
 
-The harness is recognised from the client name in the MCP handshake; its session file is `~/.config/constructor-research/sessions/<harness>.txt` (`claude-code`, `codex`, `opencode`; another client gets its own name), mode 600. Separate windows matter because a refresh token works once: two holders of one session would log each other out by renewing. Several sessions of the same harness share its file safely (below).
+Without a key, or when Constructor rejects it (401: revoked, expired or for another Constructor), tools return `needs_key` with the command above; a deployment pauses as `needs_key` and resumes on the next check once a valid key is saved. A desk link from another Constructor returns `wrong_environment`.
 
-The access token lasts an hour. When it has under 10 minutes left, the next request first renews it: `GET /auth/session` with only the refresh token, which answers with new tokens that are saved at once. Renewal runs under `<session file>.lock`, so processes sharing a file renew once and the others use the saved tokens. Requests send only the access token, so the gateway never renews behind the MCP's back. The server allows renewal until the `max_slt` claim, 14 days after sign-in; from a day before that, every response carries `auth_warning` asking the agent to have the user sign in again. If the refresh token was already used elsewhere, it is dropped and, once the access token expires, `needs_auth` explains why. A session is never sent to a Constructor other than the one it was signed in to.
+Deployment must be switched on for the project. If it is off and the key may not switch it on (403), the operation fails at stage `prepare` with a message asking the user to switch it on in Constructor.
 
-The same sign-in from a terminal (use `codex` or `opencode` in place of `claude-code`, or `--to <file>`; `--url` names a Constructor other than constructor.app):
+| Variable                            | Default                                                                                         |
+| ----------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `CONSTRUCTOR_BASE_URL`              | unset: the Constructor of the saved key, else `https://constructor.app`; set, it fixes the host |
+| `CONSTRUCTOR_API_PATH`              | `/api/platform-account/v1`                                                                      |
+| `CONSTRUCTOR_STORAGE_PATH`          | `/api/platform-storage`                                                                         |
+| `CONSTRUCTOR_ACCESS_KEY`            | unset: the key file is used                                                                     |
+| `CONSTRUCTOR_KEY_FILE`              | `~/.config/constructor-research/access-key.json`                                                |
+| `CONSTRUCTOR_DESK_ROOT`             | `~/project` (inside a desk only)                                                                |
+| `CONSTRUCTOR_STATE_DIR`             | `~/.local/state/constructor-research-mcp`                                                       |
+| `CONSTRUCTOR_UPLOAD_SETTLE_SECONDS` | `30`                                                                                            |
+| `CONSTRUCTOR_READINESS_SECONDS`     | `60`                                                                                            |
 
-```sh
-npx -y -p constructor-research-mcp constructor-research-login --for claude-code
-npx -y -p constructor-research-mcp constructor-research-login --url https://acme.constructor.app --for claude-code
-```
-
-On a machine without a screen (Linux without `DISPLAY`/`WAYLAND_DISPLAY`), `sign_in` says so; save a session from a copied cURL (DevTools → Network → Copy as cURL) instead:
-
-```sh
-npx -y -p constructor-research-mcp constructor-research-set-token capture.txt --for codex
-```
+HTTPS is required except on localhost.
 
-The session belongs to the Constructor the cURL was sent to. It keeps the refresh token when the cURL has one (and warns that the browser it came from shares that session), and prints the expiry, never a token. A plain access token, without a refresh token, cannot be renewed and expires after an hour: under 3 minutes left, operations that change anything are refused (`get_deployment` still works); under 10 minutes every response carries `auth_warning`, and `deploy_app`/`update_app`/`build_image` warn from 40 minutes, because a build can outlast the token.
+## Inside a Constructor desk (VS Code)
 
-`CONSTRUCTOR_COOKIE_FILE` pins one session file for every harness instead (for scripts and tests). Every request rereads the session file, so a new sign-in needs no restart.
+When the MCP runs in VS Code inside a Constructor Research desk, it finds that desk from the environment Constructor sets there (`ROLOS_PROJECT_ID`/`RESEARCH_PROJECT_ID`, `ROLOS_DESK_ID`/`RESEARCH_DESK_ID`, `ROLOS_API_SERVER`/`RESEARCH_API_SERVER`) and works in it:
 
-| Variable                            | Default                                                                                  |
-| ----------------------------------- | ---------------------------------------------------------------------------------------- |
-| `CONSTRUCTOR_BASE_URL`              | unset: the signed-in Constructor, else `https://constructor.app`; set, it fixes the host |
-| `CONSTRUCTOR_API_PATH`              | `/api/platform-account`                                                                  |
-| `CONSTRUCTOR_STORAGE_PATH`          | `/api/platform-storage`                                                                  |
-| `CONSTRUCTOR_COOKIE_FILE`           | unset: `~/.config/constructor-research/sessions/<harness>.txt`                           |
-| `CONSTRUCTOR_BROWSER`               | first Chrome, Edge, Chromium or Brave found                                              |
-| `CONSTRUCTOR_STATE_DIR`             | `~/.local/state/constructor-research-mcp`                                                |
-| `CONSTRUCTOR_UPLOAD_SETTLE_SECONDS` | `30`                                                                                     |
-| `CONSTRUCTOR_READINESS_SECONDS`     | `60`                                                                                     |
+- the desk's project folder (`~/project`, or `CONSTRUCTOR_DESK_ROOT`) is its disk, so the agent creates and changes files there directly; nothing is uploaded, and `sync_files`, `list_files`, `create_folder`, `move_path` and `delete_path` answer `local_desk` for this desk;
+- `build_image`, `deploy_app`, `update_app`, `start_app`, `stop_app` and `list_images` act on this desk and project without a desk link; a `desk_url` or other IDs still name another desk;
+- `build.dockerfile` is the path inside the project folder (`/backend/Dockerfile`), or `build.local_path` names a folder inside it; Dockerfiles are checked from the local files;
+- the MCP works with the desk's Constructor (`ROLOS_API_SERVER`) unless `CONSTRUCTOR_BASE_URL` is set.
 
-HTTPS is required except on localhost. API-key authentication is not implemented yet.
+`CONSTRUCTOR_LOCAL_DESK=0` turns this off.
 
-## Fourteen tools
+## Thirteen tools
 
 | Tool                     | Agent's task                                                                        |
 | ------------------------ | ----------------------------------------------------------------------------------- |
@@ -90,13 +87,12 @@ HTTPS is required except on localhost. API-key authentication is not implemented
 | `build_image`            | Build an image independently when needed.                                           |
 | `list_images`            | List image IDs, Dockerfiles and native build statuses.                              |
 | `list_files`             | List a disk's files and folders; `recursive:true` walks subfolders.                 |
-| `sign_in`                | Open a sign-in window for the user when a tool returns `needs_auth`.                |
 | `create_folder`          | Create a disk folder, including missing parents.                                    |
 | `sync_files`             | Upload new and changed files; asks once before replacing existing files.            |
 | `move_path`              | Rename or move files/folders in one batch, approved once; never overwrites.         |
 | `delete_path`            | Delete files/folders in one batch; reports first, deletes only with `confirm:true`. |
 
-No special clone/new-instance workflow is implemented. The fourteen tools use the same standard MCP transport across harnesses.
+No special clone/new-instance workflow is implemented. The thirteen tools use the same standard MCP transport across harnesses.
 
 ## Where to act: the desk link
 
@@ -106,7 +102,7 @@ The agent does not choose a project or desk. It asks the user for the desk link:
 https://constructor.app/research/projects/<project_id>/desks/<desk_id>/viewer/file
 ```
 
-Every tool accepts it as `desk_url`, in place of `project_id`/`desk_id`. Anything after `/desks/<desk_id>` is ignored. The link's host must be the signed-in Constructor; a link from another one returns `wrong_environment` (see sign-in above). Explicit IDs, if also sent, must agree with the link. In `deploy_app`/`update_app`, builds without their own `desk_id` use the link's desk; `start_app`/`stop_app` and `get_deployment` take only the project from it.
+Every tool accepts it as `desk_url`, in place of `project_id`/`desk_id`. Anything after `/desks/<desk_id>` is ignored. The link's host must be the Constructor the key belongs to; a link from another one returns `wrong_environment` (see the access key above). Explicit IDs, if also sent, must agree with the link. In `deploy_app`/`update_app`, builds without their own `desk_id` use the link's desk; `start_app`/`stop_app` and `get_deployment` take only the project from it.
 
 ## Normal deployment flow
 
@@ -187,7 +183,7 @@ Replace a service's `build` with `"image_id":"IMAGE_ID"` to skip building. `list
 
 ## Missing prerequisites
 
-- **No/expired token:** `needs_auth` with the file and format to use (see Authentication). Replace the token, then check the same deployment again.
+- **No or rejected key:** `needs_key` with the command to save one (see Access key). Save a valid key, then check the same deployment again.
 - **No project/disk:** omit `project_id`, optionally supply `project_name`, and use build sources without disk IDs. MCP creates the project/disk and enables deployment tools.
 - **Files absent:** `needs_upload` lists disks and Dockerfile paths. Upload with `sync_files` (or manually), then call `get_deployment` with `deployment_id` and `files_uploaded:true`.
 
@@ -234,11 +230,11 @@ Learned from live runs (28 Oct 2026):
 
 ## State and recovery
 
-Progress and sanitized results are checkpointed. Configuration secrets remain in owner-only local checkpoint files (`0600`, directory `0700`); tool responses return environment-variable names, never values. Cookies are not checkpointed. Do not commit credentials or state.
+Progress and sanitized results are checkpointed. Configuration secrets remain in owner-only local checkpoint files (`0600`, directory `0700`); tool responses return environment-variable names, never values. The access key is not checkpointed. Do not commit credentials or state.
 
 Checkpoints are bound to the API endpoint. A shared state directory coordinates local harnesses. `resume:false` on `get_deployment` observes without scheduling execution or confirming uploads; already running background work is not paused.
 
-Terminal states: `built`, `started`, `stopped`, `failed`, `needs_reconciliation`, `superseded`. A new `update_app`, `start_app` or `stop_app` for an application ends that application's unfinished deployments as `superseded`, so an older one cannot apply its images after the newer one; its builds keep running on Constructor but are not used. The new result lists them in `replaced`, with the services they were changing that the new update leaves out. User-action pauses: `needs_auth`, `needs_upload`. Other statuses indicate background progress. An executor stops after one hour rather than retrying forever.
+Terminal states: `built`, `started`, `stopped`, `failed`, `needs_reconciliation`, `superseded`. A new `update_app`, `start_app` or `stop_app` for an application ends that application's unfinished deployments as `superseded`, so an older one cannot apply its images after the newer one; its builds keep running on Constructor but are not used. The new result lists them in `replaced`, with the services they were changing that the new update leaves out. User-action pauses: `needs_key`, `needs_upload`. Other statuses indicate background progress. An executor stops after one hour rather than retrying forever.
 
 For `needs_reconciliation`, inspect the possible remote mutation before submitting a new operation. The server never blindly repeats an uncertain create. A `.lock` left by a process that no longer exists (a server killed or restarted mid-step) is removed automatically on the next operation; a lock held by a live process returns `busy`. Checkpoints remain available. No rollback or resource deletion is automated.
 
@@ -256,10 +252,10 @@ Constructor serves logs only live, as a stream: a build log while the build runs
 
 ## Waiting for long builds
 
-Builds can run for many minutes. The MCP keeps executing in the background, but an agent that has ended its turn is not told when they finish. `dist/wait.js` (bin `constructor-research-wait`) blocks until the given deployments, or all in-progress ones when no ID is given, finish, and prints one line each: status, message, services with public URLs, next step. Exit codes: `0` finished, `2` needs the user (failed, token, upload, volume confirmation), `3` still running at `--max-minutes` (default 60), `4` nothing in progress.
+Builds can run for many minutes. The MCP keeps executing in the background, but an agent that has ended its turn is not told when they finish. `dist/wait.js` (bin `constructor-research-wait`) blocks until the given deployments, or all in-progress ones when no ID is given, finish, and prints one line each: status, message, services with public URLs, next step. Exit codes: `0` finished, `2` needs the user (failed, key, upload, volume confirmation), `3` still running at `--max-minutes` (default 60), `4` nothing in progress.
 
 ```sh
-npx -y -p constructor-research-mcp constructor-research-wait <deployment_id>
+npx -y -p constructor-research-mcp@beta constructor-research-wait <deployment_id>
 ```
 
 It watches the checkpoints the MCP writes. For deployments named by ID, if no process has advanced one for a minute (the MCP was closed), it continues it itself, exactly as the MCP would on restart. Without IDs it only watches, since those deployments may belong to other sessions. While a deployment runs, `next_action` gives the agent the exact command, including the MCP's non-default `CONSTRUCTOR_*` settings; the wait command needs the same settings as the MCP.
@@ -287,7 +283,7 @@ Use the executable directly to keep stdout reserved for MCP. `structuredContent`
 
 ## Disk files
 
-The tools use the disk's WebDAV storage (`/api/platform-storage/desks/{disk}/dav/project/`) with the same cookie. `sync_files`:
+The tools use the disk's WebDAV storage (`/api/platform-storage/desks/{disk}/dav/project/`) with the same key. `sync_files`:
 
 - compares each local file with the disk by size, then by the server's SHA-256 checksum; only new and changed files are sent, and nothing is deleted;
 - uploads new files and creates folders without asking; if existing files would be replaced, it uploads nothing and returns `confirm_required` with the whole plan, to be approved once and repeated with `confirm:true`; `dry_run:true` only previews;

package/dist/api.d.ts

@@ -6,8 +6,8 @@ export declare class ToolError extends Error {
     constructor(code: string, message: string, status?: number | undefined, apiCode?: number | undefined);
 }
 export declare const segment: (s: string) => string;
-/** `exp` (seconds) of the ap_access_token JWT, if readable. */
-export declare function expiry(cookie: string): number | undefined;
+/** A key as Constructor shows it, with or without the "Bearer " the header adds. */
+export declare function cleanKey(raw: string | undefined): string | undefined;
 export declare class PlatformApi {
     readonly config: Config;
     private readonly deadline;
@@ -15,35 +15,16 @@ export declare class PlatformApi {
     /** End of the current call's time budget (epoch ms); Infinity outside one. */
     deadlineMs(): number;
     withBudget<T>(milliseconds: number, fn: () => Promise<T>): Promise<T>;
-    /** How to supply a fresh token, with the exact file this MCP reads. */
-    authHelp(what?: string): string;
+    /** How the user supplies a key; the key itself never passes through the chat. */
+    keyHelp(what?: string): string;
     /**
-     * Works with the Constructor the saved session belongs to; without one, with the host of the
-     * last desk link the user gave, or the default. CONSTRUCTOR_BASE_URL fixes it instead.
+     * Works with the Constructor the saved key belongs to, unless CONSTRUCTOR_BASE_URL fixes it.
+     * Read before every tool call, so a key saved meanwhile is used without a restart.
      */
-    followSession(): Promise<void>;
-    /** The host of a desk link given while nobody is signed in: sign_in opens there. */
-    aimed?: string;
-    /** Set while the sign_in tool's window is open. */
-    signingIn: boolean;
-    /**
-     * Time left on the saved credentials: the login session when it can be renewed
-     * (`max_slt`, the latest renewal the server allows), else the access token.
-     */
-    authLeft(): Promise<{
-        minutes: number;
-        renewable: boolean;
-    } | undefined>;
-    private renewing?;
-    /** The Cookie header for a request: only the access token, renewed first when it runs low. */
-    private cookie;
-    /**
-     * Trades the refresh token for new tokens and saves them before anything else. A refresh
-     * token works once, so several MCP processes sharing the file renew under one lock, and
-     * a process that waited uses the tokens another one just saved.
-     */
-    private renew;
-    private usable;
+    refresh(): Promise<void>;
+    /** The access-key header for a request. */
+    private auth;
+    private rejected;
     /**
      * WebDAV request to a disk's project folder; callers interpret statuses other than 401.
      * The storage gateway answers 502/503/504 now and then under load; requests that are
@@ -55,7 +36,7 @@ export declare class PlatformApi {
     }): Promise<Response>;
     /**
      * Opens a build-log stream. It stays open while the build runs; the caller reads the
-     * body and aborts through `signal`. 401 becomes needs_auth; other statuses are returned.
+     * body and aborts through `signal`. 401 becomes needs_key; other statuses are returned.
      */
     stream(path: string, signal: AbortSignal): Promise<Response>;
     /** Backoff before each storage retry; tests shorten it. */