agent-world 0.10.0 → 0.11.1

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,8 +35,27 @@ 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
+- ✅ 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 - React + Next.js frontend with real-time chat
+- ✅ Web + CLI + Electron - Modern interfaces with real-time streaming and status feedback
+
+## Latest Highlights (v0.11.0)
+
+- Electron desktop app with workspace-folder world loading, recents, and improved world info
+- Concurrent chat session isolation with chat-scoped event routing and stop controls
+- World-level `mainAgent` routing and agent-level `autoReply` configuration
+- Core-owned edit/resubmit and chat-title flows for consistent behavior across clients
+- World variables as `.env` text with runtime interpolation support
+- Progressive skills (`load_skill`) with skill registry sync and HITL-gated activation
+
+## Release Notes
+
+- **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
 
@@ -81,7 +106,7 @@ Each Agent World has a collection of agents that can communicate through a share
 | **Human message** | `Hello everyone!` | All active agents |
 | **Direct mention** | `@alice Can you help?` | Only @alice |
 | **Paragraph mention** | `Please review this:\n@alice` | Only @alice |
-| **Mid-text mention** | `I think @alice should help` | Nobody (saved to memory) |
+| **Mid-text mention** | `I think @alice should help` | Nobody (event is persisted; no agent-memory save) |
 | **Stop World** | `<world>pass</world>` | No agents |
 
 ### Agent Behavior
@@ -93,8 +118,12 @@ Each Agent World has a collection of agents that can communicate through a share
 
 **Agents never respond to:**
 - Their own messages
-- Other agents (unless @mentioned), but will save message to memory
-- Mid-text mentions (will save message to memory)
+- Other agents (unless @mentioned at paragraph start)
+- Mid-text mentions (not at paragraph start)
+
+**When messages are saved to agent memory:**
+- Incoming messages are saved only for agents that will respond
+- Non-responding agents skip agent-memory save (message events are still persisted)
 
 **Turn limits prevent loops:**
 - Default: 5 responses per conversation thread
@@ -129,46 +158,47 @@ 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)
 
-## Development Scripts Convention
+## Development Scripts
 
-Agent World follows a consistent naming convention for all npm scripts:
+Agent World provides simple, consistent npm scripts for three main applications:
 
-| 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` |
+### Development (hot reload)
+```bash
+npm run dev              # Web app with server (default)
+npm run web:dev          # Web app with server (explicit)
+npm run cli:dev          # CLI with watch mode
+npm run electron:dev     # Electron app
+```
 
-**Available modules:** `server`, `cli`, `ws`, `tui`
+### Production
+```bash
+npm start                # Web server (default)
+npm run web:start        # Web server (explicit)
+npm run cli:start        # CLI (built)
+npm run electron:start   # Electron app
+```
 
-**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)
+### Behind the Scenes
+The scripts handle dependencies automatically:
+- **Web**: Builds core, starts server in watch mode, launches Vite dev server
+- **CLI**: Runs with tsx watch mode for instant feedback
+- **Electron**: Builds core, launches Electron with Vite HMR
 
-**Examples:**
+### Other Useful Scripts
 ```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
+npm run build            # Build all (core + root + web)
+npm run check            # TypeScript type checking
+npm test                 # Run unit tests
+npm run test:watch       # Watch mode
 ```
 
 ### Environment Setup
@@ -187,6 +217,13 @@ 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
+OLLAMA_BASE_URL=http://localhost:11434
+```
+
 ## Testing
 
 **Run all tests:**
@@ -218,18 +255,18 @@ Agent World uses **scenario-based logging** to help you debug specific issues wi
 
 ```bash
 # Database migration issues
-LOG_STORAGE_MIGRATION=info npm run server
+LOG_STORAGE_MIGRATION=info npm run web:dev
 
 # MCP server problems  
-LOG_MCP=debug npm run server
+LOG_MCP=debug npm run web:dev
 
 # Agent response debugging
-LOG_EVENTS_AGENT=debug LOG_LLM=debug npm run server
+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
 
@@ -245,9 +282,12 @@ 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
 - **[Using Core from npm](docs/core-npm-usage.md)** - Integration guide for server and browser apps
+- **[Electron Desktop App](docs/electron-desktop.md)** - Open-folder workflow and local world creation
 
 
 ## Built-in Tools
@@ -257,16 +297,51 @@ 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", "./"]
 }
 ```
 
 See [Shell Command Tool Documentation](docs/shell-cmd-tool.md) for complete details.
 
