# ElizaOS Developer Update - September 5, 2025

## 1. Core Framework

This week brought significant architectural changes to ElizaOS core, highlighted by a major refactoring effort to improve code organization and developer experience:

- **Architectural Refactoring**: Centralized business logic from CLI to server package, creating a new `ElizaOS` orchestration class with dedicated managers for Agent, Plugin, and Config. This reduced code duplication and established cleaner separation of concerns ([PR #5864](https://github.com/elizaos/eliza/pull/5864)).

- **Version Management System**: Implemented a standardized versioning system where the develop branch uses alpha versions (1.5.8-alpha.x) while the main branch uses beta versions, ensuring consistent package synchronization across the framework ([Discord](https://discord.com/channels/1253563209462448241/1377726087789940836)).

- **Build System Improvements**: 
  - Updated Bun to version 1.2.21 across the entire monorepo ([PR #5874](https://github.com/elizaos/eliza/pull/5874))
  - Unified NPM release workflows with an alpha pattern for better release reliability ([PR #5877](https://github.com/elizaos/eliza/pull/5877))
  - Added automated testing for published alpha CLI versions ([PR #5873](https://github.com/elizaos/eliza/pull/5873))

- **Improved Core Debugging**: Embedded CLI version into build output for easier debugging ([PR #5869](https://github.com/elizaos/eliza/pull/5869)) and fixed logger debug level and styling for better readability ([PR #5849](https://github.com/elizaos/eliza/pull/5849)).

## 2. New Features

### Standalone CLI Chat Interface

```typescript
// examples/standalone-cli-chat.ts
import { createClient, createStorage, createRuntime } from "@elizaos/core";
import { getPluginBootstrap } from "@elizaos/plugin-bootstrap";
import { getPluginOpenAI } from "@elizaos/plugin-openai";

// Configure options
const options = {
  LOG_LEVEL: process.env.LOG_LEVEL || "info",
  OPENAI_API_KEY: process.env.OPENAI_API_KEY
};

// Initialize runtime
const storage = createStorage();
const runtime = createRuntime({ storage });
const client = createClient({ runtime });

// Load plugins
runtime.use(getPluginBootstrap());
runtime.use(getPluginOpenAI({ apiKey: options.OPENAI_API_KEY }));

// Start interactive chat loop
console.log("Chat with ElizaOS (type 'exit' to quit)");
process.stdout.write("> ");

// Handle user input
process.stdin.on("data", async (data) => {
  const input = data.toString().trim();
  if (input.toLowerCase() === "exit" || input.toLowerCase() === "quit") {
    process.exit(0);
  }
  
  // Process message with ElizaOS
  const messageId = await client.sendMessage(input);
  
  // Wait for response
  process.stdout.write("> ");
});
```

### Real-time Action Execution UI

Added a comprehensive real-time action execution UI system that provides transparency into agent operations ([PR #5865](https://github.com/elizaos/eliza/pull/5865)):

- Interactive tool cards showing action execution details
- Live updates via WebSocket as actions progress through their lifecycle
- Input/output parameter visualization
- Error handling with clear error messages

```jsx
// Usage in chat component
{message.content.includes("ACTION_CALLED") && (
  <ActionTool
    action={actionData.action}
    inputs={actionData.inputs}
    outputs={actionData.outputs}
    status={actionData.status}
    error={actionData.error}
  />
)}
```

### Sentry Node Telemetry Support

Added Sentry integration with AI telemetry support for monitoring LLM interactions ([PR #5867](https://github.com/elizaos/eliza/pull/5867)):

```typescript
// Configuration example
const config = {
  SENTRY_DSN: "your-sentry-dsn",
  SENTRY_TRACE_FILTER: "ai-only", // or "all"
  OPENAI_EXPERIMENTAL_TELEMETRY: true
};

// Automatically captures:
// - AI SDK calls (generateText, streamText)
// - Input/output recording
// - Performance metrics (duration, success rates)
```

### Docker Support for Project Starter

Added Docker files to the project-starter template ([PR #5858](https://github.com/elizaos/eliza/pull/5858)), enabling seamless containerization and deployment:

```yaml
# docker-compose.yaml
version: '3'
services:
  elizaos:
    image: ${DOCKER_IMAGE}
    environment:
      - LOG_LEVEL=info
      - POSTGRES_URL=${POSTGRES_URL}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    ports:
      - "3000:3000"
      - "3001:3001"
```

## 3. Bug Fixes

### Critical GUI Loading Issue

A bug was identified in ElizaOS core 1.5.7 where the admin GUI wouldn't load due to "watcher watching test files" ([Discord](https://discord.com/channels/1253563209462448241/1300025221834739744)):

```
// Error in logs
[ERROR] Watcher error: watcher limit reached (system specific)
[ERROR] Admin GUI failed to load - dashboard unavailable
```

**Root cause**: The file watcher was incorrectly configured to include test files in the watch list, causing it to exceed system limits.

**Temporary solution**: Use the `start` command instead of `dev`:

```bash
elizaos start  # Use this instead of elizaos dev until fix is deployed
```

**Permanent fix**: A PR is in progress to properly exclude test files from the watcher configuration.

### Port Detection Issue

Fixed port detection for automatic fallback when the default port is already in use ([PR #5876](https://github.com/elizaos/eliza/pull/5876)):

```typescript
// Before: Failed when port 3000 was taken
// After: Automatically tries port 3001 when 3000 is unavailable
export async function checkPortAvailability(port: number, host: string): Promise<boolean> {
  return new Promise((resolve) => {
    const server = createServer();
    server.once('error', () => resolve(false));
    server.once('listening', () => {
      server.close(() => resolve(true));
    });
    server.listen(port, host);
  });
}
```

### Other Important Fixes

- Fixed crypto-browserify dependency issue that was causing runtime errors ([PR #5872](https://github.com/elizaos/eliza/pull/5872))
- Resolved TypeScript compilation errors by adding DOM types to configuration ([PR #5878](https://github.com/elizaos/eliza/pull/5878))
- Fixed unhandled promise rejection in action update ([PR #5870](https://github.com/elizaos/eliza/pull/5870))
- Fixed Discord image generation functionality to work properly in Discord channels ([PR #5861](https://github.com/elizaos/eliza/pull/5861))

## 4. API Changes

### New Orchestration APIs

The introduction of the `ElizaOS` orchestration class in the server package brings several new APIs:

```typescript
// New class-based API for ElizaOS orchestration
const elizaOS = new ElizaOS({
  configPath: "./config.json",
  plugins: ["@elizaos/plugin-openai", "@elizaos/plugin-bootstrap"]
});

// Start the server and initialize agents
await elizaOS.start();

// Access managers for specific functionality
const agent = elizaOS.agentManager.getAgent("myAgent");
const pluginInstance = elizaOS.pluginLoader.getPlugin("@elizaos/plugin-openai");
const config = elizaOS.configManager.getConfig();
```

### Action Lifecycle Events

Enhanced action lifecycle events with detailed payloads for better tracking and UI updates:

```typescript
// Subscribe to action lifecycle events
runtime.on('ACTION_STARTED', (data) => {
  console.log(`Action ${data.action} started with inputs:`, data.inputs);
});

runtime.on('ACTION_COMPLETED', (data) => {
  console.log(`Action ${data.action} completed with result:`, data.outputs);
});

// New message API for action updates
await messageBus.notifyActionStart({
  messageId: 'msg_123',
  agentId: 'agent_456',
  action: 'SEARCH_WEB',
  inputs: { query: 'ElizaOS documentation' }
});

await messageBus.notifyActionUpdate({
  messageId: 'msg_123',
  outputs: { results: [...] },
  status: 'completed'
});
```

## 5. Social Media Integrations

### Discord Plugin Fix

Fixed image generation capabilities in Discord channels ([PR #5861](https://github.com/elizaos/eliza/pull/5861)):

```typescript
// Before: Images weren't being properly attached to Discord messages
// After: Fixed attachment handling
export const imageGenerationAction: ActionDefinition = {
  name: "IMAGE_GENERATION",
  description: "Generate an image based on a prompt",
  parameters: {
    // ... parameter definitions
  },
  handler: async ({ inputs, runtime, agentId }) => {
    // ... image generation logic
    
    // Fixed Discord attachment handling
    if (message.source === "discord") {
      await runtime.events.emit("DISCORD_ATTACHMENT", {
        channelId: message.channelId,
        messageId: message.messageId,
        attachment: {
          filename: "generated-image.png",
          url: imageUrl,
          contentType: "image/png"
        }
      });
    }
    
    return { url: imageUrl };
  }
};
```

### Legal Update on X Integration

A legal case is ongoing between Eliza Labs and X Corporation, with X required to respond by September 19th ([Discord](https://discord.com/channels/1253563209462448241/1301363808421543988)). This is related to the previously suspended ElizaOS Twitter account, which has impacted the X integration functionality.

## 6. Model Provider Updates

### Protocol Standards Decision

After extensive debate between JSON-RPC, MCP (Model Context Protocol), and ACP (Agent Communication Protocol), the team has decided to standardize on JSON-RPC for agent-to-agent and agent-to-plugin communications ([Discord](https://discord.com/channels/1253563209462448241/1377726087789940836)).

### Bidirectional MCP Implementation

The team has implemented bidirectional communication in MCP by passing the agent's completion endpoint to MCP with a key in an init() tool. This allows for callbacks and real-time updates between components ([Discord](https://discord.com/channels/1253563209462448241/1377726087789940836)):

```typescript
// Implementation example for bidirectional MCP
const mcpClient = new MCPClient({
  endpoint: "https://api.example.com/mcp",
  callbacks: {
    completion: {
      endpoint: "https://myagent.example.com/api/completion",
      apiKey: "agent_callback_key_123"
    }
  }
});

// Initialize with callback capability
await mcpClient.init();

// Now MCP service can call back to the agent
```

### x402 Protocol Integration

ElizaOS is exploring integration with x402, a protocol for managing API payments using crypto wallets instead of API keys ([Discord](https://discord.com/channels/1253563209462448241/1377726087789940836)). This would allow agents to pay per request using cryptocurrency, eliminating the need for traditional API key management.

## 7. Breaking Changes

### Migration from CLI to Server Package

The refactoring of business logic from CLI to server package ([PR #5864](https://github.com/elizaos/eliza/pull/5864)) maintains backward compatibility but introduces changes for developers extending the CLI:

- If you've extended the CLI with custom commands using internal modules, update imports to reference the new server package locations
- Custom loaders need to be updated to work with the new `ElizaOS` orchestration class
- Plugin resolution now happens through the `PluginLoader` class rather than directly in CLI code

### Package Version Standardization

The version management system now enforces a strict pattern ([Discord](https://discord.com/channels/1253563209462448241/1377726087789940836)):

- Develop branch: Uses alpha versions (e.g., 1.5.8-alpha.0)
- Main branch: Uses beta versions (e.g., 1.5.8-beta.0)

If you're maintaining forks or custom builds, ensure you follow this pattern to prevent version conflicts.

### Note on Web UI Documentation

A significant issue was identified where the web UI dashboard is completely undocumented, causing confusion for new users ([Issue #5857](https://github.com/elizaos/eliza/issues/5857)). Until this is fixed in the official documentation, note that you can access the web interface at:

```
http://localhost:3001
```

Look for this line in the startup logs: "Go to the dashboard at http://localhost:3001"