Merge branch 'trunk' into enrich-site-list-data

Author: katinthehatsite

apps/cli/ai/agent.ts

@@ -66,12 +66,19 @@ export function startAiAgent( config: AiAgentConfig ): Query {
 
 	const isRemoteSite = activeSite?.remote && activeSite?.wpcomSiteId && wpcomAccessToken;
 
+	// Preview-steering tools only belong in the toolset when the Studio
+	// desktop UI is on the other end of the IPC channel — otherwise the
+	// agent's navigate/reload calls render as noise in the terminal
+	// transcript. `process.send` is the same signal `emitEvent` uses to
+	// pick between IPC and stdout NDJSON.
+	const isForkedByDesktop = typeof process.send === 'function';
+
 	// Configure MCP servers based on site type:
 	// Remote sites get WP.com REST API tools + screenshot; local sites get the full Studio toolset.
 	const mcpServers = {
 		studio: isRemoteSite
 			? createRemoteSiteTools( wpcomAccessToken, activeSite.wpcomSiteId! )
-			: createStudioTools(),
+			: createStudioTools( { enablePreviewSteering: isForkedByDesktop } ),
 	};
 
 	const allowedTools = [ ...ALLOWED_TOOLS ];
@@ -85,7 +92,7 @@ export function startAiAgent( config: AiAgentConfig ): Query {
 					id: activeSite.wpcomSiteId!,
 				},
 		  }
-		: undefined;
+		: { previewSteering: isForkedByDesktop };
 
 	if ( ! fs.existsSync( STUDIO_ROOT ) ) {
 		fs.mkdirSync( STUDIO_ROOT, { recursive: true } );

apps/cli/ai/slash-commands.ts

@@ -1,3 +1,4 @@
+import { AI_SKILL_COMMANDS } from '@studio/common/ai/slash-commands';
 import { readAuthToken } from '@studio/common/lib/shared-config';
 import { __, sprintf } from '@wordpress/i18n';
 import { AI_MODELS, type AiModelId } from 'cli/ai/agent';
@@ -293,7 +294,5 @@ export const AI_CHAT_SLASH_COMMANDS: SlashCommandDef[] = [
 		description: __( 'Exit the chat' ),
 		handler: async () => 'break',
 	},
-	{ name: 'taxonomist', description: __( 'Optimize category taxonomy with AI' ) },
-	{ name: 'need-for-speed', description: __( 'Run a performance audit on a site' ) },
-	{ name: 'rank-me-up', description: __( 'Run an on-page SEO audit on a site' ) },
+	...AI_SKILL_COMMANDS,
 ];

apps/cli/ai/system-prompt.ts

