agent-world 0.11.0 → 0.12.0

package/README.md

@@ -1,5 +1,11 @@
 # Agent World
 
+[![Latest Release](https://img.shields.io/github/v/release/yysun/agent-world?label=release)](https://github.com/yysun/agent-world/releases)
+
+<p align="center">
+	<img src="electron/assets/icons/agent-world-icon.svg" alt="Agent World Logo" width="120" />
+</p>
+
 *Build AI agent teams with just words—no coding required.*
 
 ## Why Agent World?
@@ -29,9 +35,28 @@ Paste that prompt. Agents come alive instantly.
 - ✅ No Code Required - Agents are defined entirely in natural language
 - ✅ Natural Communication - Agents understand context and conversations
 - ✅ Built-in Rules for Messages - Turn limits to prevent loops
-- ✅ Progressive Agent Skills - Skills are discovered and loaded on demand
+- ✅ Concurrent Chat Sessions - Isolated `chatId` routing enables parallel conversations
+- ✅ Progressive Agent Skills - Skills are discovered and loaded on demand via `load_skill`
+- ✅ Cross-Client HITL Approval - Option-based approvals in CLI, Web, and Electron
+- ✅ Runtime Controls - Session-scoped send/stop flows and tool lifecycle visibility
+- ✅ Safer Tool Execution - Trusted-CWD and argument-scope guards for `shell_cmd`
 - ✅ Multiple AI Providers - Use different models for different agents
-- ✅ Modern Web Interface - Clean, responsive UI with real-time chat
+- ✅ Web + CLI + Electron - Modern interfaces with real-time streaming and status feedback
+
+## Latest Highlights (since v0.11.1)
+
+- Web app now includes a Settings page, chat-history search, and branch-from-message workflow
+- Built-in `create_agent` tool now supports approval-first creation and inherits world chat defaults
+- File exploration is easier with built-in `read_file`, `list_files` (including recursive mode), and `grep`
+- Electron now supports folder-based world import/export with validation and conflict handling
+- Chat UX is smoother with clearer inline working status, better streaming feedback, and UI refinements
+- Real-time refresh behavior is improved across web and desktop when agents/world data changes
+
+## Release Notes
+
+- **v0.12.0** - Web settings/search/branching, built-in `create_agent`, new file tools, Electron folder import/export, and chat/status UX improvements
+- **v0.11.0** - Electron desktop workflow, concurrent chat sessions, main-agent routing, progressive skills + HITL, and runtime safety hardening
+- Full history: [CHANGELOG.md](CHANGELOG.md)
 
 ## What You Can Build
 
@@ -134,6 +159,11 @@ npx agent-world -w default-world "hi"
 echo "hi" | npx agent-world -w default-world
 ```
 
+**Option 3: Electron Desktop App (repo)**
+```bash
+npm run electron:dev
+```
+
 ## Project Structure
 
 See [Project Structure Documentation](project.md)
@@ -175,12 +205,17 @@ npm run test:watch       # Watch mode
 ### Environment Setup
 
 Export your API keys as environment variables 
+For Azure OpenAI, all four `AZURE_OPENAI_*` variables are required together.
 
 ```bash
 # Required if Choose one or more
 export OPENAI_API_KEY="your-key-here"
 export ANTHROPIC_API_KEY="your-key-here"  
 export GOOGLE_API_KEY="your-key-here"
+export AZURE_OPENAI_API_KEY="your-key-here"
+export AZURE_OPENAI_RESOURCE_NAME="your-resource-name"
+export AZURE_OPENAI_DEPLOYMENT_NAME="your-deployment-name"
+export AZURE_OPENAI_API_VERSION="2024-10-21-preview"
 
 # Default: For local models
 export OLLAMA_BASE_URL="http://localhost:11434"
@@ -188,6 +223,17 @@ export OLLAMA_BASE_URL="http://localhost:11434"
 
 Or create a `.env` file in your working directory with:
 
+```bash
+OPENAI_API_KEY=your-key-here
+ANTHROPIC_API_KEY=your-key-here
+GOOGLE_API_KEY=your-key-here
+AZURE_OPENAI_API_KEY=your-key-here
+AZURE_OPENAI_RESOURCE_NAME=your-resource-name
+AZURE_OPENAI_DEPLOYMENT_NAME=your-deployment-name
+AZURE_OPENAI_API_VERSION=2024-10-21-preview
+OLLAMA_BASE_URL=http://localhost:11434
+```
+
 ## Testing
 
 **Run all tests:**
@@ -230,7 +276,7 @@ LOG_EVENTS_AGENT=debug LOG_LLM=debug npm run web:dev
 
 **For complete logging documentation**, see [Logging Guide](docs/logging-guide.md).
 
-## Learn More
+## Storage Configuration
 
 ### World Database Setup
 
@@ -246,6 +292,7 @@ export AGENT_WORLD_DATA_PATH=./data/worlds
 
 ## Learn More
 
+- **[Docs Home](docs/docs-home.md)** - Central navigation page for all major documentation
 - **[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
 - **[HITL Approval Flow](docs/hitl-approval-flow.md)** - Option-based approval flow across Core/Electron/Web/CLI
@@ -260,11 +307,15 @@ Agent World includes built-in tools that are automatically available to all agen
 ### shell_cmd
 Execute shell commands with full output capture and execution history. Perfect for file operations, system information, and automation tasks.
 
+- Enforces trusted working-directory scope from world/tool context
+- Validates command/path arguments to prevent out-of-scope traversal patterns
+- Supports lifecycle tracking and session-scoped cancellation in active runtimes
+
 ```typescript
 // Available to LLMs as 'shell_cmd' tool
 {
   "command": "ls",
-  "parameters": ["-la", "/tmp"]
+	"parameters": ["-la", "./"]
 }
 ```
 

package/dist/cli/commands.d.ts

@@ -0,0 +1,109 @@
+/**
+ * CLI Commands Implementation - Direct Core Integration with Space-Separated and Bidirectional Aliases
+ *
+ * Features:
+ * - Direct command mapping system with interactive parameter collection
+ * - Core function calls without command processing layer
+ * - User-friendly messages with technical details for debugging
+ * - Automatic world state management and refreshing
+ * - Help message generation with command documentation
+ * - Dual input handling for commands and messages
+ * - World instance isolation and proper cleanup during refresh
+ * - Space-separated command aliases for natural command syntax
+ * - Bidirectional aliases (e.g., /chat new and /new chat both work)
+ * - Backward compatibility with hyphenated aliases
+ * - Context-sensitive commands that adapt based on world selection
+ * - World data persistence to File Storage or SQLite with folder selection
+ *
+ * Available Commands:
+ * - World: list, show, create, update, delete, select, export, save
+ * - Agent: list, show, create, update, delete, clear
+ * - Chat: list, create, select, switch, delete, rename, export
+ * - System: help, quit, exit
+ * - Short Explicit: lsw (list worlds), lsa (list agents)
+ *
+ * Alias System:
+ * - Space-separated format: /new chat, /add agent, /list worlds (preferred)
+ * - Bidirectional aliases: /chat new = /new chat, /agent add = /add agent
+ * - Backward compatible: /new-chat, /add-agent, /list-worlds (still work)
+ * - Context-sensitive: /new creates world, /add creates agent (when world selected)
+ * - Explicit aliases like /lsw, /lsa provide unambiguous targeting
+ *
+ * World Refresh Mechanism:
+ * - Commands that modify world state signal refresh requirement via `refreshWorld: true`
+ * - CLI properly destroys old world instances and creates fresh ones
+ * - Event subscriptions are cleanly transferred to new world instances
+ * - Prevents memory leaks and ensures event isolation between old/new worlds
+ * - Agent persistence maintained across refresh cycles
+ *
+ * World Save Feature:
+ * - Interactive storage type selection (File or SQLite)
+ * - Custom folder path with default option
+ * - Saves world, all agents, all chat histories, and all events
+ * - Creates target directory if it doesn't exist
+ * - Supports migration between storage types
+ * - Event history preserved across different storage backends
+ */
+import { World } from '../core/types.js';
+export interface CLIResponse {
+    success: boolean;
+    message: string;
+    data?: any;
+    technicalDetails?: string;
+    needsWorldRefresh?: boolean;
+    refreshWorld?: boolean;
+    error?: string;
+}
+export interface CLIContext {
+    currentWorldName?: string;
+    currentWorld?: World | null;
+}
+export type PromptFunction = (question: string, options?: string[]) => Promise<string>;
+/**
+ * Display chat messages in a formatted, readable way
+ * Shows sender, timestamp, and content for each message
+ * Logic:
+ * - HUMAN messages: deduplicate by messageId (they're replicated across all agents)
+ * - Agent messages: only show if sender matches agentId (the agent that created it)
+ * - System messages: deduplicate by messageId
+ */
+export declare function displayChatMessages(worldId: string, chatId?: string | null): Promise<void>;
+type CLICommandCategory = 'world' | 'agent' | 'chat' | 'system';
+interface CLICommandParameter {
+    name: string;
+    required: boolean;
+    description: string;
+    type: 'string' | 'number' | 'boolean';
+    options?: string[];
+}
+export interface CLICommandDefinition {
+    type: string;
+    requiresWorld: boolean;
+    description: string;
+    usage: string;
+    parameters: CLICommandParameter[];
+    aliases?: string[];
+    category: CLICommandCategory;
+}
+export declare const CLI_COMMAND_MAP: Record<string, CLICommandDefinition>;
+export declare const CLI_COMMAND_ALIASES: Record<string, string>;
+export declare function parseCLICommand(input: string): {
+    command: string;
+    args: string[];
+    commandType: string;
+    isValid: boolean;
+    error?: string;
+};
+export declare function generateHelpMessage(target?: string): string;
+export declare function checkTargetExists(targetPath: string, storageType: 'file' | 'sqlite', worldId: string): Promise<{
+    exists: boolean;
+    message: string;
+}>;
+export declare function deleteExistingData(targetPath: string, storageType: 'file' | 'sqlite', worldId: string): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+export declare function performWorldSave(world: World, storageType: 'file' | 'sqlite', targetPath: string): Promise<CLIResponse>;
+export declare function processCLICommand(input: string, context: CLIContext, promptFn: PromptFunction): Promise<CLIResponse>;
+export declare function processCLIInput(input: string, world: World | null, sender?: string): Promise<CLIResponse>;
+export {};