@prmichaelsen/acp-mcp 0.5.1 → 0.7.0

package/agent/milestones/milestone-4-progress-streaming-server.md

@@ -0,0 +1,84 @@
+# Milestone 4: Progress Streaming - Server Implementation (acp-mcp)
+
+**Goal**: Implement server-side progress streaming support in acp-mcp
+**Duration**: 1 week
+**Dependencies**: None
+**Status**: Not Started
+**Project**: acp-mcp (this project)
+
+---
+
+## Overview
+
+Implement the server-side infrastructure for real-time progress streaming in acp-mcp. This includes SSH streaming execution, progress notification sending, and graceful fallback for clients that don't support progress.
+
+This milestone focuses ONLY on the acp-mcp server implementation. Client-side changes (mcp-auth, agentbase.me) are separate milestones.
+
+## Deliverables
+
+- ✅ SSH streaming execution method (`execStream()`)
+- ✅ Progress notification support in `acp_remote_execute_command`
+- ✅ Graceful fallback to timeout mode
+- ✅ Rate limiting for progress notifications
+- ✅ Comprehensive error handling
+- ✅ Unit and integration tests
+- ✅ Documentation updates
+
+## Success Criteria
+
+- [ ] `execStream()` method implemented in SSHConnectionManager
+- [ ] `acp_remote_execute_command` sends progress notifications when `progressToken` provided
+- [ ] Falls back to timeout mode when no `progressToken`
+- [ ] Progress notifications include stdout chunks
+- [ ] Rate limiting prevents notification spam
+- [ ] All existing tests still pass
+- [ ] New tests for streaming added
+- [ ] TypeScript compiles without errors
+- [ ] Build completes successfully
+- [ ] README.md documents progress support
+- [ ] CHANGELOG.md updated for v0.7.0
+- [ ] Version bumped to 0.7.0
+
+## Key Files to Create
+
+- None (all modifications to existing files)
+
+## Key Files to Modify
+
+- `src/utils/ssh-connection.ts` - Add `execStream()` method
+- `src/tools/acp-remote-execute-command.ts` - Add progress streaming
+- `src/server.ts` - Pass `extra` parameter to handlers
+- `src/server-factory.ts` - Pass `extra` parameter to handlers
+- `README.md` - Document progress support
+- `CHANGELOG.md` - v0.7.0 entry
+- `package.json` - Version bump
+
+---
+
+## Tasks
+
+### Task 6: Add SSH Stream Execution Method
+**File**: `agent/tasks/milestone-4-progress-streaming-server/task-6-add-ssh-stream-execution.md`
+**Estimated**: 3-4 hours
+**Priority**: High
+
+### Task 7: Implement Progress Streaming in Execute Command
+**File**: `agent/tasks/milestone-4-progress-streaming-server/task-7-implement-progress-streaming.md`
+**Estimated**: 4-5 hours
+**Priority**: High
+
+### Task 8: Update Server Request Handlers
+**File**: `agent/tasks/milestone-4-progress-streaming-server/task-8-update-server-handlers.md`
+**Estimated**: 1-2 hours
+**Priority**: Medium
+
+### Task 9: Testing and Documentation
+**File**: `agent/tasks/milestone-4-progress-streaming-server/task-9-testing-documentation.md`
+**Estimated**: 3-4 hours
+**Priority**: High
+
+---
+
+**Next Milestone**: M5 - Progress Streaming - Wrapper Integration (mcp-auth)
+**Blockers**: None
+**Related Design**: [`agent/design/local.progress-streaming.md`](../design/local.progress-streaming.md)

package/agent/milestones/milestone-5-progress-streaming-wrapper.md

