feat(serial): cursor-based reads and wait_for

arduino-mcp-extension/README.md

@@ -363,12 +363,20 @@ error) and can keep waiting with `arduino_task_status {wait:true}`. Without
 | `list_ports` | - | List available serial ports |
 | `connect` | `port`, `baud_rate`, `fqbn` (optional) | Open connection |
 | `disconnect` | - | Close connection |
-| `read` | `max_lines` | Read buffered board output |
+| `read` | `max_lines`, `since` | Read buffered board output (cursor-based) |
+| `wait_for` | `pattern`, `is_regex`, `timeout_seconds`, `since` | Block until a matching line arrives |
 | `write` | `data`, `line_ending` | Send data |
-| `clear` | - | Clear read buffer |
+| `clear` | - | Clear read buffer (cursors stay monotonic) |
 | `get_config` | - | Get current connection config |
 | `set_config` | `baud_rate` | Update connection settings |
 
+Every `read`/`wait_for` response includes a `cursor`. Pass it back as `since`
+to page through output **losslessly**: you get the next lines after that
+offset, a `dropped` count if the 512 KB buffer overflowed in between, and
+`has_more` when more complete lines are already buffered. Without `since`,
+`read` returns the familiar tail snapshot. `wait_for` resolves with the
+matching line, or `timed_out: true` / `disconnected: true` (never an error).
+
 ### arduino_library
 
 | Action | Parameters | Description |

arduino-mcp-extension/src/common/mcp-tool-router.ts

@@ -50,7 +50,8 @@ export const TOOL_CATEGORIES: ToolCategory[] = [
     name: 'serial',
     description: 'Serial monitor operations - connect, read output, send data to devices.',
     toolNames: ['arduino_serial'],
-    useWhen: 'Debugging via serial output, sending commands to device, monitoring data',
+    useWhen:
+      'Debugging via serial output, sending commands to device, waiting for specific output (wait_for), following logs losslessly with cursor-based reads',
   },
   {
     name: 'library',

arduino-mcp-extension/src/common/mcp-tools.ts

@@ -277,7 +277,7 @@ export const ARDUINO_TOOLS: ToolDefinition[] = [
   {
     name: 'arduino_serial',
     description:
-      'Serial monitor operations - connect to a board, read its output, send data, change the baud rate. The connection is shared with the IDE serial monitor.',
+      'Serial monitor operations - connect to a board, read its output, send data, change the baud rate. Reads are cursor-based: every read returns a `cursor`; pass it back as `since` to page through output losslessly. wait_for blocks until a line matching a pattern arrives. The connection is shared with the IDE serial monitor.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -287,6 +287,7 @@ export const ARDUINO_TOOLS: ToolDefinition[] = [
             'connect',
             'disconnect',
             'read',
+            'wait_for',
             'write',
             'clear',
             'get_config',
@@ -322,6 +323,26 @@ export const ARDUINO_TOOLS: ToolDefinition[] = [
           type: 'number',
           description: 'Maximum lines to return for read (default: 100)',
         },
+        since: {
+          type: 'number',
+          description:
+            'Cursor from a previous read/wait_for response (for read, wait_for). Returns only output at or after that offset, with `dropped` counting anything lost to buffer overflow - lossless paging instead of an overlapping tail.',
+        },
+        pattern: {
+          type: 'string',
+          description:
+            'Substring (or regex when is_regex=true) to wait for (for wait_for). Blocks until a matching line arrives.',
+        },
+        is_regex: {
+          type: 'boolean',
+          description:
+            'Treat pattern as a regular expression (for wait_for; default: false)',
+        },
+        timeout_seconds: {
+          type: 'number',
+          description:
+            'Max seconds wait_for blocks (default 30, clamp 1-120). A timeout returns matched:false with a cursor - not an error.',
+        },
       },
       required: ['action'],
     },