@runsnative/mcp-server 0.4.0 → 0.5.1

package/dist/inferrer/nav-error.js

@@ -0,0 +1,31 @@
+// Navigation-failure classification, extracted from page-fetcher.ts (JUNE-607) so the
+// Cloudflare Worker port can import it without dragging in page-fetcher's lazy
+// `import('playwright')` — esbuild cannot bundle a literal dynamic import of a package
+// that is not installed. This module is pure (no imports, no I/O); page-fetcher.ts
+// re-exports everything here, so existing consumers are unaffected.
+/**
+ * Map a Chromium/Playwright navigation error string to a user-meaningful reason. Signatures
+ * verified against live failures: ecolab.com → ERR_HTTP2_PROTOCOL_ERROR (bot-block),
+ * a dead domain → ERR_NAME_NOT_RESOLVED, badssl.com → ERR_CERT_*, port 1 → ERR_UNSAFE_PORT.
+ */
+export function classifyNavError(cause) {
+    const c = cause.toUpperCase();
+    if (/\bTIMEOUT\b|EXCEEDED/.test(c))
+        return 'timeout';
+    if (c.includes('ERR_NAME_NOT_RESOLVED') || c.includes('ERR_NAME_RESOLUTION_FAILED'))
+        return 'not_found';
+    if (c.includes('ERR_CERT'))
+        return 'tls';
+    // Connection reset / HTTP2 protocol errors on the initial navigation are the fingerprint of
+    // a WAF/bot wall fingerprinting headless Chromium (verified: ecolab.com). ERR_ACCESS_DENIED
+    // and ERR_BLOCKED_BY_* are the explicit forms.
+    if (c.includes('ERR_HTTP2_PROTOCOL_ERROR') || c.includes('ERR_CONNECTION_RESET') ||
+        c.includes('ERR_ACCESS_DENIED') || c.includes('ERR_BLOCKED'))
+        return 'blocked';
+    if (c.includes('ERR_CONNECTION_REFUSED') || c.includes('ERR_CONNECTION_TIMED_OUT') ||
+        c.includes('ERR_ADDRESS_UNREACHABLE') || c.includes('ERR_UNSAFE_PORT') ||
+        c.includes('ERR_CONNECTION_CLOSED') || c.includes('ERR_EMPTY_RESPONSE') ||
+        c.includes('ERR_SOCKET_NOT_CONNECTED'))
+        return 'unreachable';
+    return 'unknown';
+}

package/dist/inferrer/page-fetcher.js

@@ -1,4 +1,10 @@
 import { extractStylesFromPage } from './style-extractor.js';