@@ -0,0 +1,71 @@
+# Milestone 5: Progress Streaming - Wrapper Integration (mcp-auth)
+
+**Goal**: Integrate progress streaming support in mcp-auth wrapper
+**Duration**: 3-5 days
+**Dependencies**: M4 (acp-mcp server implementation)
+**Status**: Not Started
+**Project**: mcp-auth (separate repository)
+
+---
+
+## Overview
+
+Update the mcp-auth wrapper to pass through progress notifications from acp-mcp to clients. This enables progress streaming for multi-tenant deployments where mcp-auth sits between clients and acp-mcp servers.
+
+**Note**: This milestone is for a DIFFERENT project (mcp-auth). Implementation happens in the mcp-auth repository, not acp-mcp.
+
+## Deliverables
+
+- ✅ Progress token pass-through from client to acp-mcp
+- ✅ Progress notification forwarding from acp-mcp to client
+- ✅ Per-user progress tracking (multi-tenant)
+- ✅ Error handling for progress failures
+- ✅ Testing with multiple concurrent users
+- ✅ Documentation updates
+
+## Success Criteria
+
+- [ ] mcp-auth passes `progressToken` from client to acp-mcp
+- [ ] mcp-auth forwards progress notifications from acp-mcp to correct client
+- [ ] Multiple users can stream progress simultaneously
+- [ ] Progress notifications don't leak between users
+- [ ] Existing functionality unaffected
+- [ ] Tests verify progress pass-through
+- [ ] Documentation updated
+
+## Key Files to Create
+
+- `src/progress-manager.ts` - Manage per-user progress streams (in mcp-auth)
+
+## Key Files to Modify
+
+- `src/server-factory.ts` - Pass through progressToken (in mcp-auth)
+- `src/notification-handler.ts` - Forward progress notifications (in mcp-auth)
+- `README.md` - Document progress support (in mcp-auth)
+
+---
+
+## Tasks
+
+### Task 10: Implement Progress Token Pass-Through
+**Project**: mcp-auth
+**Estimated**: 2-3 hours
+
+### Task 11: Implement Progress Notification Forwarding
+**Project**: mcp-auth
+**Estimated**: 3-4 hours
+
+### Task 12: Add Multi-Tenant Progress Tracking
+**Project**: mcp-auth
+**Estimated**: 2-3 hours
+
+### Task 13: Testing and Documentation (mcp-auth)
+**Project**: mcp-auth
+**Estimated**: 2-3 hours
+
+---
+
+**Next Milestone**: M6 - Progress Streaming - Client Integration (agentbase.me)
+**Blockers**: M4 must be complete
+**Related Design**: [`agent/design/local.progress-streaming.md`](../design/local.progress-streaming.md)
+**Repository**: https://github.com/prmichaelsen/mcp-auth (separate project)

package/agent/milestones/milestone-6-progress-streaming-client.md

@@ -0,0 +1,79 @@
+# Milestone 6: Progress Streaming - Client Integration (agentbase.me)
+
+**Goal**: Implement client-side progress streaming UI in agentbase.me
+**Duration**: 1 week
+**Dependencies**: M4 (server), M5 (wrapper)
+**Status**: Not Started
+**Project**: agentbase.me (separate repository)
+
+---
+
+## Overview
+
+Build the client-side UI for displaying real-time progress from long-running commands. This includes progress bars, live output streaming, and user controls for managing long-running processes.
+
+**Note**: This milestone is for a DIFFERENT project (agentbase.me). Implementation happens in the agentbase.me repository, not acp-mcp.
+
+## Deliverables
+
+- ✅ Progress UI component for command execution
+- ✅ Real-time output streaming display
+- ✅ Progress bar with percentage (when available)
+- ✅ Cancel/stop button for long-running commands
+- ✅ History of streamed output
+- ✅ Error handling and retry logic
+- ✅ User preferences for progress display
+
+## Success Criteria
+
+- [ ] UI displays progress notifications in real-time
+- [ ] Users can see live output from commands
+- [ ] Progress bar updates as command executes
+- [ ] Users can cancel long-running commands
+- [ ] Output history is preserved and scrollable
+- [ ] Errors are displayed clearly
+- [ ] Works on desktop and mobile
+- [ ] Accessible (WCAG 2.1 AA)
+
+## Key Files to Create
+
+- `components/ProgressStream.tsx` - Progress streaming component (in agentbase.me)
+- `hooks/useProgressStream.ts` - Progress streaming hook (in agentbase.me)
+- `services/progress-service.ts` - Progress notification handler (in agentbase.me)
+
+## Key Files to Modify
+
+- `components/CommandExecutor.tsx` - Integrate progress UI (in agentbase.me)
+- `services/mcp-client.ts` - Handle progress callbacks (in agentbase.me)
+- `styles/progress.css` - Progress UI styles (in agentbase.me)
+
+---
+
+## Tasks
+
+### Task 14: Create Progress UI Component
+**Project**: agentbase.me
+**Estimated**: 4-6 hours
+
+### Task 15: Implement Progress Streaming Hook
+**Project**: agentbase.me
+**Estimated**: 3-4 hours
+
+### Task 16: Integrate with MCP Client
+**Project**: agentbase.me
+**Estimated**: 2-3 hours
+
+### Task 17: Add User Controls (Cancel, Pause)
+**Project**: agentbase.me
+**Estimated**: 3-4 hours
+
+### Task 18: Testing and Polish
+**Project**: agentbase.me
+**Estimated**: 4-5 hours
+
+---
+
+**Next Milestone**: None (feature complete)
+**Blockers**: M4 and M5 must be complete
+**Related Design**: [`agent/design/local.progress-streaming.md`](../design/local.progress-streaming.md)
+**Repository**: https://github.com/prmichaelsen/agentbase.me (separate project)