+### load_skill (Agent Skills)
+
+Agent World includes progressive skill loading through the `load_skill` built-in tool.
+
+- Skills are discovered from `SKILL.md` files in:
+  - Project roots: `.agents/skills`, `skills`
+  - User roots: `~/.agents/skills`, `~/.codex/skills`
+- The model receives compact skill summaries first, then calls `load_skill` only when full instructions are needed.
+- Skill activation in interactive runtimes is HITL-gated.
+
+Minimal `SKILL.md` example:
+
+```md
+---
+name: sql-review
+description: Review SQL migrations for safety and rollback compatibility.
+---
+
+# SQL Review Skill
+
+1. Check for destructive DDL.
+2. Verify index and lock impact.
+3. Validate rollback path.
+```
+
+HITL options for skill activation:
+
+- `yes_once`: approve this call only
+- `yes_in_session`: approve this `skill_id` in the current world/chat session
+- `no`: decline
+
 ## Experimental Features
 
 - **MCP Support** - *Currently in experiment* - Model Context Protocol integration for tools like search and code execution. e.g.,
@@ -308,4 +383,3 @@ Agent World thrives on community examples and improvements:
 MIT License - Build amazing things and share them with the world!
 
 Copyright © 2025 Yiyi Sun
-

package/dist/cli/index.js

@@ -13,6 +13,9 @@
  * - Work with loaded world without importing (uses external storage path)
  *
  * Changes:
+ * - 2026-02-14: Added interactive + pipeline HITL option response handling for generic approval requests.
+ * - 2026-02-11: Fixed tool-stream timeout: extendTimeout() resets idle timeout on streaming data
+ * - 2026-02-11: Pipeline mode now listens for tool-stream SSE events to extend timeout
  * - 2026-01-09: Added --streaming flag for explicit streaming control (overrides TTY auto-detection)
  * - 2025-02-06: Prevented duplicate MESSAGE output when streaming already rendered agent responses
  * - 2025-11-01: Added multi-world selection in loadWorldFromFile
@@ -73,17 +76,20 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import { program } from 'commander';
 import readline from 'readline';
-import { listWorlds, subscribeWorld, createCategoryLogger, LLMProvider, enableStreaming, disableStreaming } from '../core/index.js';
+import { listWorlds, subscribeWorld, submitWorldOptionResponse, createCategoryLogger, LLMProvider, enableStreaming, disableStreaming } from '../core/index.js';
 import { EventType } from '../core/types.js';
 import { getDefaultRootPath } from '../core/storage/storage-factory.js';
 import { processCLIInput, displayChatMessages } from './commands.js';
-import { createStreamingState, handleWorldEventWithStreaming, handleToolEvents, handleActivityEvents, } from './stream.js';
+import { createStreamingState, handleWorldEventWithStreaming, handleToolEvents, } from './stream.js';
 import { configureLLMProvider } from '../core/llm-config.js';
+import { createStatusLineManager, log as statusLog, } from './display.js';
+import { parseHitlOptionRequest, resolveHitlOptionSelectionInput, } from './hitl.js';
 // Create CLI category logger after logger auto-initialization
 const logger = createCategoryLogger('cli');
 function createGlobalState() {
     return {
-        awaitingResponse: false
+        awaitingResponse: false,
+        hitlPromptActive: false
     };
 }
 // Color helpers - consolidated styling API
@@ -163,7 +169,8 @@ class WorldActivityMonitor {
                     cleanup();
                     reject(error);
                 },
-                seenProcessing: false
+                seenProcessing: false,
+                timeoutMs
             };
             const cleanup = () => {
                 if (waiter.timeoutId) {
@@ -208,6 +215,26 @@ class WorldActivityMonitor {
         }
         this.lastEvent = null;
     }
+    /**
+     * Extend timeout for all active waiters.
+     * Called when streaming data arrives to prevent premature timeout.
+     */
+    extendTimeout() {
+        for (const waiter of this.waiters) {
+            // Reset the main timeout
+            if (waiter.timeoutId) {
+                clearTimeout(waiter.timeoutId);
+                waiter.timeoutId = setTimeout(() => {
+                    this.finishWaiter(waiter, false, new Error('Timed out waiting for world to become idle'));
+                }, waiter.timeoutMs);
+            }
+            // Clear noActivity timeout since we have activity
+            if (waiter.noActivityTimeoutId) {
+                clearTimeout(waiter.noActivityTimeoutId);
+                waiter.noActivityTimeoutId = undefined;
+            }
+        }
+    }
     getActiveSources() {
         return this.lastEvent?.activeSources ?? [];
     }
@@ -243,34 +270,37 @@ function parseActivitySource(source) {
     }
     return null;
 }
