byterover-cli 0.4.0 → 1.0.0

package/dist/infra/cipher/blob/blob-reference-resolver.js

@@ -0,0 +1,228 @@
+/**
+ * Blob reference resolver for lazy media evaluation.
+ *
+ * This service resolves @blob:id references in message content to actual data
+ * at format-time (when sending to LLM), enabling lazy evaluation of large media.
+ *
+ * Key features:
+ * - Lazy expansion: Blob references only resolved when needed
+ * - MIME type filtering: Exclude unsupported media types
+ * - Placeholder generation: Replace filtered media with descriptive placeholders
+ *
+ */
+import { BLOB_REF_PATTERN, containsBlobReferences, extractBlobId, generateMediaPlaceholder, matchesAnyMimePattern, parseBlobReferences, } from './blob-reference-utils.js';
+/**
+ * Blob reference resolver.
+ *
+ * Resolves @blob:id references to actual content at format-time.
+ */
+export class BlobReferenceResolver {
+    blobStorage;
+    constructor(blobStorage) {
+        this.blobStorage = blobStorage;
+    }
+    /**
+     * Expand blob references in message content.
+     *
+     * Processes an array of message parts and resolves any @blob:id references
+     * to actual content. Supports blob refs in:
+     * - TextPart.text (inline references)
+     * - ImagePart.image (blob ref instead of base64)
+     * - FilePart.data (blob ref instead of base64)
+     *
+     * @param content - Array of message parts to expand
+     * @param options - Resolution options
+     * @returns Array of message parts with blob refs resolved
+     */
+    async expandBlobReferences(content, options) {
+        const expanded = [];
+        const expandedParts = await Promise.all(content.map((part) => this.expandPart(part, options)));
+        for (const parts of expandedParts) {
+            expanded.push(...parts);
+        }
+        return expanded;
+    }
+    /**
+     * Get all blob IDs referenced in content.
+     */
+    getBlobIds(content) {
+        const ids = new Set();
+        for (const part of content) {
+            if (part.type === 'text') {
+                for (const id of parseBlobReferences(part.text)) {
+                    ids.add(id);
+                }
+            }
+            if (part.type === 'image' && typeof part.image === 'string') {
+                const id = extractBlobId(part.image);
+                if (id)
+                    ids.add(id);
+            }
+            if (part.type === 'file' && typeof part.data === 'string') {
+                const id = extractBlobId(part.data);
+                if (id)
+                    ids.add(id);
+            }
+        }
+        return [...ids];
+    }
+    /**
+     * Check if content contains any blob references.
+     *
+     * Useful for determining if expansion is needed before calling expandBlobReferences.
+     */
+    hasAnyBlobReferences(content) {
+        for (const part of content) {
+            if (part.type === 'text' && containsBlobReferences(part.text)) {
+                return true;
+            }
+            if (part.type === 'image' && typeof part.image === 'string' && part.image.startsWith('@blob:')) {
+                return true;
+            }
+            if (part.type === 'file' && typeof part.data === 'string' && part.data.startsWith('@blob:')) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Prefetch blobs for a set of message parts.
+     *
+     * Useful for warming the cache before expansion.
+     */
+    async prefetchBlobs(content) {
+        const ids = this.getBlobIds(content);
+        await Promise.all(ids.map((id) => this.blobStorage.retrieve(id)));
+    }
+    /**
+     * Expand blob references embedded in text.
+     *
+     * Text like "Here is the image: @blob:abc123" will be split into
+     * multiple parts: text before, image part, text after.
+     */
+    async expandBlobsInText(text, options) {
+        const blobIds = parseBlobReferences(text);
+        if (blobIds.length === 0) {
+            return [{ text, type: 'text' }];
+        }
+        const parts = [];
+        let lastIndex = 0;
+        const matches = [...text.matchAll(new RegExp(BLOB_REF_PATTERN.source, 'g'))];
+        const resolvedParts = await Promise.all(matches.map((match) => {
+            const blobId = match[1];
+            return this.resolveBlobToParts(blobId, options);
+        }));
+        for (const [index, match] of matches.entries()) {
+            const matchIndex = match.index;
+            // Add text before this match
+            if (matchIndex > lastIndex) {
+                const segment = text.slice(lastIndex, matchIndex);
+                if (segment.length > 0) {
+                    parts.push({ text: segment, type: 'text' });
+                }
+            }
+            // Resolve the blob
+            parts.push(...resolvedParts[index]);
+            lastIndex = matchIndex + match[0].length;
+        }
+        // Add remaining text
+        if (lastIndex < text.length) {
+            const trailing = text.slice(lastIndex);
+            if (trailing.length > 0) {
+                parts.push({ text: trailing, type: 'text' });
+            }
+        }
+        return parts;
+    }
+    /**
+     * Expand a single message part.
+     */
+    async expandPart(part, options) {
+        // Text part with embedded blob refs
+        if (part.type === 'text' && containsBlobReferences(part.text)) {
+            return this.expandBlobsInText(part.text, options);
+        }
+        // Image part with blob ref
+        if (part.type === 'image' && typeof part.image === 'string' && part.image.startsWith('@blob:')) {
+            const resolved = await this.resolveImageBlob(part, options);
+            return [resolved];
+        }
+        // File part with blob ref
+        if (part.type === 'file' && typeof part.data === 'string' && part.data.startsWith('@blob:')) {
+            const resolved = await this.resolveFileBlob(part, options);
+            return [resolved];
+        }
+        // No blob refs, return as-is
+        return [part];
+    }
+    /**
+     * Resolve a blob ID to message parts.
+     */
+    async resolveBlobToParts(blobId, options) {
+        try {
+            const blob = await this.blobStorage.retrieve(blobId);
+            if (!blob) {
+                return [{ text: `[Attachment unavailable: @blob:${blobId}]`, type: 'text' }];
+            }
+            const mimeType = blob.metadata.contentType || 'application/octet-stream';
+            // Check MIME type filtering
+            if (options?.allowedMimeTypes && !matchesAnyMimePattern(mimeType, options.allowedMimeTypes)) {
+                const placeholder = generateMediaPlaceholder({
+                    mimeType,
+                    originalName: blob.metadata.originalName,
+                    size: blob.metadata.size,
+                });
+                return [{ text: placeholder, type: 'text' }];
+            }
+            // Convert to appropriate part type
+            const base64Content = blob.content.toString('base64');
+            if (mimeType.startsWith('image/')) {
+                return [{
+                        image: base64Content,
+                        mimeType,
+                        type: 'image',
+                    }];
+            }
+            return [{
+                    data: base64Content,
+                    mimeType,
+                    type: 'file',
+                    ...(blob.metadata.originalName && { filename: blob.metadata.originalName }),
+                }];
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            return [{ text: `[Attachment unavailable: @blob:${blobId} - ${message}]`, type: 'text' }];
+        }
+    }
+    /**
+     * Resolve a file part with blob reference.
+     */
+    async resolveFileBlob(part, options) {
+        const blobId = extractBlobId(part.data);
+        if (!blobId)
+            return part;
+        const resolved = await this.resolveBlobToParts(blobId, options);
+        // If resolved to a file part, preserve the original filename
+        if (resolved[0]?.type === 'file' && part.filename && !resolved[0].filename) {
+            return { ...resolved[0], filename: part.filename };
+        }
+        return resolved[0] || part;
+    }
+    /**
+     * Resolve an image part with blob reference.
+     */
+    async resolveImageBlob(part, options) {
+        const blobId = extractBlobId(part.image);
+        if (!blobId)
+            return part;
+        const resolved = await this.resolveBlobToParts(blobId, options);
+        return resolved[0] || part;
+    }
+}
+/**
+ * Create a BlobReferenceResolver instance.
+ */
+export function createBlobReferenceResolver(blobStorage) {
+    return new BlobReferenceResolver(blobStorage);
+}

package/dist/infra/cipher/blob/blob-reference-utils.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Blob reference utilities for lazy media evaluation.
+ *
+ * Blob references are URIs that point to data stored in blob storage.
+ * Format: @blob:{id}
+ *
+ * This allows messages to reference large media without embedding the
+ * actual data, deferring resolution to format-time when needed.
+ *
+ * Based on dexto's @blob: reference pattern.
+ */
+/**
+ * Regular expression for matching blob references.
+ * Captures the blob ID from @blob:{id} format.
+ */
+export declare const BLOB_REF_PATTERN: RegExp;
+/**
+ * Prefix for blob references.
+ */
+export declare const BLOB_REF_PREFIX = "@blob:";
+/**
+ * Check if a string contains any blob references.
+ *
+ * @param content - String to check
+ * @returns true if content contains @blob: references
+ */
+export declare function containsBlobReferences(content: string): boolean;
+/**
+ * Parse all blob references from a string.
+ *
+ * @param content - String containing blob references
+ * @returns Array of blob IDs (without @blob: prefix)
+ */
+export declare function parseBlobReferences(content: string): string[];
+/**
+ * Create a blob reference string from a blob ID.
+ *
+ * @param blobId - The blob storage key
+ * @returns Blob reference string (@blob:{id})
+ */
+export declare function createBlobRef(blobId: string): string;
+/**
+ * Extract blob ID from a reference string.
+ *
+ * @param ref - Blob reference string (@blob:{id})
+ * @returns Blob ID or null if not a valid reference
+ */
+export declare function extractBlobId(ref: string): null | string;
+/**
+ * Check if a string is a blob reference.
+ *
+ * @param value - String to check
+ * @returns true if the string is a blob reference
+ */
+export declare function isBlobReference(value: string): boolean;
+/**
+ * Check if a MIME type matches a pattern.
+ *
+ * Supports exact match, wildcard subtype (image/*), and wildcard all.
+ *
+ * @param mimeType - MIME type to check
+ * @param pattern - Pattern to match against
+ * @returns true if the MIME type matches the pattern
+ */
+export declare function matchesMimePattern(mimeType: string | undefined, pattern: string): boolean;
+/**
+ * Check if a MIME type matches any pattern in an array.
+ *
+ * @param mimeType - MIME type to check
+ * @param patterns - Array of patterns to match against
+ * @returns true if the MIME type matches any pattern
+ */
+export declare function matchesAnyMimePattern(mimeType: string | undefined, patterns: string[]): boolean;
+/**
+ * Format byte size as human-readable string.
+ *
+ * @param bytes - Number of bytes
+ * @returns Formatted string like "1.5 KB" or "2.3 MB"
+ */
+export declare function formatByteSize(bytes: number): string;
+/**
+ * Generate a placeholder string for filtered/unavailable media.
+ *
+ * @param metadata - Media metadata
+ * @param metadata.mimeType - MIME type of the media
+ * @param metadata.originalName - Original filename if available
+ * @param metadata.size - Size in bytes
+ * @returns Placeholder string like "[Video: demo.mp4 (5.2 MB)]"
+ */
+export declare function generateMediaPlaceholder(metadata: {
+    mimeType: string;
+    originalName?: string;
+    size: number;
+}): string;
+/**
+ * Replace a blob reference in a string with resolved content.
+ *
+ * @param content - String containing blob reference
+ * @param blobId - Blob ID to replace
+ * @param replacement - Replacement string
+ * @returns String with blob reference replaced
+ */
+export declare function replaceBlobReference(content: string, blobId: string, replacement: string): string;
+/**
+ * Get MIME type category for display purposes.
+ *
+ * @param mimeType - MIME type
+ * @returns Category label
+ */
+export declare function getMimeTypeCategory(mimeType: string): string;
+/**
+ * Infer MIME type from filename extension.
+ *
+ * @param filename - Filename with extension
+ * @returns MIME type or undefined if not recognized
+ */
+export declare function inferMimeTypeFromFilename(filename: string): string | undefined;

package/dist/infra/cipher/blob/blob-reference-utils.js

@@ -0,0 +1,230 @@
+/**
+ * Blob reference utilities for lazy media evaluation.
+ *
+ * Blob references are URIs that point to data stored in blob storage.
+ * Format: @blob:{id}
+ *
+ * This allows messages to reference large media without embedding the
+ * actual data, deferring resolution to format-time when needed.
+ *
+ * Based on dexto's @blob: reference pattern.
+ */
+/**
+ * Regular expression for matching blob references.
+ * Captures the blob ID from @blob:{id} format.
+ */
+export const BLOB_REF_PATTERN = /@blob:([a-zA-Z0-9_-]+)/g;
+/**
+ * Prefix for blob references.
+ */
+export const BLOB_REF_PREFIX = '@blob:';
+/**
+ * Check if a string contains any blob references.
+ *
+ * @param content - String to check
+ * @returns true if content contains @blob: references
+ */
+export function containsBlobReferences(content) {
+    if (!content || typeof content !== 'string')
+        return false;
+    return content.includes(BLOB_REF_PREFIX);
+}
+/**
+ * Parse all blob references from a string.
+ *
+ * @param content - String containing blob references
+ * @returns Array of blob IDs (without @blob: prefix)
+ */
+export function parseBlobReferences(content) {
+    if (!content || typeof content !== 'string')
+        return [];
+    const matches = [...content.matchAll(new RegExp(BLOB_REF_PATTERN.source, 'g'))];
+    return matches.map((m) => m[1]);
+}
+/**
+ * Create a blob reference string from a blob ID.
+ *
+ * @param blobId - The blob storage key
+ * @returns Blob reference string (@blob:{id})
+ */
+export function createBlobRef(blobId) {
+    return `${BLOB_REF_PREFIX}${blobId}`;
+}
+/**
+ * Extract blob ID from a reference string.
+ *
+ * @param ref - Blob reference string (@blob:{id})
+ * @returns Blob ID or null if not a valid reference
+ */
+export function extractBlobId(ref) {
+    if (!ref || typeof ref !== 'string')
+        return null;
+    if (!ref.startsWith(BLOB_REF_PREFIX))
+        return null;
+    return ref.slice(BLOB_REF_PREFIX.length);
+}
+/**
+ * Check if a string is a blob reference.
+ *
+ * @param value - String to check
+ * @returns true if the string is a blob reference
+ */
+export function isBlobReference(value) {
+    if (!value || typeof value !== 'string')
+        return false;
+    return value.startsWith(BLOB_REF_PREFIX) && extractBlobId(value) !== null;
+}
+/**
+ * Check if a MIME type matches a pattern.
+ *
+ * Supports exact match, wildcard subtype (image/*), and wildcard all.
+ *
+ * @param mimeType - MIME type to check
+ * @param pattern - Pattern to match against
+ * @returns true if the MIME type matches the pattern
+ */
+export function matchesMimePattern(mimeType, pattern) {
+    if (!mimeType)
+        return false;
+    const normalizedMime = mimeType.toLowerCase().trim();
+    const normalizedPattern = pattern.toLowerCase().trim();
+    // Any type
+    if (normalizedPattern === '*' || normalizedPattern === '*/*')
+        return true;
+    // Exact match
+    if (normalizedMime === normalizedPattern)
+        return true;
+    // Wildcard subtype (e.g., "image/*")
+    if (normalizedPattern.endsWith('/*')) {
+        const patternType = normalizedPattern.slice(0, -2);
+        const mimeTypePrefix = normalizedMime.split('/')[0];
+        return mimeTypePrefix === patternType;
+    }
+    return false;
+}
+/**
+ * Check if a MIME type matches any pattern in an array.
+ *
+ * @param mimeType - MIME type to check
+ * @param patterns - Array of patterns to match against
+ * @returns true if the MIME type matches any pattern
+ */
+export function matchesAnyMimePattern(mimeType, patterns) {
+    if (!patterns || patterns.length === 0)
+        return true; // No filter = allow all
+    return patterns.some((pattern) => matchesMimePattern(mimeType, pattern));
+}
+/**
+ * Format byte size as human-readable string.
+ *
+ * @param bytes - Number of bytes
+ * @returns Formatted string like "1.5 KB" or "2.3 MB"
+ */
+export function formatByteSize(bytes) {
+    if (bytes === 0)
+        return '0 B';
+    const k = 1024;
+    const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return `${Number.parseFloat((bytes / k ** i).toFixed(1))} ${sizes[i]}`;
+}
+/**
+ * Generate a placeholder string for filtered/unavailable media.
+ *
+ * @param metadata - Media metadata
+ * @param metadata.mimeType - MIME type of the media
+ * @param metadata.originalName - Original filename if available
+ * @param metadata.size - Size in bytes
+ * @returns Placeholder string like "[Video: demo.mp4 (5.2 MB)]"
+ */
+export function generateMediaPlaceholder(metadata) {
+    let typeLabel = 'File';
+    if (metadata.mimeType.startsWith('video/'))
+        typeLabel = 'Video';
+    else if (metadata.mimeType.startsWith('audio/'))
+        typeLabel = 'Audio';
+    else if (metadata.mimeType.startsWith('image/'))
+        typeLabel = 'Image';
+    else if (metadata.mimeType === 'application/pdf')
+        typeLabel = 'PDF';
+    const size = formatByteSize(metadata.size);
+    const name = metadata.originalName || 'unnamed';
+    return `[${typeLabel}: ${name} (${size})]`;
+}
+/**
+ * Replace a blob reference in a string with resolved content.
+ *
+ * @param content - String containing blob reference
+ * @param blobId - Blob ID to replace
+ * @param replacement - Replacement string
+ * @returns String with blob reference replaced
+ */
+export function replaceBlobReference(content, blobId, replacement) {
+    const ref = createBlobRef(blobId);
+    return content.replace(ref, replacement);
+}
+/**
+ * Get MIME type category for display purposes.
+ *
+ * @param mimeType - MIME type
+ * @returns Category label
+ */
+export function getMimeTypeCategory(mimeType) {
+    const lower = mimeType.toLowerCase();
+    if (lower.startsWith('image/'))
+        return 'Image';
+    if (lower.startsWith('video/'))
+        return 'Video';
+    if (lower.startsWith('audio/'))
+        return 'Audio';
+    if (lower === 'application/pdf')
+        return 'PDF';
+    if (lower.startsWith('text/'))
+        return 'Text';
+    return 'File';
+}
+/**
+ * File extension to MIME type mapping for common types.
+ */
+const EXTENSION_TO_MIME = {
+    '.avi': 'video/x-msvideo',
+    '.bmp': 'image/bmp',
+    '.css': 'text/css',
+    '.flac': 'audio/flac',
+    '.gif': 'image/gif',
+    '.gz': 'application/gzip',
+    '.html': 'text/html',
+    '.ico': 'image/x-icon',
+    '.jpeg': 'image/jpeg',
+    '.jpg': 'image/jpeg',
+    '.js': 'text/javascript',
+    '.json': 'application/json',
+    '.m4a': 'audio/mp4',
+    '.mkv': 'video/x-matroska',
+    '.mov': 'video/quicktime',
+    '.mp3': 'audio/mpeg',
+    '.mp4': 'video/mp4',
+    '.ogg': 'audio/ogg',
+    '.pdf': 'application/pdf',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml',
+    '.tar': 'application/x-tar',
+    '.txt': 'text/plain',
+    '.wav': 'audio/wav',
+    '.webm': 'video/webm',
+    '.webp': 'image/webp',
+    '.xml': 'application/xml',
+    '.zip': 'application/zip',
+};
+/**
+ * Infer MIME type from filename extension.
+ *
+ * @param filename - Filename with extension
+ * @returns MIME type or undefined if not recognized
+ */
+export function inferMimeTypeFromFilename(filename) {
+    if (!filename)
+        return undefined;
+    const ext = filename.slice(filename.lastIndexOf('.')).toLowerCase();
+    return EXTENSION_TO_MIME[ext];
+}

package/dist/infra/cipher/consumer/consumer-lock.js

@@ -1,3 +1,4 @@
+// TODO(v0.5.0): Remove this file. Consumer locking is no longer needed (one CoreProcess per TUI).
 import { getAgentStorage, getAgentStorageSync } from '../storage/agent-storage.js';
 // Consumer is considered stale after 30 seconds without heartbeat
 const STALE_TIMEOUT_MS = 30_000;

package/dist/infra/cipher/consumer/consumer-service.js

@@ -1,3 +1,4 @@
+// TODO(v0.5.0): Remove this file. ConsumerService is replaced by CoreProcess → TaskProcessor.
 import { ProjectConfigStore } from '../../config/file-config-store.js';
 import { KeychainTokenStore } from '../../storage/keychain-token-store.js';
 import { closeAgentStorage } from '../storage/agent-storage.js';

package/dist/infra/cipher/consumer/execution-consumer.d.ts

@@ -54,7 +54,12 @@ export declare class ExecutionConsumer {
      */
     stop(): void;
     /**
-     * Execute a curate job
+     * Execute a curate job using the Plan Agent for orchestration.
+     *
+     * The Plan Agent orchestrates the curation workflow by:
+     * 1. Analyzing the user's request
+     * 2. Delegating to Query subagent to find existing context
+     * 3. Delegating to Curate subagent to create/update topics
      */
     private executeCurate;
     /**