feat: implement session step recording, history lifecycle, and WebdriverIO code generation

- Added `RecordedStep` and `SessionHistory` types for session tracking.
- Introduced `withRecording` HOF and `appendStep` for step logging.
- Extended browser and app session management to initialize and maintain session histories, including transition sentinels and lifecycle markers.
- Developed WebdriverIO JavaScript code generator from recorded steps.
- Registered MCP resources for session indexing and step inspection.
- Added corresponding tests and updated design documentation.

Author: Winify

src/recording/code-generator.ts

@@ -0,0 +1,66 @@
+// src/recording/code-generator.ts
+import type { RecordedStep, SessionHistory } from '../types/recording';
+
+/** Escape single quotes so generated JS string literals are valid. */
+function escapeStr(value: unknown): string {
+  return String(value).replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+
+function formatParams(params: Record<string, unknown>): string {
+  return Object.entries(params)
+    .map(([k, v]) => `${k}="${v}"`)
+    .join(' ');
+}
+
+function generateStep(step: RecordedStep): string {
+  if (step.tool === '__session_transition__') {
+    const newId = (step.params.newSessionId as string) ?? 'unknown';
+    return `// --- new session: ${newId} started at ${step.timestamp} ---`;
+  }
+
+  if (step.status === 'error') {
+    return `// [error] ${step.tool}: ${formatParams(step.params)} — ${step.error ?? 'unknown error'}`;
+  }
+
+  const p = step.params;
+  switch (step.tool) {
+    case 'navigate':
+      return `await browser.url('${escapeStr(p.url)}');`;
+    case 'click_element':
+      return `await $('${escapeStr(p.selector)}').click();`;
+    case 'set_value':
+      return `await $('${escapeStr(p.selector)}').setValue('${escapeStr(p.value)}');`;
+    case 'scroll': {
+      const scrollAmount = (p.direction as string) === 'down' ? (p.pixels as number) : -(p.pixels as number);
+      return `await browser.execute(() => window.scrollBy(0, ${scrollAmount}));`;
+    }
+    case 'tap_element':
+      if (p.selector !== undefined) {
+        return `await $('${escapeStr(p.selector)}').click();`;
+      }
+      return `await browser.tap({ x: ${p.x}, y: ${p.y} });`;
+    case 'swipe':
+      return `await browser.execute('mobile: swipe', { direction: '${escapeStr(p.direction)}' });`;
+    case 'drag_and_drop':
+      if (p.targetSelector !== undefined) {
+        return `await $('${escapeStr(p.sourceSelector)}').dragAndDrop($('${escapeStr(p.targetSelector)}'));`;
+      }
+      return `await $('${escapeStr(p.sourceSelector)}').dragAndDrop({ x: ${p.x}, y: ${p.y} });`;
+    default:
+      return `// [unknown tool] ${step.tool}`;
+  }
+}
+
+function buildHeader(history: SessionHistory): string {
+  const caps = JSON.stringify(history.capabilities, null, 2)
+    .split('\n')
+    .map((line) => `  ${line}`)
+    .join('\n');
+  return `import { remote } from 'webdriverio';\nconst browser = await remote(\n${caps}\n);`;
+}
+
+export function generateCode(history: SessionHistory): string {
+  const header = buildHeader(history);
+  const steps = history.steps.map(generateStep).join('\n');
+  return `${header}\n\n${steps}\n\nawait browser.deleteSession();`;
+}

src/recording/resources.ts

@@ -0,0 +1,55 @@
+// src/recording/resources.ts
+import type { SessionHistory } from '../types/recording';
+import { generateCode } from './code-generator';
+import { getSessionHistory } from './step-recorder';
+import { getBrowser } from '../tools/browser.tool';
+
+function getCurrentSessionId(): string | null {
+  return (getBrowser as any).__state?.currentSession ?? null;
+}
+
+export function buildSessionsIndex(): string {
+  const histories = getSessionHistory();
+  if (histories.size === 0) return 'No sessions recorded.';
+
+  const currentId = getCurrentSessionId();
+  const lines = [`Sessions (${histories.size} total):\n`];
+  for (const [id, h] of histories) {
+    const ended = h.endedAt ?? '-';
+    const current = id === currentId ? '  [current]' : '';
+    lines.push(`- ${id}  ${h.type}  started: ${h.startedAt}  ended: ${ended}  ${h.steps.length} steps${current}`);
+  }
+  return lines.join('\n');
+}
+
+export function buildCurrentSessionSteps(): string {
+  const currentId = getCurrentSessionId();
+  if (!currentId) return 'No active session.';
+  return buildSessionStepsById(currentId);
+}
+
+export function buildSessionStepsById(sessionId: string): string {
+  const history = getSessionHistory().get(sessionId);
+  if (!history) return `Session not found: ${sessionId}`;
+  return formatSessionSteps(history);
+}
+
+function formatSessionSteps(history: SessionHistory): string {
+  const header = `Session: ${history.sessionId} (${history.type}) — ${history.steps.length} steps\n`;
+
+  const stepLines = history.steps.map((step) => {
+    if (step.tool === '__session_transition__') {
+      return `--- session transitioned to ${step.params.newSessionId ?? 'unknown'} at ${step.timestamp} ---`;
+    }
+    const statusLabel = step.status === 'ok' ? '[ok]   ' : '[error]';
+    const params = Object.entries(step.params)
+      .map(([k, v]) => `${k}="${v}"`)
+      .join(' ');
+    const errorSuffix = step.error ? ` — ${step.error}` : '';
+    return `${step.index}. ${statusLabel}  ${step.tool.padEnd(24)} ${params}${errorSuffix}  ${step.durationMs}ms`;
+  });
+
+  const stepsText = stepLines.length > 0 ? stepLines.join('\n') : '(no steps yet)';
+  const jsCode = generateCode(history);
+  return `${header}\nSteps:\n${stepsText}\n\n--- Generated WebdriverIO JS ---\n${jsCode}`;
+}

src/recording/step-recorder.ts

@@ -0,0 +1,64 @@
+// src/recording/step-recorder.ts
+import type { ToolCallback } from '@modelcontextprotocol/sdk/server/mcp';
+import type { RecordedStep, SessionHistory } from '../types/recording';
+import { getBrowser } from '../tools/browser.tool';
+
+function getState() {
+  return (getBrowser as any).__state as {
+    currentSession: string | null;
+    sessionHistory: Map<string, SessionHistory>;
+  };
+}
+
+export function appendStep(
+  toolName: string,
+  params: Record<string, unknown>,
+  status: 'ok' | 'error',
+  durationMs: number,
+  error?: string,
+): void {
+  const state = getState();
+  const sessionId = state.currentSession;
+  if (!sessionId) return;
+
+  const history = state.sessionHistory.get(sessionId);
+  if (!history) return;
+
+  const step: RecordedStep = {
+    index: history.steps.length + 1,
+    tool: toolName,
+    params,
+    status,
+    durationMs,
+    timestamp: new Date().toISOString(),
+    ...(error !== undefined && { error }),
+  };
+  history.steps.push(step);
+}
+
+export function getSessionHistory(): Map<string, SessionHistory> {
+  return getState().sessionHistory;
+}
+
+function extractErrorText(result: Awaited<ReturnType<ToolCallback>>): string {
+  const textContent = result.content.find((c: any) => c.type === 'text');
+  return textContent ? (textContent as any).text : 'Unknown error';
+}
+
+export function withRecording(toolName: string, callback: ToolCallback): ToolCallback {
+  return async (params, extra) => {
+    const start = Date.now();
+    const result = await callback(params, extra);
+    const isError = result.content.some(
+      (c: any) => c.type === 'text' && typeof (c as any).text === 'string' && (c as any).text.startsWith('Error'),
+    );
+    appendStep(
+      toolName,
+      params as Record<string, unknown>,
+      isError ? 'error' : 'ok',
+      Date.now() - start,
+      isError ? extractErrorText(result) : undefined,
+    );
+    return result;
+  };
+}

src/server.ts

@@ -57,6 +57,9 @@ import { executeScriptTool, executeScriptToolDefinition } from './tools/execute-
 import { attachBrowserTool, attachBrowserToolDefinition } from './tools/attach-browser.tool';
 import { emulateDeviceTool, emulateDeviceToolDefinition } from './tools/emulate-device.tool';
 import pkg from '../package.json' with { type: 'json' };
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { withRecording } from './recording/step-recorder';
+import { buildSessionsIndex, buildCurrentSessionSteps, buildSessionStepsById } from './recording/resources';
 
 // IMPORTANT: Redirect all console output to stderr to avoid messing with MCP protocol (Chrome writes to console)
 const _originalConsoleLog = console.log;
@@ -79,6 +82,7 @@ const server = new McpServer({
   instructions: 'MCP server for browser and mobile app automation using WebDriverIO. Supports Chrome, Firefox, Edge, and Safari browser control plus iOS/Android native app testing via Appium.',
   capabilities: {
     tools: {},
+    resources: {},
   },
 });
 
@@ -95,18 +99,18 @@ registerTool(startAppToolDefinition, startAppTool);
 registerTool(closeSessionToolDefinition, closeSessionTool);
 registerTool(attachBrowserToolDefinition, attachBrowserTool);
 registerTool(emulateDeviceToolDefinition, emulateDeviceTool);
-registerTool(navigateToolDefinition, navigateTool);
+registerTool(navigateToolDefinition, withRecording('navigate', navigateTool));
 
 // Element Discovery
 registerTool(getVisibleElementsToolDefinition, getVisibleElementsTool);
 registerTool(getAccessibilityToolDefinition, getAccessibilityTreeTool);
 
 // Scrolling
-registerTool(scrollToolDefinition, scrollTool);
+registerTool(scrollToolDefinition, withRecording('scroll', scrollTool));
 
 // Element Interaction
-registerTool(clickToolDefinition, clickTool);
-registerTool(setValueToolDefinition, setValueTool);
+registerTool(clickToolDefinition, withRecording('click_element', clickTool));
+registerTool(setValueToolDefinition, withRecording('set_value', setValueTool));
 
 // Screenshots
 registerTool(takeScreenshotToolDefinition, takeScreenshotTool);
@@ -117,9 +121,9 @@ registerTool(setCookieToolDefinition, setCookieTool);
 registerTool(deleteCookiesToolDefinition, deleteCookiesTool);
 
 // Mobile Gesture Tools
-registerTool(tapElementToolDefinition, tapElementTool);
-registerTool(swipeToolDefinition, swipeTool);
-registerTool(dragAndDropToolDefinition, dragAndDropTool);
+registerTool(tapElementToolDefinition, withRecording('tap_element', tapElementTool));
+registerTool(swipeToolDefinition, withRecording('swipe', swipeTool));
+registerTool(dragAndDropToolDefinition, withRecording('drag_and_drop', dragAndDropTool));
 
 // App Lifecycle Management
 registerTool(getAppStateToolDefinition, getAppStateTool);
@@ -138,6 +142,38 @@ registerTool(setGeolocationToolDefinition, setGeolocationTool);
 // Script Execution (Browser JS / Appium Mobile Commands)
 registerTool(executeScriptToolDefinition, executeScriptTool);
 
+// Session Recording Resources
+server.registerResource(
+  'sessions',
+  'wdio://sessions',
+  { description: 'Index of all browser and app sessions with step counts' },
+  async () => ({
+    contents: [{ uri: 'wdio://sessions', mimeType: 'text/plain', text: buildSessionsIndex() }],
+  }),
+);
+
+server.registerResource(
+  'session-current-steps',
+  'wdio://session/current/steps',
+  { description: 'Steps for the currently active session with generated WebdriverIO JS' },
+  async () => ({
+    contents: [{ uri: 'wdio://session/current/steps', mimeType: 'text/plain', text: buildCurrentSessionSteps() }],
+  }),
+);
+
+server.registerResource(
+  'session-steps',
+  new ResourceTemplate('wdio://session/{sessionId}/steps', { list: undefined }),
+  { description: 'Steps for a specific session by ID with generated WebdriverIO JS' },
+  async (uri, { sessionId }) => ({
+    contents: [{
+      uri: uri.href,
+      mimeType: 'text/plain',
+      text: buildSessionStepsById(sessionId as string),
+    }],
+  }),
+);
+
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);

