@dev-mainsequence/codex-plugin 0.4.2 → 0.7.9

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() {
@@ -78,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) => {
@@ -108,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 {
@@ -143,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' });

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

@@ -0,0 +1,437 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectToolCatalogPath = exports.projectToolConnectionLabel = exports.isProjectToolName = exports.MAX_PROJECT_TOOL_TIMEOUT_MS = exports.DEFAULT_PROJECT_REQUEST_TIMEOUT_MS = exports.PROJECT_TOOL_TIMEOUT_HINT = exports.MAX_PROJECT_TOOLS_PER_CONNECTION = exports.PROJECT_TOOL_PREFIX = void 0;
+exports.projectToolName = projectToolName;
+exports.projectToolConnection = projectToolConnection;
+exports.projectToolDefinition = projectToolDefinition;
+exports.projectToolDefinitions = projectToolDefinitions;
+exports.projectToolBinding = projectToolBinding;
+exports.projectToolRegistration = projectToolRegistration;
+exports.projectToolResult = projectToolResult;
+exports.projectToolTimeoutMs = projectToolTimeoutMs;
+exports.readProjectToolCatalog = readProjectToolCatalog;
+exports.readProjectToolCatalogFile = readProjectToolCatalogFile;
+exports.createProjectToolCatalog = createProjectToolCatalog;
+const fs = __importStar(require("node:fs"));
+const fsp = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const models_1 = require("./models.js");
+const stateDirectory_1 = require("./stateDirectory.js");
+exports.PROJECT_TOOL_PREFIX = 'ms_';
+exports.MAX_PROJECT_TOOLS_PER_CONNECTION = 80;
+/** A project may advertise how long one of its tools can take; the client honours it up to the cap. */
+exports.PROJECT_TOOL_TIMEOUT_HINT = 'mainsequence.ai/timeout-seconds/v1';
+exports.DEFAULT_PROJECT_REQUEST_TIMEOUT_MS = 120_000;
+exports.MAX_PROJECT_TOOL_TIMEOUT_MS = 300_000;
+const CATALOG_FILE = 'project-tool-catalog.json';
+const LOCK_STALE_MS = 10 * 60_000;
+const UUID = /^[\da-f]{8}(?:-[\da-f]{4}){3}-[\da-f]{12}$/i;
+const HINTS = ['readOnlyHint', 'destructiveHint', 'idempotentHint', 'openWorldHint'];
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const text = (value, max = 300) => typeof value === 'string' ? value.trim().slice(0, max) : '';
+const clean = (value, max) => value.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g, '').slice(0, max);
+/** `ms_` + the remote name (unsafe characters replaced, cut to 32) + `_` + FNV-1a 32-bit of
+ * `backend:environment:release:tool`. The hash binds the saved connection and environment; the
+ * prefix keeps the remote name readable. The cut is 32 because Codex qualifies the name as
+ * `mcp__mainsequence__<name>` under a 64-character limit; for remote names up to 32 characters
+ * the result is the name Claude Desktop has registered since 0.4.13. */
+function projectToolName(backend, environmentUid, releaseUid, tool) {
+    const value = `${backend}:${environmentUid}:${releaseUid}:${tool}`;
+    let hash = 2166136261;
+    for (let i = 0; i < value.length; i++)
+        hash = Math.imul(hash ^ value.charCodeAt(i), 16777619) >>> 0;
+    return `${exports.PROJECT_TOOL_PREFIX}${String(tool).replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 32)}_${hash.toString(16)}`;
+}
+const isProjectToolName = (name) => typeof name === 'string' && name.startsWith(exports.PROJECT_TOOL_PREFIX);
+exports.isProjectToolName = isProjectToolName;
+function hints(value) {
+    const result = {};
+    for (const flag of HINTS)
+        if (object(value) && typeof value[flag] === 'boolean')
+            result[flag] = value[flag];
+    return result;
+}
+/** Only what a host needs to register and call a tool: name, description, object schema and the four hints. */
+function normalizeTool(value) {
+    if (!object(value) || typeof value.name !== 'string' || !value.name || !object(value.inputSchema))
+        return;
+    return { name: value.name, ...(typeof value.description === 'string' ? { description: value.description } : {}), inputSchema: value.inputSchema, annotations: hints(value.annotations) };
+}
+const normalizeTools = (tools) => (Array.isArray(tools) ? tools : []).map(normalizeTool).filter((tool) => Boolean(tool)).slice(0, exports.MAX_PROJECT_TOOLS_PER_CONNECTION);
+/** The release's own name, else its repository's name, else the release UID. */
+const projectToolConnectionLabel = (connection) => text(connection.name) || text(connection.display_name) || connection.resource_release_uid;
+exports.projectToolConnectionLabel = projectToolConnectionLabel;
+/** The catalog record of a saved connection and its current tools. */
+function projectToolConnection(connection, tools = []) {
+    return { backend: connection.backend, releaseUid: connection.resource_release_uid.toLowerCase(), environmentUid: connection.mcp_connection.organization_environment_uid.toLowerCase(),
+        environmentName: text(connection.mcp_connection.organization_environment_name), name: (0, exports.projectToolConnectionLabel)(connection), tools: normalizeTools(tools) };
+}
+const source = (connection) => 'mcp_connection' in connection ? projectToolConnection(connection) : connection;
+/** The host-neutral definition of one remote tool: `MainSequence <connection> [<environment>]: <description>`,
+ * an object schema (`type: 'object'` added when the server omitted it) and the four boolean hints,
+ * open-world by default. */
+function projectToolDefinition(connection, tool) {
+    const c = source(connection), label = c.name || c.releaseUid;
+    const schema = object(tool.inputSchema) ? tool.inputSchema : {};
+    return { name: projectToolName(c.backend, c.environmentUid, c.releaseUid, tool.name), title: `${label}: ${tool.name}`,
+        description: clean(`MainSequence ${label} [${c.environmentName || c.environmentUid}]: ${tool.description || tool.name}`, 2000),
+        inputSchema: schema.type === 'object' ? schema : { type: 'object', ...schema }, annotations: { openWorldHint: true, ...hints(tool.annotations) } };
+}
+/** Up to 80 definitions per connection, one per distinct name. */
+function projectToolDefinitions(connection, tools) {
+    const seen = new Set(), definitions = [];
+    for (const tool of normalizeTools(tools ?? ('tools' in connection ? connection.tools : []))) {
+        const definition = projectToolDefinition(connection, tool);
+        if (seen.has(definition.name))
+            continue;
+        seen.add(definition.name);
+        definitions.push(definition);
+    }
+    return definitions;
+}
+/** What a host sends back to `mcp-call` for a registered tool. */
+function projectToolBinding(connection, tool) {
+    const c = source(connection);
+    return { backend: c.backend, environmentUid: c.environmentUid, environmentName: c.environmentName, releaseUid: c.releaseUid, connection: c.name || c.releaseUid, tool: typeof tool === 'string' ? tool : tool.name };
+}
+const inScope = (connection, scope) => (!scope?.backend || connection.backend === scope.backend) && (!scope?.environmentUid || connection.environmentUid === scope.environmentUid.toLowerCase());
+/** Definitions and bindings for every tool of the catalog's connections in scope. */
+function projectToolRegistration(catalog, scope) {
+    const definitions = [], bindings = new Map();
+    for (const connection of catalog?.connections ?? []) {
+        if (!inScope(connection, scope))
+            continue;
+        for (const tool of connection.tools.slice(0, exports.MAX_PROJECT_TOOLS_PER_CONNECTION)) {
+            const definition = projectToolDefinition(connection, tool);
+            if (bindings.has(definition.name))
+                continue;
+            bindings.set(definition.name, projectToolBinding(connection, tool));
+            definitions.push(definition);
+        }
+    }
+    return { definitions, bindings };
+}
+/** The host-neutral result of a forwarded `mcp-call`: the remote content blocks, then one JSON text
+ * block with `summary`, `effects`, `error` and `structuredContent` when the call failed, returned
+ * structured content or no blocks at all; `isError` on any non-success, including `MCP_TOOL_ERROR`,
+ * whose original remote content is preserved. A failure without structured content carries that
+ * JSON as `structuredContent`, so a host that reads only structured output still sees the error. */
+function projectToolResult(result) {
+    const data = object(result.data) ? result.data : undefined;
+    const blocks = Array.isArray(data?.content) ? data.content.filter((block) => object(block) && typeof block.type === 'string') : [];
+    const failed = result.status !== 'success', structured = data?.structuredContent;
+    const extra = { summary: result.summary, ...(result.effects ? { effects: result.effects } : {}), ...(result.error ? { error: result.error } : {}), ...(structured !== undefined ? { structuredContent: structured } : {}) };
+    const content = [...blocks, ...(!blocks.length || failed || structured !== undefined ? [{ type: 'text', text: JSON.stringify(extra) }] : [])];
+    return { ...(failed ? { isError: true } : {}), content, ...(structured !== undefined ? { structuredContent: structured } : failed ? { structuredContent: extra } : {}) };
+}
+/** The HTTP budget for one `tools/call`: the default, or the tool's advertised seconds when larger, capped. */
+function projectToolTimeoutMs(tool, defaultMs = exports.DEFAULT_PROJECT_REQUEST_TIMEOUT_MS) {
+    const hint = object(tool?._meta) ? tool._meta[exports.PROJECT_TOOL_TIMEOUT_HINT] : undefined;
+    if (typeof hint !== 'number' || !Number.isFinite(hint) || hint <= 0)
+        return defaultMs;
+    return Math.max(defaultMs, Math.min(Math.round(hint * 1000), exports.MAX_PROJECT_TOOL_TIMEOUT_MS));
+}
+function success(result) {
+    if (result.status !== 'success')
+        throw new models_1.ToolingError(result.error?.code ?? 'API_ERROR', result.summary);
+    if (result.data === undefined)
+        throw new models_1.ToolingError('API_ERROR', 'MainSequence returned no data.');
+    return result.data;
+}
+/** Every saved connection in scope and its current tools: `mcp-list` (read-only), then one `mcp-tools`
+ * per connection, two at a time (the shared transport's per-origin limit). A connection whose catalog
+ * cannot be read now keeps its `previous` tools and is named in `unavailable`; a removed connection
+ * loses them; connections outside the scope are carried over from `previous` unchanged. No account
+ * snapshot is attached: a registered tool is bound to a saved connection, and the session for that
+ * connection's backend is verified when the tool is called. */
+async function readProjectToolCatalog(dispatch, options = {}) {
+    const status = options.session ?? success(await dispatch({ action: 'auth-status', ...(options.backend ? { backend: options.backend } : {}) }));
+    if (!status.authenticated || !status.backend)
+        throw new models_1.ToolingError('NOT_AUTHENTICATED', 'Sign in to MainSequence to register saved project MCP tools.');
+    const backend = status.backend, environmentUid = options.environmentUid?.toLowerCase();
+    if (environmentUid !== undefined && !UUID.test(environmentUid))
+        throw new models_1.ToolingError('INVALID_REQUEST', 'The environment must be an organization environment UUID.');
+    const scope = { backend, environmentUid }, environment = environmentUid ? { environmentUid } : {};
+    const rows = success(await dispatch({ action: 'mcp-list', backend, readOnly: true, ...environment }));
+    const previous = options.previous?.connections ?? [];
+    const connections = previous.filter(connection => !inScope(connection, scope)), unavailable = [];
+    let retained = 0;
+    const pending = [...rows];
+    await Promise.all(Array.from({ length: Math.min(2, pending.length) }, async () => {
+        while (pending.length) {
+            options.signal?.throwIfAborted();
+            const row = pending.shift();
+            try {
+                const output = success(await dispatch({ action: 'mcp-tools', backend, releaseUid: row.resource_release_uid, ...environment }));
+                const current = output.connection;
+                connections.push(projectToolConnection({ ...row, name: row.name ?? current?.name, display_name: row.display_name ?? current?.display_name,
+                    mcp_connection: { ...row.mcp_connection, organization_environment_name: row.mcp_connection.organization_environment_name ?? current?.mcp_connection?.organization_environment_name } }, output.tools));
+            }
+            catch (error) {
+                if (error instanceof models_1.ToolingError && error.code === 'CANCELLED')
+                    throw error;
+                options.signal?.throwIfAborted();
+                const earlier = previous.find(connection => connection.backend === backend && connection.releaseUid === row.resource_release_uid.toLowerCase());
+                if (earlier) {
+                    connections.push(earlier);
+                    retained += earlier.tools.length;
+                }
+                unavailable.push((0, exports.projectToolConnectionLabel)(row));
+            }
+        }
+    }));
+    connections.sort((a, b) => a.backend.localeCompare(b.backend) || a.environmentUid.localeCompare(b.environmentUid) || a.releaseUid.localeCompare(b.releaseUid));
+    return { catalog: { version: 1, updatedAt: new Date().toISOString(), connections }, backend, unavailable, retained };
+}
+function connectionRecord(value) {
+    if (!object(value) || typeof value.backend !== 'string' || !UUID.test(String(value.releaseUid)) || !UUID.test(String(value.environmentUid)) || !Array.isArray(value.tools))
+        return;
+    return { backend: value.backend, releaseUid: String(value.releaseUid).toLowerCase(), environmentUid: String(value.environmentUid).toLowerCase(),
+        environmentName: text(value.environmentName), name: text(value.name), tools: normalizeTools(value.tools) };
+}
+/** Beside `mcp-connections.json`, shared by every host on the machine. */
+const projectToolCatalogPath = (env = process.env) => path.join((0, stateDirectory_1.mainSequenceStateDirectory)(env), CATALOG_FILE);
+exports.projectToolCatalogPath = projectToolCatalogPath;
+/** A missing or damaged cache is an empty catalog, never an error. */
+function readProjectToolCatalogFile(file) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (!object(raw) || raw.version !== 1 || !Array.isArray(raw.connections))
+            return null;
+        return { version: 1, updatedAt: text(raw.updatedAt, 40), connections: raw.connections.map(connectionRecord).filter((item) => Boolean(item)) };
+    }
+    catch {
+        return null;
+    }
+}
+const sleep = (ms, signal) => new Promise(resolve => {
+    const timer = setTimeout(done, ms);
+    function done() { clearTimeout(timer); signal?.removeEventListener('abort', done); resolve(); }
+    signal?.addEventListener('abort', done, { once: true });
+});
+/** The file-backed catalog: read at once from the shared cache so a host can register tools before
+ * any network request, refreshed under a lock so one process reads the catalogs at a time while the
+ * others pick its result up from the file, and reloaded when another process wrote it. */
+function createProjectToolCatalog(options) {
+    const file = options.file ?? (0, exports.projectToolCatalogPath)(options.env), staleMs = options.staleMs ?? 15 * 60_000;
+    let catalog = readProjectToolCatalogFile(file), loadedAt = mtime(), running = null;
+    let current = null;
+    // The scope of the last refresh: the current account's backend (learned from auth-status), so a
+    // listing shows this host's connections even when another backend's are cached beside them.
+    let known;
+    const state = { unavailable: [], retained: 0, error: null };
+    function mtime() { try {
+        return fs.statSync(file).mtimeMs;
+    }
+    catch {
+        return 0;
+    } }
+    /** Another process may have refreshed the shared cache since this one read it. */
+    function reload() {
+        const now = mtime();
+        if (now === loadedAt)
+            return;
+        catalog = readProjectToolCatalogFile(file);
+        loadedAt = now;
+    }
+    const registration = (scope) => projectToolRegistration(catalog, scope ?? known);
+    async function write(next) {
+        await fsp.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+        const temporary = `${file}.${(0, node_crypto_1.randomUUID)()}.tmp`;
+        try {
+            await fsp.writeFile(temporary, JSON.stringify(next, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+            await fsp.rename(temporary, file);
+        }
+        finally {
+            await fsp.rm(temporary, { force: true });
+        }
+    }
+    function adopt(next, scope) {
+        const before = JSON.stringify(registration().definitions);
+        if (next) {
+            catalog = next;
+            loadedAt = mtime();
+        }
+        if (scope)
+            known = scope;
+        if (JSON.stringify(registration().definitions) !== before)
+            options.notify?.();
+    }
+    /** One process refreshes at a time. A live lock means another process is refreshing: without a
+     * wait the caller reuses its result from the file; with one it waits for the lock up to `waitMs`.
+     * An interrupted refresh from a closed host must not block every later one (stale after 10 min). */
+    async function lock(waitMs, signal) {
+        const name = file + '.lock', deadline = Date.now() + waitMs;
+        for (let attempt = 0; attempt < 10_000; attempt++) {
+            signal.throwIfAborted();
+            try {
+                const handle = await fsp.open(name, 'wx', 0o600);
+                await handle.writeFile(JSON.stringify({ pid: process.pid, at: new Date().toISOString() }));
+                return async () => { await handle.close(); await fsp.rm(name, { force: true }); };
+            }
+            catch (error) {
+                if (error?.code === 'ENOENT') {
+                    await fsp.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+                    continue;
+                }
+                if (error?.code !== 'EEXIST')
+                    return null;
+                let stale;
+                try {
+                    stale = Date.now() - (await fsp.stat(name)).mtimeMs >= LOCK_STALE_MS;
+                }
+                catch {
+                    continue;
+                }
+                if (stale) {
+                    await fsp.rm(name, { force: true });
+                    continue;
+                }
+                if (Date.now() >= deadline)
+                    return null;
+                await sleep(250, signal);
+            }
+        }
+        return null;
+    }
+    return {
+        file,
+        /** Definitions for the host's tool list, from the newest shared cache. */
+        list(scope) { reload(); return registration(scope).definitions; },
+        binding(name) { reload(); return registration({}).bindings.get(name); },
+        state(scope) {
+            reload();
+            const selected = scope ?? known;
+            return { count: registration(scope).definitions.length,
+                connections: (catalog?.connections ?? []).filter(connection => inScope(connection, selected)).map(connection => ({ backend: connection.backend, releaseUid: connection.releaseUid,
+                    environmentUid: connection.environmentUid, environmentName: connection.environmentName, name: connection.name, tools: connection.tools.length })),
+                updatedAt: catalog?.updatedAt || null, refreshing: running !== null, unavailable: state.unavailable, retained: state.retained, error: state.error };
+        },
+        /** The state plus definitions and bindings, as the `mcp-catalog` action returns them. */
+        view(scope) {
+            const { definitions, bindings } = registration(scope);
+            return { ...this.state(scope), definitions, bindings: Object.fromEntries(bindings) };
+        },
+        /** Read every saved connection's current catalog. Without `force`, a fresh cache is kept. Resolves
+         * true when this process read and wrote the catalog; the state carries why it did not. */
+        refresh(force = false, extra = {}) {
+            if (options.disabled)
+                return Promise.resolve(false);
+            if (running)
+                return running;
+            reload();
+            const controller = new AbortController();
+            current = { controller, locked: false };
+            running = (async () => {
+                const dispatch = options.dispatch(controller.signal), scope = extra.scope;
+                const fresh = () => Boolean(catalog && Date.parse(catalog.updatedAt) > Date.now() - staleMs);
+                try {
+                    // A fresh cache with a known scope needs nothing; otherwise one local session read tells
+                    // whether there is a session to read catalogs with, and which backend the listing is for.
+                    if (!force && (known || scope) && fresh()) {
+                        if (scope)
+                            adopt(null, scope);
+                        return false;
+                    }
+                    const session = success(await dispatch({ action: 'auth-status', ...(scope?.backend ? { backend: scope.backend } : {}) }));
+                    if (session.backend)
+                        adopt(null, scope ?? { backend: session.backend });
+                    if (!session.authenticated || !session.backend)
+                        throw new models_1.ToolingError('NOT_AUTHENTICATED', 'Sign in to MainSequence to register saved project MCP tools.');
+                    if (!force && fresh())
+                        return false;
+                    const release = await lock(extra.waitMs ?? 0, controller.signal);
+                    if (!release) {
+                        if (extra.waitMs)
+                            state.error = { code: 'PROJECT_BUSY', message: 'Another MainSequence process is refreshing the project tool catalog. The registered tools come from its last result; refresh again later.' };
+                        return false;
+                    }
+                    current.locked = true;
+                    try {
+                        reload();
+                        const read = await readProjectToolCatalog(dispatch, { ...scope, backend: session.backend, previous: catalog, signal: controller.signal, session });
+                        await write(read.catalog);
+                        state.unavailable = read.unavailable;
+                        state.retained = read.retained;
+                        state.error = null;
+                        adopt(read.catalog, scope ?? { backend: read.backend });
+                        return true;
+                    }
+                    finally {
+                        current.locked = false;
+                        await release();
+                    }
+                }
+                catch (error) {
+                    state.error = { code: error instanceof models_1.ToolingError ? error.code : 'INTERNAL_ERROR', message: error instanceof models_1.ToolingError ? error.message : 'The saved project MCP tools could not be refreshed.' };
+                    return false;
+                }
+            })().finally(() => { running = null; current = null; });
+            return running;
+        },
+        /** A host process is ending: stop its refresh and free the shared lock for the next one at once. */
+        dispose() {
+            if (!current)
+                return;
+            current.controller.abort();
+            if (current.locked) {
+                try {
+                    fs.rmSync(file + '.lock', { force: true });
+                }
+                catch { /* the stale-lock rule still applies */ }
+            }
+        },
+        /** A catalog just read explicitly for one saved release replaces that connection's tools without another round trip. */
+        async update(releaseUid, tools, backend) {
+            if (options.disabled)
+                return;
+            reload();
+            const index = catalog?.connections.findIndex(item => item.releaseUid === releaseUid.toLowerCase() && (!backend || item.backend === backend)) ?? -1;
+            if (!catalog || index < 0) {
+                void this.refresh(true);
+                return;
+            }
+            const connections = catalog.connections.map((item, i) => i === index ? { ...item, tools: normalizeTools(tools) } : item);
+            const next = { version: 1, updatedAt: new Date().toISOString(), connections };
+            try {
+                await write(next);
+                adopt(next);
+            }
+            catch { /* the in-memory tools are already current */ }
+        },
+    };
+}