# ElizaOS Developer Update - Week of June 4, 2025

## Core Framework

The ElizaOS framework has undergone significant architectural improvements this week, enhancing modularity and performance:

- **Message Server Refactoring**: The message server has been completely refactored to operate independently from agents, creating a more modular architecture. This significant change affects how agents interact with messages and provides better separation of concerns. ([PR #4864](https://github.com/elizaos/eliza/pull/4864))

- **Plugin Specification System**: Core now includes plugin specifications, enabling future plugin migration without modifying code outside of core. This lays the groundwork for V2 to V1 compatibility and makes plugin development more consistent. ([PR #4851](https://github.com/elizaos/eliza/pull/4851))

- **Server Sync Optimization**: A new efficient method for handling server synchronization has been proposed, particularly important for large installations with many entities (such as the ai16z Discord server with 23k entities). ([PR #4896](https://github.com/elizaos/eliza/pull/4896))

- **Database Enhancements**: Fixed foreign key issues in chat messages that were breaking message sending functionality. The framework also now cleans `.elizadb` and `.eliza` directories during cleanup operations to prevent database corruption. ([PR #4898](https://github.com/elizaos/eliza/pull/4898), [PR #4910](https://github.com/elizaos/eliza/pull/4910))

## New Features

### macOS Setup Guide

A comprehensive macOS development setup guide has been added to help developers get started with ElizaOS on Apple systems:

```bash
# Example installation command for macOS
brew install bun node postgresql@14

# Verify installations
bun --version
node --version
postgres --version

# Clone and setup ElizaOS
git clone https://github.com/elizaos/eliza.git
cd eliza
bun install
```

The guide includes troubleshooting steps for common macOS-specific issues and explains how to set up local databases correctly. ([PR #4903](https://github.com/elizaos/eliza/pull/4903))

### TEE Starter Project Creation

Added TEE (Trusted Execution Environment) starter project creation to the CLI, expanding secure computing options:

```bash
# Create a new TEE project
npx elizaos create -t tee my-secure-project
cd my-secure-project
npx elizaos dev
```

This enables developers to build agents with enhanced security guarantees for sensitive operations. ([PR #4830](https://github.com/elizaos/eliza/pull/4830))

### Alethea AI Plugin Structure

Initialized the Alethea AI Plugin Structure and Configuration, providing a new AI provider integration:

```javascript
import { Alethea } from '@elizaos-plugins/plugin-alethea';

// Example configuration
const alethea = new Alethea({
  apiKey: process.env.ALETHEA_API_KEY,
  modelId: 'alethea-default'
});

// Generate content
const result = await alethea.generateContent({
  prompt: 'Explain quantum computing in simple terms'
});
```

This expands the available AI capabilities within the ElizaOS ecosystem. ([PR #4902](https://github.com/elizaos/eliza/pull/4902))

## Bug Fixes

### Twitter Plugin Issues

The Twitter plugin has received significant attention due to several reported issues:

- Fixed Cloudflare blocking with release v1.0.1, followed by v1.0.2 with additional improvements
- Resolved issues with Twitter activity detection that prevented agent responses to mentions
- Fixed undefined property errors that were causing maximum call stack size exceeded errors

Users should update to the latest version with:

```bash
npx elizaos plugins update @elizaos-plugins/plugin-twitter
```

Note that versions before v1.0.2 may not be compatible with older ElizaOS versions. ([Issues #4272](https://github.com/elizaos/eliza/issues/4272), [#4588](https://github.com/elizaos/eliza/issues/4588))

### Plugin System Improvements

- Fixed plugin auto-import when starting from a plugin directory, improving developer workflow ([PR #4900](https://github.com/elizaos/eliza/pull/4900))
- Resolved workspace dependencies in plugin loading to ensure correct package resolution ([PR #4905](https://github.com/elizaos/eliza/pull/4905))
- Removed unnecessary Telegram and Discord config requirements from plugin templates ([Issue #4872](https://github.com/elizaos/eliza/issues/4872))

### Choice Action Validation

Fixed choice action validation to return false instead of throwing errors during validation, providing more graceful error handling:

```javascript
// Before fix (would throw error)
if (!isValidChoice(choice)) throw new Error('Invalid choice');

// After fix (returns false, allowing graceful handling)
if (!isValidChoice(choice)) return false;
```

This prevents crashes in UI interfaces when invalid choices are encountered. ([PR #4904](https://github.com/elizaos/eliza/pull/4904))

## API Changes

### New Room API Endpoint

Added missing GET `/agents/:agentId/rooms/:roomId` API endpoint, addressing a gap in the API surface:

```javascript
// Example usage
const roomInfo = await fetch(`/api/agents/${agentId}/rooms/${roomId}`)
  .then(res => res.json());

// Returns room details including participants, messages, and metadata
console.log(`Room name: ${roomInfo.name}`);
console.log(`Participant count: ${roomInfo.participants.length}`);
```

This enables developers to build more sophisticated UIs that need detailed room information. ([PR #4860](https://github.com/elizaos/eliza/pull/4860))

### Enhanced Core Package Build Process

Refactored the core package's build process for improved modularity and maintainability:

- Added dedicated entry points for different API versions
- Updated the build configuration to use `tsup` for all build tasks
- Enabled declaration maps for better TypeScript developer experience

These changes don't affect the API surface but improve how developers can interact with core package exports. ([PR #4874](https://github.com/elizaos/eliza/pull/4874))

## Social Media Integrations

### Twitter Plugin Updates

The Twitter plugin has received substantial updates to fix critical issues:

- Fixed cookie handling and added better TypeScript support
- Improved handling of "Cannot read properties of undefined (reading 'id_str')" error
- Added comprehensive documentation on using `TWITTER_TARGET_USERS`, `TWITTER_POST_INTERVAL_MIN/MAX` environment variables

```javascript
// Updated environment variables for Twitter plugin
TWITTER_TARGET_USERS=user1,user2
TWITTER_POST_INTERVAL_MIN=5 // minutes
TWITTER_POST_INTERVAL_MAX=60 // minutes
ACTION_PROCESSING=enabled
ACTION_INTERVAL=15 // minutes
```

The plugin now more reliably detects mentions and can interact with target users more consistently. ([PR #4883](https://github.com/elizaos/eliza/pull/4883))

### Discord Integration

Fixed Discord client behavior with ignoring messages, implementing a more intelligent filtering approach:

```javascript
// Configure Discord behavior in settings
settings: { 
  discord: { 
    shouldIgnoreBotMessages: true,
    shouldRespond: {
      bypassTypes: ['DIRECT_MESSAGE', 'MENTION']
    }
  }
}
```

This improvement helps prevent spam while ensuring important messages are still processed. ([PR #4844](https://github.com/elizaos/eliza/pull/4844))

## Model Provider Updates

### Optimized Embedding Generation

Enhanced the embedding model initialization and usage flow:

```
[2025-06-02 08:22:47] INFO: Model already exists at: /home/user/.eliza/models/bge-small-en-v1.5.Q4_K_M.gguf
[2025-06-02 08:22:48] INFO: Embedding model initialized successfully
[2025-06-02 08:22:48] INFO: Generating embedding for text
    textLength: 18
[2025-06-02 08:22:48] INFO: Embedding generation complete
    dimensions: 384
```

Fixed issues with local model functionality in plugin development that were causing parsing errors. ([Issue #4339](https://github.com/elizaos/eliza/issues/4339))

## Breaking Changes

### V1 to V2 Migration Issues

ElizaOS V2 has been quietly released (versions 1.0.0-1.0.2) but not officially announced yet. The team is preparing for a full V2 announcement next week. Here are important migration considerations:

1. **Plugin Migration Path**: Many plugins require updating to work with V2:

   ```bash
   # Update ElizaOS and plugin dependencies
   npx elizaos update
   ```

2. **Deprecated Methods**: Replace `updateRecentMessageState` with `runtime.composeState`:

   ```javascript
   // Old V1 approach
   const updateRecentMessageState = runtime.getMethod('updateRecentMessageState');
   await updateRecentMessageState(message);

   // New V2 approach
   await runtime.composeState({
     provider: 'recentMessages',
     message: message
   });
   ```

3. **Database Changes**: V2 uses a different database structure. When migrating, you may need to clear your database:

   ```bash
   # Clean up old database files
   rm -rf .elizadb .eliza
   ```

4. **Plugin Compatibility**: Plugins created for V1 may not work with V2. Use the plugin-specification from core to ensure compatibility:

   ```javascript
   // Import V2 plugin specification
   import { Plugin } from '@elizaos/core/v2';
   
   // Create V2-compatible plugin
   export class MyPlugin extends Plugin {
     // Plugin implementation
   }
   ```

The team is actively working on "The Org" - a multi-agent system within the ElizaOS ecosystem - which will be part of the upcoming V2 full release.