@prmichaelsen/acp-mcp 0.6.0 → 0.7.0

package/agent/tasks/milestone-4-progress-streaming-server/task-7-implement-progress-streaming.md

@@ -0,0 +1,191 @@
+# Task 7: Implement Progress Streaming in Execute Command
+
+**Milestone**: M4 - Progress Streaming - Server Implementation
+**Estimated Time**: 4-5 hours
+**Dependencies**: Task 6 (SSH stream execution)
+**Status**: Not Started
+**Priority**: High
+
+---
+
+## Objective
+
+Update `acp_remote_execute_command` tool to support progress streaming when client provides a `progressToken`. Implement graceful fallback to timeout mode when no progress token is provided.
+
+## Context
+
+**Design Reference**: [`agent/design/local.progress-streaming.md`](../../design/local.progress-streaming.md)
+
+**Current State**: Tool uses `execWithTimeout()` and returns all output at once
+
+**Desired State**: Tool detects `progressToken`, streams output with progress notifications, maintains backward compatibility
+
+---
+
+## Steps
+
+### 1. Update Handler Signature
+
+**File**: `src/tools/acp-remote-execute-command.ts`
+
+**Actions**:
+- Add `extra?: { progressToken?: string | number }` parameter
+- Import server instance for sending notifications
+- Add type definitions for progress params
+
+### 2. Add Progress Detection Logic
+
+**Actions**:
+- Check if `extra?.progressToken` exists
+- If yes: call `executeWithProgress()`
+- If no: use existing `execWithTimeout()` (fallback)
+
+### 3. Implement executeWithProgress() Function
+
+**Actions**:
+- Call `sshConnection.execStream()`
+- Set up stdout data handler
+- Send progress notification for each chunk
+- Collect full output for final result
+- Handle stderr separately (no progress)
+- Wait for exit code
+- Return structured result
+
+**Code Pattern**:
+```typescript
+async function executeWithProgress(
+  command: string,
+  cwd: string | undefined,
+  sshConnection: SSHConnectionManager,
+  progressToken: string | number
+): Promise<{ content: Array<{ type: string; text: string }> }> {
+  const { stream, stderr: stderrStream, exitCode } = await sshConnection.execStream(command, cwd);
+  
+  let stdout = '';
+  let stderr = '';
+  let bytesReceived = 0;
+
+  stream.on('data', (chunk: Buffer) => {
+    const text = chunk.toString();
+    stdout += text;
+    bytesReceived += chunk.length;
+    
+    // Send progress notification
+    server.notification({
+      method: 'notifications/progress',
+      params: {
+        progressToken,
+        progress: bytesReceived,
+        total: undefined,
+        message: text,
+      },
+    });
+  });
+
+  stderrStream.on('data', (chunk: Buffer) => {
+    stderr += chunk.toString();
+  });
+
+  const finalExitCode = await exitCode;
+
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        stdout,
+        stderr,
+        exitCode: finalExitCode,
+        timedOut: false,
+        streamed: true,
+      }, null, 2),
+    }],
+  };
+}
+```
+
+### 4. Add Rate Limiting
+
+**Actions**:
+- Limit progress notifications to max 10/second
+- Batch small chunks
+- Track last notification time
+- Only send if enough time elapsed
+
+**Code Pattern**:
+```typescript
+let lastProgressTime = 0;
+const MIN_PROGRESS_INTERVAL = 100; // 100ms
+
+stream.on('data', (chunk: Buffer) => {
+  stdout += chunk.toString();
+  bytesReceived += chunk.length;
+  
+  const now = Date.now();
+  if (now - lastProgressTime >= MIN_PROGRESS_INTERVAL) {
+    server.notification({ /* ... */ });
+    lastProgressTime = now;
+  }
+});
+```
+
+### 5. Add Error Handling
+
+**Actions**:
+- Handle stream errors
+- Handle connection loss
+- Send error via progress notification
+- Return error in final result
+
+### 6. Update Tool Schema
+
+**Actions**:
+- Update description to mention progress support
+- Note that timeout is ignored when streaming
+- Add examples of progress usage
+
+### 7. Test Implementation
+
+**Actions**:
+- Build project
+- Test with progressToken (streaming mode)
+- Test without progressToken (fallback mode)
+- Test with long-running command
+- Test with command that fails
+- Test error scenarios
+
+---
+
+## Verification
+
+- [ ] Handler accepts `extra` parameter
+- [ ] Detects `progressToken` correctly
+- [ ] Calls `executeWithProgress()` when token provided
+- [ ] Falls back to `execWithTimeout()` when no token
+- [ ] Sends progress notifications for stdout chunks
+- [ ] Rate limiting prevents notification spam
+- [ ] Collects full output for final result
+- [ ] Handles errors gracefully
+- [ ] TypeScript compiles without errors
+- [ ] Build completes successfully
+- [ ] Both modes tested and working
+
+---
+
+## Expected Output
+
+### Files Modified
+- `src/tools/acp-remote-execute-command.ts` - Progress streaming implementation
+
+### New Function
+```typescript
+async function executeWithProgress(
+  command: string,
+  cwd: string | undefined,
+  sshConnection: SSHConnectionManager,
+  progressToken: string | number
+): Promise<{ content: Array<{ type: string; text: string }> }>
+```
+
+---
+
+**Next Task**: [Task 8: Update Server Request Handlers](task-8-update-server-handlers.md)

