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

package/dist/api.js

@@ -1,8 +1,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { setTimeout as delay } from "node:timers/promises";
-import { DEFAULT_BASE_URL } from "./config.js";
-import { claims, readSession, saveSession, sessionHost, setCookies, } from "./session.js";
-import { withLock } from "./store.js";
+import { DEFAULT_BASE_URL, VERSION } from "./config.js";
+import { readKeyFile } from "./key.js";
 export class ToolError extends Error {
     code;
     status;
@@ -15,14 +14,12 @@ export class ToolError extends Error {
     }
 }
 export const segment = (s) => encodeURIComponent(s);
-/** `exp` (seconds) of the ap_access_token JWT, if readable. */
-export function expiry(cookie) {
-    const token = /(?:^|;\s*)ap_access_token=([^;\s]+)/.exec(cookie)?.[1];
-    const exp = claims(token)?.exp;
-    return typeof exp === "number" ? exp : undefined;
+/** A key as Constructor shows it, with or without the "Bearer " the header adds. */
+export function cleanKey(raw) {
+    const key = raw?.trim().replace(/^Bearer\s+/i, "");
+    // Printable ASCII only: anything else could not travel in a header.
+    return key && /^[\x21-\x7e]{8,512}$/.test(key) ? key : undefined;
 }
-/** Renew the access token when it has less than this left (it lasts an hour). */
-const RENEW_MS = 10 * 60000;
 export class PlatformApi {
     config;
     deadline = new AsyncLocalStorage();
@@ -36,123 +33,45 @@ export class PlatformApi {
     withBudget(milliseconds, fn) {
         return this.deadline.run(Date.now() + milliseconds, fn);
     }
-    /** How to supply a fresh token, with the exact file this MCP reads. */
-    authHelp(what = "Not signed in to Constructor.") {
-        const to = this.config.cookieFile;
-        return `${what} ${this.signingIn
-            ? "A sign-in window is already open: ask the user to finish signing in there, then call sign_in to confirm."
-            : "Tell the user a sign-in window is about to open, then call the sign_in tool: the user signs in in a separate Chrome window that closes by itself, and the MCP renews the session automatically for up to 14 days."} Without a desktop browser, the user runs: npx -y -p constructor-research-mcp constructor-research-set-token <file with a copied cURL> --to ${to}. Then repeat the same call.`;
+    /** How the user supplies a key; the key itself never passes through the chat. */
+    keyHelp(what = "No Constructor access key is set.") {
+        return `${what} The MCP needs the user's personal access key (rk-…) for ${this.config.baseUrl}. Ask the user to run this in a terminal and paste the key when asked: npx -y -p constructor-research-mcp@${VERSION} constructor-research-set-key ${this.config.baseUrl} (or to set CONSTRUCTOR_ACCESS_KEY and CONSTRUCTOR_BASE_URL in the MCP settings). Never ask the user to paste the key into the chat. Then repeat the same call.`;
     }
     /**
-     * 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.
      */
-    async followSession() {
-        if (this.config.baseUrlFixed)
+    async refresh() {
+        if (this.config.baseUrlFixed || this.config.accessKey)
             return;
-        const host = await sessionHost(this.config.cookieFile);
-        this.config.baseUrl = host ?? this.aimed ?? DEFAULT_BASE_URL;
+        const saved = await readKeyFile(this.config.keyFile).catch(() => undefined);
+        this.config.baseUrl = saved?.url ?? DEFAULT_BASE_URL;
     }
-    /** The host of a desk link given while nobody is signed in: sign_in opens there. */
-    aimed;
-    /** Set while the sign_in tool's window is open. */
-    signingIn = false;
-    /**
-     * 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.
-     */
-    async authLeft() {
-        const saved = await readSession(this.config.cookieFile);
-        const access = claims(saved.get("ap_access_token"));
-        const renewable = saved.has("ap_refresh_token");
-        const end = renewable ? access?.max_slt : access?.exp;
-        if (renewable && end === undefined)
-            return undefined;
-        if (typeof end !== "number")
-            return undefined;
-        return { minutes: (end * 1000 - Date.now()) / 60000, renewable };
-    }
-    renewing;
-    /** The Cookie header for a request: only the access token, renewed first when it runs low. */
-    async cookie() {
-        let saved;
-        try {
-            saved = await readSession(this.config.cookieFile);
-        }
-        catch {
-            saved = new Map();
-        }
-        let token = saved.get("ap_access_token");
-        const exp = expiry(`ap_access_token=${token}`);
-        // Never send one Constructor's session to another.
-        const owner = await sessionHost(this.config.cookieFile);
-        if (owner && owner !== this.config.baseUrl)
-            throw new ToolError("needs_auth", this.authHelp(`${this.config.cookieFile} holds a session for ${owner}, but this MCP works with ${this.config.baseUrl}.`));
-        if (saved.has("ap_refresh_token") &&
-            (!token || (exp !== undefined && exp * 1000 - Date.now() < RENEW_MS)))
-            token = await (this.renewing ??= this.renew().finally(() => (this.renewing = undefined)));
-        else if (!token)
-            throw new ToolError("needs_auth", this.authHelp());
-        else if (exp !== undefined && exp * 1000 <= Date.now())
-            throw new ToolError("needs_auth", this.authHelp(`Token expired at ${new Date(exp * 1000).toISOString().slice(11, 16)} UTC.`));
-        return `ap_access_token=${token}`;
-    }
-    /**
-     * 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.
-     */
-    renew() {
-        const file = this.config.cookieFile;
-        return withLock(file + ".lock", async () => {
-            const saved = await readSession(file);
-            const token = saved.get("ap_access_token");
-            const exp = expiry(`ap_access_token=${token}`);
-            const valid = !!token && (exp === undefined || exp * 1000 > Date.now());
-            const refresh = saved.get("ap_refresh_token");
-            if (!refresh ||
-                (exp !== undefined && exp * 1000 - Date.now() >= RENEW_MS))
-                return this.usable(token, valid);
-            let response;
+    /** The access-key header for a request. */
+    async auth() {
+        let key = this.config.accessKey;
+        if (key === undefined) {
+            let saved;
             try {
-                response = await fetch(this.config.baseUrl + this.config.apiPath + "/auth/session", {
-                    // Without an access token the server must renew; the browser does the same.
-                    headers: {
-                        Cookie: `ap_refresh_token=${refresh}`,
-                        Accept: "application/json",
-                    },
-                    redirect: "manual",
-                    signal: AbortSignal.timeout(this.config.requestTimeoutMs),
-                });
-            }
-            catch {
-                if (valid)
-                    return token;
-                throw new ToolError("connection_error", "Could not reach Constructor to renew the session; repeat the same call.");
+                saved = await readKeyFile(this.config.keyFile);
             }
-            await response.body?.cancel();
-            const fresh = setCookies(response);
-            if (fresh.has("ap_access_token") && fresh.has("ap_refresh_token")) {
-                await saveSession(file, new Map([...saved, ...fresh]));
-                return fresh.get("ap_access_token");
+            catch (err) {
+                throw new ToolError("needs_key", this.keyHelp(`${this.config.keyFile} could not be read (${err?.message ?? "invalid"}).`));
             }
-            if (response.status === 401) {
-                // The refresh token is spent; drop it so the file behaves like a plain token.
-                saved.delete("ap_refresh_token");
-                await saveSession(file, saved);
-                if (valid)
-                    return token;
-                throw new ToolError("needs_auth", this.authHelp("The saved login session can no longer be renewed: its refresh token was already used (a browser holding the same session renews it too) or the session reached its 14-day limit."));
-            }
-            if (valid)
-                return token;
-            throw new ToolError("connection_error", `Constructor answered HTTP ${response.status} without new tokens while renewing the session; repeat the same call.`);
-        }, 15000, () => new ToolError("busy", `Another process is renewing the session (${file}.lock); repeat the same call.`));
+            if (!saved)
+                throw new ToolError("needs_key", this.keyHelp());
+            // Never send one Constructor's key to another.
+            if (saved.url !== this.config.baseUrl)
+                throw new ToolError("needs_key", this.keyHelp(`The saved key belongs to ${saved.url}, but this MCP works with ${this.config.baseUrl}.`));
+            key = saved.key;
+        }
+        const clean = cleanKey(key);
+        if (!clean)
+            throw new ToolError("needs_key", this.keyHelp("The access key is not in a valid format."));
+        return { "X-Research-AccessKey": `Bearer ${clean}` };
     }
-    usable(token, valid) {
-        if (valid)
-            return token;
-        throw new ToolError("needs_auth", this.authHelp(token ? "Token expired." : undefined));
+    rejected() {
+        return new ToolError("needs_key", this.keyHelp("Constructor rejected the access key (revoked, expired or for another Constructor)."), 401);
     }
     /**
      * WebDAV request to a disk's project folder; callers interpret statuses other than 401.
@@ -160,7 +79,7 @@ export class PlatformApi {
      * safe to repeat (all but MOVE and DELETE) are retried a few times with backoff.
      */
     async storage(method, desk, path, init = {}) {
-        const cookie = await this.cookie();
+        const auth = await this.auth();
         const retries = ["MOVE", "DELETE"].includes(method)
             ? []
             : this.storageRetryMs;
@@ -174,7 +93,7 @@ export class PlatformApi {
             try {
                 response = await fetch(this.config.baseUrl + this.davRoot(desk) + path, {
                     method,
-                    headers: { Cookie: cookie, ...init.headers },
+                    headers: { ...auth, ...init.headers },
                     body: init.body,
                     redirect: "manual",
                     signal: AbortSignal.timeout(Math.max(1, Math.floor(Math.min(60000, remaining)))),
@@ -192,23 +111,25 @@ export class PlatformApi {
                 await delay(wait);
                 continue;
             }
-            if (response.status === 401)
-                throw new ToolError("needs_auth", this.authHelp("Constructor rejected the token (expired or invalid)."), 401);
+            if (response.status === 401) {
+                await response.body?.cancel();
+                throw this.rejected();
+            }
             return 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.
      */
     async stream(path, signal) {
-        const cookie = await this.cookie();
+        const auth = await this.auth();
         let response;
         try {
             response = await fetch(this.config.baseUrl +
                 (this.config.keeperPath ?? "/api/platform-keeper") +
                 path, {
-                headers: { Cookie: cookie, Accept: "text/event-stream" },
+                headers: { ...auth, Accept: "text/event-stream" },
                 redirect: "manual",
                 signal,
             });
@@ -218,7 +139,7 @@ export class PlatformApi {
         }
         if (response.status === 401) {
             await response.body?.cancel();
-            throw new ToolError("needs_auth", this.authHelp("Constructor rejected the token (expired or invalid)."), 401);
+            throw this.rejected();
         }
         return response;
     }
@@ -229,7 +150,7 @@ export class PlatformApi {
         return `${this.config.storagePath ?? "/api/platform-storage"}/desks/${segment(desk)}/dav/project/`;
     }
     async request(method, path, body) {
-        const cookie = await this.cookie();
+        const auth = await this.auth();
         const remaining = (this.deadline.getStore() ?? Infinity) - Date.now();
         if (remaining <= 0)
             throw new ToolError("connection_error", "Operation time budget exhausted before sending the next request; resume with get_deployment.");
@@ -238,7 +159,7 @@ export class PlatformApi {
             response = await fetch(this.config.baseUrl + this.config.apiPath + path, {
                 method,
                 headers: {
-                    Cookie: cookie,
+                    ...auth,
                     Accept: "application/json",
                     ...(body === undefined ? {} : { "Content-Type": "application/json" }),
                 },
@@ -252,8 +173,10 @@ export class PlatformApi {
                 ? "API connection failed or timed out; retry the read."
                 : "The API request may have been applied. Inspect resources before retrying this mutation.");
         }
-        if (response.status === 401)
-            throw new ToolError("needs_auth", this.authHelp("Constructor rejected the token (expired or invalid)."), 401);
+        if (response.status === 401) {
+            await response.body?.cancel();
+            throw this.rejected();
+        }
         if (!response.ok) {
             if (method !== "GET" && response.status >= 500)
                 throw new ToolError("uncertain_outcome", `Constructor API returned HTTP ${response.status}. The mutation may have been applied; inspect resources before retrying.`, response.status);

package/dist/config.d.ts

@@ -1,14 +1,18 @@
+import { type LocalDesk } from "./desk.js";
 export interface Config {
-    /** The Constructor the MCP works with: the signed-in one, unless CONSTRUCTOR_BASE_URL fixes it. */
+    /** The Constructor the MCP works with: CONSTRUCTOR_BASE_URL, else the one the saved key belongs to. */
     baseUrl: string;
     baseUrlFixed?: boolean;
+    /** The Constructor desk this MCP runs inside (VS Code in Constructor Research), if any. */
+    localDesk?: LocalDesk;
     apiPath: string;
     storagePath?: string;
     /** Build-log service root; build logs stream only while a build runs. */
     keeperPath?: string;
-    /** Session file; each harness gets its own unless CONSTRUCTOR_COOKIE_FILE fixes one. */
-    cookieFile: string;
-    cookieFileFixed?: boolean;
+    /** Personal access key (rk-…) from CONSTRUCTOR_ACCESS_KEY; without it the key file is read. */
+    accessKey?: string;
+    /** Saved key and the Constructor it belongs to (JSON, mode 600); CONSTRUCTOR_KEY_FILE moves it. */
+    keyFile: string;
     stateDir: string;
     requestTimeoutMs: number;
     /** How long to wait for public URLs to answer after start; 0 disables the check. */
@@ -16,28 +20,13 @@ export interface Config {
     /** Pause between uploading to a disk and building from it; 0 disables. */
     uploadSettleSeconds?: number;
 }
-/** Where the MCP works until the user signs in somewhere else. */
+/** Where the MCP works unless CONSTRUCTOR_BASE_URL or the saved key names another Constructor. */
 export declare const DEFAULT_BASE_URL = "https://constructor.app";
 /** The origin of a Constructor link; HTTPS except on localhost. */
 export declare function originOf(link: string): string;
 export declare function configFromEnv(env?: NodeJS.ProcessEnv): Config;
-/** Harnesses with their own session: one sign-in each, nothing shared between them. */
-export declare const HARNESSES: readonly ["claude-code", "codex", "opencode"];
-/** The harness behind an MCP client name (from the initialize handshake). */
-export declare function harnessOf(client?: string): string;
-/** Where a harness's Constructor session is kept (mode 600). */
-export declare function sessionFile(harness: string): string;
-/**
- * Session file named on a command line: --for <harness> or --to <file>; without either,
- * CONSTRUCTOR_COOKIE_FILE. Returns the remaining arguments too.
- */
-export declare function sessionArgs(args: string[], config: Config): {
-    file: string;
-    rest: string[];
-} | {
-    file: undefined;
-    rest: string[];
-};
+/** Where constructor-research-set-key saves the key; the MCP and the wait command read it. */
+export declare const DEFAULT_KEY_FILE = "~/.config/constructor-research/access-key.json";
 /** Shell command that waits for deployments, carrying the settings that differ from the defaults. */
 export declare function waitCommand(config: Config, ids: string[]): string;
 /** This package's version, as published; the server reports it on connect. */

package/dist/config.js

@@ -2,7 +2,8 @@ import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-/** Where the MCP works until the user signs in somewhere else. */
+import { localDeskFromEnv } from "./desk.js";
+/** Where the MCP works unless CONSTRUCTOR_BASE_URL or the saved key names another Constructor. */
 export const DEFAULT_BASE_URL = "https://constructor.app";
 /** The origin of a Constructor link; HTTPS except on localhost. */
 export function originOf(link) {
@@ -28,8 +29,10 @@ export function configFromEnv(env = process.env) {
         if (url.search || url.hash || url.pathname !== "/")
             throw new Error("CONSTRUCTOR_BASE_URL must be an origin without a path or credentials.");
     }
-    const baseUrl = originOf(fixed ?? DEFAULT_BASE_URL);
-    const apiPath = env.CONSTRUCTOR_API_PATH ?? "/api/platform-account";
+    // Inside a Constructor desk, its Constructor is the one to work with.
+    const localDesk = localDeskFromEnv(env, originOf);
+    const baseUrl = originOf(fixed ?? localDesk?.server ?? DEFAULT_BASE_URL);
+    const apiPath = env.CONSTRUCTOR_API_PATH ?? "/api/platform-account/v1";
     if (!/^\/[a-zA-Z0-9/_-]+$/.test(apiPath) || apiPath.includes("//"))
         throw new Error("Invalid CONSTRUCTOR_API_PATH.");
     const storagePath = env.CONSTRUCTOR_STORAGE_PATH ?? "/api/platform-storage";
@@ -41,63 +44,28 @@ export function configFromEnv(env = process.env) {
     const expand = (s) => resolve(s.startsWith("~/") ? homedir() + s.slice(1) : s);
     return {
         baseUrl,
-        baseUrlFixed: !!fixed,
+        baseUrlFixed: !!fixed || !!localDesk?.server,
+        localDesk,
         apiPath: apiPath.replace(/\/$/, ""),
         storagePath: storagePath.replace(/\/$/, ""),
         keeperPath: keeperPath.replace(/\/$/, ""),
-        cookieFile: env.CONSTRUCTOR_COOKIE_FILE
-            ? expand(env.CONSTRUCTOR_COOKIE_FILE)
-            : sessionFile("default"),
-        cookieFileFixed: !!env.CONSTRUCTOR_COOKIE_FILE,
+        accessKey: env.CONSTRUCTOR_ACCESS_KEY?.trim() || undefined,
+        keyFile: expand(env.CONSTRUCTOR_KEY_FILE ?? DEFAULT_KEY_FILE),
         stateDir: expand(env.CONSTRUCTOR_STATE_DIR ?? "~/.local/state/constructor-research-mcp"),
         requestTimeoutMs: 15000,
         uploadSettleSeconds: Math.max(0, Math.min(300, Number(env.CONSTRUCTOR_UPLOAD_SETTLE_SECONDS ?? 30) || 0)),
         readinessSeconds: Math.max(0, Math.min(300, Number(env.CONSTRUCTOR_READINESS_SECONDS ?? 60) || 0)),
     };
 }
-/** Harnesses with their own session: one sign-in each, nothing shared between them. */
-export const HARNESSES = ["claude-code", "codex", "opencode"];
-/** The harness behind an MCP client name (from the initialize handshake). */
-export function harnessOf(client) {
-    const name = (client ?? "").toLowerCase();
-    if (name.includes("claude"))
-        return "claude-code";
-    if (name.includes("codex"))
-        return "codex";
-    if (name.includes("opencode"))
-        return "opencode";
-    return name.replace(/[^a-z0-9-]+/g, "-").replace(/^-|-$/g, "") || "default";
-}
-/** Where a harness's Constructor session is kept (mode 600). */
-export function sessionFile(harness) {
-    return join(homedir(), ".config", "constructor-research", "sessions", `${harness}.txt`);
-}
-/**
- * Session file named on a command line: --for <harness> or --to <file>; without either,
- * CONSTRUCTOR_COOKIE_FILE. Returns the remaining arguments too.
- */
-export function sessionArgs(args, config) {
-    const value = (flag) => {
-        const i = args.indexOf(flag);
-        return i >= 0 ? args[i + 1] : undefined;
-    };
-    const to = value("--to"), harness = value("--for");
-    const rest = args.filter((_, n) => !["--to", "--for"].includes(args[n]) &&
-        !["--to", "--for"].includes(args[n - 1]));
-    if (to)
-        return { file: resolve(to), rest };
-    if (harness && HARNESSES.includes(harness))
-        return { file: sessionFile(harness), rest };
-    if (!harness && config.cookieFileFixed)
-        return { file: config.cookieFile, rest };
-    return { file: undefined, rest };
-}
+/** Where constructor-research-set-key saves the key; the MCP and the wait command read it. */
+export const DEFAULT_KEY_FILE = "~/.config/constructor-research/access-key.json";
 const quote = (s) => /^[\w@%+=:,./-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
 /** Shell command that waits for deployments, carrying the settings that differ from the defaults. */
 export function waitCommand(config, ids) {
     const defaults = configFromEnv({});
     const env = [
-        // The wait command reads the host from the session, as the MCP does, unless it is fixed.
+        // The wait command reads the host from the key file, as the MCP does, unless it is fixed.
+        // The key itself never goes into a command line: CONSTRUCTOR_ACCESS_KEY stays in the environment.
         [
             "CONSTRUCTOR_BASE_URL",
             config.baseUrlFixed ? config.baseUrl : undefined,
@@ -106,7 +74,7 @@ export function waitCommand(config, ids) {
         ["CONSTRUCTOR_API_PATH", config.apiPath, defaults.apiPath],
         ["CONSTRUCTOR_STORAGE_PATH", config.storagePath, defaults.storagePath],
         ["CONSTRUCTOR_KEEPER_PATH", config.keeperPath, defaults.keeperPath],
-        ["CONSTRUCTOR_COOKIE_FILE", config.cookieFile, defaults.cookieFile],
+        ["CONSTRUCTOR_KEY_FILE", config.keyFile, defaults.keyFile],
         ["CONSTRUCTOR_STATE_DIR", config.stateDir, defaults.stateDir],
     ]
         .filter(([, value, standard]) => value !== standard)

package/dist/deployment.d.ts

@@ -72,6 +72,8 @@ export declare class DeploymentEngine {
     get(raw: unknown): Promise<any>;
     private mutate;
     private advance;
+    /** Switches on deployment; when the key may not, the operation stops with what to do instead. */
+    private enableDeployment;
     private advanceBuild;
     private advanceLifecycle;
     private advanceApp;

package/dist/deployment.js

@@ -244,7 +244,7 @@ export class DeploymentEngine {
                 });
             }
             catch (err) {
-                if (err instanceof ToolError && err.code === "needs_auth")
+                if (err instanceof ToolError && err.code === "needs_key")
                     throw err;
             }
         if (this.files) {
@@ -605,7 +605,7 @@ export class DeploymentEngine {
                     }));
                 }
                 catch (err) {
-                    if (err instanceof ToolError && err.code === "needs_auth")
+                    if (err instanceof ToolError && err.code === "needs_key")
                         throw err;
                     row.error =
                         err instanceof ToolError
@@ -751,8 +751,8 @@ export class DeploymentEngine {
             if (err.code === "invalid_input")
                 throw err;
             op.status =
-                err.code === "needs_auth"
-                    ? "needs_auth"
+                err.code === "needs_key"
+                    ? "needs_key"
                     : err.code === "uncertain_outcome"
                         ? "needs_reconciliation"
                         : err.code === "connection_error" || err.code === "not_ready"
@@ -762,7 +762,11 @@ export class DeploymentEngine {
                 op.status === "failed"
                     ? `${err.message} Please check the logs in Constructor.`
                     : err.message;
-            if (op.status === "failed") {
+            if (err.code === "deployment_disabled") {
+                op.failure = { stage: "prepare" };
+                op.message = err.message;
+            }
+            else if (op.status === "failed") {
                 op.failure = op.action ?? {
                     stage: op.kind === "build" ? "build" : "deployment",
                 };
@@ -778,6 +782,19 @@ export class DeploymentEngine {
             return this.view(op);
         }
     }
+    /** Switches on deployment; when the key may not, the operation stops with what to do instead. */
+    async enableDeployment(op, project) {
+        try {
+            await this.mutate(op, "PATCH", this.root(project), { deployment_enabled: true }, () => {
+                op.status = "preparing";
+            });
+        }
+        catch (err) {
+            if (err instanceof ToolError && err.status === 403)
+                throw new ToolError("deployment_disabled", "Deployment is switched off for this project, and the access key may not switch it on. Ask the user to switch on deployment for the project in Constructor, then repeat the same call.", 403, err.apiCode);
+            throw err;
+        }
+    }
     async advanceBuild(op) {
         const i = op.input;
         await this.project(i.project_id);
@@ -785,9 +802,7 @@ export class DeploymentEngine {
         if (!op.images.image) {
             const p = await this.project(i.project_id);
             if (!p.deployment_enabled) {
-                await this.mutate(op, "PATCH", this.root(i.project_id), { deployment_enabled: true }, () => {
-                    op.status = "preparing";
-                });
+                await this.enableDeployment(op, i.project_id);
                 return this.view(op);
             }
             if (await this.settling(op, i.desk_id))
@@ -957,9 +972,7 @@ export class DeploymentEngine {
             return this.view(op);
         }
         if (!project.deployment_enabled) {
-            await this.mutate(op, "PATCH", this.root(op.project_id), { deployment_enabled: true }, () => {
-                op.status = "preparing";
-            });
+            await this.enableDeployment(op, op.project_id);
             return this.view(op);
         }
         const builds = services.filter((s) => s.build);
@@ -1218,8 +1231,8 @@ export class DeploymentEngine {
                 ? "Tell the user which stage/service failed and pass on the message. failure.log_tail has the last log lines when the MCP captured them; get_logs shows more. Do not use browser or other tools to investigate."
                 : terminal.has(op.status)
                     ? undefined
-                    : op.status === "needs_auth"
-                        ? `${this.api.authHelp("The token expired or is invalid.")} Then call get_deployment with this deployment_id.`
+                    : op.status === "needs_key"
+                        ? `${this.api.keyHelp("Constructor rejected the access key, or none is set.")} Then call get_deployment with this deployment_id.`
                         : op.status === "needs_upload"
                             ? "Upload files with sync_files, then call get_deployment with files_uploaded=true."
                             : "Execution continues automatically in the MCP. Keep calling get_deployment with wait_seconds=20 until it is finished, then tell the user the result; do not orchestrate individual steps.",

package/dist/desk.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The Constructor desk this MCP runs inside (VS Code in Constructor Research), from the
+ * environment Constructor sets there. Its project folder is the desk's disk, so the agent edits
+ * files in place and the MCP never uploads to it.
+ */
+export interface LocalDesk {
+    projectId: string;
+    deskId: string;
+    /** The desk's project folder on this machine; the disk root for builds. */
+    root: string;
+    /** The Constructor the desk belongs to. */
+    server?: string;
+}
+export declare function localDeskFromEnv(env: NodeJS.ProcessEnv, origin: (link: string) => string): LocalDesk | undefined;
+/**
+ * Disk path ("/a/Dockerfile") of a local path inside the desk's project folder, or undefined
+ * when it lies outside. Symlinks are resolved on both sides when the path exists.
+ */
+export declare function diskPath(desk: LocalDesk, local: string): string | undefined;
+/** Absolute local path of a disk path; refuses anything that escapes the project folder. */
+export declare function localPath(desk: LocalDesk, disk: string): string;
+/** What the agent is told about working inside the desk. */
+export declare function deskInstructions(desk: LocalDesk): string;

package/dist/desk.js

@@ -0,0 +1,52 @@
+import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+const ID = /^[a-zA-Z0-9_-]{4,128}$/;
+export function localDeskFromEnv(env, origin) {
+    if (["0", "false", "off"].includes((env.CONSTRUCTOR_LOCAL_DESK ?? "").toLowerCase()))
+        return undefined;
+    const projectId = env.ROLOS_PROJECT_ID || env.RESEARCH_PROJECT_ID;
+    const deskId = env.ROLOS_DESK_ID || env.RESEARCH_DESK_ID;
+    if (!projectId || !deskId || !ID.test(projectId) || !ID.test(deskId))
+        return undefined;
+    let server;
+    try {
+        const s = env.ROLOS_API_SERVER || env.RESEARCH_API_SERVER;
+        server = s ? origin(s) : undefined;
+    }
+    catch {
+        server = undefined;
+    }
+    const home = env.HOME || homedir();
+    const root = resolve(env.CONSTRUCTOR_DESK_ROOT ?? join(home, "project"));
+    return { projectId, deskId, root, server };
+}
+/**
+ * Disk path ("/a/Dockerfile") of a local path inside the desk's project folder, or undefined
+ * when it lies outside. Symlinks are resolved on both sides when the path exists.
+ */
+export function diskPath(desk, local) {
+    const real = (p) => {
+        try {
+            return realpathSync(p);
+        }
+        catch {
+            return resolve(p);
+        }
+    };
+    const rel = relative(real(desk.root), real(local));
+    if (rel.startsWith("..") || isAbsolute(rel))
+        return undefined;
+    return "/" + rel.split(sep).filter(Boolean).join("/");
+}
+/** Absolute local path of a disk path; refuses anything that escapes the project folder. */
+export function localPath(desk, disk) {
+    const parts = disk.split("/").filter(Boolean);
+    if (parts.some((p) => p === ".." || p === "."))
+        throw new Error("Disk paths must not contain . or ..");
+    return join(desk.root, ...parts);
+}
+/** What the agent is told about working inside the desk. */
+export function deskInstructions(desk) {
+    return `This MCP runs inside Constructor desk ${desk.deskId} of project ${desk.projectId} (VS Code in Constructor Research). That desk's disk is the local folder ${desk.root}: create and change its files there directly with your own file and shell tools, and do not use sync_files, list_files, create_folder, move_path or delete_path for this desk. build_image, deploy_app, update_app, start_app, stop_app and list_images use this desk and project by default, so no desk link is needed; pass desk_url only when the user names another desk. When the Dockerfile and sources are ready, call deploy_app (or build_image) with build.dockerfile as the path inside ${desk.root} (for example /backend/Dockerfile), or build.local_path set to a folder inside ${desk.root}; nothing is uploaded.`;
+}

package/dist/files.d.ts

@@ -32,6 +32,10 @@ export declare class FileManager {
     /** Type of a path, or null when missing. */
     private stat;
     private mkcol;
+    /** The desk this MCP runs inside, when `desk` is it. */
+    private here;
+    /** File tools never touch the desk the MCP runs in: its files are local. */
+    private notHere;
     list(raw: unknown): Promise<{
         desk_id: string;
         path: string;
@@ -108,6 +112,8 @@ export declare class FileManager {
         missing: string[];
         warnings: string[];
     }>;
+    /** The same checks as on a disk, for the desk this MCP runs in: its files are local. */
+    private checkLocal;
     /** Upload to a fresh temp file, move it over the target, then verify the server checksum. */
     private upload;
 }