Merge PR #1: Response Filtering Foundation

Implements the foundation for response filtering with expectation parameters.
This enables selective response content to reduce token consumption.

Author: Tomohiko Hiraki

src/response.ts

@@ -15,10 +15,12 @@
  */
 
 import { renderModalStates } from './tab.js';
+import { mergeExpectations } from './schemas/expectation.js';
 
 import type { Tab, TabSnapshot } from './tab.js';
 import type { ImageContent, TextContent } from '@modelcontextprotocol/sdk/types.js';
 import type { Context } from './context.js';
+import type { ExpectationOptions } from './schemas/expectation.js';
 
 export class Response {
   private _result: string[] = [];
@@ -28,15 +30,17 @@ export class Response {
   private _includeSnapshot = false;
   private _includeTabs = false;
   private _tabSnapshot: TabSnapshot | undefined;
+  private _expectation: NonNullable<ExpectationOptions>;
 
   readonly toolName: string;
   readonly toolArgs: Record<string, any>;
   private _isError: boolean | undefined;
 
-  constructor(context: Context, toolName: string, toolArgs: Record<string, any>) {
+  constructor(context: Context, toolName: string, toolArgs: Record<string, any>, expectation?: ExpectationOptions) {
     this._context = context;
     this.toolName = toolName;
     this.toolArgs = toolArgs;
+    this._expectation = mergeExpectations(toolName, expectation);
   }
 
   addResult(result: string) {
@@ -83,8 +87,16 @@ export class Response {
   async finish() {
     // All the async snapshotting post-action is happening here.
     // Everything below should race against modal states.
-    if (this._includeSnapshot && this._context.currentTab())
-      this._tabSnapshot = await this._context.currentTabOrDie().captureSnapshot();
+    if ((this._includeSnapshot || this._expectation.includeSnapshot) && this._context.currentTab()) {
+      const options = this._expectation.snapshotOptions;
+      if (options?.selector) {
+        // TODO: Implement partial snapshot capture based on selector
+        // For now, capture full snapshot
+        this._tabSnapshot = await this._context.currentTabOrDie().captureSnapshot();
+      } else {
+        this._tabSnapshot = await this._context.currentTabOrDie().captureSnapshot();
+      }
+    }
     for (const tab of this._context.tabs())
       await tab.updateTitle();
   }
@@ -103,25 +115,28 @@ export class Response {
       response.push('');
     }
 
-    // Add code if it exists.
-    if (this._code.length) {
+    // Add code if it exists and expectation allows it.
+    if (this._code.length && this._expectation.includeCode) {
       response.push(`### Ran Playwright code
 \`\`\`js
 ${this._code.join('\n')}
 \`\`\``);
       response.push('');
     }
 
-    // List browser tabs.
-    if (this._includeSnapshot || this._includeTabs)
-      response.push(...renderTabsMarkdown(this._context.tabs(), this._includeTabs));
+    // List browser tabs based on expectation.
+    const shouldIncludeTabs = this._expectation.includeTabs || this._includeTabs;
+    const shouldIncludeSnapshot = this._expectation.includeSnapshot || this._includeSnapshot;
+    
+    if (shouldIncludeSnapshot || shouldIncludeTabs)
+      response.push(...renderTabsMarkdown(this._context.tabs(), shouldIncludeTabs));
 
-    // Add snapshot if provided.
-    if (this._tabSnapshot?.modalStates.length) {
+    // Add snapshot if provided and expectation allows it.
+    if (shouldIncludeSnapshot && this._tabSnapshot?.modalStates.length) {
       response.push(...renderModalStates(this._context, this._tabSnapshot.modalStates));
       response.push('');
-    } else if (this._tabSnapshot) {
-      response.push(renderTabSnapshot(this._tabSnapshot));
+    } else if (shouldIncludeSnapshot && this._tabSnapshot) {
+      response.push(this.renderFilteredTabSnapshot(this._tabSnapshot));
       response.push('');
     }
 
@@ -138,6 +153,73 @@ ${this._code.join('\n')}
 
     return { content, isError: this._isError };
   }
+
+  private renderFilteredTabSnapshot(tabSnapshot: TabSnapshot): string {
+    const lines: string[] = [];
+    const consoleOptions = this._expectation.consoleOptions;
+
+    // Include console messages based on expectation
+    if (this._expectation.includeConsole && tabSnapshot.consoleMessages.length) {
+      const filteredMessages = this.filterConsoleMessages(tabSnapshot.consoleMessages, consoleOptions);
+      if (filteredMessages.length) {
+        lines.push(`### New console messages`);
+        for (const message of filteredMessages)
+          lines.push(`- ${trim(message.toString(), 100)}`);
+        lines.push('');
+      }
+    }
+
+    // Include downloads based on expectation
+    if (this._expectation.includeDownloads && tabSnapshot.downloads.length) {
+      lines.push(`### Downloads`);
+      for (const entry of tabSnapshot.downloads) {
+        if (entry.finished)
+          lines.push(`- Downloaded file ${entry.download.suggestedFilename()} to ${entry.outputFile}`);
+        else
+          lines.push(`- Downloading file ${entry.download.suggestedFilename()} ...`);
+      }
+      lines.push('');
+    }
+
+    lines.push(`### Page state`);
+    lines.push(`- Page URL: ${tabSnapshot.url}`);
+    lines.push(`- Page Title: ${tabSnapshot.title}`);
+    lines.push(`- Page Snapshot:`);
+    lines.push('```yaml');
+    
+    // Apply snapshot format and length restrictions
+    let snapshot = tabSnapshot.ariaSnapshot;
+    const snapshotOptions = this._expectation.snapshotOptions;
+    
+    if (snapshotOptions?.maxLength && snapshot.length > snapshotOptions.maxLength) {
+      snapshot = snapshot.slice(0, snapshotOptions.maxLength) + '...';
+    }
+    
+    lines.push(snapshot);
+    lines.push('```');
+
+    return lines.join('\n');
+  }
+
+  private filterConsoleMessages(messages: any[], options?: NonNullable<ExpectationOptions>['consoleOptions']): any[] {
+    let filtered = messages;
+    
+    // Filter by levels if specified
+    if (options?.levels && options.levels.length > 0) {
+      filtered = filtered.filter(msg => {
+        const level = msg.type || 'log';
+        return options.levels!.includes(level);
+      });
+    }
+    
+    // Limit number of messages
+    const maxMessages = options?.maxMessages ?? 10;
+    if (filtered.length > maxMessages) {
+      filtered = filtered.slice(0, maxMessages);
+    }
+    
+    return filtered;
+  }
 }
 
 function renderTabSnapshot(tabSnapshot: TabSnapshot): string {

src/schemas/expectation.ts

@@ -0,0 +1,152 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { z } from 'zod';
+
+/**
+ * Schema for expectation configuration that controls response content
+ */
+export const expectationSchema = z.object({
+  includeSnapshot: z.boolean().optional().default(true),
+  includeConsole: z.boolean().optional().default(true),
+  includeDownloads: z.boolean().optional().default(true),
+  includeTabs: z.boolean().optional().default(true),
+  includeCode: z.boolean().optional().default(true),
+  snapshotOptions: z.object({
+    selector: z.string().optional().describe('CSS selector to limit snapshot scope'),
+    maxLength: z.number().optional().describe('Maximum characters for snapshot'),
+    format: z.enum(['aria', 'text', 'html']).optional().default('aria')
+  }).optional(),
+  consoleOptions: z.object({
+    levels: z.array(z.enum(['log', 'warn', 'error', 'info'])).optional(),
+    maxMessages: z.number().optional().default(10)
+  }).optional(),
+  imageOptions: z.object({
+    quality: z.number().min(1).max(100).optional().describe('JPEG quality (1-100)'),
+    maxWidth: z.number().optional().describe('Maximum width in pixels'),
+    maxHeight: z.number().optional().describe('Maximum height in pixels'),
+    format: z.enum(['jpeg', 'png', 'webp']).optional()
+  }).optional()
+}).optional();
+
+export type ExpectationOptions = z.infer<typeof expectationSchema>;
+
+/**
+ * Tool-specific default expectation configurations
+ * These optimize token usage based on typical tool usage patterns
+ */
+const TOOL_DEFAULTS: Record<string, Required<Omit<NonNullable<ExpectationOptions>, 'snapshotOptions' | 'consoleOptions' | 'imageOptions'>>> = {
+  // Navigation tools need full context for verification
+  navigate: {
+    includeSnapshot: true,
+    includeConsole: true,
+    includeDownloads: true,
+    includeTabs: true,
+    includeCode: true
+  },
+  
+  // Interactive tools need snapshot for feedback but less verbose logging
+  click: {
+    includeSnapshot: true,
+    includeConsole: false,
+    includeDownloads: false,
+    includeTabs: false,
+    includeCode: true
+  },
+  
+  fill: {
+    includeSnapshot: true,
+    includeConsole: false,
+    includeDownloads: false,
+    includeTabs: false,
+    includeCode: true
+  },
+  
+  // Screenshot tools don't need additional context
+  screenshot: {
+    includeSnapshot: false,
+    includeConsole: false,
+    includeDownloads: false,
+    includeTabs: false,
+    includeCode: false
+  },
+  
+  // Code evaluation needs console output but minimal other info
+  evaluate: {
+    includeSnapshot: false,
+    includeConsole: true,
+    includeDownloads: false,
+    includeTabs: false,
+    includeCode: true
+  },
+  
+  // Wait operations typically don't need verbose output
+  wait: {
+    includeSnapshot: false,
+    includeConsole: false,
+    includeDownloads: false,
+    includeTabs: false,
+    includeCode: true
+  }
+};
+
+/**
+ * General default configuration for tools without specific settings
+ */
+const GENERAL_DEFAULT: Required<Omit<NonNullable<ExpectationOptions>, 'snapshotOptions' | 'consoleOptions' | 'imageOptions'>> = {
+  includeSnapshot: true,
+  includeConsole: true,
+  includeDownloads: true,
+  includeTabs: true,
+  includeCode: true
+};
+
+/**
+ * Get default expectation configuration for a specific tool
+ * @param toolName - Name of the tool (e.g., 'click', 'navigate', 'screenshot')
+ * @returns Default expectation configuration optimized for the tool
+ */
+export function getDefaultExpectation(toolName: string): Required<Omit<NonNullable<ExpectationOptions>, 'snapshotOptions' | 'consoleOptions' | 'imageOptions'>> {
+  return TOOL_DEFAULTS[toolName] || GENERAL_DEFAULT;
+}
+
+/**
+ * Merge user-provided expectation with tool-specific defaults
+ * @param toolName - Name of the tool
+ * @param userExpectation - User-provided expectation options
+ * @returns Merged expectation configuration
+ */
+export function mergeExpectations(
+  toolName: string, 
+  userExpectation?: ExpectationOptions
+): NonNullable<ExpectationOptions> {
+  const defaults = getDefaultExpectation(toolName);
+  
+  if (!userExpectation) {
+    return defaults;
+  }
+  
+  return {
+    includeSnapshot: userExpectation.includeSnapshot ?? defaults.includeSnapshot,
+    includeConsole: userExpectation.includeConsole ?? defaults.includeConsole,
+    includeDownloads: userExpectation.includeDownloads ?? defaults.includeDownloads,
+    includeTabs: userExpectation.includeTabs ?? defaults.includeTabs,
+    includeCode: userExpectation.includeCode ?? defaults.includeCode,
+    snapshotOptions: userExpectation.snapshotOptions,
+    consoleOptions: userExpectation.consoleOptions,
+    imageOptions: userExpectation.imageOptions
+  };
+}