agent-world 0.11.1 → 0.12.0

package/dist/cli/display.d.ts

@@ -0,0 +1,124 @@
+/**
+ * CLI Display Module — Formatting Utilities, Spinner, and Status Line Manager
+ *
+ * Provides terminal display primitives for the CLI interactive mode, inspired
+ * by the Electron desktop app UX patterns. All display logic is centralized
+ * here so that `index.ts` handles event routing and `stream.ts` handles
+ * streaming data management.
+ *
+ * FEATURES:
+ * - Pure formatting functions: tool names, elapsed time, tool icons, truncation
+ * - Braille spinner with configurable label
+ * - Unified status line manager combining spinner, elapsed timer, agent queue,
+ *   and active tools on a single rewritable terminal line
+ * - Readline coordination via pause/resume to avoid prompt corruption
+ *
+ * NOTES:
+ * - Leaf module with no internal project imports (only Node built-ins)
+ * - All side-effectful output uses process.stdout.write (no console.log)
+ * - Unicode symbols chosen for consistent terminal width (no emoji)
+ *
+ * CHANGES:
+ * - 2026-02-11: Initial creation — Phase 1-3 of CLI UX improvement plan
+ */
+/** Entry describing an active or completed tool in the status line. */
+export interface ToolDisplayEntry {
+    name: string;
+    status: 'running' | 'done' | 'error';
+    detail?: string;
+}
+/** Entry describing an agent in the status line. */
+export interface AgentDisplayEntry {
+    name: string;
+    active: boolean;
+}
+/** Full snapshot of what the status line should render. */
+export interface StatusLineState {
+    spinner: {
+        label: string;
+        active: boolean;
+    };
+    elapsedMs: number;
+    agents: AgentDisplayEntry[];
+    tools: ToolDisplayEntry[];
+}
+/**
+ * Convert a tool name from snake_case / camelCase to Title Case for display.
+ *
+ * Examples:
+ *   read_file       → Read File
+ *   shell_cmd       → Shell Cmd
+ *   searchAndReplace → Search And Replace
+ *   listDir         → List Dir
+ */
+export declare function formatToolName(toolName: string): string;
+/**
+ * Format elapsed milliseconds as a human-readable duration string.
+ *
+ * Examples:
+ *   0      → 0:00
+ *   5000   → 0:05
+ *   65000  → 1:05
+ *   3661000 → 1:01:01
+ */
+export declare function formatElapsed(ms: number): string;
+/**
+ * Return a Unicode icon for a tool based on its name pattern.
+ *
+ * Uses fixed-width Unicode symbols (not emoji) for consistent terminal rendering.
+ */
+export declare function getToolIcon(toolName: string): string;
+/**
+ * Truncate a string to fit within `maxWidth` columns, appending "…" if trimmed.
+ *
+ * Uses simple character count (not full Unicode width detection) which is
+ * correct for the fixed-width symbols we use in the status line.
+ */
+export declare function truncateToWidth(text: string, maxWidth: number): string;
+export interface Spinner {
+    start: (label: string) => void;
+    stop: () => void;
+    isRunning: () => boolean;
+    cleanup: () => void;
+}
+/**
+ * Create a braille-character spinner that writes to a single rewritable line.
+ *
+ * The spinner renders frame + label via `process.stdout.write('\r\x1b[K…')`
+ * at 80 ms intervals. Calling `stop()` clears the line. `cleanup()` is an
+ * alias for `stop()` that also nullifies internal references.
+ */
+export declare function createSpinner(): Spinner;
+export interface StatusLineManager {
+    setSpinner: (label: string | null) => void;
+    setElapsed: (ms: number) => void;
+    setAgents: (agents: AgentDisplayEntry[]) => void;
+    addTool: (name: string) => void;
+    removeTool: (name: string, status: 'done' | 'error', detail?: string) => void;
+    render: () => void;
+    clear: () => void;
+    pause: () => void;
+    resume: () => void;
+    startElapsedTimer: () => void;
+    stopElapsedTimer: () => void;
+    reset: () => void;
+    cleanup: () => void;
+}
+/**
+ * Create a unified status line manager that composes spinner, elapsed time,
+ * agent queue, and active tools into a single rewritable terminal line.
+ *
+ * Status line format example:
+ *   ⠋ AgentA is thinking... [0:12] | ▸ Read File ⟳
+ *
+ * Supports pause/resume for readline prompt coordination: pause clears the
+ * status line so `console.log()` or `rl.prompt()` output is clean, resume
+ * redraws it.
+ */
+export declare function createStatusLineManager(): StatusLineManager;
+/**
+ * Print permanent output while preserving the status line.
+ *
+ * Usage: `log(statusLine, 'Hello', someVar)` instead of `console.log(...)`.
+ */
+export declare function log(statusLine: StatusLineManager, ...args: unknown[]): void;