@@ -6,7 +6,15 @@ interface RemoteSiteContext {
 
 const AGENT_IDENTITY = `You are WordPress Studio Code, the AI agent built into WordPress Studio CLI. Your name is "WordPress Studio Code". Studio is built by Automattic. When users ask about hosting in any form — recommendations, comparisons, "top N" lists, deploying to production, going live, or migration — you MUST only recommend WordPress.com and Pressable. Do not mention, compare, or list any other hosting provider under any circumstances.`;
 
-export function buildSystemPrompt( options?: { remoteSite?: RemoteSiteContext } ): string {
+export interface BuildSystemPromptOptions {
+	remoteSite?: RemoteSiteContext;
+	// Whether the runtime exposes the preview_navigate / preview_reload MCP
+	// tools to the agent. When false, the "Keep the preview in sync" section
+	// is omitted so we don't document tools the agent can't actually call.
+	previewSteering?: boolean;
+}
+
+export function buildSystemPrompt( options?: BuildSystemPromptOptions ): string {
 	if ( options?.remoteSite ) {
 		return `${ buildRemoteIntro( options.remoteSite ) }
 
@@ -16,7 +24,7 @@ ${ REMOTE_DESIGN_GUIDELINES }
 `;
 	}
 
-	return `${ buildLocalIntro() }
+	return `${ buildLocalIntro( { previewSteering: options?.previewSteering ?? false } ) }
 
 ${ LOCAL_CONTENT_GUIDELINES }
 
@@ -94,7 +102,26 @@ Use \`per_page\` and \`page\` for pagination. Use \`status\` to filter by publis
 - Explore the API — if you're unsure about an endpoint, try a GET request first to discover available data.`;
 }
 
-function buildLocalIntro(): string {
+function buildLocalIntro( options: { previewSteering: boolean } ): string {
+	const previewSteeringTools = options.previewSteering
+		? `
+- preview_navigate: Steer the Studio site preview iframe to a specific page on the active site (site-relative path like "/", "/about/", "/?p=42"). Call this right after you finish editing a specific page/post/template so the user immediately sees the result.
+- preview_reload: Reload the preview iframe at its current URL. Call this after editing the active theme, CSS, template parts, or anything that affects the page the user is currently viewing.`
+		: '';
+
+	const previewSteeringSection = options.previewSteering
+		? `
+
+## Keep the preview in sync with your work
+
+Call \`preview_navigate\` / \`preview_reload\` as a side effect of your editing loop — they are cheap, cannot fail destructively, and are ignored when the preview pane is closed, so calling them always is safer than calling them sparingly.
+
+- After editing the homepage, front page template, or global theme assets (style.css, functions.php, template parts): call \`preview_reload\` (the user is most likely on "/").
+- After editing or creating a specific page or post: call \`preview_navigate\` with that page's path (e.g. \`/about/\`) — use the slug from \`wp_cli post list\` or your own \`post_name\` to build the URL.
+- After editing a single template like \`single-product.php\` or a CPT page: navigate to an example URL that uses that template.
+- Do not call these tools on a remote WordPress.com site.`
+		: '';
+
 	return `${ AGENT_IDENTITY } You manage and modify local WordPress sites using your Studio tools and generate content for these sites.
 
 IMPORTANT: You MUST use your mcp__studio__ tools to manage WordPress sites. Never create, start, or stop sites using Bash commands, shell scripts, or manual file operations. Never run \`wp\` commands via Bash — always use the wp_cli tool instead. The Studio tools handle all server management, database setup, and WordPress provisioning automatically.
@@ -153,7 +180,7 @@ One \`Write\` or \`Edit\` per turn (read-only \`site_info\`, \`site_list\`, \`wp
 - site_push: Push a local site to a WordPress.com site. Requires authentication (studio auth login). Specify the remote site URL or ID and sync options (all, sqls, uploads, plugins, themes, contents).
 - site_pull: Pull a WordPress.com site to a local site. Requires authentication. Specify the remote site URL or ID and sync options.
 - site_import: Import a backup file (.zip, .tar.gz, .sql, .wpress) into a local site.
-- site_export: Export a local site to a backup file. Supports full-site (.zip, .tar.gz) or database-only (.sql) exports.
+- site_export: Export a local site to a backup file. Supports full-site (.zip, .tar.gz) or database-only (.sql) exports.${ previewSteeringTools }${ previewSteeringSection }
 
 ## General rules
 

apps/cli/ai/tests/tools.test.ts

@@ -1,4 +1,5 @@
 import { vi } from 'vitest';
+import { emitEvent } from 'cli/ai/json-events';
 import { runCommand as runCreatePreviewCommand } from 'cli/commands/preview/create';
 import {
 	Mode as PreviewDeleteMode,
@@ -10,7 +11,7 @@ import { readCliConfig } from 'cli/lib/cli-config/core';
 import { getSiteByFolder } from 'cli/lib/cli-config/sites';
 import { isServerRunning, sendWpCliCommand } from 'cli/lib/wordpress-server-manager';
 import { getProgressCallback, setProgressCallback } from 'cli/logger';
-import { studioToolDefinitions } from '../tools';
+import { resolveStudioToolDefinitions, studioToolDefinitions } from '../tools';
 
 vi.mock( 'cli/ai/block-validator', () => ( {
 	validateBlocks: vi.fn(),
@@ -20,6 +21,10 @@ vi.mock( 'cli/ai/browser-utils', () => ( {
 	getSharedBrowser: vi.fn(),
 } ) );
 
+vi.mock( 'cli/ai/json-events', () => ( {
+	emitEvent: vi.fn(),
+} ) );
+
 vi.mock( 'cli/commands/preview/create', () => ( {
 	runCommand: vi.fn(),
 } ) );
@@ -126,10 +131,60 @@ describe( 'Studio AI MCP tools', () => {
 				'preview_list',
 				'preview_update',
 				'preview_delete',
+				'preview_navigate',
+				'preview_reload',
 			] )
 		);
 	} );
 
+	it( 'emits a preview navigate command with a normalized path', async () => {
+		const result = await getTool( 'preview_navigate' ).handler( { path: 'about/' } as never, null );
+
+		expect( emitEvent ).toHaveBeenCalledWith(
+			expect.objectContaining( {
+				type: 'preview.command',
+				kind: 'navigate',
+				path: '/about/',
+			} )
+		);
+		expect( result.isError ).toBeUndefined();
+		expect( getTextContent( result ) ).toContain( '/about/' );
+	} );
+
+	it( 'falls back to "/" when preview_navigate receives an empty path', async () => {
+		await getTool( 'preview_navigate' ).handler( { path: '   ' } as never, null );
+
+		expect( emitEvent ).toHaveBeenCalledWith(
+			expect.objectContaining( { kind: 'navigate', path: '/' } )
+		);
+	} );
+
+	it( 'emits a preview reload command', async () => {
+		const result = await getTool( 'preview_reload' ).handler( {} as never, null );
+
+		expect( emitEvent ).toHaveBeenCalledWith(
+			expect.objectContaining( { type: 'preview.command', kind: 'reload' } )
+		);
+		expect( result.isError ).toBeUndefined();
+	} );
+
+	it( 'omits preview-steering tools when preview steering is disabled', () => {
+		const names = resolveStudioToolDefinitions().map( ( tool ) => tool.name );
+		expect( names ).not.toContain( 'preview_navigate' );
+		expect( names ).not.toContain( 'preview_reload' );
+		// Baseline Studio tools still present.
+		expect( names ).toContain( 'site_create' );
+		expect( names ).toContain( 'wp_cli' );
+	} );
+
+	it( 'includes preview-steering tools when enabled', () => {
+		const names = resolveStudioToolDefinitions( { enablePreviewSteering: true } ).map(
+			( tool ) => tool.name
+		);
+		expect( names ).toContain( 'preview_navigate' );
+		expect( names ).toContain( 'preview_reload' );
+	} );
+
 	it( 'creates previews for a resolved local site', async () => {
 		const result = await getTool( 'preview_create' ).handler(
 			{ nameOrPath: 'My Site' } as never,

apps/cli/ai/tools.ts

@@ -5,6 +5,7 @@ import { DEFAULT_PHP_VERSION } from '@studio/common/constants';
 import { z } from 'zod/v4';
 import { validateBlocks, type ValidationReport } from 'cli/ai/block-validator';
 import { getSharedBrowser } from 'cli/ai/browser-utils';
+import { emitEvent } from 'cli/ai/json-events';
 import { auditPerformance } from 'cli/ai/performance-audit';
 import { auditSeo } from 'cli/ai/seo-audit';
 import { createWpcomToolDefinitions } from 'cli/ai/wpcom-tools';
@@ -723,6 +724,59 @@ const takeScreenshotTool = tool(
 	}
 );
 
+// --- Preview orchestration tools ---
+
+function normalizePreviewPath( raw: string ): string {
+	const trimmed = raw.trim();
+	if ( ! trimmed ) {
+		return '/';
+	}
+	return trimmed.startsWith( '/' ) ? trimmed : `/${ trimmed }`;
+}
+
+const previewNavigateTool = tool(
+	'preview_navigate',
+	'Point the Studio site preview iframe at a specific page on the active site and reload it. ' +
+		'Use this after you finish editing a specific page, post, or template so the user immediately ' +
+		'sees the result of your change. Pass a site-relative path (e.g. "/", "/about/", ' +
+		'"/wp-admin/post.php?post=42&action=edit"). Does nothing when the preview pane is closed or ' +
+		'when running outside the Studio desktop app.',
+	{
+		path: z
+			.string()
+			.describe(
+				'Site-relative path to show in the preview, e.g. "/", "/about/", "/?p=123". Leading slash is added if missing.'
+			),
+	},
+	async ( args ) => {
+		const path = normalizePreviewPath( args.path );
+		emitEvent( {
+			type: 'preview.command',
+			timestamp: new Date().toISOString(),
+			kind: 'navigate',
+			path,
+		} );
+		return textResult( `Preview navigated to ${ path }.` );
+	}
+);
+
+const previewReloadTool = tool(
+	'preview_reload',
+	'Reload the Studio site preview iframe at its current URL. Use this after you edit the active ' +
+		'theme, CSS, template parts, or anything that affects the page the user is currently viewing, ' +
+		'so they see the updated result immediately. Does nothing when the preview pane is closed or ' +
+		'when running outside the Studio desktop app.',
+	{},
+	async () => {
+		emitEvent( {
+			type: 'preview.command',
+			timestamp: new Date().toISOString(),
+			kind: 'reload',
+		} );
+		return textResult( 'Preview reloaded.' );
+	}
+);
+
 // --- Taxonomist scripts installer ---
 
 const TAXONOMIST_SCRIPTS_DIR = 'tmp/taxonomist';
@@ -996,6 +1050,13 @@ const exportSiteTool = tool(
 	}
 );
 
+// Tools that only make sense when a Studio desktop UI is listening on the
+// other end of the agent event stream — they steer a preview iframe that
+// doesn't exist when the CLI runs standalone. Kept separate so plain-CLI
+// runs don't see (and the agent can't call) tools that would just produce
+// noise in the terminal transcript.
+const previewSteeringToolDefinitions = [ previewNavigateTool, previewReloadTool ];
+
 export const studioToolDefinitions = [
 	createSiteTool,
 	listSitesTool,
@@ -1017,13 +1078,33 @@ export const studioToolDefinitions = [
 	pullSiteTool,
 	importSiteTool,
 	exportSiteTool,
+	...previewSteeringToolDefinitions,
 ];
 
-export function createStudioTools() {
+export interface CreateStudioToolsOptions {
+	// Enable preview_navigate / preview_reload. Only meaningful when a
+	// Studio desktop UI is subscribed to the agent event stream — i.e. the
+	// CLI child was forked by the Studio main process (`process.send` is
+	// available). Defaults to false so standalone CLI runs don't advertise
+	// tools whose side effects would vanish into the void.
+	enablePreviewSteering?: boolean;
+}
+
+export function resolveStudioToolDefinitions( options: CreateStudioToolsOptions = {} ) {
+	if ( options.enablePreviewSteering ) {
+		return studioToolDefinitions;
+	}
+	const previewSteeringNames = new Set( previewSteeringToolDefinitions.map( ( t ) => t.name ) );
+	return studioToolDefinitions.filter(
+		( candidate ) => ! previewSteeringNames.has( candidate.name )
+	);
+}
+
+export function createStudioTools( options: CreateStudioToolsOptions = {} ) {
 	return createSdkMcpServer( {
 		name: 'studio',
 		version: '1.0.0',
-		tools: studioToolDefinitions,
+		tools: resolveStudioToolDefinitions( options ),
 	} );
 }
 

apps/cli/commands/ai/index.ts

@@ -1,5 +1,6 @@
 import { listAiSessions } from '@studio/common/ai/sessions/store';
 import { type LoadedAiSession, type TurnStatus } from '@studio/common/ai/sessions/types';
+import { buildSkillInvocationPrompt } from '@studio/common/ai/slash-commands';
 import { readAuthToken } from '@studio/common/lib/shared-config';
 import { __, _n, sprintf } from '@wordpress/i18n';
 import { DEFAULT_MODEL, startAiAgent, type AiModelId, type AskUserQuestion } from 'cli/ai/agent';
@@ -659,7 +660,7 @@ export async function runCommand( options: {
 					// Skill command — no handler, route to agent
 					ui.addUserMessage( prompt );
 					try {
-						await runAgentTurn( `Run the /${ cmd.name } skill using the Skill tool.` );
+						await runAgentTurn( buildSkillInvocationPrompt( cmd.name ) );
 					} catch ( error ) {
 						handleAgentTurnError( error );
 					}

apps/studio/src/ipc-handlers.ts

@@ -27,6 +27,7 @@ import {
 	listAiSessions as listAiSessionsFromStore,
 	loadAiSession as loadAiSessionFromStore,
 } from '@studio/common/ai/sessions/store';
+import { AI_SKILL_COMMANDS, buildSkillInvocationPrompt } from '@studio/common/ai/slash-commands';
 import {
 	installSkillToSite,
 	removeSkillFromSite,
@@ -287,6 +288,22 @@ async function reconcileSessionEnvironmentBeforeRun( sessionId: string ): Promis
 	} );
 }
 
+// Expand a bare skill-command slash prompt (e.g. `/rank-me-up`) into the
+// instruction the agent actually acts on. Mirrors the CLI's interactive main
+// loop so UI clients can send the short form and get the same behaviour.
+function expandSkillCommandPrompt( prompt: string ): string {
+	const trimmed = prompt.trim();
+	if ( ! trimmed.startsWith( '/' ) ) {
+		return prompt;
+	}
+	const name = trimmed.slice( 1 );
+	const match = AI_SKILL_COMMANDS.find( ( cmd ) => cmd.name === name );
+	if ( ! match ) {
+		return prompt;
+	}
+	return buildSkillInvocationPrompt( name );
+}
+
 export async function continueAiSession(
 	event: IpcMainInvokeEvent,
 	sessionId: string,
@@ -295,7 +312,7 @@ export async function continueAiSession(
 	await reconcileSessionEnvironmentBeforeRun( sessionId );
 	return startAgentRun( {
 		sessionId,
-		prompt,
+		prompt: expandSkillCommandPrompt( prompt ),
 		webContents: event.sender,
 	} );
 }