agent-world 0.7.0 → 0.10.0

package/README.md

@@ -133,6 +133,44 @@ echo "hi" | npx agent-world -w default-world
 
 See [Project Structure Documentation](project.md)
 
+## Development Scripts Convention
+
+Agent World follows a consistent naming convention for all npm scripts:
+
+| Script Pattern | Description | Example |
+|---------------|-------------|---------|
+| `<module>` | Shorthand for `<module>:start` | `npm run server` |
+| `<module>:start` | Run compiled code from `dist/` | `npm run server:start` |
+| `<module>:dev` | Run with tsx (no build needed) | `npm run server:dev` |
+| `<module>:watch` | Run with tsx in watch mode | `npm run server:watch` |
+
+**Available modules:** `server`, `cli`, `ws`, `tui`
+
+**Module Dependencies:**
+- `web:dev` / `web:watch` → Depends on `server` (waits for server to be ready)
+- `tui:dev` / `tui:watch` → Depends on `ws` (waits for WebSocket server)
+
+**Examples:**
+```bash
+# Production execution (requires build)
+npm run server        # Runs: node dist/server/index.js
+npm run cli           # Runs: node dist/cli/index.js
+
+# Development (no build needed)
+npm run server:dev    # Runs: npx tsx server/index.ts
+npm run ws:dev        # Runs: npx tsx ws/index.ts
+
+# Watch mode (auto-restart on changes)
+npm run server:watch  # Runs: npx tsx --watch server/index.ts
+npm run cli:watch     # Runs: npx tsx --watch cli/index.ts
+
+# With dependencies (auto-start required services)
+npm run web:dev       # Waits for server, then starts web
+npm run web:watch     # Runs server:watch + web in parallel
+npm run tui:dev       # Waits for ws, then starts tui
+npm run tui:watch     # Runs ws:watch + tui in parallel
+```
+
 ### Environment Setup
 
 Export your API keys as environment variables 
@@ -149,13 +187,50 @@ export OLLAMA_BASE_URL="http://localhost:11434"
 
 Or create a `.env` file in your working directory with:
 
-```env
-OPENAI_API_KEY=your-key-here
-ANTHROPIC_API_KEY=your-key-here
-GOOGLE_API_KEY=your-key-here
-OLLAMA_BASE_URL=http://localhost:11434
+## Testing
+
+**Run all tests:**
+```bash
+npm test              # Run all unit tests
+npm run test:watch    # Watch mode with hot reload
+npm run test:ui       # Visual test UI
+npm run test:coverage # Generate coverage report
 ```
 
+**Run specific tests:**
+```bash
+npm test -- tests/core/events/  # Test a directory
+npm test -- message-saving      # Test files matching pattern
+```
+
+**Integration tests:**
+```bash
+npm run test:integration  # Run integration tests with real filesystem
+```
+
+Agent World uses Vitest for fast, modern testing with native TypeScript support.
+
+## Logging and Debugging
+
+Agent World uses **scenario-based logging** to help you debug specific issues without noise. Enable only the logs you need for your current task.
+
+### Quick Examples
+
+```bash
+# Database migration issues
+LOG_STORAGE_MIGRATION=info npm run server
+
+# MCP server problems  
+LOG_MCP=debug npm run server
+
+# Agent response debugging
+LOG_EVENTS_AGENT=debug LOG_LLM=debug npm run server
+```
+
+**For complete logging documentation**, see [Logging Guide](docs/logging-guide.md).
+
+## Learn More
+
 ### World Database Setup
 
 The worlds are stored in the SQLite database under the `~/agent-world` directory. You can change the database path by setting the environment variable `AGENT_WORLD_SQLITE_DATABASE`.
@@ -171,8 +246,27 @@ export AGENT_WORLD_DATA_PATH=./data/worlds
 ## Learn More
 
 - **[Building Agents with Just Words](docs/Building%20Agents%20with%20Just%20Words.md)** - Complete guide with examples
+- **[Shell Command Tool (shell_cmd)](docs/shell-cmd-tool.md)** - Built-in tool for executing shell commands
+- **[Using Core from npm](docs/core-npm-usage.md)** - Integration guide for server and browser apps
 
 
+## Built-in Tools
+
+Agent World includes built-in tools that are automatically available to all agents:
+
+### shell_cmd
+Execute shell commands with full output capture and execution history. Perfect for file operations, system information, and automation tasks.
+
+```typescript
+// Available to LLMs as 'shell_cmd' tool
+{
+  "command": "ls",
+  "parameters": ["-la", "/tmp"]
+}
+```
+
+See [Shell Command Tool Documentation](docs/shell-cmd-tool.md) for complete details.
+
 ## Experimental Features
 
 - **MCP Support** - *Currently in experiment* - Model Context Protocol integration for tools like search and code execution. e.g.,
@@ -215,4 +309,3 @@ MIT License - Build amazing things and share them with the world!
 
 Copyright © 2025 Yiyi Sun
 
-