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

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

@@ -0,0 +1,444 @@
+"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.MachineSessionService = void 0;
+exports.requireBackend = requireBackend;
+exports.createSessionService = createSessionService;
+// Extracted from ms-vscode-extension/src/api.ts and authSession.ts (0.1.45).
+// Host-independent machine mode; the VS Code legacy fallback stays with that host.
+const crypto = __importStar(require("crypto"));
+const mcpTransport_1 = require("./mcpTransport.js");
+const http = __importStar(require("http"));
+const config_1 = require("./config.js");
+const machineSession_1 = require("./machineSession.js");
+const models_1 = require("./models.js");
+function requireBackend(input) {
+    const backend = (0, config_1.normalizeBackendUrl)(input);
+    let url;
+    try {
+        url = new URL(backend);
+    }
+    catch {
+        throw new models_1.ToolingError('INVALID_REQUEST', 'An HTTP(S) backend URL is required.');
+    }
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash || /[\r\n]/.test(backend)) {
+        throw new models_1.ToolingError('INVALID_REQUEST', 'The backend must be an HTTP(S) URL without credentials, query, or fragment.');
+    }
+    // Keep the original normalized text: URL serialization would change the session account hash.
+    return backend;
+}
+function expiry(access) {
+    try {
+        const exp = JSON.parse(Buffer.from(access.split('.')[1], 'base64url').toString()).exp;
+        return typeof exp === 'number' && Number.isFinite(exp) ? new Date(exp * 1000).toISOString() : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** " on 2026-09-30 18:45 UTC" when the token carries an expiry that has passed. */
+function expiredOn(token) {
+    const at = expiry(token);
+    return at && Date.parse(at) <= Date.now() ? ` on ${at.slice(0, 16).replace('T', ' ')} UTC` : '';
+}
+/** Say which credentials the backend refused and how to repair them; no token value is included. */
+function refusedCredentials(source, backend, token) {
+    const when = expiredOn(token);
+    if (source === 'environment') {
+        return new models_1.ToolingError('AUTH_REJECTED', `The backend refused the credentials set in this process's environment (MAINSEQUENCE_ACCESS_TOKEN / MAINSEQUENCE_REFRESH_TOKEN) for ${backend}` +
+            (when ? `: they expired${when}.` : '.') +
+            ' They win over the saved session. Start the process without them to use the saved session, or sign in again and set a current pair.');
+    }
+    return new models_1.ToolingError('AUTH_REJECTED', `The backend refused the saved session for ${backend}` + (when ? `: it expired${when}.` : ': it was revoked or belongs to another backend.') +
+        ' Sign in again.');
+}
+function tokenPair(data, previous) {
+    const access = data?.access || data?.access_token || data?.token || data?.jwt;
+    const refresh = data?.refresh || data?.refresh_token || previous?.refresh;
+    const user = data?.user || data?.profile || data?.metadata?.user || data?.user_metadata || {};
+    const username = data?.username || data?.user_name || user?.username || user?.user_name || previous?.username || '';
+    if (typeof access !== 'string' || !access || typeof refresh !== 'string' || !refresh) {
+        throw new models_1.ToolingError('API_ERROR', 'The backend did not return a valid session pair.');
+    }
+    return { access, refresh, username: typeof username === 'string' ? username : '' };
+}
+class MachineSessionService {
+    host;
+    options;
+    store;
+    env;
+    renewals = new Map();
+    secrets = new Set();
+    constructor(host, options = {}) {
+        this.host = host;
+        this.options = options;
+        this.env = { ...(options.env ?? process.env) };
+        this.store = options.store === undefined ? (0, machineSession_1.openCredentialStore)({ env: this.env }) : options.store;
+        for (const [key, value] of Object.entries(this.env)) {
+            if (value && /TOKEN|CREDENTIAL_SECRET/i.test(key))
+                this.secrets.add(value);
+        }
+    }
+    /** Only for internal error/output sanitization; never a token transport. */
+    sanitize(text) {
+        let output = text;
+        for (const secret of this.secrets) {
+            if (output === secret)
+                return '[redacted]';
+            if (secret.length >= 8)
+                output = output.split(secret).join('[redacted]');
+        }
+        return output
+            .replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, '[redacted]')
+            .replace(/(https?:\/\/)[^/\s@]+@/gi, '$1[redacted]@')
+            .replace(/([?&](?:access_token|refresh_token|token|credential_secret|client_secret)=)[^&#\s]+/gi, '$1[redacted]');
+    }
+    remember(session) {
+        if (session.access)
+            this.secrets.add(session.access);
+        if (session.refresh)
+            this.secrets.add(session.refresh);
+        return session;
+    }
+    requireStore() {
+        if (!this.store)
+            throw new models_1.ToolingError('STORE_UNAVAILABLE', 'A machine credential store is required: macOS Keychain or Linux Secret Service with secret-tool.');
+        return this.store;
+    }
+    async saved(backend) {
+        try {
+            const value = this.options.persistence ? await this.options.persistence.read(backend) : (0, machineSession_1.readSession)(this.requireStore(), backend);
+            return value ? this.remember(value) : null;
+        }
+        catch (error) {
+            if (error instanceof models_1.ToolingError)
+                throw error;
+            throw new models_1.ToolingError('STORE_ERROR', error instanceof machineSession_1.ForeignEntryError
+                ? 'The saved entry belongs to an older tool. Sign in to replace it.'
+                : 'The machine session could not be read. Check that the credential store is unlocked and available.');
+        }
+    }
+    environment(backend) {
+        if (this.env.MAINSEQUENCE_RUNTIME_CREDENTIAL_ID || this.env.MAINSEQUENCE_RUNTIME_CREDENTIAL_SECRET) {
+            throw new models_1.ToolingError('UNSUPPORTED_ACTION', 'Runtime credentials are not a developer session. Use a separate developer process.');
+        }
+        if (this.env.MAINSEQUENCE_TOKEN)
+            throw new models_1.ToolingError('INVALID_REQUEST', 'MAINSEQUENCE_TOKEN is unsupported; use explicit MAINSEQUENCE_ACCESS_TOKEN and MAINSEQUENCE_ENDPOINT.');
+        if (!this.env.MAINSEQUENCE_ACCESS_TOKEN && !this.env.MAINSEQUENCE_REFRESH_TOKEN)
+            return null;
+        if (!this.env.MAINSEQUENCE_ENDPOINT || requireBackend(this.env.MAINSEQUENCE_ENDPOINT) !== backend) {
+            throw new models_1.ToolingError('BACKEND_MISMATCH', 'Process credentials must name the same backend with MAINSEQUENCE_ENDPOINT.');
+        }
+        return this.remember({ access: this.env.MAINSEQUENCE_ACCESS_TOKEN || '', refresh: this.env.MAINSEQUENCE_REFRESH_TOKEN || '', username: '' });
+    }
+    async selected(backend) {
+        const explicit = this.environment(backend);
+        if (explicit)
+            return { session: explicit, source: 'environment' };
+        const session = await this.saved(backend);
+        if (!session)
+            throw new models_1.ToolingError('NOT_AUTHENTICATED', 'No session is saved for this backend. Run login.');
+        return { session, source: 'machine' };
+    }
+    async http(backend, method, apiPath, body, access, timeoutMs) {
+        this.options.signal?.throwIfAborted();
+        if ((apiPath !== '/mcp' && !/^\/(api|auth)\//.test(apiPath)) || apiPath.includes('..'))
+            throw new models_1.ToolingError('INVALID_REQUEST', 'Only existing /api/, /auth/, or central /mcp endpoints can be requested.');
+        const controller = new AbortController();
+        const abort = () => controller.abort();
+        this.options.signal?.addEventListener('abort', abort, { once: true });
+        const timer = setTimeout(abort, this.options.requestTimeoutMs ?? timeoutMs ?? 30_000);
+        try {
+            const response = await (this.options.fetch ?? fetch)(backend + apiPath, {
+                method, redirect: 'error', signal: controller.signal,
+                headers: { 'Content-Type': 'application/json', ...(apiPath === '/mcp' ? { Accept: 'application/json, text/event-stream', 'MCP-Protocol-Version': '2025-11-25' } : {}), ...(access ? { Authorization: `Bearer ${access}` } : {}) },
+                body: body === undefined ? undefined : JSON.stringify(body)
+            });
+            if (response.status === 401 || response.status === 403)
+                throw new models_1.ToolingError('AUTH_REJECTED', 'The backend rejected the selected credentials.');
+            if (!response.ok)
+                throw new models_1.ToolingError('API_ERROR', `The backend returned HTTP ${response.status}.`);
+            if (apiPath === '/mcp')
+                return await (0, mcpTransport_1.readMcpResponse)(response, body);
+            if (response.status === 204)
+                return undefined;
+            try {
+                return await response.json();
+            }
+            catch {
+                throw new models_1.ToolingError('API_ERROR', 'The backend returned an invalid JSON response.');
+            }
+        }
+        catch (error) {
+            if (this.options.signal?.aborted)
+                throw new models_1.ToolingError('CANCELLED', 'The action was cancelled.');
+            if (error instanceof models_1.ToolingError)
+                throw error;
+            throw new models_1.ToolingError('BACKEND_UNREACHABLE', 'The backend could not be reached. The saved session has been kept.');
+        }
+        finally {
+            clearTimeout(timer);
+            this.options.signal?.removeEventListener('abort', abort);
+        }
+    }
+    renew(backend) {
+        const running = this.renewals.get(backend);
+        if (running)
+            return running;
+        const task = (async () => {
+            // Bypass cached state: another SDK process may have rotated the refresh token.
+            const previous = await this.saved(backend);
+            if (!previous?.refresh)
+                throw new models_1.ToolingError('NOT_AUTHENTICATED', 'No refreshable machine session is saved for this backend.');
+            let data;
+            try {
+                data = await this.http(backend, 'POST', '/auth/jwt-token/token/refresh/', { refresh: previous.refresh });
+            }
+            catch (error) {
+                if (error instanceof models_1.ToolingError && error.code === 'AUTH_REJECTED')
+                    throw refusedCredentials('machine', backend, previous.refresh);
+                throw error;
+            }
+            const session = this.remember(tokenPair(data, previous));
+            await this.persist(backend, session);
+            return session;
+        })();
+        this.renewals.set(backend, task);
+        void task.finally(() => this.renewals.delete(backend)).catch(() => { });
+        return task;
+    }
+    async persist(backend, session) {
+        try {
+            if (this.options.persistence)
+                await this.options.persistence.write(backend, session);
+            else
+                (0, machineSession_1.saveSession)(this.requireStore(), backend, session);
+            const saved = await this.saved(backend);
+            if (!saved || saved.access !== session.access || saved.refresh !== session.refresh)
+                throw new Error('verification failed');
+        }
+        catch {
+            throw new models_1.ToolingError('PERSISTENCE_FAILED', 'Authorization completed but the machine session could not be saved and verified.');
+        }
+    }
+    async status(input, check = false) {
+        const backend = requireBackend(input);
+        const explicit = this.environment(backend);
+        let session = explicit || ((this.store || this.options.persistence) ? await this.saved(backend) : null);
+        const source = explicit ? 'environment' : session ? (this.options.persistence?.mode ?? 'machine') : 'none';
+        let expiresAt = expiry(session?.access || '');
+        let authenticated = Boolean(session?.access && (!expiresAt || Date.parse(expiresAt) > Date.now()) || (!explicit && session?.refresh));
+        if (check) {
+            if (!authenticated)
+                throw new models_1.ToolingError('NOT_AUTHENTICATED', 'No usable session is selected for this backend.');
+            if (authenticated) {
+                const profile = await this.request(backend, 'GET', '/api/v1/users/me/');
+                const username = profile?.user?.username || profile?.username;
+                if (typeof username === 'string')
+                    session = { ...session, username };
+                authenticated = true;
+                expiresAt = expiry((explicit || await this.saved(backend))?.access || '');
+            }
+        }
+        return {
+            backend, authenticated, source,
+            persistence: explicit ? 'environment' : this.options.persistence?.mode ?? (this.store ? 'machine' : 'unavailable'),
+            store: this.options.persistence?.name ?? this.store?.name ?? null,
+            ...(session?.username ? { username: session.username } : {}),
+            ...(expiresAt ? { expiresAt } : {}), ...(check ? { checked: true } : {})
+        };
+    }
+    async request(input, method, apiPath, body, retrySafe = method === 'GET', options) {
+        if (options?.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0 || options.timeoutMs > 300000))
+            throw new models_1.ToolingError('INVALID_REQUEST', 'Request timeout must be between 1 and 300000 milliseconds.');
+        const backend = requireBackend(input);
+        let { session, source } = await this.selected(backend);
+        if (!session.access || (expiry(session.access) && Date.parse(expiry(session.access)) <= Date.now() + 30_000)) {
+            if (source === 'machine')
+                session = await this.renew(backend);
+            else if (!session.access)
+                throw new models_1.ToolingError('NOT_AUTHENTICATED', 'The explicit environment has no access token.');
+        }
+        try {
+            return await this.http(backend, method, apiPath, body, session.access, options?.timeoutMs);
+        }
+        catch (error) {
+            if (!(error instanceof models_1.ToolingError) || error.code !== 'AUTH_REJECTED')
+                throw error;
+            if (source === 'environment')
+                throw refusedCredentials('environment', backend, session.access);
+            if (!retrySafe)
+                throw error;
+            const latest = await this.saved(backend);
+            const retry = latest?.access && latest.access !== session.access ? latest : await this.renew(backend);
+            try {
+                return await this.http(backend, method, apiPath, body, retry.access, options?.timeoutMs);
+            }
+            catch (retryError) {
+                if (retryError instanceof models_1.ToolingError && retryError.code === 'AUTH_REJECTED')
+                    throw refusedCredentials('machine', backend, retry.refresh || retry.access);
+                throw retryError;
+            }
+        }
+    }
+    async refresh(input) {
+        const backend = requireBackend(input);
+        await this.renew(backend); // Explicitly renew the saved machine pair, not a user process override.
+        return this.machineStatus(backend);
+    }
+    async machineStatus(backend) {
+        const session = await this.saved(backend);
+        return { backend, authenticated: Boolean(session?.access || session?.refresh), source: session ? (this.options.persistence?.mode ?? 'machine') : 'none', persistence: this.options.persistence?.mode ?? 'machine', store: this.options.persistence?.name ?? this.store?.name ?? null, username: session?.username, expiresAt: expiry(session?.access || '') };
+    }
+    async logout(input) {
+        const backend = requireBackend(input);
+        const session = await this.saved(backend);
+        let revoked = false;
+        try {
+            if (session?.refresh) {
+                await this.http(backend, 'POST', '/auth/cli/revoke/', { refresh: session.refresh });
+                revoked = true;
+            }
+        }
+        catch { /* local logout is still useful offline; report revocation separately */ }
+        if (this.options.signal?.aborted)
+            throw new models_1.ToolingError('CANCELLED', 'The action was cancelled.');
+        try {
+            if (this.options.persistence)
+                await this.options.persistence.remove(backend);
+            else
+                (0, machineSession_1.clearSession)(this.requireStore(), backend);
+        }
+        catch {
+            throw new models_1.ToolingError('STORE_ERROR', 'The machine session could not be removed.');
+        }
+        return { revoked };
+    }
+    async login(input) {
+        const backend = requireBackend(input);
+        if (!this.options.persistence)
+            this.requireStore();
+        // Probe before opening the browser. An old marked entry can be replaced by explicit login.
+        try {
+            await this.saved(backend);
+        }
+        catch (error) {
+            if (!(error instanceof machineSession_1.ForeignEntryError) && !(error instanceof models_1.ToolingError && error.code === 'STORE_ERROR' && error.message.includes('older tool')))
+                throw new models_1.ToolingError('STORE_ERROR', 'The credential store is unavailable. Unlock it before signing in.');
+        }
+        this.options.signal?.throwIfAborted();
+        const state = crypto.randomBytes(32).toString('base64url');
+        const verifier = crypto.randomBytes(64).toString('base64url');
+        const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
+        let resolveCallback;
+        let rejectCallback;
+        const callback = new Promise((resolve, reject) => { resolveCallback = resolve; rejectCallback = reject; });
+        void callback.catch(() => { });
+        let completed = false;
+        const server = http.createServer((req, res) => {
+            const parsed = new URL(req.url || '/', 'http://127.0.0.1');
+            res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+            res.setHeader('Cache-Control', 'no-store');
+            if (parsed.pathname !== '/callback') {
+                res.writeHead(404).end('Not found');
+                return;
+            }
+            if (parsed.searchParams.get('state') !== state) {
+                res.writeHead(400).end('Invalid authorization state');
+                return;
+            }
+            if (completed) {
+                res.writeHead(409).end('Callback already handled');
+                return;
+            }
+            completed = true;
+            const code = parsed.searchParams.get('code');
+            if (!code || parsed.searchParams.has('error')) {
+                rejectCallback(new models_1.ToolingError('INVALID_CALLBACK', 'Browser authorization did not return an authorization code.'));
+                res.writeHead(400).end('MainSequence authorization failed. Return to your developer tool.');
+            }
+            else {
+                resolveCallback(code);
+                res.end('MainSequence authorization received. Return to your developer tool to check that it was saved.');
+            }
+        });
+        const abort = () => rejectCallback(new models_1.ToolingError('CANCELLED', 'Login was cancelled.'));
+        this.options.signal?.addEventListener('abort', abort, { once: true });
+        const timer = setTimeout(() => rejectCallback(new models_1.ToolingError('LOGIN_TIMEOUT', 'Timed out waiting for browser authorization.')), this.options.loginTimeoutMs ?? 300_000);
+        try {
+            await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); });
+            const address = server.address();
+            if (!address || typeof address === 'string')
+                throw new models_1.ToolingError('BROWSER_FAILED', 'Could not start the loopback callback.');
+            const redirectUri = `http://127.0.0.1:${address.port}/callback`;
+            const params = new URLSearchParams({ client_id: 'mainsequence-cli', response_type: 'code', state, redirect_uri: redirectUri, code_challenge: challenge, code_challenge_method: 'S256', prompt: 'select_account' });
+            let opened = false;
+            try {
+                opened = await this.host.openBrowser(`${backend}/auth/cli/authorize/?${params}`);
+            }
+            catch { /* safe error below */ }
+            if (!opened)
+                throw new models_1.ToolingError('BROWSER_FAILED', 'Could not open the browser. Check your desktop browser configuration.');
+            const code = await callback;
+            const session = this.remember(tokenPair(await this.http(backend, 'POST', '/auth/cli/token/', { client_id: 'mainsequence-cli', code, code_verifier: verifier, redirect_uri: redirectUri })));
+            await this.persist(backend, session);
+            if (!session.username) {
+                try {
+                    const profile = await this.request(backend, 'GET', '/api/v1/users/me/');
+                    const username = profile?.user?.username || profile?.username;
+                    const latest = await this.saved(backend);
+                    if (typeof username === 'string' && username.trim() && latest)
+                        await this.persist(backend, { ...latest, username: username.trim() });
+                }
+                catch { /* Profile is best-effort; the authorization pair is already durable. */ }
+            }
+            this.options.signal?.throwIfAborted();
+            return this.machineStatus(backend);
+        }
+        finally {
+            clearTimeout(timer);
+            this.options.signal?.removeEventListener('abort', abort);
+            server.closeAllConnections();
+            await new Promise(resolve => { if (server.listening)
+                server.close(() => resolve());
+            else
+                resolve(); });
+        }
+    }
+}
+exports.MachineSessionService = MachineSessionService;
+function createSessionService(host, options = {}) {
+    return new MachineSessionService(host, options);
+}

package/docs/adr/0002-conversational-project-mcp-client.md

@@ -0,0 +1,59 @@
+# ADR 0002: Conversational project MCP connections in the Codex plugin
+
+Date: 2026-10-09. Moved from mainsequence-devtools on 2026-10-21 with the Codex plugin; "this repository" below refers to devtools, where the MCP client (the `mcp-*` actions and the connection store) still lives. The skill, hook and bundled runner that expose it in Codex are released from this repository.
+
+Status: Accepted for implementation by the owner's instruction, "OK then extend the codex plugin", following the explicit proposal to use a bundled client instead of native Codex MCP registration.
+
+## Decision
+
+Extend this repository's shared dispatcher and bundled runner with discovery, add, list, remove, tool-catalog and tool-call actions. Package a normally discoverable mainsequence-mcp skill alongside the explicit-only ms developer-command skill. A person can ask which project MCPs exist, select one, use its tools in the same conversation, and use the saved connection in later conversations. They do not invoke /ms or edit Codex configuration for these actions.
+
+The plugin is an MCP client. Codex runs its bundled helper through its existing execution capability. Each project remains a direct remote MCP endpoint; the platform directory is not a proxy for its tools. No new service, background daemon, application deployment, backend endpoint, credential namespace, or native host modification is introduced.
+
+The distinction from native registration is part of the contract: a saved project does not appear as its own native Codex MCP server or model tool namespace. The helper discovers the live schemas and invokes the selected tool through MCP. The plugin must already be installed and its conversational skill loaded by the host. Distributing an updated plugin is separate from adding a project connection.
+
+## Authentication decision and evidence
+
+Reuse the existing developer machine session and authenticated GET /api/v1/resource-releases/{uid}/exchange-launch/. For a FastAPI release this returns mode=token, release_kind=fastapi, an opaque short-lived release credential, and rpc_url. The current project gateway accepts these release credentials on POST /mcp under current User, release and Environment permissions. Resource-bound browser OAuth remains the independent direct-client login mechanism; this client neither modifies it nor copies a central OAuth token to a project.
+
+This resolves the implementation question using an existing mechanism: an already signed-in developer needs no new browser consent per project and no new backend authorization handoff. A central MCP connection in Codex alone is not a machine session. When that session is missing or expired beyond renewal, the existing hosted developer login remains necessary; the plugin cannot promise first-time sign-in entirely within chat.
+
+The inspected platform contract is owned by platform ADR-0050 sections 4 and 6. Its current text explicitly permits existing release bearer credentials at project MCP endpoints, and its gateway tests cover that path. This ADR records the decision to consume that existing contract so it can be evaluated independently of implementation. No platform ADR amendment or backend behavior change is required by this implementation. No agent-specific approval/exclusion list is introduced.
+
+The platform credential is sent only to the selected backend. The release credential is sent only to the freshly resolved canonical project endpoint, after matching the exchange's RPC origin. It is held in memory for that invocation, redacted from results, and never added to connection files, tool arguments or command lines. Existing machine-session rotation, OS-store behavior and explicit process-identity precedence remain authoritative.
+
+## Discovery and connection lifecycle
+
+Discovery initializes central POST /mcp and calls resource_release.mcp_endpoints with search, limit and offset. It returns the existing directory projection; there is no copied application tool catalog.
+
+Add selects a release UID, rereads the authenticated release detail, validates its current connection, exchanges a release credential, initializes the project and enumerates its paginated tools before saving. Repeated add replaces only the same backend/UID record. Duplicate display names require selecting a UID. Arbitrary caller-provided project URLs are not accepted.
+
+Saved records contain only backend, release UID, display name, and the canonical MCP connection metadata (URL, transport, resource metadata URL, Environment UID, active revision UID). Store them in mcp-connections.json next to the existing CLI configuration:
+
+- macOS: ~/Library/Application Support/MainSequenceCLI/
+- Linux: ~/.config/mainsequence/
+- Windows: %APPDATA%/MainSequenceCLI/ (connection metadata only; native saved authentication remains unsupported by the existing Node store).
+
+Writes use a private file, a lock, and atomic replacement. Corrupt records are preserved and reported. Library/test hosts may supply mcpConnectionsPath without changing the platform credential store.
+
+List is local and does not promise availability. Tools/call require a saved record, reread current release access and MCP capability, and reject an endpoint change until the person adds that release again. A new active revision on the same endpoint uses its current catalog. Remove forgets only the selected record; it does not log out or revoke credentials.
+
+## Transport and operation semantics
+
+Use only the platform's stateless Streamable HTTP profile, MCP 2025-11-25, including initialize, notifications/initialized, tools/list and tools/call. Support JSON and POST SSE results, bounded bodies, pagination, request timeouts and cancellation. Do not add deprecated HTTP+SSE endpoint discovery, protocol downgrade, stateful sessions, subscriptions, tasks, sampling, elicitation, native Codex registration or reload fallbacks.
+
+All server-advertised ordinary tools can be selected, including writes. Tool annotations inform the harness; they do not constitute another permission system. The server validates tool arguments and operation permissions.
+
+Project requests do not follow redirects and are never automatically replayed. Once a tools/call request starts, failure or cancellation reports potentially partial/uncertain effects. MCP isError results remain available as error data with known authentication credentials redacted.
+
+## Classification and verification
+
+A: Amend ADR 0001 to distinguish its original deterministic developer path from the newly approved conversational MCP client.
+
+B: This ADR owns the new local connection lifecycle and host limitation.
+
+C: This is an owner-requested feature, not a defect or code-only fix; no defect issue is opened.
+
+D: Update README and the conversational MCP guide in the same change.
+
+Verification uses separate loopback platform and project servers, synthetic credentials and temporary connection files. Cover discovery through the actual tool name, same-session use, persistence across client instances/processes, duplicate names, backend isolation, private renewal, revocation, endpoint changes, pagination, JSON/SSE, bounded transport failures, no write replay, cancellation, redaction and packaged runner execution. No live project operation or OpenAI inference is required. Real endpoint interoperability and automatic model selection remain deployment validation; fixture tests must not be described as live desktop end-to-end proof.

package/docs/codex-verification.md

@@ -0,0 +1,124 @@
+# Codex plugin verification
+
+## 0.3.0 — extraction from devtools and rename to `mainsequence` (2026-10-21)
+
+The plugin moved out of [mainsequence-devtools](https://github.com/mainsequence-sdk/mainsequence-devtools)
+(its [ADR 0003](https://github.com/mainsequence-sdk/mainsequence-devtools/blob/main/docs/adr/0003-codex-plugin-extraction.md))
+and was renamed from `mainsequence-devtools` to `mainsequence` by the owner's decision. The
+one open question was how an installed Codex host treats the marketplace change: an update
+of the installed plugin, or a new plugin. Everything below ran against the Codex CLI bundled
+with the desktop app, version 0.163.0-alpha.10.2 on macOS, in isolated `CODEX_HOME`
+directories; the user's own Codex home was not touched, and the only model endpoint was a
+counted loopback fixture that rejects inference. The npm package was not published yet, so
+the renamed plugin was installed from a local marketplace copy of the built `codex/`
+artifact; `npm run release:check` verifies that the npm archive contains the same files.
+
+### Marketplace change in an installed host
+
+A marketplace shaped like the devtools one (name `mainsequence`) first listed the former
+entry, `mainsequence-devtools` from `@dev-mainsequence/devtools@0.2.8`, which Codex installed
+from the npm registry. Its hook was trusted by copying the already reviewed hook hash into
+`config.toml`. The marketplace file was then replaced by the new single entry `mainsequence`.
+
+| Step | `codex plugin list` | `hooks/list` | `skills/list` | `/ms --help` |
+| --- | --- | --- | --- | --- |
+| 1. Old plugin installed and trusted | `mainsequence-devtools@mainsequence` installed, enabled, 0.2.8 | old hook trusted, enabled | `mainsequence-devtools:ms`, `mainsequence-devtools:mainsequence-mcp` | blocked by the old hook, 0 model requests |
+| 2. Marketplace entry replaced, nothing else changed | no installed plugin listed; `mainsequence@mainsequence` available, not installed | old hook still trusted and enabled | old skills still registered | blocked by the old hook, 0 model requests |
+| 3. New plugin installed, hook not yet trusted | `mainsequence@mainsequence` installed, enabled, 0.3.0 | old hook trusted; new hook untrusted | both plugins' skills, two entries named `ms` | blocked by the old hook only, 0 model requests |
+| 4. New hook trusted as well | same | both trusted | same | blocked twice, once per hook, 0 model requests |
+| 5. `codex plugin remove mainsequence-devtools@mainsequence` | `mainsequence@mainsequence` only | new hook only | `mainsequence:ms`, `mainsequence:mainsequence-mcp` | blocked once, 0 model requests; an ordinary prompt passes through with 1 fixture request |
+
+Findings:
+
+- Codex identifies a plugin by `<marketplace entry name>@<marketplace name>`. Replacing the
+  entry is **a new plugin, not an update**: `mainsequence@mainsequence` installs beside
+  `mainsequence-devtools@mainsequence` into `plugins/cache/mainsequence/mainsequence/0.3.0`.
+- The old install keeps running from Codex's cache after its marketplace entry disappears.
+  `config.toml` still has `[plugins."mainsequence-devtools@mainsequence"] enabled = true`,
+  the app server still loads its hook and skills, and `/ms` is still intercepted, although
+  `codex plugin list` no longer shows it. `codex plugin remove` still accepts its id.
+- Hook trust is recorded per plugin id. The trusted hash is identical for both ids
+  (`sha256:8935862c…`) because the hook definition did not change, so what a user reviews
+  for the new plugin is exactly what they reviewed before, but the new id must be trusted
+  once; until then the new hook does not run.
+- With both plugins installed and trusted, both hooks run on every `/ms` and both block the
+  turn, and the slash menu carries two `ms` entries. Removing the old plugin is therefore part
+  of the upgrade, not optional cleanup. Removal leaves the old `hooks.state` trust entry in
+  `config.toml`; it is inert.
+
+Migration note for users of `mainsequence-devtools` (also in the README):
+
+```sh
+codex plugin marketplace upgrade mainsequence
+codex plugin add mainsequence@mainsequence
+codex plugin remove mainsequence-devtools@mainsequence
+```
+
+then review and trust the new plugin's hook and start a new chat (or toggle the plugin in
+the desktop Plugins settings). The MainSequence login and saved MCP connections live
+outside the plugin and need no migration.
+
+### Installed host check (`npm run verify:codex`)
+
+Run with `CODEX_HOME` pointing at the isolated home from step 5 above and
+`MAINSEQUENCE_CODEX_PLUGIN_ID=mainsequence@mainsequence`. `skills/list` reported the enabled
+`mainsequence:ms` entry with display name `ms`; `hooks/list` reported the hook trusted and
+enabled. Every handled prompt blocked with zero model requests; ordinary prompts reached the
+offline fixture once.
+
+| Prompt | Action result | Host hook status | Model requests |
+| --- | --- | --- | --- |
+| selected `ms` + `--help` | success | blocked | 0 |
+| selected `ms` + `--help --json` | success, structured output | blocked | 0 |
+| selected `ms` + `--help` with the desktop's trailing newline | success | blocked | 0 |
+| selected `ms` without arguments | success, help | blocked | 0 |
+| selected `ms` + `invalid-action` | failure | blocked | 0 |
+| selected `ms` + `sync --message "retired option"` | failure, retired option explained | blocked | 0 |
+| literal `/ms --help` ending in LF or CRLF | success | blocked | 0 |
+| literal `/ms --help --all` | success, complete command menu | blocked | 0 |
+| literal `/ms sync --help` | success, command-specific options | blocked | 0 |
+| literal `/ms --help` followed by `status` on another line | failure, invalid request | blocked | 0 |
+| literal `/ms sync` in a Python fixture project | success, dependency files refreshed, Git unchanged, 0 backend requests | blocked | 0, including in flight |
+| selected `ms` + `sync` in a Node fixture project | success, dependency files refreshed, Git unchanged, 0 backend requests | blocked | 0, including in flight |
+| ordinary fixture prompt | passes through | completed | 1, to the offline fixture |
+| `:ms --help` | passes through | completed | 1, to the offline fixture |
+
+The sync cases ran the vendored devtools 0.3.0 inside the installed plugin, from Codex's
+cache, without `node_modules`. The script now passes the `mcp_servers.main_sequence`
+override only where that server is configured, since the override is invalid in a home
+without it, and it reports Codex's stderr when the app server exits early.
+
+### Existing-chat reload regression (`npm run verify:codex:reload`)
+
+Rerun from this repository's artifact in a temporary Codex home with the renamed plugin id.
+Same behaviour as recorded for 0.2.x:
+
+| Case | Hook runs | Model requests |
+| --- | --- | --- |
+| Existing thread after external enable | none | 1, rejected by the offline fixture |
+| New thread in the same backend | blocked | 0 |
+| Existing thread after `config/batchWrite` with `reloadUserConfig: true` | blocked | 0 |
+
+### Package checks
+
+`npm run release:check` under Node 22.22.0 and npm 11.6.2: type-check, build from the
+locally packed devtools 0.3.0 (its archive integrity is recorded in `package-lock.json` and
+`build-info.json`), 15 Node tests (hook dispatch, skill-mention ownership including the
+rejection of the former `mainsequence-devtools:ms` mention, presentation, tokenizer safety,
+Python and Node sync fixtures, the self-contained artifact outside the checkout, and the
+dependency boundary), release metadata, the standalone archive and the npm archive, which
+was unpacked and exercised as Codex installs it (manifest, hooks, skills, bundled runner,
+pass-through, mention handling and the terminal CLI).
+
+### Remaining
+
+- `@dev-mainsequence/devtools@0.3.0` is not on the registry yet. The lockfile integrity
+  comes from a local `npm pack` of the devtools release branch; confirm it against
+  `npm view @dev-mainsequence/devtools@0.3.0 dist.integrity` after publication, and update
+  the lockfile and rebuild if it differs, before tagging this package.
+- The renamed plugin was installed from a local marketplace source, not from npm. The npm
+  install path itself is the one Codex used for 0.2.8 in step 1 and is unchanged.
+- The desktop composer and renderer were not visually verified; the host API, event stream
+  and CLI presentation were.
+- The owner's own Codex home still has `mainsequence-devtools@mainsequence` 0.2.7 installed
+  and the former local marketplace registered; migrating it is a user step after publication.