codeceptjs 4.0.0-rc.18 → 4.0.0-rc.19

package/bin/mcp-server.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import { Server } from '@modelcontextprotocol/sdk/server/index.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'
@@ -17,6 +18,11 @@ import {
 } from '../lib/utils/trace.js'
 import event from '../lib/event.js'
 import recorder from '../lib/recorder.js'
+import WebElement from '../lib/element/WebElement.js'
+import { locate, within, session, secret, inject, pause } from '../lib/index.js'
+import { tryTo, retryTo, hopeThat } from '../lib/effects.js'
+import step from '../lib/steps.js'
+import { element, eachElement, expectElement, expectAnyElement, expectAllElements } from '../lib/els.js'
 import { setPauseHandler, pauseNow } from '../lib/pause.js'
 import { EventEmitter } from 'events'
 import { fileURLToPath, pathToFileURL } from 'url'
@@ -39,6 +45,7 @@ let shellSessionActive = false
 let bootstrapDone = false
 let currentPluginsSig = ''
 let currentAiTraceDir = null  // mirrors the dir aiTrace plugin computes per test/session
+let aiTraceEnabled = false  // tracked across the session so tool responses can surface a hint when off
 
 event.dispatcher.on(event.test.before, test => {
   try {
@@ -47,7 +54,27 @@ event.dispatcher.on(event.test.before, test => {
   } catch {}
 })
 
-const SESSION_REQUIRED_ERROR = 'No active CodeceptJS session. Call `start_browser` to open a shell session, or `run_test` (use `pause()` in the test, or set `pauseAt`) to inspect during a test run.'
+function aiTraceHint() {
+  if (aiTraceEnabled) return undefined
+  return 'aiTrace plugin is disabled — re-run start_browser with plugins={ aiTrace: { enabled: true } } to capture per-step DOM/ARIA/console traces for debugging.'
+}
+
+function applyMochaGrep(grep) {
+  if (!grep) return
+  const mocha = typeof container.mocha === 'function' ? container.mocha() : container.mocha
+  if (mocha && typeof mocha.grep === 'function') mocha.grep(grep)
+}
+
+function pauseAtMatcher(pauseAt) {
+  if (pauseAt == null) return () => false
+  if (typeof pauseAt === 'number') return (idx) => idx === pauseAt
+  if (typeof pauseAt === 'string') {
+    const m = pauseAt.match(/^\/(.+)\/([gimsuy]*)$/)
+    const re = m ? new RegExp(m[1], m[2]) : new RegExp(pauseAt.replace(/[.+?^${}()|[\]\\]/g, '\\$&'), 'i')
+    return (_idx, name) => re.test(name)
+  }
+  return () => false
+}
 
 async function ensureBootstrap() {
   if (bootstrapDone) return
@@ -80,9 +107,9 @@ async function endShellSession() {
   shellSessionActive = false
 }
 
-function ensureSession() {
+async function ensureSession() {
   if (shellSessionActive || pausedController) return
-  throw new Error(SESSION_REQUIRED_ERROR)
+  await startShellSession()
 }
 
 function normalizePluginOverrides(plugins) {
@@ -109,18 +136,33 @@ function pluginsSignature(plugins) {
 
 async function teardownContainer() {
   if (!containerInitialized) return
-  await endShellSession()
-  const helpers = container.helpers()
-  for (const helperName in helpers) {
-    const helper = helpers[helperName]
-    try { if (helper._finish) await helper._finish() } catch {}
+  try {
+    await closeBrowser()
+    try { if (codecept?.teardown) await codecept.teardown() } catch {}
+  } finally {
+    containerInitialized = false
+    browserStarted = false
+    bootstrapDone = false
+    aiTraceEnabled = false
+    codecept = null
+    currentPluginsSig = ''
   }
-  try { if (codecept?.teardown) await codecept.teardown() } catch {}
-  containerInitialized = false
-  browserStarted = false
-  bootstrapDone = false
-  codecept = null
-  currentPluginsSig = ''
+}
+
+let shutdownStarted = false
+function installShutdownHooks() {
+  const onSignal = (signal) => {
+    if (shutdownStarted) return
+    shutdownStarted = true
+    teardownContainer().finally(() => process.exit(signal === 'SIGINT' ? 130 : 0))
+  }
+  process.on('SIGTERM', () => onSignal('SIGTERM'))
+  process.on('SIGINT', () => onSignal('SIGINT'))
+  process.on('beforeExit', () => {
+    if (shutdownStarted) return
+    shutdownStarted = true
+    teardownContainer().catch(() => {})
+  })
 }
 
 let runLock = Promise.resolve()
@@ -331,15 +373,17 @@ function outputBaseDir() {
 // pause(), the handler registered via setPauseHandler resolves a "paused"
 // promise that run_test is racing against test completion. The "pause" tool
 // then drives the REPL by mutating next/abort and resolving the controller.
-let pausedController = null   // { resolveContinue, registeredVariables }
-let pendingRunPromise = null  // run_test's run() promise while paused
-let pendingRunResults = null  // results array being collected while paused
-let pendingRunCleanup = null  // cleanup callback to detach test.after / step.after listeners
-let pendingTestFile = null    // file path of the test currently running
-let pendingStepInfo = null    // { index, name, status } of the last step that fired step.after
+let pausedController = null
+let pendingRunPromise = null
+let pendingRunResults = null
+let pendingRunCleanup = null
+let pendingTestFile = null
+let pendingStepInfo = null
+let abortRun = false
 const pauseEvents = new EventEmitter()
 
 setPauseHandler(({ registeredVariables }) => {
+  if (abortRun) return Promise.reject(new Error('MCP session aborted'))
   return new Promise(resolve => {
     pausedController = {
       registeredVariables,
@@ -352,6 +396,33 @@ setPauseHandler(({ registeredVariables }) => {
   })
 })
 
+async function cancelRun() {
+  if (!pendingRunPromise && !pausedController) return false
+  abortRun = true
+  if (typeof pendingRunCleanup === 'function') { try { pendingRunCleanup() } catch {} }
+  if (pausedController) { try { pausedController.resolveContinue() } catch {} ; pausedController = null }
+  if (pendingRunPromise) {
+    try { await Promise.race([pendingRunPromise.catch(() => {}), new Promise(r => setTimeout(r, 5000))]) } catch {}
+  }
+  pendingRunPromise = null
+  pendingRunResults = null
+  pendingTestFile = null
+  pendingStepInfo = null
+  abortRun = false
+  return true
+}
+
+async function closeBrowser() {
+  if (!containerInitialized) return
+  await cancelRun()
+  await endShellSession()
+  for (const helper of Object.values(container.helpers() || {})) {
+    try { if (helper._cleanup) await helper._cleanup() } catch {}
+    try { if (helper._finishTest) await helper._finishTest() } catch {}
+  }
+  browserStarted = false
+}
+
 async function captureLiveArtifacts(prefix = 'pause') {
   const helper = pickActingHelper(container.helpers())
   if (!helper) return {}
@@ -388,10 +459,16 @@ function collectRunCompletion(errorMessage) {
   pendingRunResults = null
   pendingTestFile = null
   pendingStepInfo = null
+  let error = errorMessage || null
+  if (!error && results.length === 0) {
+    error = 'No tests ran and no error was reported. The Mocha instance may have been disposed (set mocha.cleanReferencesAfterRun=false in config) or the test file matched no scenarios.'
+  }
   return {
-    status: 'completed',
+    status: error ? 'failed' : 'completed',
+    aiTraceDir: currentAiTraceDir,
     reporterJson: { stats, tests: results },
-    error: errorMessage,
+    error,
+    aiTraceHint: aiTraceHint(),
   }
 }
 
@@ -399,11 +476,13 @@ function pausedPayload() {
   return {
     status: 'paused',
     file: pendingTestFile,
+    aiTraceDir: currentAiTraceDir,
     pausedAfter: pendingStepInfo,
     suggestions: [
       'Call snapshot to capture URL/HTML/ARIA/screenshot/console/storage at this point',
       'Call run_code to inspect or manipulate state (e.g. return await I.grabText("h1"))',
       'Call continue to release the pause and let the test run the next step (or finish)',
+      'Query a saved step snapshot offline: codeceptq <locator> --file <aiTraceDir>/<NNNN>_<step>_page.html',
     ],
   }
 }
@@ -443,98 +522,133 @@ async function initCodecept(configPath, pluginOverrides) {
   // aiTrace is the canonical per-step ARIA/HTML/screenshot capture for MCP.
   // Always on so run_code / continue can read the latest snapshot from disk
   // instead of double-capturing through grabAriaSnapshot etc.
-  applyPluginOverrides(config, { aiTrace: {}, ...plugins })
+  applyPluginOverrides(config, { aiTrace: { on: 'step' }, browser: { show: false }, ...plugins })
 
   codecept = new Codecept(config, {})
   await codecept.init(testRoot)
-  await container.create(config, {})
   await container.started()
 
   containerInitialized = true
   browserStarted = true
+  aiTraceEnabled = config.plugins?.aiTrace?.enabled === true
   currentPluginsSig = sig
 }
 
-const PLUGINS_DESCRIPTION = 'Enable CodeceptJS plugins for this run, mirroring the CLI `-p` flag. Keys are plugin names (e.g. screencast, aiTrace, pause, pageInfo, heal, retryFailedStep, screenshotOnFail, autoDelay). Value `true` or `{}` enables with defaults; an object merges options, e.g. {"screencast": {"saveScreenshots": true}, "aiTrace": {"on": "fail"}}. Changing the plugin set tears down and re-initializes the container (closes the browser).'
+async function formatReturnValue(value) {
+  if (value instanceof WebElement) return await value.describe()
+  if (Array.isArray(value) && value.length && value.every(v => v instanceof WebElement)) {
+    return await Promise.all(value.map(v => v.describe()))
+  }
+  return value
+}
 
 const server = new Server(
   { name: 'codeceptjs-mcp-server', version: '1.0.0' },
   { capabilities: { tools: {} } }
 )
 
+const PLUGINS_PROP = {
+  type: 'object',
+  description: 'Plugin configs to enable for this session, keyed by plugin name. Same shape as `plugins` in codecept.conf.js — each value is the plugin\'s config object (`enabled: true` is added automatically). Common entries:\n' +
+    '  • { browser: { show: true } } — visible browser (headed)\n' +
+    '  • { browser: { show: false } } — headless\n' +
+    '  • { browser: { browser: "firefox", windowSize: "1280x720" } } — switch browser + viewport\n' +
+    '  • { pause: { on: "fail" } } / { screenshot: { on: "step" } } / { aiTrace: {} }\n' +
+    'Override or add to whatever the project config already enables.',
+  additionalProperties: { type: 'object' },
+}
+
+const CONFIG_PROP = {
+  type: 'string',
+  description: 'Path to codecept.conf.js (or .cjs). Defaults to $CODECEPTJS_CONFIG, then ./codecept.conf.js in $CODECEPTJS_PROJECT_DIR or cwd. Only needed for projects with a non-standard config location.',
+}
+
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: [
     {
       name: 'list_tests',
-      description: 'List all tests in the CodeceptJS project',
-      inputSchema: { type: 'object', properties: { config: { type: 'string' } } },
+      description: 'List all tests in the CodeceptJS project. Uses the active session if start_browser was called, otherwise auto-inits with project defaults.',
+      inputSchema: { type: 'object', properties: {} },
     },
     {
       name: 'list_actions',
-      description: 'List all available CodeceptJS actions (I.* methods)',
-      inputSchema: { type: 'object', properties: { config: { type: 'string' } } },
+      description: 'List all available CodeceptJS actions (I.* methods). Uses the active session if start_browser was called, otherwise auto-inits with project defaults.',
+      inputSchema: { type: 'object', properties: {} },
     },
     {
       name: 'run_code',
-      description: 'Run arbitrary CodeceptJS code.',
+      description: 'Run arbitrary CodeceptJS code. Response includes `availableObjects` listing every symbol in scope (I, helpers, container, step, tryTo, within, etc.).',
       inputSchema: {
         type: 'object',
         properties: {
           code: { type: 'string' },
           timeout: { type: 'number' },
-          config: { type: 'string' },
           saveArtifacts: { type: 'boolean' },
+          settleMs: { type: 'number', description: 'Wait N ms after the code finishes before capturing artifacts. Default 300. Set higher (1000+) when actions trigger slow re-renders, or 0 to skip.' },
         },
         required: ['code'],
       },
     },
     {
       name: 'run_test',
-      description: 'Run a specific test. If the test calls pause() — or if pauseAt is set and reached — returns early with status "paused" so the agent can inspect via run_code and release with continue. Otherwise returns the json reporter result on completion. To learn step indices for pauseAt, run "list" with --steps or call run_step_by_step first.',
+      description: 'Run a specific test. Returns reporter JSON with one entry per scenario; each entry has a `traceFile` (file:// URL) pointing to the aiTrace markdown for that scenario — Read it on failures to see the failing step\'s DOM/ARIA/screenshot. If aiTrace is disabled the response includes an `aiTraceHint`. If the test calls pause() — or if pauseAt is set and reached — returns early with status "paused" so the agent can inspect via run_code and release with continue. To learn step indices for pauseAt, call run_step_by_step first. Auto-inits with project defaults if no session is active — call start_browser first to customize launch (e.g. plugins={ browser: { show: true } } to watch the run).',
       inputSchema: {
         type: 'object',
         properties: {
           test: { type: 'string' },
           timeout: { type: 'number' },
-          config: { type: 'string' },
-          pauseAt: { type: 'number', description: '1-based step index. Test will pause after the Nth step completes. Useful as a programmatic breakpoint without editing the test.' },
-          plugins: { type: 'object', description: PLUGINS_DESCRIPTION, additionalProperties: true },
+          grep: { type: 'string', description: 'Filter scenarios by title (passed to mocha.grep). Mirrors --grep on the CLI.' },
+          pauseAt: {
+            description: 'Programmatic breakpoint. Either a 1-based step index (number) or a step-name match (string — substring case-insensitive, or `/regex/i` literal). Examples: 5 / "fill field" / "/grab.*url/i".',
+            oneOf: [{ type: 'number' }, { type: 'string' }],
+          },
+          plugins: PLUGINS_PROP,
         },
         required: ['test'],
       },
     },
     {
       name: 'run_step_by_step',
-      description: 'Run a test interactively, pausing after every step. Returns paused payload after the first step (URL/title/contentSize, last step info, suggestions). Call continue to advance one step (and re-pause), or run_code/snapshot to inspect state. The test runs to completion when no more steps remain.',
+      description: 'Run a test interactively, pausing after every step. Returns paused payload after the first step (URL/title/contentSize, last step info, suggestions). Call continue to advance one step (and re-pause), or run_code/snapshot to inspect state. On completion each scenario in `reporterJson.tests[]` has a `traceFile` (file:// URL) for the per-step aiTrace markdown — Read it for the full execution log. Much more useful when start_browser was called with plugins={ browser: { show: true } } so you can watch what happens between pauses.',
       inputSchema: {
         type: 'object',
         properties: {
           test: { type: 'string' },
           timeout: { type: 'number' },
-          config: { type: 'string' },
-          plugins: { type: 'object', description: PLUGINS_DESCRIPTION, additionalProperties: true },
+          grep: { type: 'string', description: 'Filter scenarios by title (passed to mocha.grep). Mirrors --grep on the CLI.' },
+          plugins: PLUGINS_PROP,
         },
         required: ['test'],
       },
     },
     {
       name: 'start_browser',
-      description: 'Start the browser session.',
-      inputSchema: { type: 'object', properties: { config: { type: 'string' } } },
+      description: 'Start the session — initializes the codeceptjs container, loads helpers, and applies any plugin overrides. This is the only tool that customizes initialization; every other tool either uses the active session or auto-inits with project defaults.\n\n' +
+        'MCP enforces two plugin defaults so the agent gets useful telemetry:\n' +
+        '  • aiTrace: { on: "step", enabled: true } — per-step DOM/ARIA/console/screenshot traces for debugging\n' +
+        '  • browser: { show: false, enabled: true } — headless by default\n' +
+        'Both can be overridden via the `plugins` arg. To watch the run live: plugins={ browser: { show: true } }. To skip per-step trace overhead on a re-run: plugins={ aiTrace: { enabled: false } } (or { on: "fail" } to only capture failures). To switch config or plugins mid-session, call stop_browser first.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          config: CONFIG_PROP,
+          plugins: PLUGINS_PROP,
+        },
+      },
     },
     {
       name: 'stop_browser',
-      description: 'Stop the browser session.',
+      description: 'Stop the session, close browsers, and tear down the container. Required before re-initing with different config or plugins.',
       inputSchema: { type: 'object', properties: {} },
     },
     {
       name: 'snapshot',
-      description: 'Capture current browser state (HTML, ARIA, screenshot, console, URL) without performing any action.',
+      description: 'Capture current browser state (HTML, ARIA, screenshot, console, URL) without performing any action. Returns `traceFile` (file:// URL) to a markdown trace bundling the captured artifacts — Read it for full context. Auto-inits with project defaults if no session is active.',
       inputSchema: {
         type: 'object',
         properties: {
-          config: { type: 'string' },
           fullPage: { type: 'boolean' },
+          settleMs: { type: 'number', description: 'Wait N ms before capturing. Default 300. Set higher when the previous action is still re-rendering, or 0 to skip.' },
         },
       },
     },
@@ -548,6 +662,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
       },
     },
+    {
+      name: 'cancel',
+      description: 'Abort the currently paused or in-progress test run without closing the browser. Use when you want to bail out of a paused test and start something else without going through stop_browser/start_browser. The browser session and Mocha state stay alive.',
+      inputSchema: { type: 'object', properties: {} },
+    },
   ],
 }))
 
@@ -557,8 +676,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   try {
     switch (name) {
       case 'list_tests': {
-        const configPath = args?.config
-        await initCodecept(configPath)
+        await initCodecept()
 
         codecept.loadTests()
         const tests = codecept.testFiles.map(testFile => {
@@ -573,8 +691,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case 'list_actions': {
-        const configPath = args?.config
-        await initCodecept(configPath)
+        await initCodecept()
 
         const helpers = container.helpers()
         const supportI = container.support('I')
@@ -602,27 +719,33 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case 'start_browser': {
-        const configPath = args?.config
+        const { config: configPath, plugins } = args || {}
         if (browserStarted && shellSessionActive) {
-          return { content: [{ type: 'text', text: JSON.stringify({ status: 'Session already active' }, null, 2) }] }
+          return { content: [{ type: 'text', text: JSON.stringify({ status: 'Session already active', plugins: plugins ?? null }, null, 2) }] }
+        }
+        await initCodecept(configPath, plugins)
+        if (containerInitialized && !browserStarted) {
+          for (const helper of Object.values(container.helpers() || {})) {
+            try { if (helper._beforeSuite) await helper._beforeSuite() } catch {}
+          }
+          browserStarted = true
         }
-        await initCodecept(configPath)
         await startShellSession()
-        return { content: [{ type: 'text', text: JSON.stringify({ status: 'Session started — run_code and snapshot are now available' }, null, 2) }] }
+        return { content: [{ type: 'text', text: JSON.stringify({ status: 'Session started — run_code and snapshot are now available', plugins: plugins ?? null }, null, 2) }] }
       }
 
       case 'stop_browser': {
         if (!containerInitialized) {
           return { content: [{ type: 'text', text: JSON.stringify({ status: 'Browser not initialized' }, null, 2) }] }
         }
-        await teardownContainer()
-        return { content: [{ type: 'text', text: JSON.stringify({ status: 'Browser stopped successfully' }, null, 2) }] }
+        await closeBrowser()
+        return { content: [{ type: 'text', text: JSON.stringify({ status: 'Browser stopped — Mocha and config preserved; call start_browser to reopen' }, null, 2) }] }
       }
 
       case 'snapshot': {
-        const { config: configPath, fullPage = false } = args || {}
-        await initCodecept(configPath)
-        ensureSession()
+        const { fullPage = false, settleMs = 300 } = args || {}
+        await initCodecept()
+        await ensureSession()
 
         const helper = pickActingHelper(container.helpers())
         if (!helper) throw new Error('No supported acting helper available (Playwright, Puppeteer, WebDriver).')
@@ -630,6 +753,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const dir = snapshotDirFor(outputBaseDir())
         mkdirp.sync(dir)
 
+        if (settleMs > 0) await new Promise(r => setTimeout(r, settleMs))
         const captured = await captureSnapshot(helper, { dir, prefix: 'snapshot', fullPage })
         const traceFile = writeTraceMarkdown({
           dir,
@@ -648,6 +772,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
               dir,
               traceFile: pathToFileURL(traceFile).href,
               artifacts: artifactsToFileUrls(captured, dir),
+              aiTraceHint: aiTraceHint(),
             }, null, 2),
           }],
         }
@@ -684,21 +809,32 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         })
       }
 
+      case 'cancel': {
+        const cancelled = await cancelRun()
+        await ensureSession()
+        return { content: [{ type: 'text', text: JSON.stringify({ status: cancelled ? 'Run cancelled — browser kept open' : 'No run in progress' }, null, 2) }] }
+      }
+
       case 'run_code': {
-        const { code, timeout = 60000, config: configPath, saveArtifacts = true } = args
-        await initCodecept(configPath)
-        ensureSession()
+        const { code, timeout = 60000, saveArtifacts = true, settleMs = 300 } = args
+        await initCodecept()
+        await ensureSession()
 
-        const I = container.support('I')
-        if (!I) throw new Error('I object not available. Make sure helpers are configured.')
+        const support = container.supportObjects() || {}
+        if (!support.I) throw new Error('I object not available. Make sure helpers are configured.')
 
         const result = { status: 'unknown', output: '', error: null, commands: [], artifacts: {} }
 
         const commands = []
+        let lastStepValue
         const onStepAfter = step => {
           try { commands.push(step.toString()) } catch {}
         }
+        const onStepPassed = (step, val) => {
+          if (val !== undefined) lastStepValue = val
+        }
         event.dispatcher.on(event.step.after, onStepAfter)
+        event.dispatcher.on(event.step.passed, onStepPassed)
 
         const traceDir = traceDirFor(`mcp_${Date.now()}`, 'run_code', outputBaseDir())
         mkdirp.sync(traceDir)
@@ -728,13 +864,27 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           console[m] = captureLog(m)
         }
 
+        const scope = {
+          locate, within, session, secret, inject, pause, share: container.share,
+          tryTo, retryTo, hopeThat,
+          step, element, eachElement, expectElement, expectAnyElement, expectAllElements,
+          container, helpers: container.helpers(),
+          ...support,
+        }
+        const paramNames = ['I', ...Object.keys(scope).filter(k => k !== 'I').sort()]
+        const paramValues = paramNames.map(k => scope[k])
+
+        const wasPaused = !!pausedController
+        if (wasPaused) recorder.session.start('mcp_run_code')
+
         let returnValue
         try {
-          const asyncFn = new Function('I', `return (async () => { ${code} })()`)
+          const asyncFn = new Function(...paramNames, `return (async () => { ${code} })()`)
           returnValue = await Promise.race([
-            asyncFn(I),
+            asyncFn(...paramValues),
             new Promise((_, reject) => setTimeout(() => reject(new Error(`Timeout after ${timeout}ms`)), timeout)),
           ])
+          await recorder.promise()
 
           result.status = 'success'
           result.output = 'Code executed successfully'
@@ -745,11 +895,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         } finally {
           for (const m of consoleMethods) console[m] = origConsoleMethods[m]
           try { event.dispatcher.removeListener(event.step.after, onStepAfter) } catch {}
+          try { event.dispatcher.removeListener(event.step.passed, onStepPassed) } catch {}
+          if (wasPaused) {
+            try { recorder.session.restore('mcp_run_code') } catch {}
+          } else {
+            try { recorder.reset() } catch {}
+          }
         }
 
         result.commands = commands
         result.logs = consoleLogs
         if (consoleLogs.length === MAX_LOG_ENTRIES) result.logsTruncated = true
+        result.availableObjects = paramNames
+
+        if (returnValue === undefined) returnValue = await Promise.resolve(lastStepValue)
+        returnValue = await formatReturnValue(returnValue)
 
         if (returnValue !== undefined) {
           const json = typeof returnValue === 'string' ? returnValue : safeStringify(returnValue, [], 2)
@@ -763,6 +923,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           const helper = pickActingHelper(container.helpers())
           if (helper) {
             try {
+              if (settleMs > 0) await new Promise(r => setTimeout(r, settleMs))
               captured = await captureSnapshot(helper, { dir: traceDir, prefix: 'mcp' })
               result.artifacts = artifactsToFileUrls(captured, traceDir)
             } catch (e) {
@@ -790,6 +951,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         })
         result.dir = traceDir
         result.traceFile = pathToFileURL(traceFile).href
+        result.aiTraceHint = aiTraceHint()
 
         return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }
       }
@@ -799,9 +961,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           if (pausedController) {
             throw new Error('A previous run_test is still paused. Call "continue" first.')
           }
-          const { test, timeout = 60000, config: configPathArg, pauseAt, plugins } = args || {}
-          await initCodecept(configPathArg, plugins)
+          const { test, timeout = 60000, pauseAt, grep, plugins } = args || {}
+          await initCodecept(undefined, plugins)
           await endShellSession()
+          applyMochaGrep(grep)
 
           return await withSilencedIO(async () => {
             codecept.loadTests()
@@ -822,26 +985,27 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             pendingTestFile = testFile
             pendingStepInfo = null
             let stepIndex = 0
+            const matchPauseAt = pauseAtMatcher(pauseAt)
 
             const onAfter = t => {
+              const aiTrace = t.artifacts?.aiTrace
               pendingRunResults.push({
                 title: t.title,
                 file: t.file,
                 status: t.err ? 'failed' : 'passed',
                 error: t.err?.message,
                 duration: t.duration,
+                traceFile: aiTrace ? pathToFileURL(aiTrace).href : null,
               })
             }
             const onStepAfter = step => {
               stepIndex += 1
-              try {
-                pendingStepInfo = { index: stepIndex, name: step.toString(), status: step.status }
-              } catch {
-                pendingStepInfo = { index: stepIndex }
-              }
-              if (typeof pauseAt === 'number' && stepIndex === pauseAt) {
-                pauseNow()
-              }
+              const idx = stepIndex
+              const name = (() => { try { return step.toString() } catch { return '' } })()
+              recorder.add('mcp pause info', () => {
+                pendingStepInfo = { index: idx, name, status: step.status }
+              })
+              if (matchPauseAt(idx, name)) pauseNow()
             }
             event.dispatcher.on(event.test.after, onAfter)
             event.dispatcher.on(event.step.after, onStepAfter)
@@ -883,6 +1047,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
 
             const final = collectRunCompletion(runError?.message)
+            await startShellSession()
             return { content: [{ type: 'text', text: JSON.stringify({ ...final, file: testFile }, null, 2) }] }
           })
         })
@@ -893,9 +1058,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           if (pausedController) {
             throw new Error('A previous run is still paused. Call "continue" first.')
           }
-          const { test, timeout = 60000, config: configPath, plugins } = args || {}
-          await initCodecept(configPath, plugins)
+          const { test, timeout = 60000, grep, plugins } = args || {}
+          await initCodecept(undefined, plugins)
           await endShellSession()
+          applyMochaGrep(grep)
 
           return await withSilencedIO(async () => {
             codecept.loadTests()
@@ -918,22 +1084,23 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             let stepIndex = 0
 
             const onAfter = t => {
+              const aiTrace = t.artifacts?.aiTrace
               pendingRunResults.push({
                 title: t.title,
                 file: t.file,
                 status: t.err ? 'failed' : 'passed',
                 error: t.err?.message,
                 duration: t.duration,
+                traceFile: aiTrace ? pathToFileURL(aiTrace).href : null,
               })
             }
             const onStepAfter = step => {
               stepIndex += 1
-              try {
-                pendingStepInfo = { index: stepIndex, name: step.toString(), status: step.status }
-              } catch {
-                pendingStepInfo = { index: stepIndex }
-              }
-              // Pause after every step — agent calls continue to advance.
+              const idx = stepIndex
+              const name = (() => { try { return step.toString() } catch { return '' } })()
+              recorder.add('mcp pause info', () => {
+                pendingStepInfo = { index: idx, name, status: step.status }
+              })
               pauseNow()
             }
             event.dispatcher.on(event.test.after, onAfter)
@@ -975,8 +1142,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
               }
             }
 
-            // Test had zero steps (or finished before first pause) — return completion
             const final = collectRunCompletion(runError?.message)
+            await startShellSession()
             return { content: [{ type: 'text', text: JSON.stringify({ ...final, file: testFile }, null, 2) }] }
           })
         })
@@ -994,6 +1161,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 })
 
 async function main() {
+  installShutdownHooks()
   const transport = new StdioServerTransport()
   await server.connect(transport)
 }