agent-world 0.11.1 → 0.12.1

package/README.md

@@ -43,17 +43,18 @@ Paste that prompt. Agents come alive instantly.
 - ✅ Multiple AI Providers - Use different models for different agents
 - ✅ Web + CLI + Electron - Modern interfaces with real-time streaming and status feedback
 
-## Latest Highlights (v0.11.0)
+## Latest Highlights (since v0.11.1)
 
-- 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
+- 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)
 
@@ -139,23 +140,26 @@ Each Agent World has a collection of agents that can communicate through a share
 
 ### Quick Start
 
+Use npm package invocations (shown below). GitHub shorthand commands such as
+`npx agent-world/agent-world` are not supported entrypoints.
+
 **Option 1: Web Interface**
 ```bash
-npx agent-world-server
+npx agent-world@latest
 ```
 
 **Option 2: CLI Interface**
 1. Interactive Mode
 ```bash
-npx agent-world
+npx -p agent-world@latest agent-world-cli
 ```
 2. Command Mode
 ```bash
-npx agent-world -w default-world "hi" 
+npx -p agent-world@latest agent-world-cli -w default-world "hi" 
 ```
 3. Pipeline Mode
 ```bash
-echo "hi" | npx agent-world -w default-world
+echo "hi" | npx -p agent-world@latest agent-world-cli -w default-world
 ```
 
 **Option 3: Electron Desktop App (repo)**
@@ -204,12 +208,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"
@@ -221,6 +230,10 @@ Or create a `.env` file in your working directory with:
 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
 ```
 

package/bin/agent-world-cli.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * Agent World Bin Launcher (CLI entry).
+ *
+ * Purpose:
+ * - Provide a stable npm bin entry for `agent-world-cli`.
+ *
+ * Key Features:
+ * - Performs a Node.js runtime preflight check with a clear user-facing error.
+ * - Defers to the published CLI runtime after validation.
+ *
+ * Notes on Implementation:
+ * - Uses dynamic import so the preflight runs before loading modern runtime dependencies.
+ *
+ * Recent Changes:
+ * - 2026-02-19: Added wrapper to avoid silent exits on unsupported Node versions.
+ */
+
+const MIN_NODE_MAJOR = 20;
+
+function getNodeMajor() {
+  const major = Number.parseInt((process.versions.node || '').split('.')[0] || '0', 10);
+  return Number.isFinite(major) ? major : 0;
+}
+
+function ensureSupportedNode() {
+  const nodeMajor = getNodeMajor();
+  if (nodeMajor >= MIN_NODE_MAJOR) return;
+
+  console.error(`[agent-world-cli] Node.js ${MIN_NODE_MAJOR}+ is required. Detected ${process.version}.`);
+  console.error('[agent-world-cli] Please upgrade Node.js and run the command again.');
+  process.exit(1);
+}
+
+ensureSupportedNode();
+
+import('../dist/cli/index.js').catch((error) => {
+  console.error('[agent-world-cli] Failed to start CLI:', error);
+  process.exit(1);
+});
+

package/bin/agent-world-server.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+/**
+ * Agent World Bin Launcher (server entry).
+ *
+ * Purpose:
+ * - Provide a stable npm bin entry for `agent-world-server`.
+ *
+ * Key Features:
+ * - Performs a Node.js runtime preflight check with a clear user-facing error.
+ * - Defers to the published server runtime after validation.
+ *
+ * Notes on Implementation:
+ * - Uses dynamic import so the preflight runs before loading modern runtime dependencies.
+ *
+ * Recent Changes:
+ * - 2026-02-19: Added wrapper to avoid silent exits on unsupported Node versions.
+ */
+
+const MIN_NODE_MAJOR = 20;
+
+function getNodeMajor() {
+  const major = Number.parseInt((process.versions.node || '').split('.')[0] || '0', 10);
+  return Number.isFinite(major) ? major : 0;
+}
+
+function ensureSupportedNode() {
+  const nodeMajor = getNodeMajor();
+  if (nodeMajor >= MIN_NODE_MAJOR) return;
+
+  console.error(`[agent-world-server] Node.js ${MIN_NODE_MAJOR}+ is required. Detected ${process.version}.`);
+  console.error('[agent-world-server] Please upgrade Node.js and run the command again.');
+  process.exit(1);
+}
+
+ensureSupportedNode();
+
+import('../dist/server/index.js').catch((error) => {
+  console.error('[agent-world-server] Failed to start server:', error);
+  process.exit(1);
+});

package/bin/agent-world.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * Agent World Bin Launcher (default server entry).
+ *
+ * Purpose:
+ * - Provide a stable npm bin entry for `agent-world`.
+ *
+ * Key Features:
+ * - Performs a Node.js runtime preflight check with a clear user-facing error.
+ * - Defers to the published server runtime after validation.
+ *
+ * Notes on Implementation:
+ * - Uses dynamic import so the preflight runs before loading modern runtime dependencies.
+ *
+ * Recent Changes:
+ * - 2026-02-19: Added wrapper to avoid silent exits on unsupported Node versions.
+ */
+
+const MIN_NODE_MAJOR = 20;
+
+function getNodeMajor() {
+  const major = Number.parseInt((process.versions.node || '').split('.')[0] || '0', 10);
+  return Number.isFinite(major) ? major : 0;
+}
+
+function ensureSupportedNode() {
+  const nodeMajor = getNodeMajor();
+  if (nodeMajor >= MIN_NODE_MAJOR) return;
+
+  console.error(`[agent-world] Node.js ${MIN_NODE_MAJOR}+ is required. Detected ${process.version}.`);
+  console.error('[agent-world] Please upgrade Node.js and run the command again.');
+  process.exit(1);
+}
+
+ensureSupportedNode();
+
+import('../dist/server/index.js')
+  .then(({ startWebServer }) => {
+    const port = Number(process.env.PORT) || 0;
+    const host = process.env.HOST || '127.0.0.1';
+    const shouldOpenBrowser = process.env.AGENT_WORLD_AUTO_OPEN !== 'false';
+
+    return startWebServer(port, host, {
+      openBrowser: shouldOpenBrowser,
+      registerProcessHandlers: true,
+    }).then(() => {
+      console.log('Server started successfully');
+    });
+  })
+  .catch((error) => {
+    console.error('[agent-world] Failed to start server:', error);
+    process.exit(1);
+  });

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 {};