@dev-mainsequence/codex-plugin 0.3.0 → 0.4.2

package/docs/agents-tools-panel.md

@@ -0,0 +1,63 @@
+# MainSequence Codex plugin — Agents and Tools panel
+
+Version 0.4.2 contains a read-only MCP App. Devtools 0.3.2 remains the head: it owns backend selection, credentials, account binding, typed discovery results, environments, connection validation and MCP transport. This upgrade changes devtools and its Codex consumer; Claude and VS Code are unchanged. The packaged panel does not depend on a sibling checkout or a custom Codex.
+
+## Use
+
+Install MainSequence from its marketplace, then ask Codex to **open MainSequence**. Expand the resulting app card when useful. The panel displays the existing devtools account and backend, verifies the session, and lists accessible organization environments. Choose one to browse Agents or Tools. A sole environment is selected automatically; multiple environments require a choice.
+
+Agents supports paginated directory browsing and semantic search. Search results are a ranked set, not an offset-paginated collection. Cards show descriptions, current directory runtime state, model defaults, response types and identifiers. They do not prepare a session or check live readiness.
+
+Tools lists available project MCP releases for the chosen environment, supports search/pagination, enriches repository names through devtools, and marks saved connections. Only saved connections enable schema inspection. A saved badge describes local metadata, not current endpoint availability; inspection checks the live catalog and refuses changed endpoints. This slice does not add/remove connections or call project tools.
+
+Refresh reloads account/environment status, retaining the selected environment only if it is still available. Changing environment clears the current page immediately. A backend/account change invalidates the prior context; late reads do not replace the current UI. Existing settings and saved connections are not rewritten by discovery. Normal credential renewal remains the existing devtools session's responsibility.
+
+The default backend comes from devtools' existing configuration/process environment. A signed-out state offers the existing `/ms login` command; the panel never starts login itself. Process sessions can be inherited using the existing `MAINSEQUENCE_ENDPOINT`, `MAINSEQUENCE_ACCESS_TOKEN` and `MAINSEQUENCE_REFRESH_TOKEN` environment variables. Do not paste credentials into the UI or conversation.
+
+## Boundaries
+
+| MCP tool | Public devtools operations |
+| --- | --- |
+| `mainsequence_open` | `auth-status`, verified `auth-status`, `mcp-environments` |
+| `mainsequence_discover` | `agents-list`, or `mcp-discover` with `enrichNames: true` plus `mcp-list` with `readOnly: true`; all use `expectedAccount` |
+| `mainsequence_tools` | `mcp-tools` for a release on the current discovery page, using `expectedAccount` |
+
+All three tools are model- and app-accessible and return useful structured results without a UI. Their arguments are allowlisted; they do not accept arbitrary devtools actions. Context identifiers are short-lived server memory, not agent session IDs or a new persistent settings store. Restarting the MCP process requires refreshing the panel.
+
+The 0.4.1 panel avoided `mcp-list` because devtools 0.3.1 could backfill saved names during inspection. Devtools 0.3.2 adds explicit read-only listing, which the panel now uses without migrating or writing connections. Public typed results replace host-side backend response parsing. Devtools binds the actual request/retry credentials to the selected account; Codex retains local backend-change checks, context IDs and late-view rejection. No private package imports or independent MainSequence HTTP client are introduced.
+
+The UI uses the public MCP Apps JSON-RPC bridge. All colors, typography and radii prefer host CSS variables, with neutral light/dark fallbacks. Data is rendered as text, including external descriptions. The UI has no external fetches, scripts or fonts and declares empty connection/resource CSP lists. Its resource URI includes a build hash; the server captures immutable HTML at startup and the panel checks its identity before using results.
+
+The existing developer-command hook and conversational MCP skill retain their behavior. Those older explicit workflows can perform user-authorized mutations; the new panel's three tools cannot. Production native agent sending and receipt recovery are the next implementation phase and still require qualified storage and authorization. Historical fixture tests are development evidence only; no probe plugin is required or shipped.
+
+## Original 0.4.1 validation recorded on 2026-10-22
+
+- 26 tests passed: existing hook/CLI regression tests, production dependency/package boundaries, and ten panel tests.
+- The actual public devtools package parsed fixture account/environment/agent/MCP responses and acquired a fixture release credential for schema inspection. Saved connection bytes were unchanged; no credential persistence, agent sends or project tool invocations occurred. Credential values were absent from panel results.
+- Detached packaged MCP server started outside the checkout, exposed exactly three read-only tools, returned immutable UI after a file changed, and refused unknown tools, arguments and resources.
+- Simulated UI bridge verified explicit environment selection, literal text rendering, stale-result rejection, account invalidation and dark/light variable changes. It did not perform any native message or draft operation.
+- The stock Codex backend (`0.163.0-alpha.10.2`) installed the package in an isolated profile, discovered all three tools and the versioned app resource, and refused a stale context. No model turn or MainSequence request occurred. This confirms host registration, not desktop rendering.
+- The real local session check selected `http://127.0.0.1:8000` and returned **not signed in**, with no environment queries. No authenticated live agent/MCP directory is claimed.
+- Browser preview of a local file was blocked by Codex's URL policy. Desktop rendering and accessibility acceptance remain unverified; bridge tests are not screenshots or live-host evidence.
+
+Run `npm test`, `npm run release:check` and `node scripts/verify-panel-host.mjs` for code/package checks. The release check unpacks the npm archive, verifies the MCP/resource contract and runs the existing hook/CLI without `node_modules` or the source checkout. No publish occurs.
+
+## 0.4.2 / devtools 0.3.2 upgrade
+
+The additional regression cases exercise shared environment pagination, account changes
+during identity verification and reads, safe same-account 401 retries, refusal to retry as
+another account, and refresh races that preserve another process's saved account. MCP
+tests cover byte-identical legacy-store reads, corrupt/missing stores, discovery-name
+enrichment and no connection mutation. Codex tests cover the new public request options,
+saved/unsaved badges and inspection controls, unchanged connection bytes and backend
+invalidation. Verified account identity takes precedence over stale saved display metadata.
+Existing native theme behavior remains covered by the bridge tests. Devtools passes 124
+tests and its standalone package checks; Codex's suite contains 30 tests. The upgrade also
+passes isolated stock Codex registration, without a model turn or MainSequence request.
+
+The release lock pins the exact devtools archive. The release sequence publishes devtools
+first and verifies registry integrity before building and publishing the Codex consumer.
+The local-archive helper described in the README supports development before publication.
+Desktop activation, rendering and authenticated live discovery remain separate acceptance steps.
+
+Remaining acceptance: activate this package in the desktop, identify the existing signed-in backend, verify real environment/directory/catalog reads and check actual host rendering. Then implement the production saved-request/receipt relay and one explicitly authorized real agent exchange with native reply/recall and duplicate protection.

