sunpeak 0.20.62 → 0.20.67

package/README.md

@@ -20,6 +20,8 @@ Server-agnostic MCP testing framework and full-stack MCP App framework.
 
 MCP Apps are cross-platform, meaning sunpeak is a ChatGPT App framework, Claude Connector framework, and more.
 
+ChatGPT apps are now submitted and published as plugins. The app remains an MCP-backed app, so sunpeak's architecture and runtime do not change. The plugin is the package used for local installation, review, and public distribution.
+
 ```bash
 npx sunpeak new
 ```
@@ -149,4 +151,5 @@ Toggle between hosts, themes, display modes, and device types from the sidebar.
 - [MCP Overview](https://sunpeak.ai/docs/mcp-apps/mcp/overview) · [Tools](https://sunpeak.ai/docs/mcp-apps/mcp/tools) · [Resources](https://sunpeak.ai/docs/mcp-apps/mcp/resources)
 - [MCP Apps SDK](https://github.com/modelcontextprotocol/ext-apps)
 - [ChatGPT Apps SDK Design Guidelines](https://developers.openai.com/apps-sdk/concepts/design-guidelines)
+- [Build ChatGPT Plugins](https://learn.chatgpt.com/docs/build-plugins) · [Submit ChatGPT Plugins](https://learn.chatgpt.com/docs/submit-plugins)
 - [Troubleshooting](https://sunpeak.ai/docs/app-framework/guides/troubleshooting)

package/bin/commands/dev.mjs

@@ -66,7 +66,12 @@ async function importFromProject(require, moduleName) {
  *
  * When a file changes during a build, the current build is killed and restarted.
  */
-function startBuildWatcher(projectRoot, resourcesDir, mcpHandle, { skipInitialBuild = false } = {}) {
+function startBuildWatcher(
+  projectRoot,
+  resourcesDir,
+  mcpHandle,
+  { skipInitialBuild = false } = {}
+) {
   let activeChild = null;
   const sunpeakBin = join(dirname(fileURLToPath(import.meta.url)), '..', 'sunpeak.js');
 
@@ -120,7 +125,9 @@ function startBuildWatcher(projectRoot, resourcesDir, mcpHandle, { skipInitialBu
     });
     console.log('[build] Watching src/resources/ for changes...');
   } catch {
-    console.warn('[build] Could not start file watcher — run "sunpeak build" manually after changes');
+    console.warn(
+      '[build] Could not start file watcher — run "sunpeak build" manually after changes'
+    );
   }
 }
 
@@ -153,7 +160,7 @@ export async function dev(projectRoot = process.cwd(), args = []) {
   // inspectServer auto-discovers a free port (and doesn't use strictPort,
   // which would crash instead of falling back when port 3000 is busy).
   let port = undefined;
-  const portArgIndex = args.findIndex(arg => arg === '--port' || arg === '-p');
+  const portArgIndex = args.findIndex((arg) => arg === '--port' || arg === '-p');
   if (portArgIndex !== -1 && args[portArgIndex + 1]) {
     port = parseInt(args[portArgIndex + 1]);
   } else if (process.env.PORT) {
@@ -167,8 +174,10 @@ export async function dev(projectRoot = process.cwd(), args = []) {
   const isProdTools = args.includes('--prod-tools');
   const isProdResources = args.includes('--prod-resources');
 
-  if (isProdTools) console.log('Prod Tools: MCP tool calls will use real handlers instead of simulation mocks');
-  if (isProdResources) console.log('Prod Resources: resources will use production-built HTML from dist/');
+  if (isProdTools)
+    console.log('Prod Tools: MCP tool calls will use real handlers instead of simulation mocks');
+  if (isProdResources)
+    console.log('Prod Resources: resources will use production-built HTML from dist/');
 
   console.log(`Starting dev server${port ? ` on port ${port}` : ''}...`);
 
@@ -195,10 +204,18 @@ export async function dev(projectRoot = process.cwd(), args = []) {
     // Import from installed sunpeak package
     const sunpeakBase = require.resolve('sunpeak').replace(/dist\/index\.(c)?js$/, '');
     sunpeakMcp = await import(pathToFileURL(join(sunpeakBase, 'dist/mcp/index.js')).href);
-    sunpeakDiscovery = await import(pathToFileURL(join(sunpeakBase, 'dist/lib/discovery-cli.js')).href);
+    sunpeakDiscovery = await import(
+      pathToFileURL(join(sunpeakBase, 'dist/lib/discovery-cli.js')).href
+    );
   }
   const { runMCPServer } = sunpeakMcp;
-  const { findResourceDirs, findSimulationFilesFlat, findToolFiles, extractResourceExport, extractToolExport } = sunpeakDiscovery;
+  const {
+    findResourceDirs,
+    findSimulationFilesFlat,
+    findToolFiles,
+    extractResourceExport,
+    extractToolExport,
+  } = sunpeakDiscovery;
 
   const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
 
@@ -243,7 +260,9 @@ export async function dev(projectRoot = process.cwd(), args = []) {
       const { tool } = await extractToolExport(toolPath);
       toolMap.set(toolName, { tool, path: toolPath });
     } catch (err) {
-      console.warn(`Warning: Could not extract metadata from tool "${toolName}" (${toolPath}):\n  ${err.message}\n  Expected: export const tool: AppToolConfig = { ... }`);
+      console.warn(
+        `Warning: Could not extract metadata from tool "${toolName}" (${toolPath}):\n  ${err.message}\n  Expected: export const tool: AppToolConfig = { ... }`
+      );
     }
   }
 
@@ -285,7 +304,9 @@ export async function dev(projectRoot = process.cwd(), args = []) {
         });
       }
     } catch (err) {
-      console.warn(`Warning: Could not load handler for tool "${toolName}" (${relativePath}):\n  ${err.message}`);
+      console.warn(
+        `Warning: Could not load handler for tool "${toolName}" (${relativePath}):\n  ${err.message}`
+      );
     }
   }
 
@@ -301,7 +322,9 @@ export async function dev(projectRoot = process.cwd(), args = []) {
     const toolEntry = toolMap.get(toolName);
     const tool = toolEntry?.tool;
     if (!tool) {
-      console.warn(`Warning: Tool "${toolName}" not found for simulation "${simName}". Expected file: src/tools/${toolName}.ts`);
+      console.warn(
+        `Warning: Tool "${toolName}" not found for simulation "${simName}". Expected file: src/tools/${toolName}.ts`
+      );
       continue;
     }
 
@@ -312,7 +335,9 @@ export async function dev(projectRoot = process.cwd(), args = []) {
       : undefined;
 
     if (resourceName && !resourceKey) {
-      console.warn(`Warning: No resource found for tool "${toolName}" in simulation "${simName}". Skipping.`);
+      console.warn(
+        `Warning: No resource found for tool "${toolName}" in simulation "${simName}". Skipping.`
+      );
       continue;
     }
 
@@ -326,25 +351,33 @@ export async function dev(projectRoot = process.cwd(), args = []) {
       ...simulation,
       ...(typeof simulation.tool === 'string' ? { tool: { name: toolName, ...tool } } : {}),
       name: simName,
-      ...(resourceKey ? {
-        distPath: join(projectRoot, `dist/${resourceKey}/${resourceKey}.html`),
-        srcPath,
-        resource: resourceMap.get(resourceKey),
-      } : {}),
+      ...(resourceKey
+        ? {
+            distPath: join(projectRoot, `dist/${resourceKey}/${resourceKey}.html`),
+            srcPath,
+            resource: resourceMap.get(resourceKey),
+          }
+        : {}),
       // Attach output schema from the tool module (if present)
-      ...(toolHandlerMap.has(toolName) && toolHandlerMap.get(toolName).outputSchema ? {
-        outputSchema: toolHandlerMap.get(toolName).outputSchema,
-      } : {}),
+      ...(toolHandlerMap.has(toolName) && toolHandlerMap.get(toolName).outputSchema
+        ? {
+            outputSchema: toolHandlerMap.get(toolName).outputSchema,
+          }
+        : {}),
       // Attach real handler so Prod Tools mode works at runtime.
       // The --prod-tools flag only sets the default checkbox state; the handler
       // must always be available for when the user toggles it in the sidebar.
-      ...(toolHandlerMap.has(toolName) ? {
-        handler: toolHandlerMap.get(toolName).handler,
-      } : {}),
+      ...(toolHandlerMap.has(toolName)
+        ? {
+            handler: toolHandlerMap.get(toolName).handler,
+          }
+        : {}),
       // Attach the raw Zod shape so the MCP server registers tools with real schemas.
-      ...(toolHandlerMap.has(toolName) && toolHandlerMap.get(toolName).schema ? {
-        inputSchema: toolHandlerMap.get(toolName).schema,
-      } : {}),
+      ...(toolHandlerMap.has(toolName) && toolHandlerMap.get(toolName).schema
+        ? {
+            inputSchema: toolHandlerMap.get(toolName).schema,
+          }
+        : {}),
     });
   }
 
@@ -354,8 +387,8 @@ export async function dev(projectRoot = process.cwd(), args = []) {
   // callServerTool calls to the MCP server because the tool isn't registered.
   for (const [toolName, { tool }] of toolMap) {
     if (tool.resource) continue; // UI tools need simulations for their resource
-    const alreadyCovered = simulations.some(s =>
-      (s.tool?.name === toolName) || (typeof s.tool === 'string' && s.tool === toolName)
+    const alreadyCovered = simulations.some(
+      (s) => s.tool?.name === toolName || (typeof s.tool === 'string' && s.tool === toolName)
     );
     if (alreadyCovered) continue;
     const handlerInfo = toolHandlerMap.get(toolName);
@@ -405,12 +438,16 @@ export async function dev(projectRoot = process.cwd(), args = []) {
           return 'console.error("Missing src or component param");';
         }
 
+        const safeSrcPath = JSON.stringify(srcPath);
+        const safeComponentName = JSON.stringify(componentName);
+
         return `
-import { createElement } from 'react';
-import { createRoot } from 'react-dom/client';
-import { AppProvider } from 'sunpeak';
-import '/src/styles/globals.css';
-import * as ResourceModule from '${srcPath}';
+	import { createElement } from 'react';
+	import { createRoot } from 'react-dom/client';
+	import { AppProvider } from 'sunpeak';
+	import '/src/styles/globals.css';
+	const ResourceModule = await import(${safeSrcPath});
+	const componentName = ${safeComponentName};
 
 // Reuse React root across HMR updates to preserve the AppProvider host connection.
 // The host renders this HTML inline (not at a fetchable URL), so location.reload()
@@ -418,10 +455,13 @@ import * as ResourceModule from '${srcPath}';
 const root = import.meta.hot?.data?.root ?? createRoot(document.getElementById('root'));
 if (import.meta.hot) import.meta.hot.data.root = root;
 
-const Component = ResourceModule.default || ResourceModule['${componentName}'];
-if (!Component) {
-  document.getElementById('root').innerHTML = '<pre style="color:red;padding:16px">Component not found: ${componentName}\\nExports: ' + Object.keys(ResourceModule).join(', ') + '</pre>';
-} else {
+	const Component = ResourceModule.default || ResourceModule[componentName];
+	if (!Component) {
+	  const error = document.createElement('pre');
+	  error.style.cssText = 'color:red;padding:16px';
+	  error.textContent = 'Component not found: ' + componentName + '\\nExports: ' + Object.keys(ResourceModule).join(', ');
+	  document.getElementById('root').replaceChildren(error);
+	} else {
   const appInfo = { name: ${JSON.stringify(pkg.name || 'sunpeak-app')}, version: ${JSON.stringify(pkg.version || '0.1.0')} };
   root.render(
     createElement(AppProvider, { appInfo }, createElement(Component))
@@ -474,10 +514,7 @@ if (import.meta.hot) {
       // resource load discovers new deps (e.g., mapbox-gl, embla-carousel),
       // triggers re-optimization, and reloads all connections — killing
       // any active ChatGPT/Claude iframe connections with ECONNRESET.
-      entries: [
-        'src/resources/**/*.{ts,tsx}',
-        'src/tools/**/*.ts',
-      ],
+      entries: ['src/resources/**/*.{ts,tsx}', 'src/tools/**/*.ts'],
       include: ['react', 'react-dom/client'],
     },
     appType: 'custom',
@@ -491,8 +528,8 @@ if (import.meta.hot) {
   // Skipped under --prod-resources where mcpViteServer is created but unused.
   if (!isProdResources && (resourceDirs.length > 0 || toolFiles.length > 0)) {
     const warmupTargets = [
-      ...resourceDirs.map(({ key, resourcePath }) =>
-        `/src/resources/${key}/${basename(resourcePath)}`
+      ...resourceDirs.map(
+        ({ key, resourcePath }) => `/src/resources/${key}/${basename(resourcePath)}`
       ),
       ...toolFiles.map(({ name: toolName }) => `/src/tools/${toolName}.ts`),
     ];
@@ -505,7 +542,9 @@ if (import.meta.hot) {
       )
     );
     await mcpViteServer.waitForRequestsIdle();
-    console.log(`Warmed Vite (${warmupTargets.length} ${warmupTargets.length === 1 ? 'entry' : 'entries'}) in ${Date.now() - warmStart}ms`);
+    console.log(
+      `Warmed Vite (${warmupTargets.length} ${warmupTargets.length === 1 ? 'entry' : 'entries'}) in ${Date.now() - warmStart}ms`
+    );
   }
 
   // Load server config from src/server.ts (if present) for server identity
@@ -522,7 +561,7 @@ if (import.meta.hot) {
         // Extract a display icon from the icons array (first non-dark icon, or first icon)
         const icons = serverMod.server.icons;
         if (Array.isArray(icons) && icons.length > 0) {
-          const lightIcon = icons.find(i => !i.theme || i.theme === 'light') ?? icons[0];
+          const lightIcon = icons.find((i) => !i.theme || i.theme === 'light') ?? icons[0];
           serverDisplayIcon = lightIcon?.src;
         }
       }
@@ -598,7 +637,10 @@ if (import.meta.hot) {
         const result = await mod.default(args, {});
         const durationMs = Math.round((performance.now() - startTime) * 10) / 10;
         if (typeof result === 'string') {
-          return { content: [{ type: 'text', text: result }], _meta: { _sunpeak: { requestTimeMs: durationMs } } };
+          return {
+            content: [{ type: 'text', text: result }],
+            _meta: { _sunpeak: { requestTimeMs: durationMs } },
+          };
         }
         const typed = result ?? {};
         return { ...typed, _meta: { ...typed._meta, _sunpeak: { requestTimeMs: durationMs } } };
@@ -617,7 +659,7 @@ if (import.meta.hot) {
 // Allow running directly
 if (import.meta.url === `file://${process.argv[1]}`) {
   const args = process.argv.slice(2);
-  dev(process.cwd(), args).catch(error => {
+  dev(process.cwd(), args).catch((error) => {
     console.error('Error:', error.message);
     process.exit(1);
   });

package/bin/commands/inspect.mjs

@@ -1032,6 +1032,12 @@ function appendInspectorRequestToken(resourceUrl, requestToken) {
   }
 }
 
+function isInspectorRequestTokenValid(req, requestToken) {
+  if (!requestToken) return true;
+  const url = new URL(req.url, 'http://localhost');
+  return url.searchParams.get('__sunpeak_token') === requestToken;
+}
+
 function addInspectorRequestTokenToSimulations(simulations, requestToken) {
   if (!requestToken || !simulations || typeof simulations !== 'object') return simulations;
   return Object.fromEntries(
@@ -2073,12 +2079,7 @@ function sunpeakInspectEndpointsPlugin(getClient, setClient, pluginOpts = {}) {
   }
 
   function requireInspectorRequestToken(req, res) {
-    if (!pluginOpts.requestToken) return true;
-    const fetchSiteHeader = req.headers['sec-fetch-site'];
-    const fetchSite = Array.isArray(fetchSiteHeader) ? fetchSiteHeader[0] : fetchSiteHeader;
-    if (fetchSite !== 'cross-site') return true;
-    const url = new URL(req.url, 'http://localhost');
-    if (url.searchParams.get('__sunpeak_token') === pluginOpts.requestToken) return true;
+    if (isInspectorRequestTokenValid(req, pluginOpts.requestToken)) return true;
     res.writeHead(403, { 'Content-Type': 'text/plain' });
     res.end('Forbidden: missing or invalid inspector request token');
     return false;
@@ -3090,6 +3091,7 @@ export const _securityTestExports = {
   formatSharedAppContextForModel,
   addInspectorRequestTokenToSimulations,
   appendInspectorRequestToken,
+  isInspectorRequestTokenValid,
   normalizeApiKey,
   normalizeModelChatMessages,
   normalizeModelAppContext,

package/bin/lib/inspect/inspect-config.mjs

@@ -55,24 +55,24 @@ export function defineInspectConfig(options) {
   const { port, sandboxPort } = resolvePorts();
 
   // Build the sunpeak inspect command
-  const serverArg = server.includes(' ') ? `"${server}"` : server;
+  const serverArg = shellQuote(server);
   const command = [
     `SUNPEAK_SANDBOX_PORT=${sandboxPort}`,
-    `${resolveSunpeakBin()} inspect`,
+    `${shellQuote(resolveSunpeakBin())} inspect`,
     `--server ${serverArg}`,
     ...(env
       ? Object.entries(env).map(([k, v]) => {
           const pair = `${k}=${v}`;
-          return pair.includes(' ') ? `--env "${pair}"` : `--env ${pair}`;
+          return `--env ${shellQuote(pair)}`;
         })
       : []),
-    ...(cwd ? [cwd.includes(' ') ? `--cwd "${cwd}"` : `--cwd ${cwd}`] : []),
+    ...(cwd ? [`--cwd ${shellQuote(cwd)}`] : []),
     ...(headers
       ? Object.entries(headers).map(([k, v]) => `--header ${shellQuote(`${k}: ${v}`)}`)
       : []),
-    ...(simulationsDir ? [`--simulations ${simulationsDir}`] : []),
+    ...(simulationsDir ? [`--simulations ${shellQuote(simulationsDir)}`] : []),
     `--port ${port}`,
-    ...(name ? [`--name "${name}"`] : []),
+    ...(name ? [`--name ${shellQuote(name)}`] : []),
   ].join(' ');
 
   return createBaseConfig({

package/bin/lib/live/chatgpt-page.mjs

@@ -11,7 +11,7 @@ import { HostPage } from './host-page.mjs';
 /**
  * All ChatGPT DOM selectors in one place for easy maintenance.
  *
- * Last verified: 2026-03-24 via live Playwright inspection.
+ * Updated: 2026-07-10 for the documented ChatGPT Plugins flow.
  */
 const SELECTORS = {
   // Chat interface
@@ -23,8 +23,9 @@ const SELECTORS = {
   loggedInIndicator: '[data-testid="accounts-profile-button"]',
   loginPage: 'button:has-text("Log in")',
 
-  // Settings navigation
-  appsTab: '[role="tab"]:has-text("Apps")',
+  // Plugin directory navigation
+  createdByYou:
+    'button:has-text("Created by you"), [role="tab"]:has-text("Created by you"), a:has-text("Created by you")',
   refreshButton: 'button:has-text("Refresh")',
   reconnectButton: 'button:has-text("Reconnect")',
 
@@ -40,40 +41,51 @@ const SELECTORS = {
 
 const URLS = {
   base: 'https://chatgpt.com',
-  settings: 'https://chatgpt.com/#settings/Connectors',
+  plugins: 'https://chatgpt.com/plugins',
 };
 
+const PLUGIN_SETUP_HINT =
+  'Enable Developer mode from the bottom-left user menu under Settings > Security and login > Developer mode, then add the app from Plugins > +.';
+
 export { SELECTORS as CHATGPT_SELECTORS, URLS as CHATGPT_URLS };
 
 export class ChatGPTPage extends HostPage {
-  get hostId() { return 'chatgpt'; }
-  get hostName() { return 'ChatGPT'; }
-  get selectors() { return SELECTORS; }
-  get urls() { return URLS; }
+  get hostId() {
+    return 'chatgpt';
+  }
+  get hostName() {
+    return 'ChatGPT';
+  }
+  get selectors() {
+    return SELECTORS;
+  }
+  get urls() {
+    return URLS;
+  }
 
   /**
-   * Refresh the MCP server connection in ChatGPT settings.
-   * Navigates to Settings > Apps, clicks the app entry, clicks Refresh,
+   * Refresh the MCP server connection from the ChatGPT Plugins directory.
+   * Opens Plugins, finds the developer-mode app, clicks Refresh,
    * and waits for the success/error toast.
    */
   async refreshMcpServer({ tunnelUrl, appName } = {}) {
-    await this.page.goto(URLS.settings, { waitUntil: 'domcontentloaded' });
+    await this.page.goto(URLS.plugins, { waitUntil: 'domcontentloaded' });
     await this.page.waitForTimeout(3_000);
 
     const found = await this._findAndClickRefresh(appName);
 
     if (!found) {
-      const appsTab = this.page.locator(SELECTORS.appsTab);
-      const hasAppsTab = await appsTab.isVisible().catch(() => false);
-      if (hasAppsTab) {
-        await appsTab.click();
+      const createdByYou = this.page.locator(SELECTORS.createdByYou).first();
+      const hasCreatedByYou = await createdByYou.isVisible().catch(() => false);
+      if (hasCreatedByYou) {
+        await createdByYou.click();
         await this.page.waitForTimeout(2_000);
         const retryFound = await this._findAndClickRefresh(appName);
         if (!retryFound) {
-          await this._screenshotAndThrow('refresh-mcp-settings', tunnelUrl);
+          await this._screenshotAndThrow('refresh-mcp-plugin', tunnelUrl, PLUGIN_SETUP_HINT);
         }
       } else {
-        await this._screenshotAndThrow('no-apps-tab', tunnelUrl);
+        await this._screenshotAndThrow('developer-plugin-not-found', tunnelUrl, PLUGIN_SETUP_HINT);
       }
     }
 
@@ -82,7 +94,7 @@ export class ChatGPTPage extends HostPage {
     if (hasError) {
       throw new Error(
         `MCP server refresh failed in ChatGPT:\n${errorText.trim()}\n\n` +
-        `Make sure your MCP dev server is running (pnpm dev) and your tunnel is active.`
+          `Make sure your MCP dev server is running (pnpm dev) and your tunnel is active.`
       );
     }
 
@@ -107,13 +119,18 @@ export class ChatGPTPage extends HostPage {
     }
 
     // Wait for the outer sandbox iframe
-    await this.page.locator(SELECTORS.mcpAppOuterIframe).first().waitFor({ state: 'attached', timeout: 30_000 });
+    await this.page
+      .locator(SELECTORS.mcpAppOuterIframe)
+      .first()
+      .waitFor({ state: 'attached', timeout: 30_000 });
 
     // Wait for the inner frame to appear inside the sandboxed outer iframe.
     // waitForFunction can't cross the sandbox boundary, so use Playwright's frameLocator instead.
     const outerFrame = this.page.frameLocator(SELECTORS.mcpAppOuterIframe).first();
     await outerFrame
-      .locator(`iframe[name="${SELECTORS.mcpAppInnerFrameName}"], iframe#${SELECTORS.mcpAppInnerFrameName}`)
+      .locator(
+        `iframe[name="${SELECTORS.mcpAppInnerFrameName}"], iframe#${SELECTORS.mcpAppInnerFrameName}`
+      )
       .waitFor({ state: 'attached', timeout: 15_000 });
 
     const appFrame = this.getAppIframe();
@@ -182,13 +199,11 @@ export class ChatGPTPage extends HostPage {
       return false;
     };
 
-    if (await tryClickRefresh()) return true;
-
     if (appName) {
       const strategies = [
         () => this.page.getByText(appName, { exact: true }).first(),
-        () => this.page.locator(`text=${appName}`).first(),
-        () => this.page.locator(`a:has-text("${appName}"), [role="button"]:has-text("${appName}")`).first(),
+        () => this.page.getByRole('link', { name: appName, exact: true }).first(),
+        () => this.page.getByRole('button', { name: appName, exact: true }).first(),
       ];
 
       for (const getLocator of strategies) {
@@ -205,6 +220,6 @@ export class ChatGPTPage extends HostPage {
       }
     }
 
-    return false;
+    return appName ? false : tryClickRefresh();
   }
 }

package/bin/lib/live/global-setup.mjs

@@ -3,7 +3,7 @@
  *
  * Runs exactly once before all workers. Two responsibilities:
  *  1. Authenticate — launch a browser, verify login, wait for user if needed.
- *  2. Refresh MCP server — navigate to host settings and click Refresh so
+ *  2. Refresh MCP server: open the host's app management UI and click Refresh so
  *     all workers start with pre-loaded resources.
  *
  * Auth approach:
@@ -150,7 +150,7 @@ export default async function globalSetup() {
     // Refresh MCP server in the SAME browser session.
     // This is critical — Cloudflare's cf_clearance cookie is HttpOnly and
     // won't be in the saved storageState. By refreshing here, the cookie
-    // is still valid for navigating to settings.
+    // is still valid for navigating to the plugin directory.
     //
     // This MUST succeed — if the MCP server isn't reachable or the refresh
     // fails, tests will fail with confusing iframe/timeout errors.

package/bin/lib/live/host-page.mjs

@@ -23,8 +23,7 @@
 /**
  * @typedef {Object} HostUrls
  * @property {string} base - Host base URL (e.g., 'https://chatgpt.com')
- * @property {string} settings - MCP settings URL
- * @property {string} loginTestId - Test ID for login detection (if using getByTestId)
+ * @property {string} [plugins] - Host plugin or app management URL
  */
 
 export class HostPage {
@@ -80,7 +79,8 @@ export class HostPage {
     if (warnings.length > 0) {
       console.warn(
         `\n⚠️  ${this.hostName} DOM may have changed — update selectors in ${this.hostId}-page.mjs:\n` +
-        warnings.join('\n') + '\n'
+          warnings.join('\n') +
+          '\n'
       );
     }
 
@@ -135,14 +135,14 @@ export class HostPage {
     // Not logged in. Wait for the user to authenticate in this browser window.
     console.log(
       `\n` +
-      `╔══════════════════════════════════════════════════════════════╗\n` +
-      `║  Not logged into ${this.hostName.padEnd(42)}║\n` +
-      `║                                                            ║\n` +
-      `║  Please log in at: ${this.urls.base.padEnd(39)}║\n` +
-      `║  in the browser window that just opened.                   ║\n` +
-      `║                                                            ║\n` +
-      `║  Waiting up to 3 minutes...                                ║\n` +
-      `╚══════════════════════════════════════════════════════════════╝\n`
+        `╔══════════════════════════════════════════════════════════════╗\n` +
+        `║  Not logged into ${this.hostName.padEnd(42)}║\n` +
+        `║                                                            ║\n` +
+        `║  Please log in at: ${this.urls.base.padEnd(39)}║\n` +
+        `║  in the browser window that just opened.                   ║\n` +
+        `║                                                            ║\n` +
+        `║  Waiting up to 3 minutes...                                ║\n` +
+        `╚══════════════════════════════════════════════════════════════╝\n`
     );
 
     // Poll for login — the user may need to pass Cloudflare + enter credentials
@@ -160,14 +160,14 @@ export class HostPage {
 
     throw new Error(
       `Login to ${this.hostName} timed out after 3 minutes.\n` +
-      `Please log in at ${this.urls.base} in the browser window and try again.\n` +
-      'If the session expired, delete the .auth/ directory and try again.'
+        `Please log in at ${this.urls.base} in the browser window and try again.\n` +
+        'If the session expired, delete the .auth/ directory and try again.'
     );
   }
 
   /**
-   * Refresh the MCP server connection in host settings.
-   * Subclasses must implement this — each host has different settings UI.
+   * Refresh the MCP server connection in the host's app management UI.
+   * Subclasses must implement this because each host has a different flow.
    *
    * @param {Object} [options]
    * @param {string} [options.tunnelUrl] - Tunnel URL for error messages
@@ -228,9 +228,10 @@ export class HostPage {
    * Capture a debug screenshot and throw with helpful message.
    * @param {string} context - Context label for the screenshot filename
    * @param {string} [tunnelUrl] - Tunnel URL for the error message
+   * @param {string} [setupHint] - Host-specific setup steps
    * @protected
    */
-  async _screenshotAndThrow(context, tunnelUrl) {
+  async _screenshotAndThrow(context, tunnelUrl, setupHint) {
     const screenshotPath = `/tmp/sunpeak-live-debug-${this.hostId}-${context}.png`;
     try {
       await this.page.screenshot({ path: screenshotPath, fullPage: true });
@@ -241,29 +242,34 @@ export class HostPage {
 
     try {
       const buttons = await this.page.locator('button').allTextContents();
-      console.error('Visible buttons on page:', buttons.filter(t => t.trim()).join(', '));
+      console.error('Visible buttons on page:', buttons.filter((t) => t.trim()).join(', '));
     } catch {
       // Best effort
     }
 
     throw new Error(
-      `Could not find Refresh/Reconnect button in ${this.hostName} settings.\n` +
-      `Make sure your MCP server is added in ${this.hostName} settings` +
-      (tunnelUrl ? ` with URL: ${tunnelUrl}/mcp` : '') +
-      `\n\nDebug screenshot: ${screenshotPath}`
+      `Could not find Refresh/Reconnect in ${this.hostName} app management.\n` +
+        `Make sure your MCP server is added to ${this.hostName}` +
+        (tunnelUrl ? ` with URL: ${tunnelUrl}/mcp` : '') +
+        (setupHint ? `\n${setupHint}` : '') +
+        `\n\nDebug screenshot: ${screenshotPath}`
     );
   }
 
   /**
    * Wait for a toast/alert banner and check for errors.
-   * Many hosts show success/error toasts after settings actions.
+   * Many hosts show success/error toasts after app management actions.
    * @param {Object} [options]
    * @param {string} [options.alertSelector='[role="alert"]'] - Selector for toast elements
    * @param {number} [options.timeout=30000] - Max time to wait
    * @param {number} [options.minTextLength=5] - Minimum text length to consider as a real toast
    * @protected
    */
-  async _waitForToast({ alertSelector = '[role="alert"]', timeout = 30_000, minTextLength = 5 } = {}) {
+  async _waitForToast({
+    alertSelector = '[role="alert"]',
+    timeout = 30_000,
+    minTextLength = 5,
+  } = {}) {
     try {
       await this.page.waitForFunction(
         ({ selector, minLen }) => {
@@ -275,7 +281,7 @@ export class HostPage {
           return false;
         },
         { selector: alertSelector, minLen: minTextLength },
-        { timeout },
+        { timeout }
       );
     } catch {
       console.warn('No toast detected — assuming success.');