+import { classifyNavError } from './nav-error.js';
+// Failure classification lives in nav-error.ts (JUNE-607) so the Cloudflare Worker port can
+// share it without importing this module's lazy `import('playwright')` (esbuild cannot bundle
+// a literal dynamic import of an uninstalled package). Re-exported so existing consumers
+// (pipeline, tests, the MCP tool) keep their import path.
+export { classifyNavError };
 export async function loadChromium() {
     try {
         const playwright = await import('playwright');
@@ -8,32 +14,6 @@ export async function loadChromium() {
         return null;
     }
 }
-/**
- * Map a Chromium/Playwright navigation error string to a user-meaningful reason. Signatures
- * verified against live failures: ecolab.com → ERR_HTTP2_PROTOCOL_ERROR (bot-block),
- * a dead domain → ERR_NAME_NOT_RESOLVED, badssl.com → ERR_CERT_*, port 1 → ERR_UNSAFE_PORT.
- */
-export function classifyNavError(cause) {
-    const c = cause.toUpperCase();
-    if (/\bTIMEOUT\b|EXCEEDED/.test(c))
-        return 'timeout';
-    if (c.includes('ERR_NAME_NOT_RESOLVED') || c.includes('ERR_NAME_RESOLUTION_FAILED'))
-        return 'not_found';
-    if (c.includes('ERR_CERT'))
-        return 'tls';
-    // Connection reset / HTTP2 protocol errors on the initial navigation are the fingerprint of
-    // a WAF/bot wall fingerprinting headless Chromium (verified: ecolab.com). ERR_ACCESS_DENIED
-    // and ERR_BLOCKED_BY_* are the explicit forms.
-    if (c.includes('ERR_HTTP2_PROTOCOL_ERROR') || c.includes('ERR_CONNECTION_RESET') ||
-        c.includes('ERR_ACCESS_DENIED') || c.includes('ERR_BLOCKED'))
-        return 'blocked';
-    if (c.includes('ERR_CONNECTION_REFUSED') || c.includes('ERR_CONNECTION_TIMED_OUT') ||
-        c.includes('ERR_ADDRESS_UNREACHABLE') || c.includes('ERR_UNSAFE_PORT') ||
-        c.includes('ERR_CONNECTION_CLOSED') || c.includes('ERR_EMPTY_RESPONSE') ||
-        c.includes('ERR_SOCKET_NOT_CONNECTED'))
-        return 'unreachable';
-    return 'unknown';
-}
 const VIEWPORT = { width: 1280, height: 800 };
 // Navigation timing. `domcontentloaded` is the hard gate; `networkidle` is a bounded bonus.
 const GOTO_TIMEOUT_MS = 25_000; // hard cap on the initial document navigation

package/dist/server.js

@@ -18,6 +18,7 @@ import { GET_EMPHASIS_SCALE_TOOL, handleGetEmphasisScale } from './tools/get-emp
 import { GET_COMPLETENESS_MAP_TOOL, handleGetCompletenessMap } from './tools/get-completeness-map.js';
 import { LINK_SESSION_TOOL, handleLinkSession } from './tools/link-session.js';
 import { SET_THEME_TOOL, handleSetTheme } from './tools/set-theme.js';
+import { APPLY_INFERRED_THEME_TOOL, handleApplyInferredTheme } from './tools/apply-inferred-theme.js';
 import { NAVIGATE_TOOL, handleNavigate } from './tools/navigate.js';
 import { SET_INSTANCE_VARIANT_TOOL, handleSetInstanceVariant } from './tools/set-instance-variant.js';
 import { GET_MARKER_CAPTURE_TOOL, handleGetMarkerCapture } from './tools/get-marker-capture.js';
@@ -60,6 +61,7 @@ export async function createRunsnativeServer() {
             GET_COMPLETENESS_MAP_TOOL,
             LINK_SESSION_TOOL,
             SET_THEME_TOOL,
+            APPLY_INFERRED_THEME_TOOL,
             NAVIGATE_TOOL,
             SET_INSTANCE_VARIANT_TOOL,
             GET_MARKER_CAPTURE_TOOL,
@@ -99,6 +101,8 @@ export async function createRunsnativeServer() {
                 return handleLinkSession(request.params.arguments ?? {});
             case 'set_theme':
                 return handleSetTheme(request.params.arguments ?? {});
+            case 'apply_inferred_theme':
+                return handleApplyInferredTheme(request.params.arguments ?? {});
             case 'navigate':
                 return handleNavigate(request.params.arguments ?? {});
             case 'set_instance_variant':

package/dist/test/validate.js

@@ -136,7 +136,7 @@ console.log('\nget_foundation');
 console.log('\nlistFoundations');
 {
     const foundations = await listFoundations();
-    check('returns 7 foundations', () => assert(foundations.length === 7, `expected 7 foundations, got ${foundations.length}`));
+    check('returns 8 foundations', () => assert(foundations.length === 8, `expected 8 foundations, got ${foundations.length}`));
     check('includes color', () => assert(foundations.some((f) => f.foundation === 'color'), 'missing color'));
     check('includes typography', () => assert(foundations.some((f) => f.foundation === 'typography'), 'missing typography'));
     check('each foundation has title and description', () => {
@@ -214,7 +214,7 @@ console.log('\nlist_exercises');
 {
     const ready = await listExerciseMeta(false);
     const all = await listExerciseMeta(true);
-    check('returns all three ready exercises', () => assert(ready.length === 3, `expected 3 ready exercises, got ${ready.length}`));
+    check('returns all four ready exercises', () => assert(ready.length === 4, `expected 4 ready exercises, got ${ready.length}`));
     check('each exercise has required fields', () => {
         for (const ex of ready) {
             assert(typeof ex.name === 'string' && ex.name.length > 0, `exercise missing name`);
@@ -284,6 +284,40 @@ console.log('\nget_step');
     });
 }
 // ---------------------------------------------------------------------------
+// Coached exercise slice — live-session binding (JUNE-625)
+//
+// migrate-to-runsnative step 5 gained a "Coached Mode" section that drives
+// the bridge's set_theme on the learner's own linked session; step 7
+// verifies the result via get_marker_capture. Regression guard: the coached
+// content must exist, name the correct bridge tools, and the exercise's
+// step count must have grown to 7 without disturbing steps 1-6.
+// ---------------------------------------------------------------------------
+console.log('\ncoached exercise slice (JUNE-625)');
+{
+    const detail = await getExerciseDetail('migrate-to-runsnative');
+    check('migrate-to-runsnative now has 7 steps', () => assert(detail.steps.length === 7, `expected 7 steps, got ${detail.steps.length}`));
+    const step5 = await getExerciseStep('migrate-to-runsnative', 5);
+    check('step 5 documents Coached Mode', () => assert(step5.content.includes('Coached Mode'), 'missing Coached Mode section'));
+    check('step 5 names set_theme', () => assert(step5.content.includes('set_theme'), 'missing set_theme reference'));
+    check('step 5 links to /ai/linked-session', () => assert(step5.content.includes('/ai/linked-session'), 'missing linked-session doc link'));
+    const step7 = await getExerciseStep('migrate-to-runsnative', 7);
+    check('step 7 returned with content', () => {
+        assert(step7.step === 7, `expected step 7, got ${step7.step}`);
+        assert(step7.title === 'Prove the live change (if linked)', `expected title match, got ${step7.title}`);
+    });
+    check('step 7 names get_marker_capture', () => assert(step7.content.includes('get_marker_capture'), 'missing get_marker_capture reference'));
+    check('step 7 is opt-in (skip guidance present)', () => assert(/skip/i.test(step7.content), 'missing skip-if-not-linked guidance'));
+    check('step 8 out-of-range throws RangeError', async () => {
+        try {
+            await getExerciseStep('migrate-to-runsnative', 8);
+            throw new Error('should have thrown');
+        }
+        catch (err) {
+            assert(err instanceof RangeError, `expected RangeError, got ${err.constructor.name}`);
+        }
+    });
+}
+// ---------------------------------------------------------------------------
 // Exercise ↔ live-site wiring (RUN-354)
 //
 // Regression guard for the RUN-326 defect class: exercises that referenced

package/dist/tools/apply-inferred-theme.js

@@ -0,0 +1,89 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { postWorkerApi, getLinkedPairId } from '../bridge-client.js';
+export const APPLY_INFERRED_THEME_TOOL = {
+    name: 'apply_inferred_theme',
+    description: "Turn a written brand brief into a bespoke theme and apply it live to the user's linked runsnative.org tab. " +
+        'Describe the brand in plain language — mood, industry, color feelings ("warm terracotta ceramics studio", ' +
+        '"midnight fintech, electric green accents") — and the RunsNative inference engine derives a full themed token ' +
+        'profile server-side, saves it to your theme library, and restyles the tab within one poll interval. This is a ' +
+        'paid capability: without an active grant the call returns an upgrade path rather than a theme. Fully ' +
+        'reversible — switch back with set_theme at any time. Requires an active linked session (call link_session first).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            brief: {
+                type: 'string',
+                description: 'The brand brief: mood, industry, audience, and color language, in plain prose (up to 4000 characters).',
+            },
+            name: { type: 'string', description: 'Optional name for the saved theme; inferred from the brief when omitted.' },
+        },
+        required: ['brief'],
+    },
+    // LSP §5.1 — session-targeting; the first entitlement:'paid' capability on
+    // the bridge (JUNE-650). `enactment` names the worker allow-list entry the
+    // command leg submits after the paid inference leg succeeds.
+    _meta: {
+        lsp: {
+            target: 'session',
+            tier: 'reversible',
+            consent: 'implicit',
+            entitlement: 'paid',
+            visibility: 'advertised',
+            enactment: 'theme.applyInferredTheme',
+        },
+    },
+};
+export async function handleApplyInferredTheme(args) {
+    const brief = args['brief'];
+    if (typeof brief !== 'string' || !brief.trim()) {
+        throw new McpError(ErrorCode.InvalidParams, 'brief must be a non-empty brand-brief string');
+    }
+    const name = typeof args['name'] === 'string' && args['name'].trim() ? args['name'].trim() : undefined;
+    const pairId = getLinkedPairId();
+    if (!pairId) {
+        throw new McpError(ErrorCode.InvalidParams, 'No linked session. Call link_session with the pairing code first, or open runsnative.org and start the pairing flow.');
+    }
+    // Leg 1 — paid inference (server-side; the reasoning never reaches this client).
+    const inferRes = await postWorkerApi('/tenant/theme/infer', { brief: brief.trim(), ...(name ? { name } : {}) });
+    if (inferRes.status === 402) {
+        const body = await inferRes.json().catch(() => ({}));
+        // §8.2: the two denial reasons are DIFFERENT conversion paths — surface
+        // them distinctly so the calling agent can relay the right next step.
+        if (body.reason === 'renewal_required') {
+            throw new McpError(ErrorCode.InvalidParams, `Your grant for inferred themes has lapsed — renew to keep using it${body.payment_url ? `: ${body.payment_url}` : '.'}`);
+        }
+        throw new McpError(ErrorCode.InvalidParams, `Inferred themes are a paid capability you don't hold yet — upgrade to unlock it${body.payment_url ? `: ${body.payment_url}` : '.'}`);
+    }
+    if (inferRes.status === 400) {
+        const body = await inferRes.json().catch(() => ({}));
+        throw new McpError(ErrorCode.InvalidParams, body.error ?? 'Invalid brief.');
+    }
+    if (!inferRes.ok) {
+        const body = await inferRes.text().catch(() => '');
+        throw new McpError(ErrorCode.InternalError, `Theme inference failed (${inferRes.status}): ${body}`);
+    }
+    const inferred = await inferRes.json();
+    // Leg 2 — free-class application via the command bridge.
+    const cmdRes = await postWorkerApi('/tenant/command', {
+        pair_id: pairId,
+        capability: 'theme',
+        method: 'applyInferredTheme',
+        args: [`custom:${inferred.slug}`],
+    });
+    if (cmdRes.status === 404) {
+        throw new McpError(ErrorCode.InvalidParams, `Theme "${inferred.name ?? inferred.slug}" was saved, but the linked session was not found or expired. Re-link with link_session, then apply it with set_theme("custom:${inferred.slug}").`);
+    }
+    if (cmdRes.status === 409) {
+        throw new McpError(ErrorCode.InvalidParams, `Theme "${inferred.name ?? inferred.slug}" was saved, but no live tab was detected. Open runsnative.org, then apply it with set_theme("custom:${inferred.slug}").`);
+    }
+    if (!cmdRes.ok) {
+        const body = await cmdRes.text().catch(() => '');
+        throw new McpError(ErrorCode.InternalError, `Theme "${inferred.name ?? inferred.slug}" was saved, but applying it failed (${cmdRes.status}): ${body}`);
+    }
+    return {
+        content: [{
+                type: 'text',
+                text: `Inferred theme "${inferred.name ?? inferred.slug}" (seed: ${inferred.seed_theme_id ?? 'n/a'}, slug: ${inferred.slug}) saved and applied — the tab restyles within one poll interval. Reverse any time with set_theme.`,
+            }],
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runsnative/mcp-server",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "type": "module",
   "files": [
     "dist/"