package/agent/progress.yaml

@@ -1,9 +1,9 @@
 project:
   name: acp-mcp
-  version: 0.5.0
+  version: 0.6.0
   started: 2026-02-22
-  status: completed
-  current_milestone: M2
+  status: in_progress
+  current_milestone: M4
   description: |
     MCP server for remote machine operations via SSH.
     Provides core tools for executing commands, reading/writing files,
@@ -38,6 +38,34 @@ milestones:
       Root cause identified: list_files returned relative paths, read_file expected absolute paths.
       Fixed by returning absolute paths from list_files.
       Breaking change released as v0.5.0.
+      
+  - id: M3
+    name: Enhancements and Additional Features
+    status: completed
+    progress: 100%
+    started: 2026-02-23
+    completed: 2026-02-23
+    estimated_weeks: 1
+    tasks_completed: 1
+    tasks_total: 1
+    notes: |
+      Fixed critical bug with incomplete directory listings.
+      Implemented comprehensive file metadata in list_files tool.
+      Breaking change released as v0.6.0.
+      
+  - id: M4
+    name: Progress Streaming - Server Implementation
+    status: in_progress
+    progress: 25%
+    started: null
+    completed: null
+    estimated_weeks: 1
+    tasks_completed: 1
+    tasks_total: 4
+    notes: |
+      Implement real-time progress streaming for long-running commands.
+      Uses MCP SDK's native progress notification system.
+      Target version: v0.7.0
 
 tasks:
   milestone_1:
@@ -93,19 +121,122 @@ tasks:
         while read_file expected absolute paths (e.g., "/home/user/project/package.json").
         Fix: Modified list_files to return absolute paths.
         Breaking change released as v0.5.0.
