@illuma-ai/agents 1.4.0-alpha.6 → 1.5.0

package/dist/cjs/content/ContentStore.cjs

@@ -1,638 +0,0 @@
-'use strict';
-
-var crypto = require('node:crypto');
-
-/**
- * Default 3-minute TTL for ephemeral content entries. Resets on every
- * access. Kept short to reduce cache-backing memory pressure — callers
- * that persist to durable storage (see {@link ArtifactStore}) rely on
- * lazy restore from the durable backend on cache miss.
- *
- * Exported so consumers can construct their injected {@link Keyv}
- * instance with a matching TTL without hard-coding the number.
- */
-const CONTENT_TTL_MS = 180_000;
-/** Default number of lines returned by readLines(). */
-const DEFAULT_READ_LINES = 200;
-/** Maximum lines that can be read in a single call. */
-const MAX_READ_LINES = 500;
-/** Maximum search results returned per call. */
-const MAX_SEARCH_RESULTS = 50;
-/** Lines of context to show around a failed edit match for diagnostics. */
-const ERROR_CONTEXT_LINES = 5;
-/**
- * Normalize line endings: CRLF → LF, stray CR → LF.
- * Prevents invisible mismatches when content originates from Windows/Office tools.
- */
-function normalizeNewlines(text) {
-    return text.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
-}
-/**
- * Trim trailing whitespace from each line — used as a fallback when
- * exact matching fails due to invisible trailing spaces.
- */
-function trimTrailingPerLine(text) {
-    return text
-        .split('\n')
-        .map((l) => l.trimEnd())
-        .join('\n');
-}
-/**
- * Fuzzy indentation-normalized matching. Compares line content after stripping
- * all leading whitespace, then maps back to the real line range in the content.
- * Returns `{ start, end }` character offsets in `content` if a unique match is found,
- * or `null` if no match or ambiguous (multiple matches).
- */
-function findIndentationNormalizedMatch(content, oldStr) {
-    const contentLines = content.split('\n');
-    const oldLines = oldStr.split('\n');
-    // Strip leading whitespace for comparison — keep non-empty lines only for matching key
-    const oldTrimmed = oldLines.map((l) => l.trimStart());
-    // Need at least 1 non-empty line to match on
-    const nonEmptyOldLines = oldTrimmed.filter((l) => l.length > 0);
-    if (nonEmptyOldLines.length === 0)
-        return null;
-    const matches = [];
-    // Slide a window of oldLines.length across contentLines
-    for (let i = 0; i <= contentLines.length - oldLines.length; i++) {
-        let matched = true;
-        for (let j = 0; j < oldLines.length; j++) {
-            const contentTrimmed = contentLines[i + j].trimStart();
-            if (contentTrimmed !== oldTrimmed[j]) {
-                matched = false;
-                break;
-            }
-        }
-        if (matched) {
-            // Calculate character offsets for the matched region
-            let charStart = 0;
-            for (let k = 0; k < i; k++) {
-                charStart += contentLines[k].length + 1; // +1 for \n
-            }
-            let charEnd = charStart;
-            for (let k = 0; k < oldLines.length; k++) {
-                charEnd +=
-                    contentLines[i + k].length + (k < oldLines.length - 1 ? 1 : 0);
-            }
-            matches.push({ start: charStart, end: charEnd });
-        }
-    }
-    // Only return if exactly one match (unambiguous)
-    return matches.length === 1 ? matches[0] : null;
-}
-/** Minimum fraction of lines that must match for partial fuzzy matching. */
-const FUZZY_MATCH_THRESHOLD = 0.6;
-/**
- * Partial fuzzy matching — tolerates some lines being slightly different.
- * LLMs often reconstruct code from memory with subtle differences on a few lines
- * (e.g., changed variable name, missing semicolon). This layer finds the best-scoring
- * region where at least FUZZY_MATCH_THRESHOLD of lines match after trimming.
- *
- * Returns `{ start, end }` character offsets if a single high-confidence region is found.
- */
-function findPartialFuzzyMatch(content, oldStr) {
-    const contentLines = content.split('\n');
-    const oldLines = oldStr.split('\n');
-    // Need at least 3 lines for fuzzy matching to be meaningful
-    if (oldLines.length < 3)
-        return null;
-    const oldTrimmed = oldLines.map((l) => l.trim());
-    const minScore = Math.ceil(oldLines.length * FUZZY_MATCH_THRESHOLD);
-    let bestScore = 0;
-    let bestIdx = -1;
-    let secondBestScore = 0;
-    for (let i = 0; i <= contentLines.length - oldLines.length; i++) {
-        let score = 0;
-        for (let j = 0; j < oldLines.length; j++) {
-            const contentTrimmed = contentLines[i + j].trim();
-            // Exact match after trimming all whitespace
-            if (contentTrimmed === oldTrimmed[j]) {
-                score++;
-            }
-            else if (
-            // Substring match — one contains the other (handles minor edits)
-            contentTrimmed.length > 0 &&
-                oldTrimmed[j].length > 0 &&
-                (contentTrimmed.includes(oldTrimmed[j]) ||
-                    oldTrimmed[j].includes(contentTrimmed))) {
-                score += 0.5;
-            }
-        }
-        if (score > bestScore) {
-            secondBestScore = bestScore;
-            bestScore = score;
-            bestIdx = i;
-        }
-        else if (score > secondBestScore) {
-            secondBestScore = score;
-        }
-    }
-    // Require: meets threshold AND is clearly better than second-best (unique match)
-    if (bestIdx < 0 ||
-        bestScore < minScore ||
-        secondBestScore >= bestScore * 0.9) {
-        return null;
-    }
-    // Calculate character offsets
-    let charStart = 0;
-    for (let k = 0; k < bestIdx; k++) {
-        charStart += contentLines[k].length + 1;
-    }
-    let charEnd = charStart;
-    for (let k = 0; k < oldLines.length; k++) {
-        charEnd +=
-            contentLines[bestIdx + k].length + (k < oldLines.length - 1 ? 1 : 0);
-    }
-    return { start: charStart, end: charEnd };
-}
-/**
- * Find the best approximate match location for `needle` in `haystack` using
- * overlapping line content. Returns the 1-based line number of the best match
- * region, or 0 if no reasonable overlap is found.
- */
-function findApproximateLocation(haystack, needle) {
-    const needleLines = needle
-        .split('\n')
-        .map((l) => l.trim())
-        .filter(Boolean);
-    if (needleLines.length === 0)
-        return 0;
-    const haystackLines = haystack.split('\n');
-    let bestScore = 0;
-    let bestLine = 0;
-    for (let i = 0; i < haystackLines.length; i++) {
-        let score = 0;
-        for (let j = 0; j < needleLines.length && i + j < haystackLines.length; j++) {
-            if (haystackLines[i + j].trim().includes(needleLines[j]) ||
-                needleLines[j].includes(haystackLines[i + j].trim())) {
-                score++;
-            }
-        }
-        if (score > bestScore) {
-            bestScore = score;
-            bestLine = i + 1; // 1-based
-        }
-    }
-    // Require at least 1 matching line to report a location
-    return bestScore >= 1 ? bestLine : 0;
-}
-/**
- * Build a diagnostic error message showing nearby content when an edit match fails.
- */
-function buildEditDiagnostic(content, oldStr) {
-    const approxLine = findApproximateLocation(content, oldStr);
-    const lines = content.split('\n');
-    let contextSnippet = '';
-    if (approxLine > 0) {
-        const start = Math.max(0, approxLine - 1 - Math.floor(ERROR_CONTEXT_LINES / 2));
-        const end = Math.min(lines.length, start + ERROR_CONTEXT_LINES);
-        const padWidth = String(end).length;
-        const snippet = lines
-            .slice(start, end)
-            .map((l, i) => `${String(start + i + 1).padStart(padWidth, ' ')} | ${l}`)
-            .join('\n');
-        contextSnippet = `\nNearest content (around line ${approxLine}):\n${snippet}`;
-    }
-    return `old_str not found in content. Re-read the file with content_tool read before retrying.${contextSnippet}`;
-}
-/**
- * Strip line-number prefixes ("  N | ") that readLines() adds.
- * Agents may copy these when constructing old_str for edits.
- */
-function stripLineNumberPrefixes(text) {
-    return text
-        .split('\n')
-        .map((line) => {
-        const match = line.match(/^\s*\d+\s*\|\s?(.*)/);
-        return match ? match[1] : line;
-    })
-        .join('\n');
-}
-/**
- * Generates a short, URL-safe random ID.
- * @param length - Number of random bytes (output is hex, so 2x chars). Default 5 → 10 hex chars.
- */
-function generateId(length = 5) {
-    return crypto.randomBytes(length).toString('hex');
-}
-/**
- * Per-conversation content store backed by a caller-provided {@link Keyv}
- * cache (typically Keyv + @keyv/redis, with in-memory fallback).
- *
- * Stores large content (MCP results, artifacts, agent-generated text)
- * outside the LLM context window. Entries inherit the TTL configured on
- * the injected {@link Keyv} instance — {@link CONTENT_TTL_MS} is the
- * recommended default.
- *
- * The caller is responsible for namespacing the Keyv instance per
- * conversation so content_ids don't collide across threads.
- *
- * @example
- * ```ts
- * import Keyv from 'keyv';
- * const cache = new Keyv({ namespace: `content-store::${conversationId}`, ttl: CONTENT_TTL_MS });
- * const store = new ContentStore(cache);
- * const id = await store.store({ name: 'report.csv', type: 'text/plain', content: csv, source: 'mcp:sharepoint' });
- * const result = await store.readLines(id, 1, 50);
- * ```
- */
-class ContentStore {
-    cache;
-    indexKey = '_index';
-    /**
-     * @param cache - A pre-namespaced {@link Keyv} instance. The store
-     *   writes both content entries and a per-store `_index` key, so
-     *   callers MUST namespace the Keyv per conversation to avoid
-     *   cross-thread collisions.
-     */
-    constructor(cache) {
-        this.cache = cache;
-    }
-    /**
-     * Store new content and return a content ID.
-     * @param entry - The content to store with metadata.
-     * @returns The generated content ID.
-     */
-    async store(entry) {
-        const id = generateId();
-        const lines = entry.content.split('\n');
-        const metadata = {
-            id,
-            name: entry.name,
-            type: entry.type,
-            source: entry.source,
-            totalLines: lines.length,
-            totalChars: entry.content.length,
-            createdAt: Date.now(),
-        };
-        const stored = { content: entry.content, metadata };
-        await this.cache.set(id, JSON.stringify(stored));
-        // Update the index
-        const index = await this.getIndex();
-        index[id] = metadata;
-        await this.cache.set(this.indexKey, JSON.stringify(index));
-        return id;
-    }
-    /**
-     * Get metadata for a content entry without loading the full content.
-     * @param contentId - The content entry ID.
-     * @returns Metadata or null if not found.
-     */
-    async info(contentId) {
-        const stored = await this.getStored(contentId);
-        if (!stored) {
-            return null;
-        }
-        // Touch both content entry and index to reset TTL
-        await this.touchEntry(contentId, stored);
-        return stored.metadata;
-    }
-    /**
-     * Read lines from a content entry with optional range.
-     * Lines are 1-based and inclusive. Returns formatted content with line numbers.
-     *
-     * @param contentId - The content entry ID.
-     * @param startLine - First line to read (1-based, default 1).
-     * @param endLine - Last line to read (inclusive, default startLine + DEFAULT_READ_LINES - 1).
-     * @returns Read result with formatted content and range info, or null if not found.
-     */
-    async readLines(contentId, startLine, endLine) {
-        const stored = await this.getStored(contentId);
-        if (!stored) {
-            return null;
-        }
-        const lines = stored.content.split('\n');
-        const totalLines = lines.length;
-        // Clamp start to valid range
-        const start = Math.max(1, startLine ?? 1);
-        // Clamp end: default to start + DEFAULT_READ_LINES - 1, cap at totalLines and start + MAX_READ_LINES - 1
-        let end = endLine ?? start + DEFAULT_READ_LINES - 1;
-        end = Math.min(end, totalLines, start + MAX_READ_LINES - 1);
-        // Slice is 0-based, our line numbers are 1-based
-        const slice = lines.slice(start - 1, end);
-        // Format with line numbers (padded for alignment)
-        const padWidth = String(end).length;
-        const formatted = slice
-            .map((line, i) => {
-            const lineNum = String(start + i).padStart(padWidth, ' ');
-            return `${lineNum} | ${line}`;
-        })
-            .join('\n');
-        // Touch both content entry and index to reset TTL
-        await this.touchEntry(contentId, stored);
-        return {
-            content: formatted,
-            startLine: start,
-            endLine: end,
-            totalLines,
-            totalChars: stored.content.length,
-            truncated: end < totalLines,
-        };
-    }
-    /**
-     * Read the full content of an entry without line-number formatting or line caps.
-     * Used by API endpoints that serve complete content to the frontend (e.g., CodeViz).
-     * Unlike readLines(), this has no MAX_READ_LINES cap and returns raw content.
-     *
-     * @param contentId - The content entry ID.
-     * @returns Raw content with total line/char counts, or null if not found.
-     */
-    async readAll(contentId) {
-        const stored = await this.getStored(contentId);
-        if (!stored) {
-            return null;
-        }
-        // Touch both content entry and index to reset TTL
-        await this.touchEntry(contentId, stored);
-        return {
-            content: stored.content,
-            totalLines: stored.content.split('\n').length,
-            totalChars: stored.content.length,
-        };
-    }
-    /**
-     * Search for a pattern within a content entry.
-     * Supports plain text matching and regex patterns.
-     *
-     * @param contentId - The content entry ID.
-     * @param pattern - Text or regex pattern to match.
-     * @param maxResults - Maximum matches to return (default MAX_SEARCH_RESULTS).
-     * @returns Array of matches with line numbers, or null if content not found.
-     */
-    async search(contentId, pattern, maxResults = MAX_SEARCH_RESULTS) {
-        const stored = await this.getStored(contentId);
-        if (!stored) {
-            return null;
-        }
-        const lines = stored.content.split('\n');
-        const matches = [];
-        // Try regex first, fall back to plain string match
-        let regex = null;
-        try {
-            regex = new RegExp(pattern, 'i');
-        }
-        catch {
-            // Invalid regex — use plain string matching below
-        }
-        for (let i = 0; i < lines.length && matches.length < maxResults; i++) {
-            const line = lines[i];
-            const isMatch = regex ? regex.test(line) : line.includes(pattern);
-            if (isMatch) {
-                matches.push({ lineNumber: i + 1, content: line });
-            }
-        }
-        // Touch both content entry and index to reset TTL
-        await this.touchEntry(contentId, stored);
-        return matches;
-    }
-    /**
-     * Surgical string replacement within a content entry.
-     * Fails if old_str is not found or appears more than once (ambiguous).
-     *
-     * Uses layered matching: exact → line-number-stripped → CRLF-normalized → trailing-whitespace-trimmed.
-     * On failure, returns diagnostic context showing nearby content to help the agent self-correct.
-     *
-     * @param contentId - The content entry ID.
-     * @param oldStr - Exact string to find.
-     * @param newStr - Replacement string.
-     * @returns Edit result with diff and affected line info.
-     */
-    async strReplace(contentId, oldStr, newStr) {
-        const stored = await this.getStored(contentId);
-        if (!stored) {
-            return {
-                success: false,
-                diff: '',
-                lineNumber: 0,
-                linesAffected: 0,
-                error: `Content "${contentId}" not found`,
-            };
-        }
-        const content = stored.content;
-        let effectiveOldStr = oldStr;
-        let firstIdx = content.indexOf(effectiveOldStr);
-        // Layer 1: Strip line-number prefixes that readLines() adds.
-        // Agents often copy formatted output (e.g., "  1 | import React") into old_str.
-        if (firstIdx === -1) {
-            const stripped = stripLineNumberPrefixes(oldStr);
-            if (stripped !== oldStr) {
-                firstIdx = content.indexOf(stripped);
-                if (firstIdx !== -1) {
-                    effectiveOldStr = stripped;
-                }
-            }
-        }
-        // Layer 2: Normalize CRLF → LF (content from Windows/Office/MCP tools may have \r\n)
-        if (firstIdx === -1) {
-            const normContent = normalizeNewlines(content);
-            const normOld = normalizeNewlines(effectiveOldStr);
-            if (normContent !== content || normOld !== effectiveOldStr) {
-                const normIdx = normContent.indexOf(normOld);
-                if (normIdx !== -1) {
-                    // Normalize stored content permanently so future edits don't hit this again
-                    stored.content = normContent;
-                    effectiveOldStr = normOld;
-                    firstIdx = normIdx;
-                }
-            }
-        }
-        // Layer 3: Trim trailing whitespace per line (invisible trailing spaces cause mismatches)
-        if (firstIdx === -1) {
-            const trimmedContent = trimTrailingPerLine(stored.content);
-            const trimmedOld = trimTrailingPerLine(effectiveOldStr);
-            if (trimmedContent !== stored.content || trimmedOld !== effectiveOldStr) {
-                const trimIdx = trimmedContent.indexOf(trimmedOld);
-                if (trimIdx !== -1) {
-                    // Use trimmed content for matching; map back to actual content position
-                    // by finding the equivalent position in the original
-                    stored.content = trimmedContent;
-                    effectiveOldStr = trimmedOld;
-                    firstIdx = trimIdx;
-                }
-            }
-        }
-        // Layer 4: Indentation-normalized line-by-line matching.
-        // Agent often gets the right code but with different indentation (e.g., 2 vs 4 spaces).
-        // Match lines by trimmed content, then replace the actual content range.
-        let rangeMatch = null;
-        if (firstIdx === -1) {
-            rangeMatch = findIndentationNormalizedMatch(stored.content, effectiveOldStr);
-            if (rangeMatch) {
-                effectiveOldStr = stored.content.substring(rangeMatch.start, rangeMatch.end);
-                firstIdx = rangeMatch.start;
-            }
-        }
-        // Layer 5: Partial fuzzy matching — tolerates some lines being slightly different.
-        // LLMs reconstruct code from memory and often get 80-90% of lines right but miss a few.
-        // This layer finds the best-scoring unique region above a match threshold.
-        if (firstIdx === -1) {
-            rangeMatch = findPartialFuzzyMatch(stored.content, effectiveOldStr);
-            if (rangeMatch) {
-                effectiveOldStr = stored.content.substring(rangeMatch.start, rangeMatch.end);
-                firstIdx = rangeMatch.start;
-            }
-        }
-        if (firstIdx === -1) {
-            const diagnostic = buildEditDiagnostic(stored.content, oldStr);
-            return {
-                success: false,
-                diff: '',
-                lineNumber: 0,
-                linesAffected: 0,
-                error: diagnostic,
-            };
-        }
-        // For range-matched edits (layers 4/5), skip the ambiguity check (already verified unique)
-        const lastIdx = rangeMatch
-            ? firstIdx
-            : stored.content.lastIndexOf(effectiveOldStr);
-        if (firstIdx !== lastIdx) {
-            return {
-                success: false,
-                diff: '',
-                lineNumber: 0,
-                linesAffected: 0,
-                error: 'old_str appears multiple times — make it more specific',
-            };
-        }
-        // Find the line number where the match starts
-        const currentContent = stored.content;
-        const beforeMatch = currentContent.substring(0, firstIdx);
-        const lineNumber = beforeMatch.split('\n').length;
-        // Perform replacement
-        const newContent = currentContent.substring(0, firstIdx) +
-            newStr +
-            currentContent.substring(firstIdx + effectiveOldStr.length);
-        // Build a simple diff
-        const oldLines = effectiveOldStr.split('\n');
-        const newLines = newStr.split('\n');
-        let diff = '';
-        for (const line of oldLines) {
-            diff += `- ${line}\n`;
-        }
-        for (const line of newLines) {
-            diff += `+ ${line}\n`;
-        }
-        const linesAffected = Math.max(oldLines.length, newLines.length);
-        // Update stored content and metadata
-        stored.content = newContent;
-        stored.metadata.totalLines = newContent.split('\n').length;
-        stored.metadata.totalChars = newContent.length;
-        await this.cache.set(contentId, JSON.stringify(stored));
-        // Update index metadata
-        const index = await this.getIndex();
-        if (index[contentId]) {
-            index[contentId] = stored.metadata;
-            await this.cache.set(this.indexKey, JSON.stringify(index));
-        }
-        return { success: true, diff: diff.trimEnd(), lineNumber, linesAffected };
-    }
-    /**
-     * Overwrite content for an existing entry, preserving its name/source/type.
-     * @param contentId - The content entry ID.
-     * @param content - New content to write.
-     * @throws If content ID is not found.
-     */
-    async write(contentId, content) {
-        const stored = await this.getStored(contentId);
-        if (!stored) {
-            throw new Error(`Content "${contentId}" not found`);
-        }
-        stored.content = content;
-        stored.metadata.totalLines = content.split('\n').length;
-        stored.metadata.totalChars = content.length;
-        await this.cache.set(contentId, JSON.stringify(stored));
-        // Update index metadata
-        const index = await this.getIndex();
-        if (index[contentId]) {
-            index[contentId] = stored.metadata;
-            await this.cache.set(this.indexKey, JSON.stringify(index));
-        }
-    }
-    /**
-     * List all content entries in this conversation's store.
-     * @returns Array of metadata for all entries.
-     */
-    async list() {
-        const index = await this.getIndex();
-        // Touch index to reset TTL on access
-        if (Object.keys(index).length > 0) {
-            await this.cache.set(this.indexKey, JSON.stringify(index));
-        }
-        return Object.values(index);
-    }
-    /**
-     * Get the raw content string for a content entry, without line-number formatting.
-     * Resets TTL on access. Used by code edit wrapper to retrieve stored code for execution.
-     *
-     * @param contentId - The content entry ID.
-     * @returns Raw content string, or null if not found/expired.
-     */
-    async getRawContent(contentId) {
-        const stored = await this.getStored(contentId);
-        if (!stored) {
-            return null;
-        }
-        await this.touchEntry(contentId, stored);
-        return stored.content;
-    }
-    /**
-     * Delete a content entry.
-     * @param contentId - The content entry ID.
-     */
-    async delete(contentId) {
-        await this.cache.delete(contentId);
-        const index = await this.getIndex();
-        delete index[contentId];
-        await this.cache.set(this.indexKey, JSON.stringify(index));
-    }
-    /**
-     * Reset TTL on both a content entry and the index.
-     * Called on every access to keep active content alive.
-     * @param contentId - The content entry ID.
-     * @param stored - The stored entry to re-set (resets TTL via Keyv).
-     */
-    async touchEntry(contentId, stored) {
-        await this.cache.set(contentId, JSON.stringify(stored));
-        const index = await this.getIndex();
-        if (Object.keys(index).length > 0) {
-            await this.cache.set(this.indexKey, JSON.stringify(index));
-        }
-    }
-    /**
-     * Retrieve the full stored entry (content + metadata) from Redis.
-     * Returns null if the entry has expired or doesn't exist.
-     */
-    async getStored(contentId) {
-        const raw = (await this.cache.get(contentId));
-        if (!raw) {
-            return null;
-        }
-        try {
-            return JSON.parse(raw);
-        }
-        catch {
-            return null;
-        }
-    }
-    /**
-     * Retrieve the conversation's content index from Redis.
-     * The index maps content IDs to their metadata.
-     */
-    async getIndex() {
-        const raw = (await this.cache.get(this.indexKey));
-        if (!raw) {
-            return {};
-        }
-        try {
-            return JSON.parse(raw);
-        }
-        catch {
-            return {};
-        }
-    }
-}
-
-exports.CONTENT_TTL_MS = CONTENT_TTL_MS;
-exports.ContentStore = ContentStore;
-//# sourceMappingURL=ContentStore.cjs.map