@dev-mainsequence/codex-plugin 0.3.0 → 0.7.9

package/dist/vendor/devtools/shared/mcp.js

@@ -34,19 +34,50 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.McpConnections = void 0;
+exports.createMcpConnectionCache = createMcpConnectionCache;
 const fs = __importStar(require("node:fs/promises"));
 const path = __importStar(require("node:path"));
-const os = __importStar(require("node:os"));
 const node_crypto_1 = require("node:crypto");
 const models_1 = require("./models.js");
 const session_1 = require("./session.js");
 const mcpTransport_1 = require("./mcpTransport.js");
+const stateDirectory_1 = require("./stateDirectory.js");
+const projectTools_1 = require("./projectTools.js");
+const repositoryModels_1 = require("./repositoryModels.js");
+const environments_1 = require("./environments.js");
+const accountScope_1 = require("./accountScope.js");
+const caches = new WeakMap();
+function createMcpConnectionCache() {
+    const cache = Object.freeze({ kind: 'mainsequence-mcp-cache' });
+    caches.set(cache, new Map());
+    return cache;
+}
+const cacheKey = (backend, uid) => JSON.stringify([backend, uid]);
+const savedIdentity = (value) => JSON.stringify([value.backend, value.resource_release_uid, value.mcp_connection]);
+function credentialExpiry(token) {
+    // This is only a conservative cache lifetime hint; the server verifies the JWT.
+    try {
+        const exp = JSON.parse(Buffer.from(token.split('.')[1], 'base64url').toString()).exp;
+        return typeof exp === 'number' && Number.isFinite(exp) ? exp * 1000 : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function uuid(value) {
-    if (typeof value !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value)) {
+    if (typeof value !== 'string' || !UUID.test(value)) {
         throw new models_1.ToolingError('INVALID_REQUEST', 'Select an exact resource release UUID from MCP discovery or saved connections.');
     }
     return value.toLowerCase();
 }
+/** Optional labels: an absent or malformed value is dropped, never an error. */
+function labels(row) {
+    const text = (value) => typeof value === 'string' && value.trim() && !/[\r\n\0]/.test(value) ? value.trim() : undefined;
+    const name = text(row?.name), display = text(row?.display_name);
+    const branch = typeof row?.code_repository_branch_uid === 'string' && UUID.test(row.code_repository_branch_uid) ? row.code_repository_branch_uid.toLowerCase() : undefined;
+    return { ...(name ? { name } : {}), ...(display ? { display_name: display } : {}), ...(branch ? { code_repository_branch_uid: branch } : {}) };
+}
 function endpoint(value, metadata = false) {
     if (typeof value !== 'string')
         throw new models_1.ToolingError('API_ERROR', 'The backend returned no MCP endpoint.');
@@ -76,27 +107,27 @@ function connection(backend, row) {
     if ([...metadataQuery.keys()].some(key => key !== 'resource_release_uid') || metadataQuery.getAll('resource_release_uid').length !== 1
         || metadataQuery.get('resource_release_uid') !== releaseUid)
         throw new models_1.ToolingError('API_ERROR', 'The MCP metadata targets another release.');
-    return { backend: (0, session_1.requireBackend)(backend), resource_release_uid: releaseUid,
-        ...(typeof row.name === 'string' && row.name.trim() ? { name: row.name } : {}),
+    return { backend: (0, session_1.requireBackend)(backend), resource_release_uid: releaseUid, ...labels(row),
         mcp_connection: { url, transport: 'streamable-http', resource_metadata_url: metadataUrl,
             organization_environment_uid: uuid(c.organization_environment_uid),
             ...(typeof c.organization_environment_name === 'string' && c.organization_environment_name.trim() ? { organization_environment_name: c.organization_environment_name.trim() } : {}), active_revision_uid: uuid(c.active_revision_uid) } };
 }
 function storagePath(env) {
-    const dir = process.platform === 'darwin' ? path.join(os.homedir(), 'Library', 'Application Support', 'MainSequenceCLI')
-        : process.platform === 'win32' ? path.join(env.APPDATA || os.homedir(), 'MainSequenceCLI') : path.join(os.homedir(), '.config', 'mainsequence');
-    return path.join(dir, 'mcp-connections.json');
+    return path.join((0, stateDirectory_1.mainSequenceStateDirectory)(env), 'mcp-connections.json');
 }
-/** Only endpoint metadata is persisted. Release credentials exist in one invocation's memory. */
+/** Only endpoint metadata is persisted. A bounded runtime may reuse an in-memory grant. */
 class McpConnections {
-    session;
+    originalSession;
     options;
     file;
     secrets = new Set();
-    constructor(session, options = {}) {
-        this.session = session;
+    session;
+    checkAccount;
+    constructor(originalSession, options = {}) {
+        this.originalSession = originalSession;
         this.options = options;
         this.file = options.connectionsPath ?? storagePath(options.env ?? process.env);
+        this.session = originalSession;
     }
     sanitize(value) {
         if (typeof value === 'string') {
@@ -128,6 +159,7 @@ class McpConnections {
     }
     async update(change) {
         this.options.signal?.throwIfAborted();
+        await this.checkAccount?.();
         await fs.mkdir(path.dirname(this.file), { recursive: true, mode: 0o700 });
         const lock = this.file + '.lock', temporary = this.file + '.' + (0, node_crypto_1.randomUUID)() + '.tmp';
         let handle;
@@ -165,6 +197,16 @@ class McpConnections {
             throw new models_1.ToolingError('API_ERROR', 'The backend returned a different release.');
         return value;
     }
+    get projectTimeoutMs() { return this.options.projectRequestTimeoutMs ?? projectTools_1.DEFAULT_PROJECT_REQUEST_TIMEOUT_MS; }
+    client(value, token, initialized = false) {
+        this.secrets.add(token);
+        return new mcpTransport_1.McpTransport(async (message, request) => {
+            await this.checkAccount?.();
+            const result = await (0, mcpTransport_1.sendProjectMcp)(value.mcp_connection.url, token, message, { fetch: this.options.fetch, signal: this.options.signal, timeoutMs: request?.timeoutMs ?? this.projectTimeoutMs });
+            await this.checkAccount?.();
+            return result;
+        }, initialized);
+    }
     async open(value) {
         const grant = await this.session.request(value.backend, 'GET', '/api/v1/resource-releases/' + value.resource_release_uid + '/exchange-launch/');
         if (grant?.mode !== 'token' || grant.release_kind !== 'fastapi' || typeof grant.token !== 'string' || !grant.token || /[\r\n]/.test(grant.token)) {
@@ -174,15 +216,153 @@ class McpConnections {
         if (new URL(endpoint(grant.rpc_url)).origin !== new URL(value.mcp_connection.url).origin) {
             throw new models_1.ToolingError('API_ERROR', 'The release credential targets a different endpoint.');
         }
-        const client = new mcpTransport_1.McpTransport(message => (0, mcpTransport_1.sendProjectMcp)(value.mcp_connection.url, grant.token, message, this.options));
+        const client = this.client(value, grant.token);
         await client.initialize();
-        return client;
+        return { client, token: grant.token, expiresAt: credentialExpiry(grant.token) };
+    }
+    /** The release's name and repository from the release directory and its branch. Whatever
+     * cannot be read is left out: labels never make a working MCP unavailable. */
+    async resolveLabels(value) {
+        const found = {};
+        const read = async (apiPath) => {
+            try {
+                return await this.session.request(value.backend, 'GET', apiPath, undefined, true);
+            }
+            catch {
+                this.options.signal?.throwIfAborted();
+                return undefined;
+            }
+        };
+        // The release detail carries no name or repository; the directory projection does.
+        const page = await read('/api/v1/resource-releases/?search=' + encodeURIComponent(value.resource_release_uid) + '&limit=100');
+        const row = Array.isArray(page?.results) ? page.results.find((item) => typeof item?.uid === 'string' && item.uid.toLowerCase() === value.resource_release_uid) : undefined;
+        if (row)
+            Object.assign(found, labels({ name: row.name, code_repository_branch_uid: row.code_repository_branch_uid }));
+        const branchUid = found.code_repository_branch_uid ?? value.code_repository_branch_uid;
+        if (branchUid) {
+            const branch = await read('/api/v1/code-repository-branches/' + encodeURIComponent(branchUid) + '/');
+            try {
+                const parsed = (0, repositoryModels_1.codeRepositoryBranchFromResponse)(branch, 'CodeRepositoryBranch response');
+                if (parsed.uid.toLowerCase() === branchUid)
+                    Object.assign(found, labels({ display_name: parsed.code_repository_name, code_repository_branch_uid: branchUid }));
+            }
+            catch { /* an unreadable branch leaves the repository name out */ }
+        }
+        return found;
+    }
+    labelled(value, found) {
+        return connection(value.backend, { ...value, ...found });
+    }
+    /** Optional discovery labels, deduplicated by branch. Never writes connection metadata. */
+    async discoveryNames(rows) {
+        const pending = [...new Set(rows.filter(row => !row.display_name).flatMap(row => row.code_repository_branch_uid ? [row.code_repository_branch_uid] : []))];
+        const names = new Map();
+        await Promise.all(Array.from({ length: Math.min(4, pending.length) }, async () => {
+            while (pending.length) {
+                this.options.signal?.throwIfAborted();
+                const uid = pending.shift();
+                try {
+                    const raw = await this.session.request(rows[0].backend, 'GET', '/api/v1/code-repository-branches/' + uid + '/');
+                    const branch = (0, repositoryModels_1.codeRepositoryBranchFromResponse)(raw, 'CodeRepositoryBranch response');
+                    if (branch.uid.toLowerCase() === uid)
+                        names.set(uid, branch.code_repository_name);
+                }
+                catch (error) {
+                    this.options.signal?.throwIfAborted();
+                    if (error instanceof models_1.ToolingError && error.code === 'CANCELLED')
+                        throw error;
+                    await this.checkAccount?.();
+                    // Unavailable optional names must not hide usable endpoints.
+                }
+            }
+        }));
+        return rows.map(row => !row.display_name && row.code_repository_branch_uid && names.has(row.code_repository_branch_uid)
+            ? this.labelled(row, { display_name: names.get(row.code_repository_branch_uid) }) : row);
+    }
+    /** Records saved before labels were stored are completed once, when the backend answers. */
+    async backfill(rows) {
+        const pending = rows.filter(row => !row.display_name);
+        if (!pending.length)
+            return rows;
+        const found = new Map();
+        await Promise.all(Array.from({ length: Math.min(4, pending.length) }, async () => {
+            while (pending.length) {
+                const row = pending.shift();
+                const resolved = await this.resolveLabels(row);
+                const added = Object.entries(resolved).filter(([key, item]) => item !== row[key]);
+                if (added.length)
+                    found.set(row.backend + ' ' + row.resource_release_uid, Object.fromEntries(added));
+            }
+        }));
+        if (!found.size)
+            return rows;
+        const key = (row) => row.backend + ' ' + row.resource_release_uid;
+        const merge = (row) => found.has(key(row)) ? this.labelled(row, { ...found.get(key(row)) }) : row;
+        try {
+            await this.update(all => all.map(merge));
+        }
+        catch (error) {
+            // A held lock or a failed write keeps the listing itself available.
+            if (error instanceof models_1.ToolingError && error.code === 'CANCELLED')
+                throw error;
+            this.options.signal?.throwIfAborted();
+        }
+        return rows.map(merge);
     }
     async dispatch(request, inputBackend) {
         let callStarted = false, resultData;
+        let key, reused = false;
+        let retained;
+        const cache = this.options.cache ? caches.get(this.options.cache) : undefined;
         try {
             const backend = (0, session_1.requireBackend)(inputBackend);
             this.options.signal?.throwIfAborted();
+            if (request.action === 'mcp-catalog' || request.action === 'mcp-tool-call')
+                throw new models_1.ToolingError('INVALID_REQUEST', 'mcp-catalog and mcp-tool-call are dispatched by createDevTools(), not by the connection client.');
+            let cached, selected;
+            if ('releaseUid' in request) {
+                key = cacheKey(backend, uuid(request.releaseUid));
+                if (cache && request.action === 'mcp-remove')
+                    cache.delete(key);
+                else if (cache) {
+                    for (const [id, item] of cache)
+                        if (item.expiresAt <= Date.now())
+                            cache.delete(id);
+                    selected = await this.originalSession.selectionIdentity?.(backend);
+                    cached = cache.get(key);
+                    if (cached && (cached.identity !== selected?.key || cached.account !== request.expectedAccount || !['mcp-tools', 'mcp-call'].includes(request.action))) {
+                        cache.delete(key);
+                        cached = undefined;
+                    }
+                    if (cached) {
+                        const saved = (await this.read()).find(row => row.backend === backend && row.resource_release_uid === request.releaseUid);
+                        if (!saved || savedIdentity(saved) !== cached.savedIdentity) {
+                            cache.delete(key);
+                            cached = undefined;
+                        }
+                    }
+                }
+            }
+            reused = Boolean(cached);
+            if (cached) {
+                const identity = cached.identity;
+                this.checkAccount = async () => {
+                    this.options.signal?.throwIfAborted();
+                    if ((await this.originalSession.selectionIdentity?.(backend))?.key !== identity)
+                        throw new models_1.ToolingError('AUTH_REJECTED', 'The shared MainSequence login changed. Refresh the current view.');
+                };
+                await this.checkAccount();
+            }
+            else {
+                this.session = await (0, accountScope_1.bindSessionAccount)(this.originalSession, backend, request.expectedAccount);
+                this.checkAccount = request.expectedAccount === undefined ? undefined : (fresh = false) => this.session.status(backend, fresh).then(() => { });
+                if (cache && key)
+                    selected = await this.originalSession.selectionIdentity?.(backend);
+            }
+            if (request.action === 'mcp-list' && request.readOnly !== undefined && typeof request.readOnly !== 'boolean'
+                || request.action === 'mcp-discover' && request.enrichNames !== undefined && typeof request.enrichNames !== 'boolean') {
+                throw new models_1.ToolingError('INVALID_REQUEST', 'Discovery and listing options must be booleans.');
+            }
             const environmentUid = request.environmentUid === undefined ? undefined : uuid(request.environmentUid);
             const belongs = (value) => !environmentUid || value.mcp_connection.organization_environment_uid === environmentUid;
             const requireEnvironment = (value) => {
@@ -191,31 +371,7 @@ class McpConnections {
             };
             let data, summary;
             if (request.action === 'mcp-environments') {
-                const environments = new Map();
-                for (let offset = 0;; offset += 100) {
-                    this.options.signal?.throwIfAborted();
-                    if (offset >= 10000)
-                        throw new models_1.ToolingError('API_ERROR', 'The environment list is too large.');
-                    const page = await this.session.request(backend, 'GET', `/api/v1/organization-environments/?limit=100&offset=${offset}`);
-                    const items = Array.isArray(page) ? page : page?.results;
-                    if (!Array.isArray(items))
-                        throw new models_1.ToolingError('API_ERROR', 'The backend returned an invalid environment list.');
-                    for (const row of items) {
-                        if (typeof row?.name !== 'string' || !row.name.trim())
-                            throw new models_1.ToolingError('API_ERROR', 'An organization environment has no name.');
-                        const uid = uuid(row.uid);
-                        environments.set(uid, { uid, name: row.name.trim(), isProduction: row.is_production === true });
-                    }
-                    if (Array.isArray(page))
-                        break;
-                    if (!Number.isInteger(page.count) || page.count < 0)
-                        throw new models_1.ToolingError('API_ERROR', 'The environment pagination is invalid.');
-                    if (offset + 100 >= page.count)
-                        break;
-                    if (!items.length)
-                        throw new models_1.ToolingError('API_ERROR', 'The environment directory changed; refresh it.');
-                }
-                data = [...environments.values()];
+                data = await (0, environments_1.listEnvironments)(this.session, backend, this.options.signal);
                 summary = 'Organization environments available to your MainSequence account.';
             }
             else if (request.action === 'mcp-discover') {
@@ -255,10 +411,15 @@ class McpConnections {
                     const values = [...matching.values()], offset = request.offset ?? 0;
                     data = { count: values.length, results: values.slice(offset, offset + (request.limit ?? 100)) };
                 }
+                if (request.enrichNames) {
+                    const page = data;
+                    data = { ...page, results: await this.discoveryNames(page.results) };
+                }
                 summary = 'Available project MCP endpoints; discovery does not save a connection.';
             }
             else if (request.action === 'mcp-list') {
-                data = (await this.read()).filter(row => row.backend === backend && belongs(row));
+                const saved = (await this.read()).filter(row => row.backend === backend && belongs(row));
+                data = request.readOnly ? saved : await this.backfill(saved);
                 summary = 'Saved MCP connections for this backend. Availability is checked when used.';
             }
             else {
@@ -272,7 +433,8 @@ class McpConnections {
                     summary = 'The saved connection was removed.';
                 }
                 else {
-                    const value = await this.current(backend, releaseUid);
+                    let value = cached?.value ?? await this.current(backend, releaseUid);
+                    let savedSnapshot = savedIdentity(value);
                     requireEnvironment(value);
                     if (request.action !== 'mcp-add') {
                         const saved = (await this.read()).find(row => row.backend === backend && row.resource_release_uid === releaseUid);
@@ -280,10 +442,17 @@ class McpConnections {
                             throw new models_1.ToolingError('INVALID_REQUEST', 'Add this MCP connection before using it.');
                         if (saved.mcp_connection.url !== value.mcp_connection.url)
                             throw new models_1.ToolingError('INVALID_REQUEST', 'The MCP endpoint changed. Add the release again to confirm its new endpoint.');
+                        savedSnapshot = savedIdentity(saved);
+                        value = this.labelled(value, labels(saved));
                     }
-                    const client = await this.open(value);
-                    const tools = await client.tools();
+                    const opened = cached ? { client: this.client(value, cached.token, true), token: cached.token, expiresAt: cached.expiresAt } : await this.open(value);
+                    const client = opened.client;
+                    // An explicit catalog read always refreshes tools. A following call reuses it.
+                    let tools = cached && request.action === 'mcp-call' ? cached.tools : await client.tools();
+                    if (cached && request.action === 'mcp-call' && !tools.some(tool => tool.name === request.tool))
+                        tools = await client.tools();
                     if (request.action === 'mcp-add') {
+                        value = this.labelled(value, await this.resolveLabels(value));
                         await this.update(rows => [...rows.filter(row => !(row.backend === backend && row.resource_release_uid === releaseUid)), value]);
                         data = { connection: value, tools };
                         summary = 'MCP connection verified and saved. Its tools can now be used through the plugin.';
@@ -299,26 +468,48 @@ class McpConnections {
                             throw new models_1.ToolingError('INVALID_REQUEST', 'Tool arguments must be a JSON object.');
                         this.options.signal?.throwIfAborted();
                         callStarted = true;
-                        const output = await client.request('tools/call', { name: request.tool, arguments: request.arguments });
+                        // A tool that advertises a longer run (`_meta["mainsequence.ai/timeout-seconds/v1"]`) gets it, capped at 300 s.
+                        const output = await client.request('tools/call', { name: request.tool, arguments: request.arguments }, { timeoutMs: (0, projectTools_1.projectToolTimeoutMs)(tools.find(tool => tool.name === request.tool), this.projectTimeoutMs) });
                         if (!output || !Array.isArray(output.content))
                             throw new models_1.ToolingError('API_ERROR', 'The MCP tool returned an invalid result.');
                         resultData = output;
-                        if (output.isError)
-                            throw new models_1.ToolingError('API_ERROR', 'The MCP tool reported an error. Inspect its result before retrying.');
+                        if (output.isError) {
+                            await this.checkAccount?.(!reused);
+                            throw new models_1.ToolingError('MCP_TOOL_ERROR', 'The connected MCP tool returned an error. Its original content and structuredContent are included in the result.');
+                        }
                         data = output;
                         summary = 'The MCP tool completed.';
                     }
                     else
                         throw new models_1.ToolingError('INVALID_REQUEST', 'Unknown MCP action.');
+                    if (cache && key && selected && (await this.originalSession.selectionIdentity?.(backend))?.key === selected.key) {
+                        // Check local selection again before retaining a grant; never extend a lease
+                        // on a warm call. Unknown/expired credential lifetimes are not cached.
+                        // A cold setup may renew the same account while resolving labels or
+                        // checking access. The account-bound checks below remain authoritative;
+                        // skip retaining an old identity instead of failing an already saved connection.
+                        const expiresAt = cached?.expiresAt ?? Math.min(Date.now() + 60_000, opened.expiresAt - 5_000, (selected.expiresAt ?? Infinity) - 5_000);
+                        if (expiresAt > Date.now()) {
+                            retained = { value, token: opened.token, tools, identity: selected.key, account: request.expectedAccount, expiresAt, savedIdentity: savedSnapshot };
+                        }
+                    }
                 }
             }
+            await this.checkAccount?.(!reused);
+            if (cache && key && retained && retained.expiresAt > Date.now()) {
+                while (cache.size >= 32 && !cache.has(key))
+                    cache.delete(cache.keys().next().value);
+                cache.set(key, retained);
+            }
             return this.sanitize({ schemaVersion: 1, action: request.action, status: 'success', summary, data });
         }
         catch (error) {
             const failure = this.options.signal?.aborted ? new models_1.ToolingError('CANCELLED', 'The MCP action was cancelled.')
                 : error instanceof models_1.ToolingError ? error : new models_1.ToolingError('INTERNAL_ERROR', 'The MCP action could not complete.');
+            if (cache && key && failure.code !== 'MCP_TOOL_ERROR')
+                cache.delete(key);
             return this.sanitize({ schemaVersion: 1, action: request.action, status: failure.code === 'CANCELLED' ? 'cancelled' : 'failure',
-                summary: failure.message, error: { code: failure.code, message: failure.message }, ...(resultData === undefined ? {} : { data: resultData }),
+                summary: failure.message, error: { code: failure.code, message: failure.message }, ...(resultData === undefined || ['AUTH_REJECTED', 'NOT_AUTHENTICATED'].includes(failure.code) ? {} : { data: resultData }),
                 ...(callStarted ? { effects: { state: 'partial-or-uncertain', message: 'The tool may have changed remote state. No automatic retry was attempted; verify the outcome before repeating it.' } } : {}) });
         }
         finally {

package/dist/vendor/devtools/shared/mcpTransport.js

@@ -1,16 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.McpTransport = void 0;
+exports.McpTransport = exports.describeSeconds = void 0;
+exports.describeMcpMessage = describeMcpMessage;
+exports.failureReason = failureReason;
 exports.readMcpResponse = readMcpResponse;
 exports.sendProjectMcp = sendProjectMcp;
 const models_1 = require("./models.js");
+const projectTools_1 = require("./projectTools.js");
+const safeText = (value, max) => String(value ?? '').replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g, '').trim().slice(0, max);
+/** `initialize`, `tools/list`, `tools/call crm_contacts_list`: what a message asked the server for. */
+function describeMcpMessage(message) {
+    const method = typeof message.method === 'string' ? message.method : 'request';
+    const name = method === 'tools/call' && message.params && typeof message.params === 'object' ? message.params.name : undefined;
+    return typeof name === 'string' && name ? `${method} ${safeText(name, 120)}` : method;
+}
+/** "0.3", "1", "120": a budget in seconds, as a person reads it. */
+const describeSeconds = (ms) => (ms / 1000).toFixed(ms % 1000 ? 1 : 0);
+exports.describeSeconds = describeSeconds;
+/** Why a request failed before any response arrived: the system error code (ECONNREFUSED, ENOTFOUND,
+ * ECONNRESET, a certificate code) when there is one. Free-text error messages never reach a host:
+ * they can carry addresses and credentials. */
+function failureReason(error) {
+    const code = error?.cause?.code ?? error?.code;
+    return typeof code === 'string' && /^[A-Z][A-Z0-9_]{1,40}$/.test(code) ? code : '';
+}
 /** The platform's stateless Streamable HTTP profile; no legacy SSE endpoint. */
 class McpTransport {
     send;
+    initialized;
     sequence = 0;
-    initialized = false;
-    constructor(send) {
+    constructor(send, initialized = false) {
         this.send = send;
+        this.initialized = initialized;
     }
     async initialize() {
         const result = await this.request('initialize', {
@@ -23,19 +44,23 @@ class McpTransport {
         await this.send({ jsonrpc: '2.0', method: 'notifications/initialized' });
         this.initialized = true;
     }
-    async request(method, params) {
+    async request(method, params, options) {
         if (method !== 'initialize' && !this.initialized)
             throw new models_1.ToolingError('API_ERROR', 'The MCP connection has not initialized.');
         const id = ++this.sequence;
-        const response = await this.send({ jsonrpc: '2.0', id, method, params });
+        const message = { jsonrpc: '2.0', id, method, params };
+        const response = await this.send(message, options);
         if (!response || response.jsonrpc !== '2.0' || response.id !== id) {
-            throw new models_1.ToolingError('API_ERROR', 'The MCP endpoint returned an invalid or mismatched response.');
+            throw new models_1.ToolingError('API_ERROR', 'The MCP endpoint returned an invalid or mismatched response to ' + describeMcpMessage(message) + '.');
+        }
+        if (response.error) {
+            // The server's own words, bounded; the dispatcher redacts credentials before any host sees them.
+            const detail = safeText(response.error.message, 300);
+            throw new models_1.ToolingError('API_ERROR', 'The MCP endpoint rejected ' + describeMcpMessage(message)
+                + (Number.isInteger(response.error.code) ? ' (JSON-RPC ' + response.error.code + ')' : '') + (detail ? ': ' + detail : '.'));
         }
-        if (response.error)
-            throw new models_1.ToolingError('API_ERROR', 'The MCP endpoint rejected ' + method
-                + (Number.isInteger(response.error.code) ? ' (JSON-RPC ' + response.error.code + ')' : '') + '.');
         if (!Object.hasOwn(response, 'result'))
-            throw new models_1.ToolingError('API_ERROR', 'The MCP response has no result.');
+            throw new models_1.ToolingError('API_ERROR', 'The MCP response to ' + describeMcpMessage(message) + ' has no result.');
         return response.result;
     }
     async tools() {
@@ -46,11 +71,24 @@ class McpTransport {
             if (!Array.isArray(page?.tools))
                 throw new models_1.ToolingError('API_ERROR', 'The MCP tool catalog is invalid.');
             for (const tool of page.tools) {
-                if (!tool || typeof tool.name !== 'string' || !tool.name || !tool.inputSchema || typeof tool.inputSchema !== 'object' || names.has(tool.name)) {
+                if (!tool || typeof tool.name !== 'string' || !tool.name || !tool.inputSchema || typeof tool.inputSchema !== 'object' || Array.isArray(tool.inputSchema) || names.has(tool.name)) {
                     throw new models_1.ToolingError('API_ERROR', 'The MCP tool catalog contains an invalid or duplicate tool.');
                 }
+                const normalized = { ...tool };
+                if (typeof normalized.description !== 'string')
+                    delete normalized.description;
+                for (const field of ['annotations', '_meta'])
+                    if (!normalized[field] || typeof normalized[field] !== 'object' || Array.isArray(normalized[field]))
+                        delete normalized[field];
+                if (normalized.annotations) {
+                    normalized.annotations = { ...normalized.annotations };
+                    for (const flag of ['readOnlyHint', 'destructiveHint', 'idempotentHint', 'openWorldHint']) {
+                        if (typeof normalized.annotations[flag] !== 'boolean')
+                            delete normalized.annotations[flag];
+                    }
+                }
                 names.add(tool.name);
-                tools.push(tool);
+                tools.push(normalized);
             }
             cursor = page.nextCursor;
             if (cursor !== undefined && (typeof cursor !== 'string' || !cursor || cursors.has(cursor))) {
@@ -65,29 +103,31 @@ class McpTransport {
     }
 }
 exports.McpTransport = McpTransport;
-/** Read bounded JSON or POST SSE; never reconnect or replay a tool invocation. */
-async function readMcpResponse(response, message) {
+/** Read bounded JSON or POST SSE; never reconnect or replay a tool invocation. `target` names the
+ * endpoint in errors ("project MCP https://crm.example"), so a person or a model sees which server
+ * answered which request with which status. */
+async function readMcpResponse(response, message, target = 'MCP endpoint') {
     if (response.headers.has('mcp-session-id')) {
         await response.body?.cancel();
         throw new models_1.ToolingError('UNSUPPORTED_ACTION', 'Stateful MCP sessions are outside the platform profile.');
     }
     if (!response.ok) {
         await response.body?.cancel();
-        throw new models_1.ToolingError(response.status === 401 || response.status === 403 ? 'AUTH_REJECTED' : 'API_ERROR', 'The MCP endpoint returned HTTP ' + response.status + '.');
+        throw new models_1.ToolingError(response.status === 401 || response.status === 403 ? 'AUTH_REJECTED' : 'API_ERROR', 'The ' + target + ' returned HTTP ' + response.status + ' for ' + describeMcpMessage(message) + '.');
     }
     if (!Object.hasOwn(message, 'id')) {
         await response.body?.cancel();
         if (response.status !== 202 && response.status !== 204)
-            throw new models_1.ToolingError('API_ERROR', 'The MCP notification was not acknowledged.');
+            throw new models_1.ToolingError('API_ERROR', 'The ' + target + ' did not acknowledge ' + describeMcpMessage(message) + ' (HTTP ' + response.status + ').');
         return undefined;
     }
     const kind = response.headers.get('content-type')?.split(';')[0].trim();
     if (kind !== 'application/json' && kind !== 'text/event-stream') {
         await response.body?.cancel();
-        throw new models_1.ToolingError('API_ERROR', 'The MCP endpoint returned an unsupported content type.');
+        throw new models_1.ToolingError('API_ERROR', 'The ' + target + ' returned an unsupported content type for ' + describeMcpMessage(message) + '.');
     }
     if (!response.body)
-        throw new models_1.ToolingError('API_ERROR', 'The MCP endpoint returned an empty response.');
+        throw new models_1.ToolingError('API_ERROR', 'The ' + target + ' returned an empty response to ' + describeMcpMessage(message) + '.');
     const reader = response.body.getReader(), decoder = new TextDecoder();
     let size = 0, text = '';
     const parse = (raw) => {
@@ -95,7 +135,7 @@ async function readMcpResponse(response, message) {
             return JSON.parse(raw);
         }
         catch {
-            throw new models_1.ToolingError('API_ERROR', 'The MCP endpoint returned invalid JSON.');
+            throw new models_1.ToolingError('API_ERROR', 'The ' + target + ' returned invalid JSON for ' + describeMcpMessage(message) + '.');
         }
     };
     try {
@@ -130,32 +170,48 @@ async function readMcpResponse(response, message) {
         text += decoder.decode();
         if (kind === 'application/json')
             return parse(text);
-        throw new models_1.ToolingError('API_ERROR', 'The MCP stream ended before the response arrived. The call was not retried.');
+        throw new models_1.ToolingError('API_ERROR', 'The MCP stream from the ' + target + ' ended before the response to ' + describeMcpMessage(message) + ' arrived. The call was not retried.');
     }
     finally {
         await reader.cancel().catch(() => { });
         reader.releaseLock();
     }
 }
+/** One request to a project's MCP endpoint with the release credential. The budget is the project
+ * request timeout (default 120 s: a scaled-to-zero release has taken over a minute to answer
+ * `initialize`), or the caller's own for a tool that advertises a longer run. A timeout and a
+ * connection failure keep the same code, `BACKEND_UNREACHABLE`, and say which they were. */
 async function sendProjectMcp(url, token, message, options) {
     options.signal?.throwIfAborted();
     const controller = new AbortController(), abort = () => controller.abort();
     options.signal?.addEventListener('abort', abort, { once: true });
-    const timer = setTimeout(abort, options.requestTimeoutMs ?? 60_000);
+    const budget = options.timeoutMs ?? projectTools_1.DEFAULT_PROJECT_REQUEST_TIMEOUT_MS;
+    let timedOut = false;
+    const timer = setTimeout(() => { timedOut = true; controller.abort(); }, budget);
+    const origin = (() => { try {
+        return new URL(url).origin;
+    }
+    catch {
+        return url;
+    } })();
     try {
         return await readMcpResponse(await (options.fetch ?? fetch)(url, {
             method: 'POST', redirect: 'error', signal: controller.signal,
+            ...(['initialize', 'notifications/initialized', 'tools/list'].includes(String(message.method)) ? { cache: 'force-cache' } : {}),
             headers: { 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream',
                 Authorization: 'Bearer ' + token, 'MCP-Protocol-Version': '2025-11-25' },
             body: JSON.stringify(message),
-        }), message);
+        }), message, 'project MCP ' + origin);
     }
     catch (error) {
         if (options.signal?.aborted)
             throw new models_1.ToolingError('CANCELLED', 'The MCP request was cancelled. Cancellation does not undo a remote operation.');
         if (error instanceof models_1.ToolingError)
             throw error;
-        throw new models_1.ToolingError('BACKEND_UNREACHABLE', 'The MCP request failed or timed out. It was not retried.');
+        if (timedOut)
+            throw new models_1.ToolingError('BACKEND_UNREACHABLE', 'The project MCP ' + describeMcpMessage(message) + ' request to ' + origin + ' timed out after ' + (0, exports.describeSeconds)(budget) + ' s. It was not retried.');
+        const reason = failureReason(error);
+        throw new models_1.ToolingError('BACKEND_UNREACHABLE', 'The project MCP ' + describeMcpMessage(message) + ' request to ' + origin + ' failed before a response arrived' + (reason ? ' (' + reason + ')' : '') + '. It was not retried.');
     }
     finally {
         clearTimeout(timer);

package/dist/vendor/devtools/shared/organizationProjectWorkspace.js

@@ -139,6 +139,8 @@ async function namedDirectory(parent, name, uid) {
 /** Stable, independent branch checkouts. No reset, stash, force checkout, deletion or automatic pull. */
 async function setupOrganizationProject(input, options) {
     const { session, signal, state } = options;
+    if (input.instructionsFile !== undefined && !['AGENTS.md', 'CLAUDE.md'].includes(input.instructionsFile))
+        throw new models_1.ToolingError('INVALID_REQUEST', 'Choose AGENTS.md or CLAUDE.md instructions.');
     const backend = (0, session_1.requireBackend)(input.backend), environmentUid = (0, organizationProjects_1.projectUid)(input.environmentUid), uid = (0, organizationProjects_1.projectUid)(input.projectUid);
     const env = (0, projects_1.projectEnvironment)({ backend }, options.env);
     // Apply the same environment to nested Git helpers, including context and .env setup.
@@ -283,13 +285,16 @@ async function setupOrganizationProject(input, options) {
             if (await run(row.path, ['symbolic-ref', '--short', 'HEAD']) !== row.branch)
                 throw new models_1.ToolingError('INVALID_GIT_CONTEXT', 'The checkout did not select the project branch.');
         }
-        const instructions = path.join(root, 'CLAUDE.md');
+        const instructionsFile = input.instructionsFile ?? 'CLAUDE.md';
+        if (!['AGENTS.md', 'CLAUDE.md'].includes(instructionsFile))
+            throw new models_1.ToolingError('INVALID_REQUEST', 'Choose AGENTS.md or CLAUDE.md instructions.');
+        const instructions = path.join(root, instructionsFile);
         if (!await exists(instructions)) {
             const legacyInstructions = path.join(container, 'CLAUDE.md');
-            const content = prior?.schemaVersion === 1 && await exists(legacyInstructions)
+            const content = instructionsFile === 'CLAUDE.md' && prior?.schemaVersion === 1 && await exists(legacyInstructions)
                 ? await fs.readFile(legacyInstructions, 'utf8')
                 : '# MainSequence workspace\n\nThe project repositories and their assigned branches are listed in `.mainsequence-project.json`.\nThe MainSequence plugin adds each repository to this Claude session with `/add-dir`.\nWork inside the appropriate repository directory; each checkout has its own Git history and instructions.\n';
-            await fs.writeFile(instructions, content, { flag: 'wx' });
+            await fs.writeFile(instructions, instructionsFile === 'AGENTS.md' ? content.replace('The MainSequence plugin adds each repository to this Claude session with `/add-dir`.', 'Open the repository paths listed in the manifest in your editor. Grant access to each checkout before working in it.') : content, { flag: 'wx' });
         }
         await atomicJson(manifestPath, { ...manifest, status: 'ready' });
         await atomicJson(path.join(root, '.mainsequence-project.json'), { ...manifest, status: 'ready' });