-class ActivityProgressRenderer {
-    activeAgents = new Set();
-    handle(event) {
-        if (!event)
-            return;
-        // Reset on idle
-        if (event.type === 'idle') {
-            this.reset();
-            return;
-        }
-        const details = parseActivitySource(event.source);
-        if (!details || details.type !== 'agent') {
-            return;
-        }
-        // Track agent start on response-start
-        if (event.type === 'response-start' && !this.activeAgents.has(details.name)) {
-            this.activeAgents.add(details.name);
-        }
-        // Track agent end on response-end
-        if (event.type === 'response-end' && this.activeAgents.has(details.name)) {
-            this.activeAgents.delete(details.name);
+async function promptHitlOptionSelection(request, statusLine, rl) {
+    const fallbackOptionId = request.defaultOptionId;
+    statusLine.pause();
+    try {
+        while (true) {
+            console.log(`\n${boldMagenta('Approval Required')}`);
+            console.log(`${boldCyan(request.title)}`);
+            if (request.message) {
+                console.log(gray(request.message));
+            }
+            console.log(gray('Select an option:'));
+            request.options.forEach((option, index) => {
+                const isDefault = option.id === fallbackOptionId;
+                const defaultSuffix = isDefault ? gray(' (default)') : '';
+                console.log(`  ${yellow(String(index + 1) + '.')} ${option.label}${defaultSuffix}`);
+                if (option.description) {
+                    console.log(`     ${gray(option.description)}`);
+                }
+            });
+            const answer = await new Promise((resolve) => {
+                rl.question(`${boldMagenta('Choice (number or option id):')} `, (input) => resolve(input.trim()));
+            });
+            const resolvedOptionId = resolveHitlOptionSelectionInput(request.options, answer, fallbackOptionId);
+            if (resolvedOptionId) {
+                return resolvedOptionId;
+            }
+            console.log(boldRed('Invalid selection. Please choose a listed option.'));
         }
     }
-    reset() {
-        if (this.activeAgents.size > 0) {
-            this.activeAgents.clear();
-            // console.log(gray('All agents finished.'));
-        }
+    finally {
+        statusLine.resume();
     }
 }
 // LLM Provider configuration from environment variables
@@ -360,19 +390,19 @@ function printCLIResult(result) {
  * @param streaming - Streaming state for interactive mode (null for pipeline mode)
  * @param globalState - Global state for interactive mode (null for pipeline mode)
  * @param activityMonitor - Activity monitor for tracking world events
- * @param progressRenderer - Progress renderer for displaying activity
+ * @param statusLine - Status line manager for interactive display (null for pipeline mode)
  * @param rl - Readline interface for interactive mode (undefined for pipeline mode)
  * @returns Map of event types to listener functions for cleanup
  */
-function attachCLIListeners(world, streaming, globalState, activityMonitor, progressRenderer, rl) {
+function attachCLIListeners(world, streaming, globalState, activityMonitor, statusLine, rl) {
     const listeners = new Map();
+    let hitlPromptChain = Promise.resolve();
     // World activity events
     const worldListener = (eventData) => {
         activityMonitor.handle(eventData);
         // Only render activity progress in interactive mode
-        if (streaming && globalState && rl) {
-            progressRenderer.handle(eventData);
-            handleWorldEvent(EventType.WORLD, eventData, streaming, globalState, activityMonitor, progressRenderer, rl)
+        if (streaming && globalState && rl && statusLine) {
+            handleWorldEvent(EventType.WORLD, eventData, streaming, globalState, activityMonitor, statusLine, rl)
                 .catch(err => console.error('Error handling world event:', err));
         }
         // Pipeline mode: silently track events for completion detection
@@ -385,8 +415,8 @@ function attachCLIListeners(world, streaming, globalState, activityMonitor, prog
             typeof eventData.content === 'string' &&
             eventData.content.includes('Success message sent'))
             return;
-        if (streaming && globalState && rl) {
-            handleWorldEvent(EventType.MESSAGE, eventData, streaming, globalState, activityMonitor, progressRenderer, rl)
+        if (streaming && globalState && rl && statusLine) {
+            handleWorldEvent(EventType.MESSAGE, eventData, streaming, globalState, activityMonitor, statusLine, rl)
                 .catch(err => console.error('Error handling message event:', err));
         }
         else {
@@ -402,22 +432,81 @@ function attachCLIListeners(world, streaming, globalState, activityMonitor, prog
     world.eventEmitter.on(EventType.MESSAGE, messageListener);
     listeners.set(EventType.MESSAGE, messageListener);
     // SSE events (interactive mode only - pipeline mode uses non-streaming LLM calls)
-    if (streaming && globalState && rl) {
+    if (streaming && globalState && rl && statusLine) {
         const sseListener = (eventData) => {
-            handleWorldEvent(EventType.SSE, eventData, streaming, globalState, activityMonitor, progressRenderer, rl)
+            // Extend timeout when tool-stream data arrives (keeps long-running tools alive)
+            if (eventData.type === 'tool-stream') {
+                activityMonitor.extendTimeout();
+            }
+            handleWorldEvent(EventType.SSE, eventData, streaming, globalState, activityMonitor, statusLine, rl)
                 .catch(err => console.error('Error handling SSE event:', err));
         };
         world.eventEmitter.on(EventType.SSE, sseListener);
         listeners.set(EventType.SSE, sseListener);
     }
+    else {
+        // Pipeline mode: listen for tool-stream events to extend timeout on long-running commands
+        const sseTimeoutListener = (eventData) => {
+            if (eventData.type === 'tool-stream') {
+                activityMonitor.extendTimeout();
+            }
+        };
+        world.eventEmitter.on(EventType.SSE, sseTimeoutListener);
+        listeners.set(EventType.SSE, sseTimeoutListener);
+    }
     // System events
     const systemListener = (eventData) => {
+        const hitlRequest = parseHitlOptionRequest(eventData);
+        if (hitlRequest) {
+            hitlPromptChain = hitlPromptChain
+                .then(async () => {
+                if (streaming && globalState && rl && statusLine) {
+                    globalState.hitlPromptActive = true;
+                    try {
+                        const selectedOptionId = await promptHitlOptionSelection(hitlRequest, statusLine, rl);
+                        const result = submitWorldOptionResponse({
+                            worldId: world.id,
+                            requestId: hitlRequest.requestId,
+                            optionId: selectedOptionId
+                        });
+                        if (!result.accepted) {
+                            statusLine.pause();
+                            console.log(boldRed(`Failed to submit approval response: ${result.reason || 'unknown error'}`));
+                            statusLine.resume();
+                            return;
+                        }
+                        statusLine.pause();
+                        console.log(green(`Approved option: ${selectedOptionId}`));
+                        statusLine.resume();
+                        return;
+                    }
+                    finally {
+                        globalState.hitlPromptActive = false;
+                    }
+                }
+                // Pipeline/non-interactive mode: auto-respond with default option to avoid blocking.
+                const result = submitWorldOptionResponse({
+                    worldId: world.id,
+                    requestId: hitlRequest.requestId,
+                    optionId: hitlRequest.defaultOptionId
+                });
+                if (!result.accepted) {
+                    console.error(boldRed(`Failed to auto-respond HITL request: ${result.reason || 'unknown error'}`));
+                    return;
+                }
+                console.log(`${gray('● system:')} Auto-selected HITL option "${hitlRequest.defaultOptionId}"`);
+            })
+                .catch((error) => {
+                console.error(boldRed(`Error handling HITL request: ${error instanceof Error ? error.message : String(error)}`));
+            });
+            return;
+        }
         if (eventData.content &&
             typeof eventData.content === 'string' &&
             eventData.content.includes('Success message sent'))
             return;
-        if (streaming && globalState && rl) {
-            handleWorldEvent(EventType.SYSTEM, eventData, streaming, globalState, activityMonitor, progressRenderer, rl)
+        if (streaming && globalState && rl && statusLine) {
+            handleWorldEvent(EventType.SYSTEM, eventData, streaming, globalState, activityMonitor, statusLine, rl)
                 .catch(err => console.error('Error handling system event:', err));
         }
         else if (eventData.message || eventData.content) {
@@ -446,7 +535,6 @@ async function runPipelineMode(options, messageFromArgs) {
     let worldSubscription = null;
     let cliListeners = null;
     const activityMonitor = new WorldActivityMonitor();
-    const progressRenderer = new ActivityProgressRenderer();
     try {
         if (options.world) {
             // Subscribe to world lifecycle but do not request forwarding callbacks
@@ -458,7 +546,7 @@ async function runPipelineMode(options, messageFromArgs) {
             world = worldSubscription.world;
             // Attach direct listeners to the world.eventEmitter for pipeline handling
             // Note: Pipeline mode uses non-streaming LLM calls, so SSE events are not needed
-            cliListeners = attachCLIListeners(world, null, null, activityMonitor, progressRenderer);
+            cliListeners = attachCLIListeners(world, null, null, activityMonitor, null);
         }
         // Execute command from --command option
         if (options.command) {
@@ -587,11 +675,11 @@ function cleanupWorldSubscription(worldState) {
  * @param streaming - Streaming state for real-time response display
  * @param globalState - Global state for timer management
  * @param activityMonitor - Activity monitor for tracking world events
- * @param progressRenderer - Progress renderer for displaying activity
+ * @param statusLine - Status line manager for interactive display
  * @param rl - Readline interface for interactive input
  * @returns WorldState with subscription and world instance
  */
-async function handleSubscribe(rootPath, worldName, streaming, globalState, activityMonitor, progressRenderer, rl) {
+async function handleSubscribe(rootPath, worldName, streaming, globalState, activityMonitor, statusLine, rl) {
     // Subscribe to world lifecycle but do not request forwarding callbacks
     const subscription = await subscribeWorld(worldName, { isOpen: true });
     if (!subscription)
@@ -603,36 +691,87 @@ async function handleSubscribe(rootPath, worldName, streaming, globalState, acti
     }
     // Attach direct listeners to the world.eventEmitter for CLI handling
     // Interactive mode needs all event types including SSE for streaming responses
-    attachCLIListeners(world, streaming, globalState, activityMonitor, progressRenderer, rl);
+    attachCLIListeners(world, streaming, globalState, activityMonitor, statusLine, rl);
     return { subscription, world };
 }
 // Handle world events with streaming support
-async function handleWorldEvent(eventType, eventData, streaming, globalState, activityMonitor, progressRenderer, rl) {
+async function handleWorldEvent(eventType, eventData, streaming, globalState, activityMonitor, statusLine, rl) {
     if (eventType === 'world') {
         const payload = eventData;
         // Handle activity events (new format: type = 'response-start' | 'response-end' | 'idle')
         if (payload.type === 'response-start' || payload.type === 'response-end' || payload.type === 'idle') {
             activityMonitor.handle(payload);
-            progressRenderer.handle(payload);
-            // Call handleActivityEvents for verbose activity logging
-            handleActivityEvents(payload);
-            if (payload.type === 'idle' && rl && globalState.awaitingResponse) {
-                globalState.awaitingResponse = false;
-                console.log(); // Empty line before prompt
-                rl.prompt();
+            // Update status line based on activity events
+            const details = parseActivitySource(payload.source);
+            const agentName = details?.type === 'agent' ? details.name : payload.source || '';
+            if (payload.type === 'response-start' && agentName) {
+                statusLine.setSpinner(`${agentName} is thinking...`);
+                statusLine.startElapsedTimer();
+                // Update agent list from activeSources
+                if (payload.activeSources) {
+                    const agentEntries = payload.activeSources
+                        .map((s) => parseActivitySource(s))
+                        .filter((d) => d?.type === 'agent')
+                        .map((d) => ({ name: d.name, active: true }));
+                    statusLine.setAgents(agentEntries);
+                }
+            }
+            if (payload.type === 'response-end') {
+                // Update agent list — remove finished agent
+                if (payload.activeSources) {
+                    const agentEntries = payload.activeSources
+                        .map((s) => parseActivitySource(s))
+                        .filter((d) => d?.type === 'agent')
+                        .map((d) => ({ name: d.name, active: true }));
+                    statusLine.setAgents(agentEntries);
+                    // Update spinner label to next active agent if any
+                    if (agentEntries.length > 0) {
+                        statusLine.setSpinner(`${agentEntries[0].name} is thinking...`);
+                    }
+                    else {
+                        statusLine.setSpinner(null);
+                        statusLine.stopElapsedTimer();
+                    }
+                }
+            }
+            if (payload.type === 'idle') {
+                statusLine.reset();
+                if (rl && globalState.awaitingResponse) {
+                    globalState.awaitingResponse = false;
+                    statusLine.clear();
+                    console.log(); // Empty line before prompt
+                    rl.prompt();
+                }
             }
         }
         // Handle informational world messages.
         else if (payload.type === 'info' && payload.message) {
-            console.log(`${gray('[World]')} ${payload.message}`);
+            statusLog(statusLine, `${gray('[World]')} ${payload.message}`);
         }
         // Handle tool events (migrated from sse channel)
         else if (payload.type === 'tool-start' || payload.type === 'tool-result' || payload.type === 'tool-error' || payload.type === 'tool-progress') {
+            // Update status line with tool info
+            if (payload.type === 'tool-start' && payload.toolExecution) {
+                statusLine.addTool(payload.toolExecution.toolName);
+            }
+            else if (payload.type === 'tool-result' && payload.toolExecution) {
+                statusLine.removeTool(payload.toolExecution.toolName, 'done');
+            }
+            else if (payload.type === 'tool-error' && payload.toolExecution) {
+                statusLine.removeTool(payload.toolExecution.toolName, 'error');
+            }
+            // Print permanent tool event output
+            statusLine.pause();
             handleToolEvents(payload);
+            // Only resume status line if not actively streaming
+            // (streaming code manages its own pause/resume lifecycle)
+            if (!streaming.isActive) {
+                statusLine.resume();
+            }
         }
         return;
     }
-    if (handleWorldEventWithStreaming(eventType, eventData, streaming)) {
+    if (handleWorldEventWithStreaming(eventType, eventData, streaming, statusLine)) {
         return;
     }
     if (eventData.content &&
@@ -662,12 +801,12 @@ async function handleWorldEvent(eventType, eventData, streaming, globalState, ac
         }
         // Display system messages
         if (eventData.sender === 'system') {
-            console.log(`${boldRed('● system:')} ${eventData.content}`);
+            statusLog(statusLine, `${boldRed('● system:')} ${eventData.content}`);
             return;
         }
         // Display agent messages (fallback for non-streaming or missed messages)
         if (eventData.content) {
-            console.log(`\n${boldGreen(`● ${eventData.sender}:`)} ${eventData.content}\n`);
+            statusLog(statusLine, `\n${boldGreen(`● ${eventData.sender}:`)} ${eventData.content}\n`);
         }
         return;
     }
@@ -1005,7 +1144,7 @@ async function runInteractiveMode(options) {
     const globalState = createGlobalState();
     const streaming = createStreamingState();
     const activityMonitor = new WorldActivityMonitor();
-    const progressRenderer = new ActivityProgressRenderer();
+    const statusLine = createStatusLineManager();
     const rl = readline.createInterface({
         input: process.stdin,
         output: process.stdout,
@@ -1022,8 +1161,8 @@ async function runInteractiveMode(options) {
             logger.debug(`Loading world: ${options.world}`);
             try {
                 activityMonitor.reset();
-                progressRenderer.reset();
-                worldState = await handleSubscribe(rootPath, options.world, streaming, globalState, activityMonitor, progressRenderer, rl);
+                statusLine.reset();
+                worldState = await handleSubscribe(rootPath, options.world, streaming, globalState, activityMonitor, statusLine, rl);
                 currentWorldName = options.world;
                 console.log(success(`Connected to world: ${currentWorldName}`));
                 if (worldState?.world) {
@@ -1048,8 +1187,8 @@ async function runInteractiveMode(options) {
             logger.debug(`Loading world: ${selectedWorld.worldName} from ${effectiveRootPath}`);
             try {
                 activityMonitor.reset();
-                progressRenderer.reset();
-                worldState = await handleSubscribe(effectiveRootPath, selectedWorld.worldName, streaming, globalState, activityMonitor, progressRenderer, rl);
+                statusLine.reset();
+                worldState = await handleSubscribe(effectiveRootPath, selectedWorld.worldName, streaming, globalState, activityMonitor, statusLine, rl);
                 currentWorldName = selectedWorld.worldName;
                 console.log(success(`Connected to world: ${currentWorldName}`));
                 if (selectedWorld.externalPath) {
@@ -1082,6 +1221,9 @@ async function runInteractiveMode(options) {
         console.log(); // Empty line before prompt
         rl.prompt();
         rl.on('line', async (input) => {
+            if (globalState.hitlPromptActive) {
+                return;
+            }
             const trimmedInput = input.trim();
             if (!trimmedInput) {
                 console.log(); // Empty line before prompt
@@ -1145,8 +1287,8 @@ async function runInteractiveMode(options) {
                         // Subscribe to the new world
                         logger.debug(`Subscribing to world: ${selectedWorld.worldName}...`);
                         activityMonitor.reset();
-                        progressRenderer.reset();
-                        worldState = await handleSubscribe(effectiveRootPath, selectedWorld.worldName, streaming, globalState, activityMonitor, progressRenderer, rl);
+                        statusLine.reset();
+                        worldState = await handleSubscribe(effectiveRootPath, selectedWorld.worldName, streaming, globalState, activityMonitor, statusLine, rl);
                         currentWorldName = selectedWorld.worldName;
                         console.log(success(`Connected to world: ${currentWorldName}`));
                         if (selectedWorld.externalPath) {
@@ -1354,6 +1496,7 @@ async function runInteractiveMode(options) {
             if (isExiting)
                 return; // Prevent duplicate cleanup
             isExiting = true;
+            statusLine.cleanup();
             console.log(`\n${boldCyan('Goodbye!')}`);
             if (worldState)
                 cleanupWorldSubscription(worldState);
@@ -1363,6 +1506,7 @@ async function runInteractiveMode(options) {
             if (isExiting)
                 return; // Prevent duplicate cleanup
             isExiting = true;
+            statusLine.cleanup();
             console.log(`\n${boldCyan('Shutting down...')}`);
             console.log(`\n${boldCyan('Goodbye!')}`);
             if (worldState)
@@ -1373,6 +1517,7 @@ async function runInteractiveMode(options) {
     }
     catch (err) {
         console.error(boldRed('Error starting interactive mode:'), err instanceof Error ? err.message : err);
+        statusLine.cleanup();
         rl.close();
         process.exit(1);
     }

package/dist/server/index.js

@@ -8,9 +8,17 @@
  * - Category-based logging with configurable levels
  * - Health check endpoint and proper error handling
  * - Environment Variables: Automatically loads .env file for API keys and configuration
+ * - Controlled startup behavior for direct execution vs imported usage
+ * - Optional browser auto-open and process signal handler registration
  *
  * Configuration: AGENT_WORLD_DATA_PATH, LOG_LEVEL, LLM provider keys
  * Endpoints: /health + API routes from ./api.ts
+ *
+ * Recent Changes:
+ * - 2026-02-08: Fixed auto-run detection to only trigger on direct execution
+ * - 2026-02-08: Made browser auto-open configurable via AGENT_WORLD_AUTO_OPEN env var
+ * - 2026-02-08: Prevented duplicate process signal handler registration using WeakSet
+ * - 2026-02-08: Added shutdown guard to prevent race conditions during graceful shutdown
  */
 // Load environment variables from .env file
 import dotenv from 'dotenv';
@@ -32,6 +40,8 @@ const PORT = Number(process.env.PORT) || 0;
 const HOST = process.env.HOST || '127.0.0.1';
 // Create server logger after logger auto-initialization
 const serverLogger = createCategoryLogger('server');
+// Track servers that have registered process handlers (prevents duplicate registration)
+const serversWithHandlers = new WeakSet();
 // LLM provider configuration
 function configureLLMProvidersFromEnv() {
     const providers = [
@@ -114,7 +124,9 @@ app.use((req, res) => {
     res.status(404).json({ error: 'Endpoint not found', code: 'NOT_FOUND' });
 });
 // Server startup function
-export function startWebServer(port = PORT, host = HOST) {
+export function startWebServer(port = PORT, host = HOST, options = {}) {
+    const openBrowser = options.openBrowser ?? false;
+    const registerProcessHandlers = options.registerProcessHandlers ?? false;
     return new Promise((resolve, reject) => {
         configureLLMProvidersFromEnv();
         // Initialize MCP registry
@@ -129,12 +141,23 @@ export function startWebServer(port = PORT, host = HOST) {
                 // console.log(`📁 Serving static files from: ${path.join(__dirname, '../public')}`);
                 // console.log(`🚀 HTTP server running with REST API and SSE chat`);
                 resolve(server);
-                open(url);
+                if (openBrowser) {
+                    open(url).catch((error) => {
+                        serverLogger.warn('Failed to open browser automatically', {
+                            error: error instanceof Error ? error.message : String(error),
+                            url
+                        });
+                    });
+                }
             }
         });
         server.on('error', reject);
         // Setup graceful shutdown handlers
+        let shuttingDown = false;
         const gracefulShutdown = async (signal) => {
+            if (shuttingDown)
+                return;
+            shuttingDown = true;
             serverLogger.info(`Received ${signal}, initiating graceful shutdown`);
             try {
                 // Shutdown MCP servers first
@@ -159,29 +182,41 @@ export function startWebServer(port = PORT, host = HOST) {
                 process.exit(1);
             }
         };
-        // Register shutdown handlers
-        process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
-        process.on('SIGINT', () => gracefulShutdown('SIGINT'));
-        // Handle uncaught exceptions and unhandled rejections
-        process.on('uncaughtException', (error) => {
-            serverLogger.error('Uncaught exception', { error: error.message });
-            gracefulShutdown('uncaughtException');
-        });
-        process.on('unhandledRejection', (reason, promise) => {
-            serverLogger.error('Unhandled rejection', {
-                reason: reason instanceof Error ? reason.message : reason,
-                promise: promise.toString()
+        if (registerProcessHandlers && !serversWithHandlers.has(server)) {
+            serversWithHandlers.add(server);
+            // Register shutdown handlers once
+            process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+            process.on('SIGINT', () => gracefulShutdown('SIGINT'));
+            // Handle uncaught exceptions and unhandled rejections
+            process.on('uncaughtException', (error) => {
+                serverLogger.error('Uncaught exception', { error: error.message });
+                gracefulShutdown('uncaughtException');
             });
-        });
+            process.on('unhandledRejection', (reason, promise) => {
+                serverLogger.error('Unhandled rejection', {
+                    reason: reason instanceof Error ? reason.message : reason,
+                    promise: promise.toString()
+                });
+            });
+        }
     });
 }
-// Direct execution handling - check both direct execution and npm bin execution
+// Direct execution handling
 const currentFileUrl = import.meta.url;
-const entryPointUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+const entryPointUrl = process.argv[1]
+    ? pathToFileURL(path.resolve(process.argv[1])).href
+    : '';
 const isDirectExecution = currentFileUrl === entryPointUrl;
-const isServerBinCommand = process.argv[1].includes('agent-world-server') || currentFileUrl.includes('server/index.js');
-if (isDirectExecution || isServerBinCommand) {
-    startWebServer()
+const isBinExecution = process.argv[1]?.includes('agent-world-server') || false;
+// Auto-open browser by default when launched via npx/bin, unless explicitly disabled
+const shouldOpenBrowser = isBinExecution
+    ? process.env.AGENT_WORLD_AUTO_OPEN !== 'false'
+    : process.env.AGENT_WORLD_AUTO_OPEN === 'true';
+if (isDirectExecution || isBinExecution) {
+    startWebServer(PORT, HOST, {
+        openBrowser: shouldOpenBrowser,
+        registerProcessHandlers: true
+    })
         .then(() => console.log('Server started successfully'))
         .catch((error) => {
         console.error('Failed to start server:', error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-world",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -17,32 +17,34 @@
   "type": "module",
   "workspaces": [
     "core",
-    "react",
     "web"
   ],
   "bin": {
-    "agent-world": "dist/cli/index.js",
+    "agent-world": "scripts/launch-electron.js",
+    "agent-world-cli": "dist/cli/index.js",
     "agent-world-server": "dist/server/index.js"
   },
   "scripts": {
-    "prestart": "npm run build",
-    "start": "node dist/server/index.js",
-    "dev": "npm-run-all --parallel server:watch web:dev react:dev",
-    "cli": "npm run cli:start",
-    "cli:start": "node dist/cli/index.js",
-    "cli:dev": "npx tsx cli/index.ts",
-    "cli:watch": "npx tsx --watch cli/index.ts",
-    "server": "npm run server:start",
-    "server:start": "node dist/server/index.js",
+    "dev": "npm run web:dev",
+    "dev:reset": "for p in 3000 8080; do pids=$(lsof -tiTCP:$p -sTCP:LISTEN 2>/dev/null || true); if [ -n \"$pids\" ]; then kill $pids; fi; done",
+    "web:dev": "npm-run-all --parallel server:watch web:vite:wait",
+    "cli:dev": "npx tsx --watch cli/index.ts",
+    "electron:dev": "npm-run-all --sequential build:core electron:dev:watch",
+    "electron:dev:watch": "npm-run-all --parallel build:core:watch electron:vite",
+    "start": "npm run web:start",
+    "web:start": "npm run build && npm run server:start",
+    "cli:start": "npm run build && node dist/cli/index.js",
+    "electron:start": "npm run build:core && npm run start --prefix electron",
+    "build": "npm run build --workspace=core && tsc --project tsconfig.build.json && npm run build --workspace=web",
+    "build:core": "npm run build --workspace=core",
+    "build:core:watch": "npm run build --workspace=core -- --watch --preserveWatchOutput",
+    "check": "tsc --noEmit --project tsconfig.build.json && npm run check --workspace=core && npm run check --workspace=web",
     "server:dev": "npx tsx server/index.ts",
     "server:watch": "npx tsx --watch server/index.ts",
-    "server:wait": "wait-on http://127.0.0.1:3000/health",
-    "web:dev": "npm-run-all --sequential server:wait web:dev:direct",
-    "web:dev:direct": "npm run dev --workspace=web",
-    "web:watch": "npm-run-all --parallel server:watch web:dev:direct",
-    "react:dev": "npm-run-all --parallel server:wait react:dev:direct",
-    "react:dev:direct": "npm run dev --workspace=react",
-    "react:watch": "npm-run-all --parallel server:watch react:dev:direct",
+    "server:start": "node dist/server/index.js",
+    "web:vite": "npm run dev --workspace=web",
+    "web:vite:wait": "wait-on tcp:127.0.0.1:3000 && npm run web:vite",
+    "electron:vite": "npm run dev --prefix electron",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:ui": "vitest --ui",
@@ -51,8 +53,6 @@
     "test:e2e": "npx tsx tests/e2e/test-agent-response-rules.ts",
     "test:e2e:interactive": "npx tsx tests/e2e/test-agent-response-rules.ts -i",
     "integration": "vitest run --config vitest.integration.config.ts",
-    "check": "tsc --noEmit --project tsconfig.build.json && npm run check --workspace=core && npm run check --workspace=web && npm run check --workspace=react",
-    "build": "npm run build --workspace=core && tsc --project tsconfig.build.json && npm run build --workspace=web && npm run build --workspace=react",
     "pkill": "pkill -f tsx"
   },
   "description": "World-mediated agent management system with clean API surface",

package/scripts/launch-electron.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+/**
+ * Launch Electron App - Simple launcher for agent-world desktop app
+ * 
+ * Purpose:
+ * - Launch the Electron desktop app when running `agent-world` command
+ * - Ensures necessary builds exist before launching
+ * 
+ * Features:
+ * - Checks for core build
+ * - Launches Electron app
+ * - Provides helpful error messages if builds are missing
+ * 
+ * Implementation Notes:
+ * - Used as bin entry point in package.json
+ * - Replaces CLI as default when running `agent-world` command
+ */
+
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const projectRoot = path.resolve(__dirname, '..');
+
+// Check if core build exists
+const coreIndexPath = path.join(projectRoot, 'dist', 'core', 'index.js');
+if (!fs.existsSync(coreIndexPath)) {
+  console.error('Error: Core build not found. Please run: npm run build');
+  process.exit(1);
+}
+
+// Check if electron directory exists
+const electronPath = path.join(projectRoot, 'electron');
+if (!fs.existsSync(electronPath)) {
+  console.error('Error: Electron app not found.');
+  process.exit(1);
+}
+
+// Launch Electron app
+const electronMainPath = path.join(electronPath, 'main.js');
+const electronProcess = spawn('npx', ['electron', electronMainPath], {
+  cwd: projectRoot,
+  stdio: 'inherit',
+  env: { ...process.env }
+});
+
+electronProcess.on('error', (error) => {
+  console.error('Failed to launch Electron app:', error);
+  process.exit(1);
+});
+
+electronProcess.on('exit', (code) => {
+  process.exit(code || 0);
+});