package/docs/codex-verification.md

@@ -1,5 +1,42 @@
 # Codex plugin verification
 
+## 0.3.1 — devtools 0.3.1: MCP names stored with saved connections (2026-10-22)
+
+The plugin bundles [devtools 0.3.1](https://github.com/mainsequence-sdk/mainsequence-devtools/pull/15)
+in place of 0.3.0; the hook adapter, manifest, hooks and skills are otherwise unchanged, so
+the hook definition and its trusted hash are the same as in 0.3.0.
+
+What the new devtools changes for this plugin:
+
+- `mcp-add` resolves the release's name, its repository's name and its repository branch
+  and stores them with the saved connection in the shared `mcp-connections.json` as `name`,
+  `display_name` and `code_repository_branch_uid`. A label that cannot be read is left out;
+  it never makes a working MCP unavailable.
+- `mcp-list` returns the stored labels without a backend request. A connection saved by an
+  earlier version is completed by the first listing that can read its labels. `mcp-add`,
+  `mcp-tools` and `mcp-call` results carry them on their connection, and discovery rows pass
+  the directory's `name` and `code_repository_branch_uid` through.
+- The connections file is shared with the Claude Desktop plugin (0.4.18 pins the same
+  devtools), so a connection labelled by either host is labelled for both.
+- The readable `/ms` output labels the new fields (`Release ID`, `Name`, `Repository`,
+  `Repository branch ID`); `--json` passes the rows to the `mainsequence-mcp` skill unchanged.
+
+Package checks under Node 22.22.0 and npm 10.9.4, `npm run release:check`: type-check, build
+from the registry archive of devtools 0.3.1 (`npm ci --ignore-scripts`; its integrity in
+`package-lock.json` and `build-info.json` is the registry's `dist.integrity`), the Node tests
+including a new case for the stored MCP connection labels in readable and `--json` output, release metadata, the standalone
+archive and the npm archive exercised as Codex installs it. Since the pinned devtools is on
+the registry, CI no longer names a devtools source branch; `scripts/install-devtools.cjs`
+falls back to the pin's release tag only for an unpublished pin.
+
+Installed-host checks with the Codex CLI 0.163.0 on macOS, in isolated `CODEX_HOME`
+directories, the only model endpoint being the counted loopback fixture: `npm run
+verify:codex` against this build installed from `artifacts/local-marketplace` and trusted
+(`skills/list` and `hooks/list` as recorded for 0.3.0; all 13 prompt cases and both sync
+cases behaved as in the 0.3.0 table below, with zero real model requests), and
+`npm run verify:codex:reload` (same three results as for 0.3.0). The hook definition did
+not change, so its trusted hash is still `sha256:8935862c…`.
+
 ## 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)

package/docs/conversational-mcp.md

@@ -35,7 +35,7 @@ If no developer session exists, use the existing Main Sequence hosted login. A c
 
 Connection metadata lives in mcp-connections.json beside the existing MainSequence CLI configuration, separated by backend and release UID. Reads/calls recheck release access and fetch the current tool catalog. A changed endpoint requires an explicit add again. Removing a connection does not revoke your login.
 
-The release UID identifies a connection. Its optional `name` is a display label from discovery; release detail responses omit it. Adding a connection and reading or calling its tools work without that label, including for saved connections. UID-based operations do not repeat discovery to obtain a name.
+The release UID identifies a connection. Since devtools 0.3.1, mcp-add also reads the release's name, its repository's name and its repository branch from the release directory and stores them with the connection as `name`, `display_name` and `code_repository_branch_uid`, so mcp-list labels a saved connection without a backend request; a connection saved by an earlier version is completed by the first listing that can read those labels, and a label that cannot be read is left out rather than making the MCP unavailable. Adding a connection and reading or calling its tools work without the labels, and UID-based operations do not repeat discovery to obtain a name. Discovery rows carry `name` and `code_repository_branch_uid` as the platform directory reports them.
 
 Project tools enforce their ordinary permissions. The client adds no agent-specific allowlist or exclusions.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dev-mainsequence/codex-plugin",
-  "version": "0.3.0",
-  "description": "MainSequence plugin for Codex: /ms developer commands executed before inference and conversational project MCPs",
+  "version": "0.4.2",
+  "description": "MainSequence for Codex: Agents and Tools discovery using existing devtools sessions, plus developer commands and conversational MCPs",
   "license": "MIT",
   "engines": {
     "node": ">=22"
@@ -15,7 +15,10 @@
   },
   "files": [
     "dist",
-    "docs",
+    "docs/agents-tools-panel.md",
+    "docs/conversational-mcp.md",
+    "docs/codex-verification.md",
+    "docs/adr",
     "README.md",
     "LICENSE",
     "NOTICE",
@@ -23,7 +26,8 @@
     "hooks",
     "skills",
     "assets",
-    "build-info.json"
+    "build-info.json",
+    ".mcp.json"
   ],
   "scripts": {
     "build": "node scripts/clean.cjs && tsc -p tsconfig.json && node scripts/build-codex.cjs",
@@ -36,7 +40,7 @@
     "release:check": "npm run typecheck && npm test && node scripts/check-release.cjs && node scripts/pack-codex.cjs && npm pack --ignore-scripts --pack-destination artifacts && npm run verify:package"
   },
   "dependencies": {
-    "@dev-mainsequence/devtools": "0.3.0"
+    "@dev-mainsequence/devtools": "0.3.2"
   },
   "devDependencies": {
     "@types/node": "18.19.130",

package/skills/mainsequence-mcp/SKILL.md

@@ -12,7 +12,7 @@ This workflow uses a client inside the plugin. Saved project connections can be
 - For "which MCPs are available?", execute the runner with mcp-discover --json. It calls resource_release.mcp_endpoints on the platform MCP. Use --search TEXT, --limit N (up to 100), and --offset N when needed; count reports the full matching collection.
 - Show names, release UIDs and Environment UIDs where needed to distinguish results. Discovery alone does not authorize adding every result.
 - For "add metatable-mcp", identify the exact discovered release. If the name identifies multiple releases, ask which one. Execute mcp-add --uid RELEASE_UUID --json. Success means initialization and tool discovery succeeded and the connection was saved. Use the returned tool catalog immediately.
-- For saved connections, execute mcp-list --json. This is local metadata, not a live health report; do not rediscover the whole directory every time the user wants to use one.
+- For saved connections, execute mcp-list --json. This is local metadata, not a live health report; do not rediscover the whole directory every time the user wants to use one. Each row carries the release UID with the saved name, display_name (the repository's name) and code_repository_branch_uid when they were readable; use them to label a connection instead of discovering again.
 - When asked to remove a saved connection, execute mcp-remove --uid RELEASE_UUID --json. This does not revoke the Main Sequence login.
 
 All commands accept --backend URL. Use the endpoint already selected for the task; absent an explicit selection, the runner uses the process endpoint, current directory's endpoint, saved CLI configuration, then the standard backend. Connections are separated by backend and release UID. Do not guess or construct project URLs.