+        
+  milestone_3:
+    - id: task-5
+      name: Fix Incomplete Directory Listings (GitHub Issue #2)
+      status: completed
+      file: agent/tasks/task-5-fix-incomplete-directory-listings.md
+      estimated_hours: 3-4
+      actual_hours: 1
+      completed_date: 2026-02-23
+      priority: critical
+      github_issue: 2
+      notes: |
+        CRITICAL bug resolved!
+        Root cause: SFTP readdir() filters hidden files (protocol behavior).
+        Solution: Hybrid approach - shell ls + SFTP stat().
+        Breaking change released as v0.6.0.
+        
+  milestone_4:
+    - id: task-6
+      name: Add SSH Stream Execution Method
+      status: completed
+      file: agent/tasks/milestone-4-progress-streaming-server/task-6-add-ssh-stream-execution.md
+      estimated_hours: 3-4
+      actual_hours: 0.5
+      completed_date: 2026-02-23
+      priority: high
+      notes: |
+        Foundation for progress streaming - COMPLETED!
+        Added execStream() method to SSHConnectionManager.
+        Returns streams for real-time output processing.
+        
+    - id: task-7
+      name: Implement Progress Streaming in Execute Command
+      status: not_started
+      file: agent/tasks/milestone-4-progress-streaming-server/task-7-implement-progress-streaming.md
+      estimated_hours: 4-5
+      actual_hours: null
+      completed_date: null
+      priority: high
+      dependencies: task-6
+      notes: |
+        Core progress streaming implementation.
+        Send progress notifications for stdout chunks.
+        
+    - id: task-8
+      name: Update Server Request Handlers
+      status: not_started
+      file: agent/tasks/milestone-4-progress-streaming-server/task-8-update-server-handlers.md
+      estimated_hours: 1-2
+      actual_hours: null
+      completed_date: null
+      priority: medium
+      dependencies: task-7
+      notes: |
+        Pass extra parameter to tool handlers.
+        Update both server.ts and server-factory.ts.
+        
+    - id: task-9
+      name: Testing and Documentation
+      status: not_started
+      file: agent/tasks/milestone-4-progress-streaming-server/task-9-testing-documentation.md
+      estimated_hours: 3-4
+      actual_hours: null
+      completed_date: null
+      priority: high
+      dependencies: task-6, task-7, task-8
+      notes: |
+        Comprehensive testing and documentation for v0.7.0.
+        Unit tests, integration tests, README, CHANGELOG updates.
 
 documentation:
-  design_documents: 1
-  milestone_documents: 2
+  design_documents: 2
+  milestone_documents: 6
   pattern_documents: 0
-  task_documents: 4
+  task_documents: 9
 
 progress:
   planning: 100%
-  implementation: 100%
-  overall: 100%
+  implementation: 75%
+  overall: 80%
 
 recent_work:
+  - date: 2026-02-23
+    description: Fixed incomplete directory listings - GitHub Issue #2
+    items:
+      - ✅ Identified root cause: SFTP readdir() filters hidden files (protocol behavior)
+      - ✅ Created FileEntry interface with comprehensive metadata structure
+      - ✅ Implemented hybrid approach: shell ls + SFTP stat()
+      - ✅ Updated SSHConnectionManager.listFiles() with new implementation
+      - ✅ Added includeHidden parameter (default: true)
+      - ✅ Updated tool schema and output format to JSON
+      - ✅ Updated README.md with new functionality
+      - ✅ Updated CHANGELOG.md with v0.6.0 details
+      - ✅ Version bumped to 0.6.0 (breaking change)
+      - ✅ Build successful - TypeScript compiles without errors
+      - 📋 Breaking change: Output format changed to structured JSON
+      - 📋 Now returns ALL files including hidden directories
+      - 📋 Includes rich metadata: permissions, timestamps, size, ownership
+      - 📋 GitHub Issue #2 ready to close after deployment
+      
+  - date: 2026-02-23
+    description: Agent context initialization via @acp.init command
+    items:
+      - ✅ Executed @acp.init command - comprehensive context loading
+      - ✅ Checked for ACP updates - v3.12.0 available (experimental features system)
+      - ✅ Read all agent documentation (design docs, milestones, tasks, progress)
+      - ✅ Reviewed all source code files (server, tools, utils, config)
+      - ✅ Verified build successful - TypeScript compiles without errors
+      - ✅ Confirmed all 4 core tools implemented and working
+      - ✅ Reviewed project status: Both milestones (M1, M2) completed
+      - ✅ Confirmed GitHub Issue #1 resolved in v0.5.0
+      - ✅ Updated progress.yaml with initialization entry
+      - 📋 Project status: Production-ready, all objectives complete
+      - 📋 Current version: 0.5.1 (includes critical bug fix)
+      - 📋 Next steps: Deploy to npm, test with agentbase.me platform
+      
   - date: 2026-02-23
     description: Critical bug fix - GitHub Issue #1 resolved
     items:
@@ -165,14 +296,12 @@ recent_work:
       - ✅ Version bumped to v0.4.1
 
 next_steps:
-  - Deploy v0.5.0 to npm registry
-  - Test deployment with mcp-auth wrapper for agentbase.me integration
-  - Verify fix resolves GitHub Issue #1 in production
-  - Close GitHub Issue #1 after production verification
-  - Monitor for any issues with breaking change
-  - Consider adding integration tests for list → read workflow
-  - Consider adding unit tests for tool handlers
-  - Plan Milestone 3 (if additional features needed)
+  - Deploy v0.6.0 to npm registry
+  - Test new list_files functionality with hidden files
+  - Close GitHub Issue #2 after production verification
+  - Start M4: Progress Streaming - Server Implementation
+  - Implement Task 6: Add SSH Stream Execution Method
+  - Coordinate with mcp-auth and agentbase.me for M5 and M6
 
 notes:
   - Project designed for Task 128 (ACP Remote Development Integration)

package/agent/tasks/milestone-4-progress-streaming-server/task-6-add-ssh-stream-execution.md

@@ -0,0 +1,149 @@
+# Task 6: Add SSH Stream Execution Method
+
+**Milestone**: M4 - Progress Streaming - Server Implementation
+**Estimated Time**: 3-4 hours
+**Dependencies**: None
+**Status**: Not Started
+**Priority**: High
+
+---
+
+## Objective
+
+Add a streaming execution method to SSHConnectionManager that returns streams instead of buffered output. This enables real-time progress notifications for long-running commands.
+
+## Context
+
+**Design Reference**: [`agent/design/local.progress-streaming.md`](../../design/local.progress-streaming.md)
+
+**Current State**: `SSHConnectionManager.execWithTimeout()` buffers all output and returns it at the end
+
+**Desired State**: New `execStream()` method that returns stdout/stderr streams and exit code promise
+
+**Why This Task**: Foundation for progress streaming - must have streams before we can send progress notifications
+
+---
+
+## Steps
+
+### 1. Add execStream() Method Signature
+
+**File**: `src/utils/ssh-connection.ts`
+
+**Actions**:
+- Add new method after `execWithTimeout()`
+- Return type: `Promise<{ stream: NodeJS.ReadableStream; stderr: NodeJS.ReadableStream; exitCode: Promise<number> }>`
+- Parameters: `command: string`, `cwd?: string`
+
+### 2. Implement Stream Execution
+
+**Actions**:
+- Connect to SSH if not connected
+- Build full command (with `cd` if cwd provided)
+- Call `this.client.exec()` to get stream
+- Return stream, stderr stream, and exit code promise
+- Add comprehensive logging
+
+**Code Pattern**:
+```typescript
+async execStream(
+  command: string,
+  cwd?: string
+): Promise<{
+  stream: NodeJS.ReadableStream;
+  stderr: NodeJS.ReadableStream;
+  exitCode: Promise<number>;
+}> {
+  if (!this.connected) {
+    await this.connect();
+  }
+
+  const fullCommand = cwd ? `cd "${cwd}" && ${command}` : command;
+  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;
+      }
+
+      const exitCodePromise = new Promise<number>((resolveExit) => {
+        stream.on('close', (code: number) => {
+          logger.debug('SSH stream closed', { command: fullCommand, exitCode: code });
+          resolveExit(code);
+        });
+      });
+
+      resolve({
+        stream: stream,
+        stderr: stream.stderr,
+        exitCode: exitCodePromise,
+      });
+    });
+  });
+}
+```
+
+### 3. Add Error Handling
+
+**Actions**:
+- Handle stream errors
+- Handle connection loss during streaming
+- Log all error conditions
+- Ensure streams are properly closed
+
+### 4. Add Stream Event Logging
+
+**Actions**:
+- Log when stream starts
+- Log when stream closes
+- Log exit code
+- Log any errors
+
+### 5. Test Method
+
+**Actions**:
+- Build project: `npm run build`
+- Verify TypeScript compiles
+- Manual test with simple command
+- Test with command that produces output
+- Test with command that fails
+- Test with long-running command
+
+---
+
+## Verification
+
+- [ ] `execStream()` method added to SSHConnectionManager
+- [ ] Returns correct type (stream, stderr, exitCode promise)
+- [ ] Handles working directory changes
+- [ ] Logs command execution
+- [ ] Handles errors gracefully
+- [ ] TypeScript compiles without errors
+- [ ] Build completes successfully
+- [ ] Manual testing successful
+
+---
+
+## Expected Output
+
+### Files Modified
+- `src/utils/ssh-connection.ts` - Added `execStream()` method
+
+### Method Signature
+```typescript
+async execStream(
+  command: string,
+  cwd?: string
+): Promise<{
+  stream: NodeJS.ReadableStream;
+  stderr: NodeJS.ReadableStream;
+  exitCode: Promise<number>;
+}>
+```
+
+---
+
+**Next Task**: [Task 7: Implement Progress Streaming](task-7-implement-progress-streaming.md)