package/agent/tasks/milestone-4-progress-streaming-server/task-8-update-server-handlers.md

@@ -0,0 +1,109 @@
+# Task 8: Update Server Request Handlers
+
+**Milestone**: M4 - Progress Streaming - Server Implementation
+**Estimated Time**: 1-2 hours
+**Dependencies**: Task 7 (Progress streaming implementation)
+**Status**: Not Started
+**Priority**: Medium
+
+---
+
+## Objective
+
+Update server request handlers in both `server.ts` and `server-factory.ts` to pass the `extra` parameter (containing `progressToken`) to tool handlers.
+
+## Context
+
+**Design Reference**: [`agent/design/local.progress-streaming.md`](../../design/local.progress-streaming.md)
+
+**Current State**: Handlers don't pass `extra` parameter to tools
+
+**Desired State**: Handlers pass `extra` to `acp_remote_execute_command` handler
+
+---
+
+## Steps
+
+### 1. Update server.ts Handler
+
+**File**: `src/server.ts`
+
+**Actions**:
+- Modify `CallToolRequestSchema` handler signature to accept `extra` parameter
+- Pass `extra` to `handleAcpRemoteExecuteCommand()`
+- Keep other tool handlers unchanged (they don't need progress)
+
+**Code Pattern**:
+```typescript
+server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+  const startTime = Date.now();
+  logger.toolInvoked(request.params.name, request.params.arguments);
+  
+  try {
+    let result;
+    
+    if (request.params.name === 'acp_remote_execute_command') {
+      result = await handleAcpRemoteExecuteCommand(
+        request.params.arguments,
+        sshConnection,
+        extra  // Pass extra with progressToken
+      );
+    } else if (request.params.name === 'acp_remote_list_files') {
+      result = await handleAcpRemoteListFiles(request.params.arguments, sshConnection);
+    }
+    // ... other tools
+    
+    return result;
+  } catch (error) {
+    logger.toolFailed(request.params.name, error as Error, request.params.arguments);
+    throw error;
+  }
+});
+```
+
+### 2. Update server-factory.ts Handler
+
+**File**: `src/server-factory.ts`
+
+**Actions**:
+- Same changes as server.ts
+- Ensure consistency between both files
+
+### 3. Verify No Breaking Changes
+
+**Actions**:
+- Confirm other tools still work
+- Verify `extra` parameter is optional
+- Test that undefined `extra` doesn't break anything
+
+### 4. Test Both Server Modes
+
+**Actions**:
+- Build project
+- Test standalone server (server.ts)
+- Test factory server (server-factory.ts)
+- Verify both pass `extra` correctly
+
+---
+
+## Verification
+
+- [ ] server.ts handler updated
+- [ ] server-factory.ts handler updated
+- [ ] `extra` parameter passed to execute_command handler
+- [ ] Other tools unaffected
+- [ ] TypeScript compiles without errors
+- [ ] Build completes successfully
+- [ ] Both server modes tested
+
+---
+
+## Expected Output
+
+### Files Modified
+- `src/server.ts` - Pass `extra` to handler
+- `src/server-factory.ts` - Pass `extra` to handler
+
+---
+
+**Next Task**: [Task 9: Testing and Documentation](task-9-testing-documentation.md)

package/agent/tasks/milestone-4-progress-streaming-server/task-9-testing-documentation.md

@@ -0,0 +1,192 @@
+# Task 9: Testing and Documentation
+
+**Milestone**: M4 - Progress Streaming - Server Implementation
+**Estimated Time**: 3-4 hours
+**Dependencies**: Tasks 6, 7, 8 (All implementation complete)
+**Status**: Not Started
+**Priority**: High
+
+---
+
+## Objective
+
+Add comprehensive tests for progress streaming functionality and update all documentation for v0.7.0 release.
+
+## Context
+
+**Design Reference**: [`agent/design/local.progress-streaming.md`](../../design/local.progress-streaming.md)
+
+**Current State**: Implementation complete, needs testing and documentation
+
+**Desired State**: Full test coverage, updated documentation, ready for v0.7.0 release
+
+---
+
+## Steps
+
+### 1. Write Unit Tests
+
+**File**: Create `src/utils/ssh-connection.test.ts` (if doesn't exist)
+
+**Actions**:
+- Test `execStream()` returns correct types
+- Test stream emits data events
+- Test exit code promise resolves
+- Test error handling
+- Mock SSH client for tests
+
+### 2. Write Integration Tests
+
+**File**: Create `src/tools/acp-remote-execute-command.test.ts`
+
+**Actions**:
+- Test with `progressToken` (streaming mode)
+- Test without `progressToken` (fallback mode)
+- Test progress notifications are sent
+- Test rate limiting works
+- Test error scenarios
+- Use real SSH connection (or mock)
+
+### 3. Manual Testing
+
+**Actions**:
+- Test with simple command: `echo "test"`
+- Test with long command: `for i in 1 2 3 4 5; do echo "Line $i"; sleep 0.5; done`
+- Test with failing command
+- Test with very long output
+- Test connection loss scenario
+
+### 4. Update README.md
+
+**File**: `README.md`
+
+**Actions**:
+- Add section on progress streaming support
+- Document that progress requires MCP SDK v1.26.0+
+- Add examples of progress usage
+- Note client requirements
+- Update tool description for `acp_remote_execute_command`
+
+**Example Addition**:
+```markdown
+### Progress Streaming (v0.7.0+)
+
+`acp_remote_execute_command` supports real-time progress streaming for long-running commands. When a client provides a `progressToken`, the tool will send progress notifications with live output.
+
+**Requirements**:
+- MCP SDK v1.26.0+ (server and client)
+- Client must provide `progressToken` in request
+- Client must handle `onprogress` callback
+
+**Example** (client-side):
+\`\`\`typescript
+const result = await client.request({
+  method: 'tools/call',
+  params: {
+    name: 'acp_remote_execute_command',
+    arguments: { command: 'npm run build' }
+  }
+}, {
+  progressToken: 'build-123',
+  onprogress: (progress) => {
+    console.log(progress.message); // Live output
+  }
+});
+\`\`\`
+
+**Fallback**: If no `progressToken` provided, uses timeout-based execution (backward compatible).
+```
+
+### 5. Update CHANGELOG.md
+
+**File**: `CHANGELOG.md`
+
+**Actions**:
+- Add v0.7.0 section
+- Document progress streaming feature
+- Note backward compatibility
+- List all changes
+
+**Example Entry**:
+```markdown
+## [0.7.0] - 2026-02-24
+
+### Added
+- **Progress Streaming** for `acp_remote_execute_command` tool
+  - Real-time output streaming for long-running commands
+  - Uses MCP SDK's native progress notification system
+  - Graceful fallback to timeout mode for clients without progress support
+  - Rate limiting prevents notification spam (max 10/second)
+  - Supports commands like `npm run build`, `npm run dev`, `npm test`
+
+### Changed
+- `acp_remote_execute_command` now accepts optional `progressToken` parameter
+- Added `execStream()` method to SSHConnectionManager
+- Server handlers now pass `extra` parameter to tool handlers
+
+### Technical Details
+- Requires MCP SDK v1.26.0+ for progress support
+- Progress notifications sent via `notifications/progress` method
+- Backward compatible - existing clients unaffected
+- No breaking changes to API
+```
+
+### 6. Update package.json
+
+**File**: `package.json`
+
+**Actions**:
+- Bump version to 0.7.0
+- Verify dependencies are correct
+
+### 7. Build and Verify
+
+**Actions**:
+- Run `npm run build`
+- Verify TypeScript compiles
+- Run tests: `npm test`
+- Verify all tests pass
+- Check for any warnings
+
+---
+
+## Verification
+
+- [ ] Unit tests written and passing
+- [ ] Integration tests written and passing
+- [ ] Manual testing completed successfully
+- [ ] README.md updated with progress documentation
+- [ ] CHANGELOG.md updated for v0.7.0
+- [ ] package.json version bumped to 0.7.0
+- [ ] TypeScript compiles without errors
+- [ ] Build completes successfully
+- [ ] All tests pass
+- [ ] No warnings or errors
+
+---
+
+## Expected Output
+
+### Files Created
+- `src/utils/ssh-connection.test.ts` - Unit tests (if doesn't exist)
+- `src/tools/acp-remote-execute-command.test.ts` - Integration tests (if doesn't exist)
+
+### Files Modified
+- `README.md` - Progress streaming documentation
+- `CHANGELOG.md` - v0.7.0 entry
+- `package.json` - Version bump to 0.7.0
+
+### Test Results
+```
+✓ SSH stream execution tests (5 passed)
+✓ Progress streaming tests (8 passed)
+✓ Fallback mode tests (3 passed)
+✓ Error handling tests (4 passed)
+
+Total: 20 tests passed
+```
+
+---
+
+**Next Milestone**: M5 - Progress Streaming - Wrapper Integration (mcp-auth)
+**Related Design**: [`agent/design/local.progress-streaming.md`](../../design/local.progress-streaming.md)

package/dist/server-factory.js

@@ -179,7 +179,7 @@ var logger = new Logger();
 // src/tools/acp-remote-execute-command.ts
 var acpRemoteExecuteCommandTool = {
   name: "acp_remote_execute_command",
-  description: "Execute a shell command on the remote machine via SSH",
+  description: "Execute a shell command on the remote machine via SSH. Supports real-time progress streaming if client provides progressToken.",
   inputSchema: {
     type: "object",
     properties: {
@@ -193,17 +193,21 @@ var acpRemoteExecuteCommandTool = {
       },
       timeout: {
         type: "number",
-        description: "Timeout in seconds (default: 30)",
+        description: "Timeout in seconds (default: 30). Ignored if progress streaming is used.",
         default: 30
       }
     },
     required: ["command"]
   }
 };
-async function handleAcpRemoteExecuteCommand(args, sshConnection) {
+async function handleAcpRemoteExecuteCommand(args, sshConnection, extra, server) {
   const { command, cwd, timeout = 30 } = args;
-  logger.debug("Executing remote command", { command, cwd, timeout });
+  const progressToken = extra?._meta?.progressToken;
+  logger.debug("Executing remote command", { command, cwd, timeout, hasProgressToken: !!progressToken });
   try {
+    if (progressToken && server) {
+      return await executeWithProgress(command, cwd, sshConnection, progressToken, server);
+    }
     const fullCommand = cwd ? `cd ${cwd} && ${command}` : command;
     const result = await sshConnection.execWithTimeout(fullCommand, timeout);
     logger.debug("Command execution result", {
@@ -244,6 +248,75 @@ async function handleAcpRemoteExecuteCommand(args, sshConnection) {
     };
   }
 }
+async function executeWithProgress(command, cwd, sshConnection, progressToken, server) {
+  logger.debug("Starting streaming execution", { command, cwd, progressToken });
+  const { stream, stderr: stderrStream, exitCode } = await sshConnection.execStream(command, cwd);
+  let stdout = "";
+  let stderr = "";
+  let bytesReceived = 0;
+  let lastProgressTime = 0;
+  const MIN_PROGRESS_INTERVAL = 100;
+  stream.on("data", (chunk) => {
+    const text = chunk.toString();
+    stdout += text;
+    bytesReceived += chunk.length;
+    const now = Date.now();
+    if (now - lastProgressTime >= MIN_PROGRESS_INTERVAL) {
+      try {
+        server.notification({
+          method: "notifications/progress",
+          params: {
+            progressToken,
+            progress: bytesReceived,
+            total: void 0,
+            // Unknown total for streaming
+            message: text
+          }
+        });
+        lastProgressTime = now;
+        logger.debug("Progress notification sent", {
+          progressToken,
+          bytes: bytesReceived,
+          chunkSize: chunk.length
+        });
+      } catch (error) {
+        logger.warn("Failed to send progress notification", {
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+  });
+  stderrStream.on("data", (chunk) => {
+    stderr += chunk.toString();
+  });
+  stream.on("error", (error) => {
+    logger.error("Stream error during execution", {
+      command,
+      error: error.message
+    });
+  });
+  const finalExitCode = await exitCode;
+  logger.debug("Streaming execution completed", {
+    command,
+    exitCode: finalExitCode,
+    stdoutBytes: stdout.length,
+    stderrBytes: stderr.length
+  });
+  const output = {
+    stdout,
+    stderr,
+    exitCode: finalExitCode,
+    timedOut: false,
+    streamed: true
+    // Indicate this was streamed
+  };
+  return {
+    content: [{
+      type: "text",
+      text: JSON.stringify(output, null, 2)
+    }]
+  };
+}
 
 // src/tools/acp-remote-read-file.ts
 var acpRemoteReadFileTool = {
@@ -559,6 +632,57 @@ var SSHConnectionManager = class {
       throw error;
     }
   }
+  /**
+   * Execute a command on the remote server with streaming output
+   * Returns streams instead of buffered output for real-time progress
+   *
+   * @param command - Shell command to execute
+   * @param cwd - Optional working directory
+   * @returns Object with stdout stream, stderr stream, and exit code promise
+   */
+  async execStream(command, cwd) {
+    if (!this.connected) {
+      await this.connect();
+    }
+    const fullCommand = cwd ? `cd "${cwd}" && ${command}` : command;
+    const startTime = Date.now();
+    logger.sshCommand(fullCommand, cwd);
+    return new Promise((resolve, reject) => {
+      this.client.exec(fullCommand, (err, stream) => {
+        if (err) {
+          logger.error("SSH exec failed", {
+            command: fullCommand,
+            error: err.message
+          });
+          reject(err);
+          return;
+        }
+        logger.debug("SSH stream started", { command: fullCommand });
+        const exitCodePromise = new Promise((resolveExit) => {
+          stream.on("close", (code) => {
+            const duration = Date.now() - startTime;
+            logger.debug("SSH stream closed", {
+              command: fullCommand,
+              exitCode: code,
+              duration: `${duration}ms`
+            });
+            resolveExit(code);
+          });
+        });
+        stream.on("error", (error) => {
+          logger.error("SSH stream error", {
+            command: fullCommand,
+            error: error.message
+          });
+        });
+        resolve({
+          stream,
+          stderr: stream.stderr,
+          exitCode: exitCodePromise
+        });
+      });
+    });
+  }
   /**
    * Get SFTP wrapper for file operations
    */
@@ -845,7 +969,7 @@ async function createServer(serverConfig) {
     logger.debug(`Returning ${tools.length} tools`, { tools: tools.map((t) => t.name), userId: serverConfig.userId });
     return { tools };
   });
-  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
     const startTime = Date.now();
     logger.toolInvoked(request.params.name, request.params.arguments, serverConfig.userId);
     try {
@@ -853,7 +977,7 @@ async function createServer(serverConfig) {
       if (request.params.name === "acp_remote_list_files") {
         result = await handleAcpRemoteListFiles(request.params.arguments, sshConnection);
       } else if (request.params.name === "acp_remote_execute_command") {
-        result = await handleAcpRemoteExecuteCommand(request.params.arguments, sshConnection);
+        result = await handleAcpRemoteExecuteCommand(request.params.arguments, sshConnection, extra, server);
       } else if (request.params.name === "acp_remote_read_file") {
         result = await handleAcpRemoteReadFile(request.params.arguments, sshConnection);
       } else if (request.params.name === "acp_remote_write_file") {