# ElizaOS Developer Update: August 13, 2025

## Core Framework

We're excited to share significant progress on ElizaOS v3 development, with major architectural improvements now in the works. CJ (cjft) has made substantial advancements, including streamlined directory structure and dramatically faster build times (down to 75ms).

Shaw has outlined key first principles for v3:
- Better developer experience
- Easier production deployment
- Improved tool calling
- Streaming-oriented design
- More opinionated architecture with less modularity

We're addressing the most critical architectural decisions:
```typescript
// Current debate on directory structure
// Option 1: /packages (monorepo style)
// Option 2: /lib (more consolidated)

// Current debate on action organization
// Option 1: /actions (current)
// Option 2: /tools (proposed)
```

We're also proposing to separate message server architecture from agent implementation using websockets instead of socket.io for improved performance. This will include creating dedicated `message-client` and `message-server` packages to enable containerization.

## New Features

### Sessions API

We've completed integration of the new Sessions API via PR #5717, providing a simplified interface for messaging between users and agents. This API abstracts away the complexity of servers, channels, and participants.

```typescript
// Example usage of the new Sessions API
const session = await client.sessions.create({
  agentId: "agent-uuid",
  userId: "user-uuid",
  metadata: { context: "customer-support" }
});

// Send a message in the session
await client.sessions.sendMessage(session.id, {
  content: "Can you help me with my order?",
  type: "text"
});

// Get all messages in a session
const messages = await client.sessions.getMessages(session.id);
```

### Context Caching

We're implementing context caching for autonomous agents to improve performance, as Shaw mentioned in the core-devs discussion:

```typescript
// Planned implementation for context caching
export class ContextCache {
  private cache: Map<string, CachedContext> = new Map();
  
  getContext(key: string): CachedContext | undefined {
    return this.cache.get(key);
  }
  
  storeContext(key: string, context: CachedContext): void {
    this.cache.set(key, context);
  }
  
  invalidate(key: string): void {
    this.cache.delete(key);
  }
}
```

### Benchmarking System

We're working on implementing comprehensive benchmarking tools for agent performance using:
- TAU-bench
- AgentBench
- Typewriter tests

Cjft has started this work by creating the `plugin-action-bench` repository to objectively measure framework performance beyond just the underlying model capabilities.

## Bug Fixes

### Agent Startup Issues

A critical issue was identified with `startAgent` hanging when `@elizaos/plugin-bootstrap` is omitted or included (Issue #5719). This appears to be a regression introduced after commit `d84963e`.

The issue manifests in two ways:
1. Without bootstrap plugin: Hangs early (before plugin dependency resolution)
2. With bootstrap plugin: Hangs after bootstrap plugin finishes loading

```bash
# Log when hanging without bootstrap plugin
[2025-08-04 02:47:47] INFO: [startAgent] Step 1 – Starting agent initialization
[2025-08-04 02:47:47] INFO: [startAgent] Step 2 – Character ID set
[2025-08-04 02:47:47] INFO: [startAgent] Step 3 – Checking character secrets
[2025-08-04 02:47:47] INFO: [startAgent] Step 3c – Character already has secrets
[2025-08-04 02:47:47] INFO: [startAgent] Step 4 – Initializing plugin loading
[2025-08-04 02:47:47] INFO: [startAgent] Step 4a – SQL plugin loaded
[2025-08-04 02:47:47] INFO: [startAgent] Step 4b – Character plugins: ["@elizaos/plugin-e2b","@elizaos/plugin-openai"]
# ... nothing further – process hangs here ...
```

This is a high-priority issue affecting scenario runners and CLI operations.

### Database Constraint Issues

The team has resolved a database constraint error with `plugin-mysql` by identifying that version 1.3.6 works without the error. Odilitime tested different versions to find the solution.

### Plugin-Related Fixes

We've addressed several plugin issues:
- Fixed CLI-based plugin publishing (mentioned by 0x8664)
- Resolved a leaked API key in a repository (identified by Shaw)
- Added support for `plugin-mysql` in PR #5718, allowing it to work alongside `plugin-sql`

## API Changes

### New Validate Function Requirements

A debate has emerged about the `validate` function for actions:

Shaw suggested making it optional to reduce boilerplate, while Odilitime argued for keeping it mandatory to ensure developers properly limit available actions:

```typescript
// Current implementation (mandatory)
export const myAction = defineAction({
  name: 'myAction',
  description: 'Performs an important task',
  parameters: z.object({
    param1: z.string().describe('First parameter'),
  }),
  validate: async (runtime, params) => {
    // Validation logic
    return true;
  },
  handler: async (runtime, params) => {
    // Action implementation
  }
});
```

### Agent Command Authentication

PR #5709 has added comprehensive authentication support to CLI agent commands, integrating the existing `@elizaos/api-client` package. This has standardized error handling for invalid agent IDs:

```typescript
try {
  const agentId = asUUID(resolvedAgentId);
  // Agent operations
} catch (error) {
  throw new Error(`Invalid agent ID format: ${resolvedAgentId}. Please provide a valid UUID, agent name, or index.`);
}
```

## Social Media Integrations

### Twitter/X Account Status

The team is actively working to restore the suspended ElizaOS Twitter account (@elizawakesup). Kenk noted "we've had the solution reaffirmed and it continues to remain positive with their team."

While waiting for account restoration, the team is implementing a multi-channel content strategy across:
- Farcaster
- LinkedIn
- TikTok
- YouTube

### Integration Issues

Users are experiencing several integration issues:
- Twitter rate limiting after reconfiguring agents (reported by Rabbidfly)
- Telegram bot conflict errors (409: Conflict) when multiple instances run simultaneously (reported by Tim1Echo)
- Twitter plugin compatibility issues with newer Eliza versions (mentioned by DJ L)

## Model Provider Updates

### OpenAI API Issues

Samuel Chauche reported an OpenAI API 500 error when connecting Eliza with Gaianet. 0xbbjoker suggested using `plugin-mcp` with Firecrawl as a solution:

```bash
# Recommended approach for web search
npm install @elizaos/plugin-mcp
# Then configure to use with Firecrawl instead of Tavily
```

The benefit of Firecrawl over Tavily API is that it can be self-hosted and offers more control over the search process.

## Breaking Changes

### V2 to V3 Migration Notes

As we transition toward v3, Shaw highlighted that tool calling is currently our "biggest weakness" - the emphasis on character and personality adds noise that makes the system worse at direct tasks like code agent functions.

The v3 architecture will address this by:
1. Separating message server from agent implementation 
2. Moving to websockets for communication
3. Adopting a more streaming-oriented design
4. Creating a message-client and message-server package

Note that these architectural changes will require adaptation in how agents are implemented and deployed. We'll provide comprehensive migration guides as we approach the v3 release.

For developers working with v2, please be aware that some v1 plugins (particularly Twitter) are no longer compatible with newer versions. We're working to restore this functionality.