agent-world 0.11.1 → 0.12.0

package/dist/core/storage/queue-storage.js

@@ -0,0 +1,290 @@
+/**
+ * Queue Storage - In-Memory Message Queue Implementation
+ *
+ * Purpose: Simple in-memory message queue for async processing
+ *
+ * Features:
+ * - FIFO per-world message queuing
+ * - Per-world locking (one message processing at a time)
+ * - Automatic retry on failure
+ * - Basic statistics tracking
+ *
+ * Implementation:
+ * - In-memory queues with Map-based storage
+ * - Simple locking via processing state tracking
+ * - Auto-retry when marking failed (up to maxRetries)
+ *
+ * Queue Message Lifecycle:
+ * 1. pending: Message enqueued, waiting in queue
+ * 2. processing: Message dequeued and being processed
+ * 3. completed: Processing finished successfully
+ * 4. failed: Processing failed after max retries
+ *
+ * Note: Data is NOT persisted - queue cleared on restart
+ * For production with persistence, use external MQ system (Redis, RabbitMQ, etc)
+ *
+ * Changes:
+ * - 2025-11-01: Replace SQL implementation with in-memory version
+ * - Reduced from 716 lines to 453 lines (242 lines of actual code)
+ * - Removed: SQL transactions, heartbeat monitoring, stuck detection, priority ordering
+ * - Kept: Core queue operations, per-world locking, auto-retry, statistics
+ * - All 31 unit tests pass with in-memory implementation
+ */
+/**
+ * Generate UUID v4
+ */
+function generateUUID() {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+/**
+ * In-Memory Queue Storage Implementation
+ */
+export function createMemoryQueueStorage() {
+    // Per-world pending message queues
+    const queues = new Map();
+    // Currently processing messages (one per world)
+    const processing = new Map();
+    // Completed/failed messages (for stats)
+    const completed = new Map();
+    const failed = new Map();
+    /**
+     * Enqueue a message for processing
+     */
+    async function enqueue(message) {
+        const queueMessage = {
+            id: generateUUID(),
+            worldId: message.worldId,
+            messageId: message.messageId,
+            content: message.content,
+            sender: message.sender,
+            chatId: message.chatId ?? null,
+            status: 'pending',
+            priority: message.priority,
+            createdAt: new Date(),
+            retryCount: 0,
+            maxRetries: message.maxRetries,
+            timeoutSeconds: message.timeoutSeconds
+        };
+        const queue = queues.get(message.worldId) || [];
+        queue.push(queueMessage);
+        queues.set(message.worldId, queue);
+        return queueMessage;
+    }
+    /**
+     * Dequeue the next pending message for a specific world
+     * Returns null if world is already processing or no pending messages
+     */
+    async function dequeue(worldId) {
+        // Check if world is already processing
+        if (processing.has(worldId)) {
+            return null;
+        }
+        // Get queue for this world
+        const queue = queues.get(worldId);
+        if (!queue || queue.length === 0) {
+            return null;
+        }
+        // Dequeue first message (FIFO)
+        const message = queue.shift();
+        message.status = 'processing';
+        message.processedAt = new Date();
+        message.heartbeatAt = new Date();
+        // Mark as processing
+        processing.set(worldId, message);
+        // Update queue
+        if (queue.length === 0) {
+            queues.delete(worldId);
+        }
+        return message;
+    }
+    /**
+     * Update heartbeat timestamp (no-op for simple implementation)
+     */
+    async function updateHeartbeat(messageId) {
+        // Find processing message and update heartbeat
+        for (const [, message] of processing) {
+            if (message.messageId === messageId) {
+                message.heartbeatAt = new Date();
+                return;
+            }
+        }
+    }
+    /**
+     * Mark a message as completed successfully
+     */
+    async function markCompleted(messageId) {
+        // Find and remove from processing
+        for (const [worldId, message] of processing) {
+            if (message.id === messageId) {
+                message.status = 'completed';
+                message.completedAt = new Date();
+                processing.delete(worldId);
+                completed.set(message.id, message);
+                return;
+            }
+        }
+    } /**
+     * Mark a message as failed with error details
+     * Automatically retries if retryCount < maxRetries
+     */
+    async function markFailed(messageId, error) {
+        // Find message in processing
+        for (const [worldId, message] of processing) {
+            if (message.id === messageId) {
+                message.error = error;
+                message.retryCount++;
+                if (message.retryCount < message.maxRetries) {
+                    // Retry: reset to pending and re-enqueue
+                    message.status = 'pending';
+                    message.processedAt = undefined;
+                    message.heartbeatAt = undefined;
+                    processing.delete(worldId);
+                    const queue = queues.get(worldId) || [];
+                    queue.push(message);
+                    queues.set(worldId, queue);
+                }
+                else {
+                    // Max retries reached: mark as failed
+                    message.status = 'failed';
+                    message.completedAt = new Date();
+                    processing.delete(worldId);
+                    failed.set(message.id, message);
+                }
+                return;
+            }
+        }
+    }
+    /**
+     * Retry a failed message (reset to pending)
+     */
+    async function retryMessage(messageId) {
+        // Find in failed messages
+        for (const [id, message] of failed) {
+            if (message.messageId === messageId && message.retryCount < message.maxRetries) {
+                message.status = 'pending';
+                message.retryCount++;
+                message.processedAt = undefined;
+                message.heartbeatAt = undefined;
+                message.completedAt = undefined;
+                failed.delete(id);
+                const queue = queues.get(message.worldId) || [];
+                queue.push(message);
+                queues.set(message.worldId, queue);
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Get queue depth for a world
+     */
+    async function getQueueDepth(worldId) {
+        const queue = queues.get(worldId);
+        return queue ? queue.length : 0;
+    }
+    /**
+     * Get queue statistics
+     */
+    async function getQueueStats(worldId) {
+        const worldIds = worldId ? [worldId] : [
+            ...new Set([
+                ...queues.keys(),
+                ...Array.from(processing.values()).map(m => m.worldId),
+                ...Array.from(completed.values()).map(m => m.worldId),
+                ...Array.from(failed.values()).map(m => m.worldId)
+            ])
+        ];
+        return worldIds.map(wid => {
+            const queue = queues.get(wid) || [];
+            const proc = Array.from(processing.values()).filter(m => m.worldId === wid);
+            const comp = Array.from(completed.values()).filter(m => m.worldId === wid);
+            const fail = Array.from(failed.values()).filter(m => m.worldId === wid);
+            const oldestPending = queue.length > 0 ? queue[0].createdAt : undefined;
+            const processingTimes = comp
+                .filter(m => m.processedAt && m.completedAt)
+                .map(m => m.completedAt.getTime() - m.processedAt.getTime());
+            const avgProcessingTime = processingTimes.length > 0
+                ? processingTimes.reduce((a, b) => a + b, 0) / processingTimes.length
+                : undefined;
+            return {
+                worldId: wid,
+                pending: queue.length,
+                processing: proc.length,
+                completed: comp.length,
+                failed: fail.length,
+                oldestPending,
+                avgProcessingTime
+            };
+        });
+    }
+    /**
+     * Detect stuck messages (not implemented for simple version)
+     */
+    async function detectStuckMessages() {
+        return 0;
+    }
+    /**
+     * Cleanup old messages
+     */
+    async function cleanup(olderThan) {
+        let count = 0;
+        const threshold = olderThan.getTime();
+        // Cleanup completed messages
+        for (const [id, message] of completed) {
+            if (message.completedAt && message.completedAt.getTime() < threshold) {
+                completed.delete(id);
+                count++;
+            }
+        }
+        // Cleanup failed messages
+        for (const [id, message] of failed) {
+            if (message.completedAt && message.completedAt.getTime() < threshold) {
+                failed.delete(id);
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Get message by ID
+     */
+    async function getMessage(messageId) {
+        // Check all storage locations
+        for (const queue of queues.values()) {
+            const msg = queue.find(m => m.messageId === messageId);
+            if (msg)
+                return msg;
+        }
+        for (const msg of processing.values()) {
+            if (msg.messageId === messageId)
+                return msg;
+        }
+        for (const msg of completed.values()) {
+            if (msg.messageId === messageId)
+                return msg;
+        }
+        for (const msg of failed.values()) {
+            if (msg.messageId === messageId)
+                return msg;
+        }
+        return null;
+    }
+    return {
+        enqueue,
+        dequeue,
+        updateHeartbeat,
+        markCompleted,
+        markFailed,
+        retryMessage,
+        getQueueDepth,
+        getQueueStats,
+        detectStuckMessages,
+        cleanup,
+        getMessage
+    };
+}
+//# sourceMappingURL=queue-storage.js.map

package/dist/core/storage/queue-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-storage.js","sourceRoot":"","sources":["../../../core/storage/queue-storage.ts"],"names":[],"mappings":"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"}

package/dist/core/storage/skill-storage.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Skill Storage Module - File I/O Operations for World-Level Agent Skills
+ *
+ * Purpose:
+ * File-based storage for world-scoped skills following the Anthropic Agent Skills Protocol.
+ * Each skill is a directory under `{world-dir}/skills/{skill-name}/` containing a `SKILL.md`
+ * file with YAML frontmatter metadata and markdown body instructions.
+ *
+ * Features:
+ * - SKILL.md parsing with YAML frontmatter extraction and validation
+ * - Skill CRUD operations (import, read, list, delete, export)
+ * - `.meta.json` write-time cache for fast metadata listing
+ * - Cache fallback to SKILL.md parsing when cache is missing or corrupt
+ * - Path traversal protection using resolve + startsWith guards
+ * - Duplicate skill rejection via `skillExists()` check before import
+ * - Content size and line-count validation with warnings
+ *
+ * Notes:
+ * - Follows `agent-storage.ts` pattern: standalone module with explicit `rootPath`
+ * - Uses `fs/promises` for all I/O, pure functions, no classes
+ * - Skills are NOT tool calls — they follow the Anthropic Agent Skills Protocol
+ *   as a content/instruction protocol (app reads SKILL.md, injects into user message)
+ * - Skill metadata limits: name max 64 chars (kebab-case), description max 256 chars
+ *
+ * Recent Changes:
+ * - 2026-02-09: Initial implementation for world-level skills system
+ */
+import type { SkillMetadata, SkillData, WorldSkill, SkillValidationResult } from '../types.js';
+/**
+ * Get the skills root directory for a world.
+ */
+export declare function getSkillsDir(rootPath: string, worldId: string): string;
+/**
+ * Get the directory path for a specific skill.
+ */
+export declare function getSkillDir(rootPath: string, worldId: string, skillName: string): string;
+/**
+ * Get the SKILL.md file path for a specific skill.
+ */
+export declare function getSkillFilePath(rootPath: string, worldId: string, skillName: string): string;
+/**
+ * Ensure the skills root directory exists.
+ */
+export declare function ensureSkillsDirectory(rootPath: string, worldId: string): Promise<void>;
+/**
+ * Ensure a specific skill directory exists.
+ */
+export declare function ensureSkillDirectory(rootPath: string, worldId: string, skillName: string): Promise<void>;
+/**
+ * Parse SKILL.md content into metadata (YAML frontmatter) and body content.
+ * Supports standard YAML frontmatter delimited by `---` lines.
+ *
+ * @param raw - Raw file content of SKILL.md
+ * @returns Parsed SkillData with metadata and content
+ * @throws Error if frontmatter is missing or malformed
+ */
+export declare function parseSkillFile(raw: string): SkillData;
+/**
+ * Extract just the metadata from a SKILL.md file (without body content).
+ */
+export declare function extractSkillMetadata(raw: string): SkillMetadata;
+/**
+ * Validate skill metadata against protocol constraints.
+ */
+export declare function validateSkillMetadata(metadata: SkillMetadata): SkillValidationResult;
+/**
+ * Validate skill content (SKILL.md body) for size and line count.
+ */
+export declare function validateSkillContent(content: string): SkillValidationResult;
+/**
+ * Check if a skill exists in a world.
+ */
+export declare function skillExists(rootPath: string, worldId: string, skillName: string): Promise<boolean>;
+/**
+ * Save a SKILL.md file for a skill.
+ */
+export declare function saveSkillFile(rootPath: string, worldId: string, skillName: string, content: string): Promise<void>;
+/**
+ * Load a SKILL.md file content for a skill.
+ */
+export declare function loadSkillFile(rootPath: string, worldId: string, skillName: string): Promise<string>;
+/**
+ * Delete a skill directory and all its contents.
+ */
+export declare function deleteSkillFolder(rootPath: string, worldId: string, skillName: string): Promise<boolean>;
+/**
+ * List all skill folder names in a world's skills directory.
+ */
+export declare function listSkillFolders(rootPath: string, worldId: string): Promise<string[]>;
+/**
+ * Get a full WorldSkill object for a specific skill.
+ */
+export declare function getWorldSkill(rootPath: string, worldId: string, skillName: string): Promise<WorldSkill | null>;
+/**
+ * Get just the metadata for a specific skill.
+ */
+export declare function getWorldSkillMetadata(rootPath: string, worldId: string, skillName: string): Promise<SkillMetadata | null>;
+/**
+ * List all WorldSkill objects in a world.
+ */
+export declare function listWorldSkills(rootPath: string, worldId: string): Promise<WorldSkill[]>;
+/**
+ * List skill metadata for all skills in a world.
+ * Uses `.meta.json` cache for fast listing; falls back to SKILL.md parsing.
+ */
+export declare function listWorldSkillsMetadata(rootPath: string, worldId: string): Promise<SkillMetadata[]>;
+/**
+ * Import a skill into a world from raw SKILL.md content.
+ * Validates metadata, rejects duplicates, and regenerates cache.
+ *
+ * @throws {DuplicateSkillError} if skill with same name already exists
+ * @throws {Error} if content is invalid
+ */
+export declare function importWorldSkill(rootPath: string, worldId: string, skillContent: string): Promise<WorldSkill>;
+/**
+ * Export a skill's SKILL.md content as a raw string.
+ */
+export declare function exportWorldSkill(rootPath: string, worldId: string, skillName: string): Promise<string | null>;
+/**
+ * Delete a skill from a world and regenerate the metadata cache.
+ */
+export declare function deleteWorldSkill(rootPath: string, worldId: string, skillName: string): Promise<boolean>;
+/**
+ * Get total size (in bytes) of all SKILL.md files in a world.
+ */
+export declare function getWorldSkillsSize(rootPath: string, worldId: string): Promise<number>;
+/**
+ * Regenerate the `.meta.json` metadata cache from all SKILL.md files.
+ */
+export declare function regenerateMetaCache(rootPath: string, worldId: string): Promise<void>;
+/**
+ * Load the `.meta.json` metadata cache.
+ * Returns null if cache is missing or corrupt.
+ */
+export declare function loadMetaCache(rootPath: string, worldId: string): Promise<SkillMetadata[] | null>;
+//# sourceMappingURL=skill-storage.d.ts.map

package/dist/core/storage/skill-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-storage.d.ts","sourceRoot":"","sources":["../../../core/storage/skill-storage.ts"],"names":[],"mappings":"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"}