refactor(mcp): simplify pause_session — code in, result out

Drops the id-keyed message multiplexer and 7-action enum (run/snapshot/step/
resume/exit/status). The yield-mode subprocess now reads plain text lines
from stdin (same shape as the TTY readline REPL) and emits one JSON line
per input on stdout.

The MCP server pause_session tool exposes only "start" and "run". A run
takes a code string with the same conventions as the TTY pause REPL —
"" steps, "resume" continues, "exit" aborts, otherwise treat as I.<expr>
or =>raw_js. Each run returns the next protocol message.

Net: 237 lines removed, 159 added.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: DavertMik

bin/mcp-server.js

@@ -236,40 +236,23 @@ function outputBaseDir() {
 }
 
 let pauseChild = null
-let pausePending = new Map() // id -> { resolve, reject, timer }
 let pauseLogs = []
 let pauseStdoutBuf = ''
-let pauseStderrBuf = ''
-let pausePausedWaiters = []
+let pauseProtocolWaiters = []
 let pauseExitInfo = null
 
-function pauseProcessLine(line) {
-  const trimmed = line.trim()
-  if (!trimmed) return
-  let msg = null
-  if (trimmed.startsWith('{')) {
-    try { msg = JSON.parse(trimmed) } catch {}
-  }
-  if (msg && msg.__mcpPause) {
-    if (msg.event === 'paused') {
-      const waiters = pausePausedWaiters
-      pausePausedWaiters = []
-      for (const w of waiters) w.resolve(msg)
-      return
-    }
-    if (msg.id != null && pausePending.has(msg.id)) {
-      const pending = pausePending.get(msg.id)
-      pausePending.delete(msg.id)
-      clearTimeout(pending.timer)
-      pending.resolve(msg)
-      return
-    }
-    if (msg.event === 'error') {
-      pauseLogs.push({ stream: 'protocol-error', line: trimmed })
-      return
-    }
-    pauseLogs.push({ stream: 'protocol', line: trimmed })
-    return
+function pauseProcessStdoutLine(line) {
+  if (!line) return
+  if (line.trim().startsWith('{')) {
+    try {
+      const msg = JSON.parse(line.trim())
+      if (msg && msg.__mcpPause) {
+        const waiter = pauseProtocolWaiters.shift()
+        if (waiter) waiter(msg)
+        else pauseLogs.push({ stream: 'protocol-unwaited', line })
+        return
+      }
+    } catch {}
   }
   pauseLogs.push({ stream: 'stdout', line })
   if (pauseLogs.length > 500) pauseLogs.splice(0, pauseLogs.length - 500)
@@ -281,7 +264,7 @@ function pauseProcessChunk(buf, chunk, stream) {
   while ((idx = buf.indexOf('\n')) !== -1) {
     const line = buf.slice(0, idx)
     buf = buf.slice(idx + 1)
-    if (stream === 'stdout') pauseProcessLine(line)
+    if (stream === 'stdout') pauseProcessStdoutLine(line)
     else {
       pauseLogs.push({ stream: 'stderr', line })
       if (pauseLogs.length > 500) pauseLogs.splice(0, pauseLogs.length - 500)
@@ -290,60 +273,42 @@ function pauseProcessChunk(buf, chunk, stream) {
   return buf
 }
 
-function pauseSendCommand(payload, { timeout = 30000 } = {}) {
-  if (!pauseChild) return Promise.reject(new Error('No active pause_session. Call action: "start" first.'))
-  if (pauseChild.exitCode != null) return Promise.reject(new Error('pause_session subprocess has exited'))
-
-  let id = payload.id
-  if (id == null) {
-    id = `req-${Date.now()}-${Math.floor(Math.random() * 1e6)}`
-    payload = { ...payload, id }
-  }
-
+function pauseAwaitProtocol({ timeout = 60000 } = {}) {
   return new Promise((resolve, reject) => {
+    if (!pauseChild) return reject(new Error('No active pause_session. Call action: "start" first.'))
+    let done = false
     const timer = setTimeout(() => {
-      pausePending.delete(id)
-      reject(new Error(`Timeout waiting for pause_session response (${payload.type}) after ${timeout}ms`))
+      if (done) return
+      done = true
+      const i = pauseProtocolWaiters.indexOf(receiver)
+      if (i >= 0) pauseProtocolWaiters.splice(i, 1)
+      pauseChild?.removeListener('exit', onExit)
+      reject(new Error(`Timeout waiting for pause_session response after ${timeout}ms`))
     }, timeout)
-    pausePending.set(id, { resolve, reject, timer })
-    try {
-      pauseChild.stdin.write(JSON.stringify(payload) + '\n')
-    } catch (e) {
+    const cleanup = () => {
+      done = true
       clearTimeout(timer)
-      pausePending.delete(id)
-      reject(e)
+      pauseChild?.removeListener('exit', onExit)
     }
-  })
-}
-
-function pauseWaitForPaused({ timeout = 60000 } = {}) {
-  if (!pauseChild) return Promise.reject(new Error('No active pause_session. Call action: "start" first.'))
-  return new Promise((resolve, reject) => {
-    const timer = setTimeout(() => {
-      const idx = pausePausedWaiters.findIndex(w => w.resolve === wrapped)
-      if (idx >= 0) pausePausedWaiters.splice(idx, 1)
-      reject(new Error(`Timeout waiting for paused event after ${timeout}ms`))
-    }, timeout)
-    const wrapped = msg => {
-      clearTimeout(timer)
+    const receiver = msg => {
+      if (done) return
+      cleanup()
       resolve(msg)
     }
-    pausePausedWaiters.push({ resolve: wrapped, reject })
+    const onExit = () => {
+      if (done) return
+      const i = pauseProtocolWaiters.indexOf(receiver)
+      if (i >= 0) pauseProtocolWaiters.splice(i, 1)
+      cleanup()
+      resolve({ event: 'exited', exitInfo: pauseExitInfo })
+    }
+    pauseProtocolWaiters.push(receiver)
+    pauseChild.once('exit', onExit)
   })
 }
 
-function pauseTeardown(reason) {
-  for (const [id, p] of pausePending.entries()) {
-    clearTimeout(p.timer)
-    p.reject(new Error(reason || 'pause_session ended'))
-  }
-  pausePending.clear()
-  for (const w of pausePausedWaiters) {
-    if (typeof w.reject === 'function') {
-      try { w.reject(new Error(reason || 'pause_session ended')) } catch {}
-    }
-  }
-  pausePausedWaiters = []
+function pauseTeardown() {
+  pauseProtocolWaiters = []
   pauseChild = null
 }
 
@@ -462,11 +427,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'pause_session',
-      description: 'Drive a paused test through pause(). Sub-actions: start (spawn test, wait for first paused event), run (execute CodeceptJS code in the paused session), snapshot (capture state without acting), step (let the test run one step then re-pause), resume (continue test to completion), exit (abort the paused test), status (return current state).',
+      description: 'Run code inside a paused test, mirroring the human pause() REPL. Two actions: "start" spawns a test and waits for it to hit pause(); "run" sends a code line (same syntax as the TTY pause REPL — empty string steps to the next test step, "resume" continues the test, "exit" aborts; any other input is treated as I.<expr> unless prefixed with "=>"). Each run returns the value plus an artifact bundle (URL, ARIA, HTML, screenshot, console, storage), like run_code.',
       inputSchema: {
         type: 'object',
         properties: {
-          action: { type: 'string', enum: ['start', 'run', 'snapshot', 'step', 'resume', 'exit', 'status'] },
+          action: { type: 'string', enum: ['start', 'run'] },
           test: { type: 'string' },
           code: { type: 'string' },
           config: { type: 'string' },
@@ -593,7 +558,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
         if (action === 'start') {
           if (pauseChild && pauseChild.exitCode == null) {
-            throw new Error('pause_session already running. Call action: "exit" or "resume" first.')
+            throw new Error('pause_session already running. Send code: "exit" via action: "run" first.')
           }
           const { test, config: configPathArg, timeout = 60000 } = args
           if (!test) throw new Error('pause_session start requires "test" parameter')
@@ -610,8 +575,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
           pauseLogs = []
           pauseStdoutBuf = ''
-          pauseStderrBuf = ''
           pauseExitInfo = null
+          pauseProtocolWaiters = []
 
           const env = {
             ...process.env,
@@ -623,29 +588,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           const cmd = isNodeScript ? process.execPath : cli
           const cmdArgs = isNodeScript ? [cli, ...runArgs] : runArgs
 
-          pauseChild = spawn(cmd, cmdArgs, {
-            cwd: root,
-            env,
-            stdio: ['pipe', 'pipe', 'pipe'],
-          })
-
-          pauseChild.stdout.on('data', d => {
-            pauseStdoutBuf = pauseProcessChunk(pauseStdoutBuf, d, 'stdout')
-          })
-          pauseChild.stderr.on('data', d => {
-            pauseStderrBuf = pauseProcessChunk(pauseStderrBuf, d, 'stderr')
-          })
+          pauseChild = spawn(cmd, cmdArgs, { cwd: root, env, stdio: ['pipe', 'pipe', 'pipe'] })
+          let stderrBuf = ''
+          pauseChild.stdout.on('data', d => { pauseStdoutBuf = pauseProcessChunk(pauseStdoutBuf, d, 'stdout') })
+          pauseChild.stderr.on('data', d => { stderrBuf = pauseProcessChunk(stderrBuf, d, 'stderr') })
           pauseChild.on('exit', (code, signal) => {
             pauseExitInfo = { code, signal }
-            pauseTeardown(`subprocess exited (code=${code}, signal=${signal})`)
-          })
-          pauseChild.on('error', err => {
-            pauseTeardown(`subprocess error: ${err.message}`)
+            pauseTeardown()
           })
 
           let pausedMsg
           try {
-            pausedMsg = await pauseWaitForPaused({ timeout })
+            pausedMsg = await pauseAwaitProtocol({ timeout })
           } catch (err) {
             try { pauseChild?.kill('SIGKILL') } catch {}
             const stderr = pauseLogs.filter(l => l.stream === 'stderr').map(l => l.line).join('\n')
@@ -655,99 +609,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           return {
             content: [{
               type: 'text',
-              text: JSON.stringify({
-                status: 'paused',
-                resolvedFile: resolvedFile || null,
-                paused: pausedMsg,
-              }, null, 2),
-            }],
-          }
-        }
-
-        if (action === 'status') {
-          return {
-            content: [{
-              type: 'text',
-              text: JSON.stringify({
-                running: !!(pauseChild && pauseChild.exitCode == null),
-                exitInfo: pauseExitInfo,
-                logs: pauseLogs.slice(-50),
-              }, null, 2),
+              text: JSON.stringify({ status: 'paused', resolvedFile: resolvedFile || null, paused: pausedMsg }, null, 2),
             }],
           }
         }
 
         if (action === 'run') {
-          const { code, timeout = 60000 } = args
-          if (!code) throw new Error('pause_session run requires "code"')
-          const resp = await pauseSendCommand({ type: 'run', code }, { timeout })
+          if (!pauseChild) throw new Error('No active pause_session. Call action: "start" first.')
+          if (pauseChild.exitCode != null) throw new Error('pause_session subprocess has exited')
+          const { code = '', timeout = 60000 } = args
+          pauseChild.stdin.write(code + '\n')
+          const resp = await pauseAwaitProtocol({ timeout })
           return { content: [{ type: 'text', text: JSON.stringify(resp, null, 2) }] }
         }
 
-        if (action === 'snapshot') {
-          const { timeout = 30000 } = args
-          const resp = await pauseSendCommand({ type: 'snapshot' }, { timeout })
-          return { content: [{ type: 'text', text: JSON.stringify(resp, null, 2) }] }
-        }
-
-        if (action === 'step') {
-          const { timeout = 60000 } = args
-          const resumed = await pauseSendCommand({ type: 'step' }, { timeout })
-          let pausedAgain = null
-          try {
-            pausedAgain = await pauseWaitForPaused({ timeout })
-          } catch {
-            // test may have ended after the step — that's fine
-          }
-          return {
-            content: [{
-              type: 'text',
-              text: JSON.stringify({ resumed, paused: pausedAgain, exitInfo: pauseExitInfo }, null, 2),
-            }],
-          }
-        }
-
-        if (action === 'resume') {
-          const { timeout = 60000 } = args
-          const resumed = await pauseSendCommand({ type: 'resume' }, { timeout })
-          await new Promise(resolve => {
-            if (!pauseChild || pauseChild.exitCode != null) return resolve()
-            pauseChild.once('exit', resolve)
-            setTimeout(resolve, timeout)
-          })
-          return {
-            content: [{
-              type: 'text',
-              text: JSON.stringify({ resumed, exitInfo: pauseExitInfo }, null, 2),
-            }],
-          }
-        }
-
-        if (action === 'exit') {
-          if (!pauseChild) {
-            return { content: [{ type: 'text', text: JSON.stringify({ status: 'no-active-session' }, null, 2) }] }
-          }
-          const { timeout = 30000 } = args
-          let resp = null
-          try {
-            resp = await pauseSendCommand({ type: 'exit' }, { timeout: Math.min(timeout, 5000) })
-          } catch {}
-          await new Promise(resolve => {
-            if (!pauseChild || pauseChild.exitCode != null) return resolve()
-            const t = setTimeout(() => {
-              try { pauseChild?.kill('SIGKILL') } catch {}
-              resolve()
-            }, timeout)
-            pauseChild.once('exit', () => { clearTimeout(t); resolve() })
-          })
-          return {
-            content: [{
-              type: 'text',
-              text: JSON.stringify({ exited: resp, exitInfo: pauseExitInfo }, null, 2),
-            }],
-          }
-        }
-
         throw new Error(`pause_session unknown action: ${action}`)
       }
 

docs/mcp.md

@@ -237,43 +237,38 @@ Capture the current state of the browser without performing any action. Useful f
 
 ### pause_session
 
-Drive a paused test through `pause()` over MCP. Replaces the human-only readline REPL with a JSON-line protocol the agent can speak. Useful when a test hits `pause()` or you want to pause-on-failure without a TTY.
+Mirrors the human `pause()` REPL for an AI agent: send a code string, get a result with artifacts (same shape as `run_code`).
 
-The subprocess is spawned with `CODECEPTJS_MCP=1` and `CODECEPTJS_MCP_PAUSE=1` so any `pause()` calls in the test land in yield mode (instead of the default skip-on-MCP behaviour).
+Two actions:
 
-**Sub-actions** (selected via `action`):
+| Action | Params | Effect |
+|---|---|---|
+| `start` | `test`, `config?`, `timeout?` | Spawn the test subprocess in pause yield mode. Resolves when the test hits `pause()` and emits `{event:"paused"}`. |
+| `run` | `code`, `timeout?` | Send one line of input — same syntax as the TTY REPL. Returns the next protocol message from the subprocess. |
 
-| Action | Effect |
-|---|---|
-| `start` | Spawn the test subprocess in pause yield mode. Resolves when the first `paused` event arrives. |
-| `run` | Execute a CodeceptJS expression in the paused session (`I.click('Save')` or `=> myVar`). Returns artifacts + return value. |
-| `snapshot` | Capture browser state without acting. Returns the same artifact bundle as the `snapshot` tool. |
-| `step` | Let the test run one step, then re-pause. Returns the `resumed` ack and the next `paused` event (or `exitInfo` if the test ended). |
-| `resume` | Continue the test to completion. Returns when the subprocess exits. |
-| `exit` | Abort the paused test and tear down the subprocess. |
-| `status` | Inspect the current session — running flag, exit info, last stdout/stderr lines. |
+`code` follows the TTY pause REPL conventions:
+- An expression like `click('Save')` runs as `I.click('Save')` and returns `{event:"result", ok, value, artifacts, error}`.
+- Prefix `=>` to evaluate raw JS: `=> myVar.id`.
+- `""` (empty) → step to the next test step. The subprocess re-pauses; response is `{event:"step"}` followed by `{event:"paused"}` on the next `run` call.
+- `"resume"` → continue the test to completion. Response is `{event:"resumed"}`; the subprocess will exit on its own.
+- `"exit"` → abort the paused test. Same `{event:"resumed"}` response, then exit.
 
-**Parameters:**
-- `action` (required): one of the values above
-- `test` (`start` only): test name or file path
-- `code` (`run` only): expression to evaluate (defaults to `I.<expr>`; prefix with `=>` for raw JS)
-- `config` (`start` only): path to codecept.conf.js
-- `timeout` (optional): per-action timeout in ms
+Each result includes the artifact bundle (URL, ARIA, HTML, screenshot, console, storage), like `run_code`. If the subprocess exits during a `run`, the response is `{event:"exited", exitInfo:{code, signal}}`.
 
 **Lifecycle example:**
 
 ```json
 { "name": "pause_session", "arguments": { "action": "start", "test": "checkout_test" } }
 { "name": "pause_session", "arguments": { "action": "run", "code": "grabCurrentUrl()" } }
-{ "name": "pause_session", "arguments": { "action": "snapshot" } }
-{ "name": "pause_session", "arguments": { "action": "step" } }
-{ "name": "pause_session", "arguments": { "action": "resume" } }
+{ "name": "pause_session", "arguments": { "action": "run", "code": "click('Save')" } }
+{ "name": "pause_session", "arguments": { "action": "run", "code": "resume" } }
 ```
 
-A single `pause_session` instance owns one subprocess. Concurrent `start` calls are rejected — `exit` (or `resume`) the running session first.
+A single `pause_session` instance owns one subprocess. Concurrent `start` calls are rejected — send `code: "exit"` (or `"resume"`) first.
 
 **Notes:**
-- `pause()` calls in tests run through MCP without yield mode (env `CODECEPTJS_MCP=1` only) print a notice and return immediately so leftover `pause()` calls don't deadlock CI runs.
+- The subprocess is spawned with `CODECEPTJS_MCP=1` and `CODECEPTJS_MCP_PAUSE=1` so `pause()` calls in the test land in yield mode.
+- `pause()` calls running under `CODECEPTJS_MCP=1` *without* `CODECEPTJS_MCP_PAUSE=1` print a notice and return immediately so leftover `pause()` calls don't deadlock CI runs invoked through MCP.
 - TTY behaviour (`npx codeceptjs run --debug` at a terminal) is unchanged — the readline REPL is used whenever `process.stdin.isTTY` is true.
 
 ### run_test