@dev-mainsequence/codex-plugin 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,338 @@
+"use strict";
+/**
+ * The developer's Main Sequence session on this machine.
+ *
+ * One session per backend lives in the operating system credential store. The Main Sequence Python
+ * CLI and the Command Center SDK CLI read and write the same record, so a login made here, or with
+ * either CLI, serves all three. The record and the way each store is reached must stay equal to
+ * theirs.
+ */
+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.ForeignEntryError = exports.CredentialStoreError = exports.SESSION_SERVICE = void 0;
+exports.openCredentialStore = openCredentialStore;
+exports.sessionAccount = sessionAccount;
+exports.readSession = readSession;
+exports.saveSession = saveSession;
+exports.clearSession = clearSession;
+const child_process_1 = require("child_process");
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("./config.js");
+exports.SESSION_SERVICE = 'MainSequenceCLI.auth';
+const SESSION_RECORD_VERSION = 1;
+// Old versions of the Python CLI wrote one account for every backend.
+const UNSCOPED_ACCOUNT = 'default';
+const SECURITY_PROGRAM = '/usr/bin/security';
+const SECURITY_ITEM_NOT_FOUND = 44;
+const STORE_TIMEOUT_MS = 10_000;
+// `security -i` reads one command per line into a 4,096-character buffer and cuts a longer line:
+// the first part runs with a truncated secret and the rest runs as another command.
+const SECURITY_STDIN_LINE_LIMIT = 4000;
+const SAFE_ENTRY_NAME = /^[A-Za-z0-9._@-]+$/;
+// The comment attribute of every Keychain entry the Main Sequence tools write. Attributes are
+// readable without consent, the secret is not: the mark tells, before the secret is asked for, that
+// `security` wrote the entry and may read it without a dialog.
+const SECURITY_ENTRY_MARK = 'MainSequenceCLI.session.v1';
+const SECURITY_COMMENT_ATTRIBUTE = /^\s*"icmt"<blob>="([^"]*)"\s*$/m;
+// The Python CLI keeps its Secret Service item under this attribute and replaces only an item
+// that carries it. Writing the same attributes makes every tool replace one item in place.
+const SECRET_SERVICE_APPLICATION = 'Python keyring library';
+/** The credential store exists and could not be read or written. */
+class CredentialStoreError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CredentialStoreError';
+    }
+}
+exports.CredentialStoreError = CredentialStoreError;
+/** The entry was written by a program this one may not ask for it without a consent dialog. */
+class ForeignEntryError extends CredentialStoreError {
+    constructor() {
+        super('The Keychain entry was written by another version of the Main Sequence tools. Asking for it would show a consent dialog in every process, so it is not read.');
+        this.name = 'ForeignEntryError';
+    }
+}
+exports.ForeignEntryError = ForeignEntryError;
+function runProgram(run, program, args, input) {
+    const result = run(program, args, {
+        input: input ?? '',
+        encoding: 'utf8',
+        timeout: STORE_TIMEOUT_MS,
+        windowsHide: true
+    });
+    if (result.error) {
+        throw new CredentialStoreError(result.error.code === 'ETIMEDOUT'
+            ? `The credential store did not answer within ${STORE_TIMEOUT_MS / 1000} seconds. It was waiting for the user: the entry belongs to another program, or the store is locked.`
+            : `The credential store program could not be run (${result.error.code || result.error.name}).`);
+    }
+    return result;
+}
+function decodeSecuritySecret(output) {
+    // `security -w` prints printable ASCII as it is and anything else as hexadecimal. The record is
+    // JSON, so a value made only of hexadecimal digits is the second form.
+    const value = output.endsWith('\n') ? output.slice(0, -1) : output;
+    if (value && value.length % 2 === 0 && /^[0-9a-fA-F]+$/.test(value)) {
+        const decoded = Buffer.from(value, 'hex').toString('utf8');
+        if (!decoded.includes('�'))
+            return decoded;
+    }
+    return value;
+}
+/**
+ * The login Keychain through Apple's `security` program, which is one program for every runtime.
+ *
+ * Asking `security` for the secret of an entry that another program wrote shows a consent dialog,
+ * in every process that starts. The secret is therefore asked for only when the entry carries the
+ * tools' mark. Any other entry is left alone until a login replaces it.
+ */
+function createMacOsKeychain(run) {
+    const readable = new Set();
+    const key = (service, account) => `${service}\n${account}`;
+    function remove(service, account) {
+        const result = runProgram(run, SECURITY_PROGRAM, ['delete-generic-password', '-s', service, '-a', account]);
+        readable.delete(key(service, account));
+        if (result.status === SECURITY_ITEM_NOT_FOUND)
+            return false;
+        if (result.status !== 0) {
+            throw new CredentialStoreError(`The Keychain entry could not be deleted (security exit ${result.status}).`);
+        }
+        return true;
+    }
+    return {
+        name: 'macOS Keychain',
+        read(service, account) {
+            readable.delete(key(service, account));
+            // Attributes only: this shows no dialog, whoever wrote the entry.
+            const inspected = runProgram(run, SECURITY_PROGRAM, ['find-generic-password', '-s', service, '-a', account]);
+            if (inspected.status === SECURITY_ITEM_NOT_FOUND)
+                return null;
+            if (inspected.status !== 0) {
+                throw new CredentialStoreError(`The Keychain entry could not be inspected (security exit ${inspected.status}).`);
+            }
+            if (SECURITY_COMMENT_ATTRIBUTE.exec(inspected.stdout)?.[1] !== SECURITY_ENTRY_MARK) {
+                throw new ForeignEntryError();
+            }
+            const result = runProgram(run, SECURITY_PROGRAM, ['find-generic-password', '-s', service, '-a', account, '-w']);
+            if (result.status === SECURITY_ITEM_NOT_FOUND)
+                return null;
+            if (result.status !== 0) {
+                throw new CredentialStoreError(`The Keychain entry could not be read (security exit ${result.status}).`);
+            }
+            readable.add(key(service, account));
+            return decodeSecuritySecret(result.stdout);
+        },
+        write(service, account, secret) {
+            if (!SAFE_ENTRY_NAME.test(service) || !SAFE_ENTRY_NAME.test(account)) {
+                throw new CredentialStoreError('Unsupported Keychain entry name.');
+            }
+            const line = `add-generic-password -U -s ${service} -a ${account} -j ${SECURITY_ENTRY_MARK} -X ${Buffer.from(secret, 'utf8').toString('hex')}\n`;
+            if (line.length > SECURITY_STDIN_LINE_LIMIT) {
+                throw new CredentialStoreError('The session record is too long to store through the Keychain helper.');
+            }
+            // An entry this process read is updated in place, so another process never finds it
+            // missing. Any other entry is removed first: updating one that another program created
+            // would wait for the user's consent, and removing it does not.
+            if (readable.has(key(service, account))) {
+                try {
+                    if (runProgram(run, SECURITY_PROGRAM, ['-i'], line).status === 0)
+                        return;
+                }
+                catch {
+                    // Fall through to remove and add.
+                }
+            }
+            remove(service, account);
+            // Never report this call's output: on a parse error it echoes the line.
+            const result = runProgram(run, SECURITY_PROGRAM, ['-i'], line);
+            if (result.status !== 0) {
+                throw new CredentialStoreError(`The Keychain entry could not be written (security exit ${result.status}).`);
+            }
+            readable.add(key(service, account));
+        },
+        remove
+    };
+}
+/** Secret Service through `secret-tool`, the program the desktop's libsecret ships. */
+function createSecretService(run, program) {
+    function call(args, input) {
+        const result = runProgram(run, program, args, input);
+        // `secret-tool` exits 1 both for "no such item" and for an unreachable service. Only the
+        // second one says something on standard error.
+        const complaint = (result.stderr || '').trim().split('\n')[0] || '';
+        if (result.status !== 0 && complaint) {
+            throw new CredentialStoreError(`Secret Service is not available: ${complaint}`);
+        }
+        return result;
+    }
+    return {
+        name: 'Secret Service',
+        read(service, account) {
+            // The exact item the tools write, and then any item another program stored for the entry.
+            for (const extra of [['application', SECRET_SERVICE_APPLICATION], []]) {
+                const result = call(['lookup', 'service', service, 'username', account, ...extra]);
+                if (result.status === 0 && result.stdout)
+                    return result.stdout;
+            }
+            return null;
+        },
+        write(service, account, secret) {
+            const result = call([
+                'store',
+                `--label=Password for '${account}' on '${service}'`,
+                'service',
+                service,
+                'username',
+                account,
+                'application',
+                SECRET_SERVICE_APPLICATION
+            ], secret);
+            if (result.status !== 0) {
+                throw new CredentialStoreError(`The Secret Service entry could not be written (secret-tool exit ${result.status}).`);
+            }
+        },
+        remove(service, account) {
+            return call(['clear', 'service', service, 'username', account]).status === 0;
+        }
+    };
+}
+function isExecutableFile(candidate) {
+    try {
+        fs.accessSync(candidate, fs.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * This system's credential store, or null when the extension can reach none. macOS and Linux each
+ * use one named store, reached through a program of the system, so every runtime on the machine
+ * sees the same entry.
+ */
+function openCredentialStore(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const env = options.env ?? process.env;
+    const run = options.run ?? child_process_1.spawnSync;
+    const isExecutable = options.isExecutable ?? isExecutableFile;
+    if (platform === 'darwin') {
+        return isExecutable(SECURITY_PROGRAM) ? createMacOsKeychain(run) : null;
+    }
+    if (platform === 'linux') {
+        for (const directory of (env.PATH || '').split(path.delimiter)) {
+            if (!directory)
+                continue;
+            const candidate = path.join(directory, 'secret-tool');
+            if (isExecutable(candidate))
+                return createSecretService(run, candidate);
+        }
+    }
+    return null;
+}
+function requireBackend(backend) {
+    const normalized = (0, config_1.normalizeBackendUrl)(backend);
+    if (!normalized)
+        throw new Error('MainSequence backend URL is required.');
+    return normalized;
+}
+/** The account that holds the session of one backend. Every tool computes it the same way. */
+function sessionAccount(backend) {
+    const digest = crypto.createHash('sha256').update(requireBackend(backend), 'utf8').digest('hex');
+    return `${UNSCOPED_ACCOUNT}.${digest.slice(0, 16)}`;
+}
+function parseRecord(raw, backend) {
+    let record;
+    try {
+        record = JSON.parse(raw);
+    }
+    catch {
+        throw new CredentialStoreError('The saved session record is not valid.');
+    }
+    if (!record || typeof record !== 'object' || Array.isArray(record)) {
+        throw new CredentialStoreError('The saved session record is not valid.');
+    }
+    // `v` is written, not checked: the Python and Command Center CLIs read a record by its fields,
+    // and the three readers must accept the same records.
+    // A record written before the backend was part of it carries none.
+    const recordedBackend = typeof record.backend === 'string' ? record.backend.trim() : '';
+    if (recordedBackend && (0, config_1.normalizeBackendUrl)(recordedBackend) !== requireBackend(backend))
+        return null;
+    const session = {
+        username: typeof record.username === 'string' ? record.username : '',
+        access: typeof record.access === 'string' ? record.access : '',
+        refresh: typeof record.refresh === 'string' ? record.refresh : ''
+    };
+    return session.access || session.refresh ? session : null;
+}
+/** Read the saved session of one backend, or null. */
+function readSession(store, backend) {
+    for (const account of [sessionAccount(backend), UNSCOPED_ACCOUNT]) {
+        const raw = store.read(exports.SESSION_SERVICE, account);
+        if (!raw)
+            continue;
+        const session = parseRecord(raw, backend);
+        if (session)
+            return session;
+    }
+    return null;
+}
+/** Save the session of one backend. */
+function saveSession(store, backend, session) {
+    const json = JSON.stringify({
+        v: SESSION_RECORD_VERSION,
+        backend: requireBackend(backend),
+        username: session.username || '',
+        access: session.access || '',
+        refresh: session.refresh || ''
+    });
+    // ASCII only, as the Python CLI writes it, so every store returns the same bytes.
+    const ascii = json.replace(/[\u007f-￿]/g, character => `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`);
+    store.write(exports.SESSION_SERVICE, sessionAccount(backend), ascii);
+}
+/**
+ * Remove the saved session of one backend. Missing state is success.
+ *
+ * The legacy unscoped entry goes too, unread, as the Python and Command Center CLIs remove it:
+ * deleting needs no consent, while reading an entry another program wrote is refused on macOS
+ * and would make the logout fail.
+ */
+function clearSession(store, backend) {
+    let removed = false;
+    for (const account of [sessionAccount(backend), UNSCOPED_ACCOUNT]) {
+        removed = store.remove(exports.SESSION_SERVICE, account) || removed;
+    }
+    return removed;
+}

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

@@ -0,0 +1,329 @@
+"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.McpConnections = void 0;
+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");
+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)) {
+        throw new models_1.ToolingError('INVALID_REQUEST', 'Select an exact resource release UUID from MCP discovery or saved connections.');
+    }
+    return value.toLowerCase();
+}
+function endpoint(value, metadata = false) {
+    if (typeof value !== 'string')
+        throw new models_1.ToolingError('API_ERROR', 'The backend returned no MCP endpoint.');
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new models_1.ToolingError('API_ERROR', 'The backend returned an invalid MCP endpoint.');
+    }
+    if (url.username || url.password || (!metadata && url.search) || url.hash || /[\r\n\0]/.test(value)
+        || (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)))) {
+        throw new models_1.ToolingError('API_ERROR', 'An HTTPS endpoint, or loopback HTTP endpoint for local development, is required.');
+    }
+    return value;
+}
+function connection(backend, row) {
+    const c = row?.mcp_connection;
+    if (!c || c.transport !== 'streamable-http') {
+        throw new models_1.ToolingError('API_ERROR', 'The selected release has no active platform MCP connection.');
+    }
+    const url = endpoint(c.url);
+    if (new URL(url).pathname !== '/mcp')
+        throw new models_1.ToolingError('API_ERROR', 'The release returned a non-canonical MCP endpoint.');
+    const releaseUid = uuid(row.resource_release_uid ?? row.uid), metadataUrl = endpoint(c.resource_metadata_url, true);
+    const metadataQuery = new URL(metadataUrl).searchParams;
+    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 } : {}),
+        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');
+}
+/** Only endpoint metadata is persisted. Release credentials exist in one invocation's memory. */
+class McpConnections {
+    session;
+    options;
+    file;
+    secrets = new Set();
+    constructor(session, options = {}) {
+        this.session = session;
+        this.options = options;
+        this.file = options.connectionsPath ?? storagePath(options.env ?? process.env);
+    }
+    sanitize(value) {
+        if (typeof value === 'string') {
+            for (const secret of this.secrets)
+                value = value.split(secret).join('[redacted]');
+            return this.session.sanitize?.(value) ?? value;
+        }
+        if (Array.isArray(value))
+            return value.map(item => this.sanitize(item));
+        if (value && typeof value === 'object')
+            return Object.fromEntries(Object.entries(value).map(([key, item]) => [this.sanitize(key), this.sanitize(item)]));
+        return value;
+    }
+    async read() {
+        try {
+            const stat = await fs.lstat(this.file);
+            if (!stat.isFile() || stat.size > 2_000_000)
+                throw new Error('invalid store');
+            const rows = JSON.parse(await fs.readFile(this.file, 'utf8'));
+            if (!Array.isArray(rows))
+                throw new Error('invalid store');
+            return rows.map(row => connection(row.backend, row));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw new models_1.ToolingError('STORE_ERROR', 'Saved MCP connections could not be read. The existing file has been kept.');
+        }
+    }
+    async update(change) {
+        this.options.signal?.throwIfAborted();
+        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;
+        try {
+            handle = await fs.open(lock, 'wx', 0o600);
+        }
+        catch {
+            throw new models_1.ToolingError('PROJECT_BUSY', 'Another action holds the saved MCP connection lock. After an interrupted action, verify it has stopped before removing ' + lock + '.');
+        }
+        try {
+            await handle.writeFile(JSON.stringify({ pid: process.pid }));
+            const rows = change(await this.read());
+            this.options.signal?.throwIfAborted();
+            const serialized = JSON.stringify(rows, null, 2) + '\n';
+            if (Buffer.byteLength(serialized) > 2_000_000)
+                throw new models_1.ToolingError('PERSISTENCE_FAILED', 'The saved MCP connections exceed the client limit.');
+            await fs.writeFile(temporary, serialized, { flag: 'wx', mode: 0o600 });
+            await fs.rename(temporary, this.file);
+        }
+        catch (error) {
+            if (error instanceof models_1.ToolingError)
+                throw error;
+            throw new models_1.ToolingError('PERSISTENCE_FAILED', 'The MCP connections could not be saved.');
+        }
+        finally {
+            await fs.rm(temporary, { force: true });
+            await handle.close();
+            await fs.unlink(lock);
+        }
+    }
+    async current(backend, releaseUid) {
+        const row = await this.session.request(backend, 'GET', '/api/v1/resource-releases/' + releaseUid + '/');
+        const value = connection(backend, row);
+        if (value.resource_release_uid !== releaseUid)
+            throw new models_1.ToolingError('API_ERROR', 'The backend returned a different release.');
+        return value;
+    }
+    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)) {
+            throw new models_1.ToolingError('API_ERROR', 'The backend returned no usable FastAPI release credential.');
+        }
+        this.secrets.add(grant.token);
+        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));
+        await client.initialize();
+        return client;
+    }
+    async dispatch(request, inputBackend) {
+        let callStarted = false, resultData;
+        try {
+            const backend = (0, session_1.requireBackend)(inputBackend);
+            this.options.signal?.throwIfAborted();
+            const environmentUid = request.environmentUid === undefined ? undefined : uuid(request.environmentUid);
+            const belongs = (value) => !environmentUid || value.mcp_connection.organization_environment_uid === environmentUid;
+            const requireEnvironment = (value) => {
+                if (!belongs(value))
+                    throw new models_1.ToolingError('INVALID_REQUEST', 'This MCP belongs to a different organization environment. Select that environment first.');
+            };
+            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()];
+                summary = 'Organization environments available to your MainSequence account.';
+            }
+            else if (request.action === 'mcp-discover') {
+                if ((request.search !== undefined && typeof request.search !== 'string')
+                    || (request.limit !== undefined && (!Number.isInteger(request.limit) || request.limit < 1 || request.limit > 100))
+                    || (request.offset !== undefined && (!Number.isInteger(request.offset) || request.offset < 0))) {
+                    throw new models_1.ToolingError('INVALID_REQUEST', 'Discovery requires a text search, a limit from 1 to 100, and a nonnegative offset.');
+                }
+                const client = new mcpTransport_1.McpTransport(message => this.session.request(backend, 'POST', '/mcp', message, true));
+                await client.initialize();
+                const query = async (offset, limit) => {
+                    const output = await client.request('tools/call', { name: 'resource_release.mcp_endpoints',
+                        arguments: { ...(request.search !== undefined ? { search: request.search } : {}), limit, offset } });
+                    if (output?.isError)
+                        throw new models_1.ToolingError('API_ERROR', 'Platform MCP could not list available project endpoints.');
+                    const page = output?.structuredContent;
+                    if (!Number.isInteger(page?.count) || page.count < 0 || !Array.isArray(page?.results))
+                        throw new models_1.ToolingError('API_ERROR', 'Platform MCP returned an invalid directory.');
+                    return { count: page.count, results: page.results.map((row) => connection(backend, row)) };
+                };
+                if (!environmentUid)
+                    data = await query(request.offset ?? 0, request.limit ?? 100);
+                else {
+                    // The existing platform MCP has no environment filter. Scan its pages
+                    // before paginating the matching releases; never show an incomplete page as complete.
+                    const matching = new Map();
+                    for (let offset = 0;; offset += 100) {
+                        this.options.signal?.throwIfAborted();
+                        if (offset >= 10000)
+                            throw new models_1.ToolingError('API_ERROR', 'MCP discovery is too large; narrow the search.');
+                        const page = await query(offset, 100);
+                        for (const value of page.results.filter(belongs))
+                            matching.set(value.resource_release_uid, value);
+                        if (offset + 100 >= page.count)
+                            break;
+                    }
+                    const values = [...matching.values()], offset = request.offset ?? 0;
+                    data = { count: values.length, results: values.slice(offset, offset + (request.limit ?? 100)) };
+                }
+                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));
+                summary = 'Saved MCP connections for this backend. Availability is checked when used.';
+            }
+            else {
+                const releaseUid = uuid(request.releaseUid);
+                if (request.action === 'mcp-remove') {
+                    const saved = (await this.read()).find(row => row.backend === backend && row.resource_release_uid === releaseUid);
+                    if (saved)
+                        requireEnvironment(saved);
+                    await this.update(rows => rows.filter(row => !(row.backend === backend && row.resource_release_uid === releaseUid)));
+                    data = { resource_release_uid: releaseUid };
+                    summary = 'The saved connection was removed.';
+                }
+                else {
+                    const value = await this.current(backend, releaseUid);
+                    requireEnvironment(value);
+                    if (request.action !== 'mcp-add') {
+                        const saved = (await this.read()).find(row => row.backend === backend && row.resource_release_uid === releaseUid);
+                        if (!saved)
+                            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.');
+                    }
+                    const client = await this.open(value);
+                    const tools = await client.tools();
+                    if (request.action === 'mcp-add') {
+                        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.';
+                    }
+                    else if (request.action === 'mcp-tools') {
+                        data = { connection: value, tools };
+                        summary = 'Current tools from the selected MCP.';
+                    }
+                    else if (request.action === 'mcp-call') {
+                        if (typeof request.tool !== 'string' || !tools.some(tool => tool.name === request.tool))
+                            throw new models_1.ToolingError('INVALID_REQUEST', 'The selected tool is absent from the current MCP catalog.');
+                        if (!request.arguments || typeof request.arguments !== 'object' || Array.isArray(request.arguments))
+                            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 });
+                        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.');
+                        data = output;
+                        summary = 'The MCP tool completed.';
+                    }
+                    else
+                        throw new models_1.ToolingError('INVALID_REQUEST', 'Unknown MCP action.');
+                }
+            }
+            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.');
+            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 }),
+                ...(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 {
+            this.secrets.clear();
+        }
+    }
+}
+exports.McpConnections = McpConnections;