src/tools/app-session.tool.ts

@@ -2,6 +2,7 @@ import { remote } from 'webdriverio';
 import type { ToolCallback } from '@modelcontextprotocol/sdk/server/mcp';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types';
 import type { ToolDefinition } from '../types/tool';
+import type { SessionHistory } from '../types/recording';
 import { z } from 'zod';
 import { buildAndroidCapabilities, buildIOSCapabilities, getAppiumServerConfig, } from '../config/appium.config';
 import { getBrowser } from './browser.tool';
@@ -43,6 +44,7 @@ export const getState = () => {
     browsers: Map<string, WebdriverIO.Browser>;
     currentSession: string | null;
     sessionMetadata: Map<string, { type: 'browser' | 'ios' | 'android'; capabilities: any; isAttached: boolean }>;
+    sessionHistory: Map<string, SessionHistory>;
   };
 };
 
@@ -156,13 +158,38 @@ export const startAppTool: ToolCallback = async (args: {
     const shouldAutoDetach = noReset === true || !appPath;
     const state = getState();
     state.browsers.set(sessionId, browser);
-    state.currentSession = sessionId;
     state.sessionMetadata.set(sessionId, {
       type: platform.toLowerCase() as 'ios' | 'android',
       capabilities: mergedCapabilities,
       isAttached: shouldAutoDetach,
     });
 
+    // If replacing an active session, close its history with transition sentinel
+    if (state.currentSession && state.currentSession !== sessionId) {
+      const outgoing = state.sessionHistory.get(state.currentSession);
+      if (outgoing) {
+        outgoing.steps.push({
+          index: outgoing.steps.length + 1,
+          tool: '__session_transition__',
+          params: { newSessionId: sessionId },
+          status: 'ok',
+          durationMs: 0,
+          timestamp: new Date().toISOString(),
+        });
+        outgoing.endedAt = new Date().toISOString();
+      }
+    }
+
+    state.sessionHistory.set(sessionId, {
+      sessionId,
+      type: platform.toLowerCase() as 'ios' | 'android',
+      startedAt: new Date().toISOString(),
+      capabilities: mergedCapabilities as Record<string, unknown>,
+      steps: [],
+    });
+
+    state.currentSession = sessionId;
+
     const appInfo = appPath ? `\nApp: ${appPath}` : '\nApp: (connected to running app)';
     const detachNote = shouldAutoDetach
       ? '\n\n(Auto-detach enabled: session will be preserved on close. Use close_session({ detach: false }) to force terminate.)'