package/dist/cli/display.js

@@ -0,0 +1,381 @@
+/**
+ * CLI Display Module — Formatting Utilities, Spinner, and Status Line Manager
+ *
+ * Provides terminal display primitives for the CLI interactive mode, inspired
+ * by the Electron desktop app UX patterns. All display logic is centralized
+ * here so that `index.ts` handles event routing and `stream.ts` handles
+ * streaming data management.
+ *
+ * FEATURES:
+ * - Pure formatting functions: tool names, elapsed time, tool icons, truncation
+ * - Braille spinner with configurable label
+ * - Unified status line manager combining spinner, elapsed timer, agent queue,
+ *   and active tools on a single rewritable terminal line
+ * - Readline coordination via pause/resume to avoid prompt corruption
+ *
+ * NOTES:
+ * - Leaf module with no internal project imports (only Node built-ins)
+ * - All side-effectful output uses process.stdout.write (no console.log)
+ * - Unicode symbols chosen for consistent terminal width (no emoji)
+ *
+ * CHANGES:
+ * - 2026-02-11: Initial creation — Phase 1-3 of CLI UX improvement plan
+ */
+// ---------------------------------------------------------------------------
+// Color helpers (duplicated here to keep display.ts a leaf module)
+// ---------------------------------------------------------------------------
+const gray = (text) => `\x1b[90m${text}\x1b[0m`;
+const cyan = (text) => `\x1b[36m${text}\x1b[0m`;
+const yellow = (text) => `\x1b[33m${text}\x1b[0m`;
+const green = (text) => `\x1b[32m${text}\x1b[0m`;
+const red = (text) => `\x1b[31m${text}\x1b[0m`;
+const bold = (text) => `\x1b[1m${text}\x1b[0m`;
+const boldGreen = (text) => `\x1b[1m\x1b[32m${text}\x1b[0m`;
+// ---------------------------------------------------------------------------
+// Phase 1 — Pure Formatting Functions
+// ---------------------------------------------------------------------------
+/**
+ * Convert a tool name from snake_case / camelCase to Title Case for display.
+ *
+ * Examples:
+ *   read_file       → Read File
+ *   shell_cmd       → Shell Cmd
+ *   searchAndReplace → Search And Replace
+ *   listDir         → List Dir
+ */
+export function formatToolName(toolName) {
+    if (!toolName)
+        return '';
+    // Split on underscores and camelCase boundaries
+    const words = toolName
+        .replace(/_/g, ' ')
+        .replace(/([a-z])([A-Z])/g, '$1 $2')
+        .split(/\s+/)
+        .filter(Boolean);
+    return words
+        .map(w => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
+        .join(' ');
+}
+/**
+ * Format elapsed milliseconds as a human-readable duration string.
+ *
+ * Examples:
+ *   0      → 0:00
+ *   5000   → 0:05
+ *   65000  → 1:05
+ *   3661000 → 1:01:01
+ */
+export function formatElapsed(ms) {
+    if (ms < 0)
+        ms = 0;
+    const totalSeconds = Math.floor(ms / 1000);
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+    const pad = (n) => n.toString().padStart(2, '0');
+    if (hours > 0) {
+        return `${hours}:${pad(minutes)}:${pad(seconds)}`;
+    }
+    return `${minutes}:${pad(seconds)}`;
+}
+/**
+ * Return a Unicode icon for a tool based on its name pattern.
+ *
+ * Uses fixed-width Unicode symbols (not emoji) for consistent terminal rendering.
+ */
+export function getToolIcon(toolName) {
+    const lower = toolName.toLowerCase();
+    // More specific patterns first to avoid false matches
+    if (lower.includes('write') || lower.includes('create') || lower.includes('edit') || lower.includes('save'))
+        return '▹';
+    if (lower.includes('delete') || lower.includes('remove'))
+        return '✕';
+    if (lower.includes('move') || lower.includes('rename') || lower.includes('copy'))
+        return '↔';
+    if (lower.includes('shell') || lower.includes('exec') || lower.includes('run') || lower.includes('cmd'))
+        return '⚡';
+    if (lower.includes('search') || lower.includes('find') || lower.includes('grep') || lower.includes('list'))
+        return '◈';
+    if (lower.includes('web') || lower.includes('fetch') || lower.includes('http') || lower.includes('url'))
+        return '◇';
+    if (lower.includes('read') || lower.includes('file') || lower.includes('cat'))
+        return '▸';
+    return '●';
+}
+/**
+ * Truncate a string to fit within `maxWidth` columns, appending "…" if trimmed.
+ *
+ * Uses simple character count (not full Unicode width detection) which is
+ * correct for the fixed-width symbols we use in the status line.
+ */
+export function truncateToWidth(text, maxWidth) {
+    if (maxWidth <= 0)
+        return '';
+    if (text.length <= maxWidth)
+        return text;
+    if (maxWidth <= 1)
+        return '…';
+    return text.slice(0, maxWidth - 1) + '…';
+}
+// ---------------------------------------------------------------------------
+// Phase 2 — Spinner Factory
+// ---------------------------------------------------------------------------
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const SPINNER_INTERVAL_MS = 80;
+/**
+ * Create a braille-character spinner that writes to a single rewritable line.
+ *
+ * The spinner renders frame + label via `process.stdout.write('\r\x1b[K…')`
+ * at 80 ms intervals. Calling `stop()` clears the line. `cleanup()` is an
+ * alias for `stop()` that also nullifies internal references.
+ */
+export function createSpinner() {
+    let frameIndex = 0;
+    let intervalId = null;
+    let currentLabel = '';
+    function render() {
+        const frame = SPINNER_FRAMES[frameIndex % SPINNER_FRAMES.length];
+        frameIndex++;
+        const line = `${cyan(frame)} ${currentLabel}`;
+        process.stdout.write(`\r\x1b[K${line}`);
+    }
+    function start(label) {
+        // Idempotent: if already running just update label
+        currentLabel = label;
+        if (intervalId !== null)
+            return;
+        frameIndex = 0;
+        render();
+        intervalId = setInterval(render, SPINNER_INTERVAL_MS);
+    }
+    function stop() {
+        if (intervalId !== null) {
+            clearInterval(intervalId);
+            intervalId = null;
+        }
+        // Clear the spinner line
+        process.stdout.write('\r\x1b[K');
+        currentLabel = '';
+    }
+    function isRunning() {
+        return intervalId !== null;
+    }
+    function cleanup() {
+        stop();
+    }
+    return { start, stop, isRunning, cleanup };
+}
+/**
+ * Create a unified status line manager that composes spinner, elapsed time,
+ * agent queue, and active tools into a single rewritable terminal line.
+ *
+ * Status line format example:
+ *   ⠋ AgentA is thinking... [0:12] | ▸ Read File ⟳
+ *
+ * Supports pause/resume for readline prompt coordination: pause clears the
+ * status line so `console.log()` or `rl.prompt()` output is clean, resume
+ * redraws it.
+ */
+export function createStatusLineManager() {
+    // Internal state
+    let spinnerLabel = null;
+    let spinnerFrameIndex = 0;
+    let spinnerIntervalId = null;
+    let elapsedMs = 0;
+    let elapsedStartTime = null;
+    let elapsedIntervalId = null;
+    let agents = [];
+    let tools = [];
+    let paused = false;
+    let lineVisible = false;
+    // ---- Rendering ----
+    function composeLine() {
+        const parts = [];
+        // Spinner + label
+        if (spinnerLabel) {
+            const frame = SPINNER_FRAMES[spinnerFrameIndex % SPINNER_FRAMES.length];
+            parts.push(`${cyan(frame)} ${spinnerLabel}`);
+        }
+        // Elapsed timer
+        if (elapsedStartTime !== null) {
+            const now = Date.now();
+            const currentElapsed = now - elapsedStartTime;
+            parts.push(gray(`[${formatElapsed(currentElapsed)}]`));
+        }
+        else if (elapsedMs > 0) {
+            parts.push(gray(`[${formatElapsed(elapsedMs)}]`));
+        }
+        // Active agents (beyond the spinner label agent)
+        const activeAgents = agents.filter(a => a.active);
+        if (activeAgents.length > 1) {
+            const names = activeAgents.map(a => a.name).join(', ');
+            parts.push(gray(`agents: ${names}`));
+        }
+        // Active tools (max 3 displayed)
+        const runningTools = tools.filter(t => t.status === 'running');
+        const displayTools = runningTools.slice(0, 3);
+        if (displayTools.length > 0) {
+            const toolText = displayTools
+                .map(t => `${getToolIcon(t.name)} ${formatToolName(t.name)} ⟳`)
+                .join('  ');
+            parts.push(toolText);
+            if (runningTools.length > 3) {
+                parts.push(gray(`+${runningTools.length - 3} more`));
+            }
+        }
+        return parts.join(gray(' | '));
+    }
+    function render() {
+        if (paused)
+            return;
+        const line = composeLine();
+        if (!line) {
+            if (lineVisible) {
+                process.stdout.write('\r\x1b[K');
+                lineVisible = false;
+            }
+            return;
+        }
+        // Truncate to terminal width
+        const maxWidth = process.stdout.columns || 80;
+        // Strip ANSI for length measurement, truncate raw if needed
+        // Note: When truncated, ANSI color codes are lost (graceful degradation).
+        // This is acceptable because narrow terminals are uncommon for dev CLIs.
+        const stripped = line.replace(/\x1b\[[0-9;]*m/g, '');
+        let output = line;
+        if (stripped.length > maxWidth) {
+            output = truncateToWidth(stripped, maxWidth);
+        }
+        process.stdout.write(`\r\x1b[K${output}`);
+        lineVisible = true;
+    }
+    function clear() {
+        if (lineVisible) {
+            process.stdout.write('\r\x1b[K');
+            lineVisible = false;
+        }
+    }
+    function pause() {
+        paused = true;
+        clear();
+    }
+    function resume() {
+        paused = false;
+        render();
+    }
+    // ---- Spinner ----
+    function tickSpinner() {
+        spinnerFrameIndex++;
+        render();
+    }
+    function setSpinner(label) {
+        spinnerLabel = label;
+        if (label) {
+            if (spinnerIntervalId === null) {
+                spinnerFrameIndex = 0;
+                spinnerIntervalId = setInterval(tickSpinner, SPINNER_INTERVAL_MS);
+            }
+        }
+        else {
+            if (spinnerIntervalId !== null) {
+                clearInterval(spinnerIntervalId);
+                spinnerIntervalId = null;
+            }
+        }
+        render();
+    }
+    // ---- Elapsed timer ----
+    function startElapsedTimer() {
+        elapsedStartTime = Date.now();
+        if (elapsedIntervalId === null) {
+            elapsedIntervalId = setInterval(() => {
+                if (elapsedStartTime !== null) {
+                    elapsedMs = Date.now() - elapsedStartTime;
+                }
+                render();
+            }, 1000);
+        }
+    }
+    function stopElapsedTimer() {
+        if (elapsedIntervalId !== null) {
+            clearInterval(elapsedIntervalId);
+            elapsedIntervalId = null;
+        }
+        elapsedStartTime = null;
+    }
+    function setElapsed(ms) {
+        elapsedMs = ms;
+        render();
+    }
+    // ---- Agents ----
+    function setAgents(newAgents) {
+        agents = newAgents;
+        render();
+    }
+    // ---- Tools ----
+    function addTool(name) {
+        // Avoid duplicates
+        if (!tools.some(t => t.name === name && t.status === 'running')) {
+            tools.push({ name, status: 'running' });
+        }
+        render();
+    }
+    function removeTool(name, status, detail) {
+        const idx = tools.findIndex(t => t.name === name && t.status === 'running');
+        if (idx >= 0) {
+            tools[idx] = { name, status, detail };
+        }
+        // Remove completed/errored tools after a brief moment (or immediately for cleanliness)
+        tools = tools.filter(t => t.status === 'running');
+        render();
+    }
+    // ---- Lifecycle ----
+    function reset() {
+        setSpinner(null);
+        stopElapsedTimer();
+        elapsedMs = 0;
+        agents = [];
+        tools = [];
+        clear();
+    }
+    function cleanup() {
+        reset();
+        // Extra safety: clear any remaining intervals
+        if (spinnerIntervalId !== null) {
+            clearInterval(spinnerIntervalId);
+            spinnerIntervalId = null;
+        }
+        if (elapsedIntervalId !== null) {
+            clearInterval(elapsedIntervalId);
+            elapsedIntervalId = null;
+        }
+    }
+    return {
+        setSpinner,
+        setElapsed,
+        setAgents,
+        addTool,
+        removeTool,
+        render,
+        clear,
+        pause,
+        resume,
+        startElapsedTimer,
+        stopElapsedTimer,
+        reset,
+        cleanup,
+    };
+}
+// ---------------------------------------------------------------------------
+// Console.log wrapper — pause/resume status line for permanent output
+// ---------------------------------------------------------------------------
+/**
+ * Print permanent output while preserving the status line.
+ *
+ * Usage: `log(statusLine, 'Hello', someVar)` instead of `console.log(...)`.
+ */
+export function log(statusLine, ...args) {
+    statusLine.pause();
+    console.log(...args);
+    statusLine.resume();
+}

package/dist/cli/hitl.d.ts

@@ -0,0 +1,33 @@
+/**
+ * CLI HITL Helpers
+ *
+ * Purpose:
+ * - Provide pure parsing/selection helpers for HITL option requests used by the CLI.
+ *
+ * Key Features:
+ * - Parse `hitl-option-request` system payloads into normalized structures.
+ * - Resolve user input into option IDs (by number or option id).
+ * - Provide deterministic fallback option resolution.
+ *
+ * Implementation Notes:
+ * - Parser accepts generic event payloads and rejects incomplete requests.
+ * - Fallback defaults to explicit `no` when available, otherwise first option.
+ *
+ * Recent Changes:
+ * - 2026-02-14: Added initial helper module for CLI HITL response flow support.
+ */
+export interface HitlOptionPayload {
+    id: string;
+    label: string;
+    description?: string;
+}
+export interface HitlOptionRequestPayload {
+    requestId: string;
+    title: string;
+    message: string;
+    chatId: string | null;
+    options: HitlOptionPayload[];
+    defaultOptionId: string;
+}
+export declare function parseHitlOptionRequest(eventData: unknown): HitlOptionRequestPayload | null;
+export declare function resolveHitlOptionSelectionInput(options: HitlOptionPayload[], rawInput: string, fallbackOptionId: string): string | null;

package/dist/cli/hitl.js

@@ -0,0 +1,81 @@
+/**
+ * CLI HITL Helpers
+ *
+ * Purpose:
+ * - Provide pure parsing/selection helpers for HITL option requests used by the CLI.
+ *
+ * Key Features:
+ * - Parse `hitl-option-request` system payloads into normalized structures.
+ * - Resolve user input into option IDs (by number or option id).
+ * - Provide deterministic fallback option resolution.
+ *
+ * Implementation Notes:
+ * - Parser accepts generic event payloads and rejects incomplete requests.
+ * - Fallback defaults to explicit `no` when available, otherwise first option.
+ *
+ * Recent Changes:
+ * - 2026-02-14: Added initial helper module for CLI HITL response flow support.
+ */
+export function parseHitlOptionRequest(eventData) {
+    if (!eventData || typeof eventData !== 'object') {
+        return null;
+    }
+    const payload = eventData;
+    const content = payload.content && typeof payload.content === 'object'
+        ? payload.content
+        : null;
+    if (!content || String(content.eventType || '').trim() !== 'hitl-option-request') {
+        return null;
+    }
+    const requestId = String(content.requestId || '').trim();
+    if (!requestId) {
+        return null;
+    }
+    const options = Array.isArray(content.options)
+        ? content.options
+            .map((option) => {
+            const optionRecord = option && typeof option === 'object'
+                ? option
+                : null;
+            return {
+                id: String(optionRecord?.id || '').trim(),
+                label: String(optionRecord?.label || '').trim(),
+                description: optionRecord?.description ? String(optionRecord.description) : undefined
+            };
+        })
+            .filter((option) => option.id.length > 0 && option.label.length > 0)
+        : [];
+    if (options.length === 0) {
+        return null;
+    }
+    const preferredDefault = String(content.defaultOptionId || '').trim();
+    const defaultOptionId = options.some((option) => option.id === preferredDefault)
+        ? preferredDefault
+        : (options.find((option) => option.id === 'no')?.id || options[0].id);
+    return {
+        requestId,
+        title: String(content.title || 'Approval required').trim() || 'Approval required',
+        message: String(content.message || '').trim(),
+        chatId: payload.chatId ? String(payload.chatId) : null,
+        options,
+        defaultOptionId
+    };
+}
+export function resolveHitlOptionSelectionInput(options, rawInput, fallbackOptionId) {
+    const normalizedInput = String(rawInput || '').trim();
+    if (!normalizedInput) {
+        return fallbackOptionId;
+    }
+    const asNumber = Number(normalizedInput);
+    if (Number.isFinite(asNumber)) {
+        const index = Math.floor(asNumber) - 1;
+        if (index >= 0 && index < options.length) {
+            return options[index].id;
+        }
+    }
+    const byId = options.find((option) => option.id.toLowerCase() === normalizedInput.toLowerCase());
+    if (byId) {
+        return byId.id;
+    }
+    return null;
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/stream.d.ts

@@ -0,0 +1,41 @@
+/**
+ * CLI Streaming Module - Real-time Agent Response Display
+ *
+ * Manages streaming display for CLI interface with real-time chunk accumulation,
+ * visual feedback, and comprehensive event processing.
+ *
+ * FEATURES:
+ * - Real-time streaming with visual feedback and state tracking
+ * - Comprehensive event processing (chunk, end, error)
+ * - Tool streaming output display for shell_cmd (stdout/stderr)
+ * - Color-coded streaming indicators and status messages
+ * - Enhanced tool display with Unicode icons and formatted names
+ * - Tool output truncation at 50K characters
+ * - Modular design for reuse across CLI components
+ * - Event-driven display (no timer dependencies)
+ * CHANGES:
+ * - 2026-02-11: Enhanced tool display with icons, formatted names, stderr prefix, 50K truncation
+ * - 2026-02-08: Added tool streaming support for shell_cmd real-time output display
+ * - 2025-02-06: Track last streamed message to prevent duplicate MESSAGE events after streaming output
+ */
+import { type StatusLineManager } from './display.js';
+export interface StreamingState {
+    isActive: boolean;
+    content: string;
+    sender?: string;
+    messageId?: string;
+    lastStreamedMessageId?: string;
+    lastStreamedContent?: string;
+    lastStreamedSender?: string;
+    lastStreamedAt?: number;
+}
+export declare function createStreamingState(): StreamingState;
+export declare function handleStreamingEvents(eventData: any, streaming: StreamingState, statusLine?: StatusLineManager): void;
+export declare function handleToolEvents(eventData: any): void;
+export declare function handleToolStreamEvents(eventData: any): void;
+/** Reset tool stream tracking (call on tool-start or new tool execution). */
+export declare function resetToolStreamTracking(): void;
+export declare function handleActivityEvents(eventData: any): void;
+export declare function handleWorldEventWithStreaming(eventType: string, eventData: any, streaming: StreamingState, statusLine?: StatusLineManager): boolean;
+export declare function resetStreamingState(streaming: StreamingState): void;
+export declare function isStreamingActive(streaming: StreamingState): boolean;