@siftd/connect-agent 0.2.30 → 0.2.32

package/dist/core/preview-worker.js

@@ -0,0 +1,408 @@
+/**
+ * Preview Worker - Fast-path local preview generation
+ *
+ * Watches ~/Lia-Hub/shared/outputs/ and generates:
+ * - Thumbnails (for images)
+ * - Metadata extraction (dimensions, page count, text snippets)
+ * - Preview JSON for instant gallery display
+ *
+ * NO LLM involvement - pure local, deterministic processing.
+ * Targets sub-second response for most assets.
+ *
+ * Uses chokidar for reliable cross-platform file watching with:
+ * - awaitWriteFinish to handle half-written files
+ * - Ignore patterns to avoid loops (*.asset.json, thumbs, etc.)
+ */
+import chokidar from 'chokidar';
+import { readFileSync, existsSync, mkdirSync } from 'fs';
+import { join, basename } from 'path';
+import { execSync } from 'child_process';
+import { createAssetManifest, writeAssetManifest, readAssetManifest, getPreviewCacheDir, getPreviewCacheKey, getPreviewFromCache, savePreviewToCache, } from './assets.js';
+import { getSharedOutputPath } from './hub.js';
+// Files to ignore when watching (prevents watcher loops)
+const IGNORE_PATTERNS = [
+    '**/*.asset.json',
+    '**/*.preview.json',
+    '**/.thumbs/**',
+    '**/thumbs/**',
+    '**/*.tmp',
+    '**/.DS_Store',
+    '**/node_modules/**',
+    '**/.git/**',
+];
+export class PreviewWorker {
+    watcher = null;
+    queue = [];
+    processing = new Set();
+    debounceTimers = new Map();
+    concurrency;
+    options;
+    running = false;
+    rootDir;
+    constructor(options = {}) {
+        this.options = options;
+        this.concurrency = options.concurrency || 4;
+        this.rootDir = getSharedOutputPath();
+    }
+    /**
+     * Start watching directories
+     */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        const dirs = this.options.watchDirs || [this.rootDir];
+        for (const dir of dirs) {
+            if (!existsSync(dir)) {
+                mkdirSync(dir, { recursive: true });
+            }
+        }
+        this.log(`Watching: ${dirs.join(', ')}`);
+        // Use chokidar for reliable watching with:
+        // - awaitWriteFinish: wait until file size is stable (handles half-written files)
+        // - ignored: prevent watcher loops
+        this.watcher = chokidar.watch(dirs, {
+            ignoreInitial: false, // Process existing files on startup
+            persistent: true,
+            awaitWriteFinish: {
+                stabilityThreshold: 400, // Wait 400ms for file size to stabilize
+                pollInterval: 100,
+            },
+            ignored: IGNORE_PATTERNS,
+            depth: 10,
+        });
+        this.watcher.on('add', (filePath) => this.handleFile(filePath));
+        this.watcher.on('change', (filePath) => this.handleFile(filePath));
+        this.watcher.on('error', (error) => this.log(`Watcher error: ${error}`));
+    }
+    /**
+     * Handle file add/change with debouncing
+     */
+    handleFile(filePath) {
+        // Clear existing debounce timer for this file
+        const existingTimer = this.debounceTimers.get(filePath);
+        if (existingTimer) {
+            clearTimeout(existingTimer);
+        }
+        // Debounce: wait 100ms before processing to batch rapid changes
+        const timer = setTimeout(() => {
+            this.debounceTimers.delete(filePath);
+            this.enqueue(filePath);
+        }, 100);
+        this.debounceTimers.set(filePath, timer);
+    }
+    /**
+     * Stop watching
+     */
+    stop() {
+        this.running = false;
+        // Clear all debounce timers
+        for (const timer of this.debounceTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.debounceTimers.clear();
+        if (this.watcher) {
+            this.watcher.close();
+            this.watcher = null;
+        }
+    }
+    /**
+     * Add file to processing queue
+     */
+    enqueue(filePath) {
+        if (this.queue.includes(filePath) || this.processing.has(filePath)) {
+            return;
+        }
+        this.queue.push(filePath);
+        this.processQueue();
+    }
+    /**
+     * Process queue with concurrency limit
+     */
+    async processQueue() {
+        while (this.running && this.queue.length > 0 && this.processing.size < this.concurrency) {
+            const filePath = this.queue.shift();
+            if (!filePath)
+                continue;
+            this.processing.add(filePath);
+            this.processFile(filePath)
+                .catch(err => this.log(`Error processing ${filePath}: ${err}`))
+                .finally(() => {
+                this.processing.delete(filePath);
+                this.processQueue();
+            });
+        }
+    }
+    /**
+     * Process a single file - generate manifest and preview
+     */
+    async processFile(filePath) {
+        // Skip if file no longer exists
+        if (!existsSync(filePath))
+            return;
+        const startTime = Date.now();
+        // Check for existing manifest
+        let manifest = readAssetManifest(filePath);
+        if (!manifest) {
+            // Create new manifest with rootDir for stable IDs
+            manifest = createAssetManifest(filePath, {
+                groupId: this.extractGroupId(filePath),
+                rootDir: this.rootDir,
+            });
+            writeAssetManifest(manifest);
+            this.log(`Created manifest: ${manifest.name} (${manifest.id})`);
+            this.options.onAsset?.(manifest);
+        }
+        // Check preview cache
+        const cacheKey = getPreviewCacheKey(manifest.sha256);
+        let preview = getPreviewFromCache(cacheKey);
+        if (!preview) {
+            // Generate preview
+            preview = await this.generatePreview(manifest, cacheKey);
+            savePreviewToCache(preview);
+            const elapsed = Date.now() - startTime;
+            this.log(`Generated preview: ${manifest.name} (${elapsed}ms)`);
+        }
+        this.options.onPreview?.(preview);
+    }
+    /**
+     * Generate preview for an asset
+     */
+    async generatePreview(manifest, cacheKey) {
+        const preview = {
+            assetId: manifest.id,
+            generatedAt: Date.now(),
+            cacheKey,
+        };
+        const mime = manifest.mime;
+        // Image preview
+        if (mime.startsWith('image/')) {
+            const imageInfo = this.getImageInfo(manifest.path);
+            if (imageInfo) {
+                preview.dimensions = imageInfo.dimensions;
+                preview.thumbnailData = this.generateImageThumbnail(manifest.path);
+            }
+        }
+        // PDF preview
+        else if (mime === 'application/pdf') {
+            const pdfInfo = this.getPdfInfo(manifest.path);
+            if (pdfInfo) {
+                preview.pageCount = pdfInfo.pageCount;
+                preview.textSnippet = pdfInfo.textSnippet;
+            }
+        }
+        // Text/code preview
+        else if (mime.startsWith('text/') || mime === 'application/json') {
+            preview.textSnippet = this.getTextSnippet(manifest.path);
+        }
+        return preview;
+    }
+    /**
+     * Get image dimensions using sips (macOS) or file command
+     */
+    getImageInfo(filePath) {
+        try {
+            // Try sips on macOS
+            if (process.platform === 'darwin') {
+                const output = execSync(`sips -g pixelWidth -g pixelHeight "${filePath}" 2>/dev/null`, { encoding: 'utf-8', timeout: 5000 });
+                const widthMatch = output.match(/pixelWidth:\s*(\d+)/);
+                const heightMatch = output.match(/pixelHeight:\s*(\d+)/);
+                if (widthMatch && heightMatch) {
+                    return {
+                        dimensions: {
+                            width: parseInt(widthMatch[1], 10),
+                            height: parseInt(heightMatch[1], 10),
+                        },
+                    };
+                }
+            }
+            // Try file command (cross-platform)
+            const output = execSync(`file "${filePath}"`, { encoding: 'utf-8', timeout: 5000 });
+            const match = output.match(/(\d+)\s*x\s*(\d+)/);
+            if (match) {
+                return {
+                    dimensions: {
+                        width: parseInt(match[1], 10),
+                        height: parseInt(match[2], 10),
+                    },
+                };
+            }
+        }
+        catch {
+            // Ignore errors
+        }
+        return null;
+    }
+    /**
+     * Generate thumbnail as base64 data URL
+     * Uses sips on macOS for fast resizing
+     */
+    generateImageThumbnail(filePath, maxSize = 200) {
+        try {
+            if (process.platform !== 'darwin')
+                return undefined;
+            const cacheDir = getPreviewCacheDir();
+            const thumbName = `thumb_${basename(filePath)}.jpg`;
+            const thumbPath = join(cacheDir, thumbName);
+            // Use sips to resize
+            execSync(`sips -Z ${maxSize} -s format jpeg "${filePath}" --out "${thumbPath}" 2>/dev/null`, { timeout: 10000 });
+            // Read as base64
+            const data = readFileSync(thumbPath);
+            return `data:image/jpeg;base64,${data.toString('base64')}`;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Get PDF info using pdfinfo or mdls
+     */
+    getPdfInfo(filePath) {
+        try {
+            let pageCount;
+            // Try pdfinfo
+            try {
+                const output = execSync(`pdfinfo "${filePath}" 2>/dev/null`, {
+                    encoding: 'utf-8',
+                    timeout: 5000,
+                });
+                const match = output.match(/Pages:\s*(\d+)/);
+                if (match) {
+                    pageCount = parseInt(match[1], 10);
+                }
+            }
+            catch {
+                // Try mdls on macOS
+                if (process.platform === 'darwin') {
+                    const output = execSync(`mdls -name kMDItemNumberOfPages "${filePath}" 2>/dev/null`, {
+                        encoding: 'utf-8',
+                        timeout: 5000,
+                    });
+                    const match = output.match(/kMDItemNumberOfPages\s*=\s*(\d+)/);
+                    if (match) {
+                        pageCount = parseInt(match[1], 10);
+                    }
+                }
+            }
+            // Try to extract text snippet
+            let textSnippet;
+            try {
+                const output = execSync(`pdftotext -l 1 -q "${filePath}" - 2>/dev/null | head -c 500`, {
+                    encoding: 'utf-8',
+                    timeout: 10000,
+                });
+                if (output.trim()) {
+                    textSnippet = output.trim().substring(0, 500);
+                }
+            }
+            catch {
+                // pdftotext not available
+            }
+            return { pageCount, textSnippet };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Get text snippet from file
+     */
+    getTextSnippet(filePath, maxChars = 500) {
+        try {
+            const content = readFileSync(filePath, 'utf-8');
+            return content.substring(0, maxChars);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Extract group ID from file path
+     * e.g., ~/Lia-Hub/shared/outputs/run_abc123/file.png -> run_abc123
+     */
+    extractGroupId(filePath) {
+        const outputPath = getSharedOutputPath();
+        if (filePath.startsWith(outputPath)) {
+            const relative = filePath.substring(outputPath.length + 1);
+            const parts = relative.split('/');
+            if (parts.length > 1) {
+                return parts[0]; // First directory is the group
+            }
+        }
+        return undefined;
+    }
+    log(message) {
+        if (this.options.verbose) {
+            console.log(`[PREVIEW] ${message}`);
+        }
+    }
+}
+let registry = null;
+export function getAssetRegistry() {
+    if (!registry) {
+        registry = {
+            assets: new Map(),
+            previews: new Map(),
+            byGroup: new Map(),
+        };
+    }
+    return registry;
+}
+export function registerAsset(manifest) {
+    const reg = getAssetRegistry();
+    reg.assets.set(manifest.id, manifest);
+    if (manifest.groupId) {
+        if (!reg.byGroup.has(manifest.groupId)) {
+            reg.byGroup.set(manifest.groupId, new Set());
+        }
+        reg.byGroup.get(manifest.groupId).add(manifest.id);
+    }
+}
+export function registerPreview(preview) {
+    const reg = getAssetRegistry();
+    reg.previews.set(preview.assetId, preview);
+}
+export function getAsset(assetId) {
+    return getAssetRegistry().assets.get(assetId);
+}
+export function getPreview(assetId) {
+    return getAssetRegistry().previews.get(assetId);
+}
+export function getAssetsByGroup(groupId) {
+    const reg = getAssetRegistry();
+    const ids = reg.byGroup.get(groupId);
+    if (!ids)
+        return [];
+    return Array.from(ids).map(id => reg.assets.get(id)).filter(Boolean);
+}
+export function getAllAssets() {
+    return Array.from(getAssetRegistry().assets.values());
+}
+// ============================================================================
+// SINGLETON WORKER
+// ============================================================================
+let previewWorker = null;
+export function startPreviewWorker(options = {}) {
+    if (previewWorker) {
+        return previewWorker;
+    }
+    previewWorker = new PreviewWorker({
+        ...options,
+        onAsset: (manifest) => {
+            registerAsset(manifest);
+            options.onAsset?.(manifest);
+        },
+        onPreview: (preview) => {
+            registerPreview(preview);
+            options.onPreview?.(preview);
+        },
+    });
+    previewWorker.start();
+    return previewWorker;
+}
+export function stopPreviewWorker() {
+    if (previewWorker) {
+        previewWorker.stop();
+        previewWorker = null;
+    }
+}

package/dist/genesis/tool-patterns.json

@@ -51,10 +51,10 @@
       "notes": "Always check memory before asking user for paths"
     },
     {
-      "scenario": "Preview HTML/web project",
-      "approach": "start_local_server + open_browser",
-      "example": "start_local_server('/path/to/project', 8080) then open_browser('http://localhost:8080')",
-      "notes": "Serve files and open in browser for preview"
+      "scenario": "Preview worker outputs (images, code, files)",
+      "approach": "Workers write files, gallery shows them automatically",
+      "example": "spawn_worker('Create the image and save to ~/Lia-Hub/shared/outputs/') - gallery displays result",
+      "notes": "NEVER use localhost servers for previews. The Connect web UI gallery handles all asset display in-app."
     },
     {
       "scenario": "Debug failing workers",
@@ -83,6 +83,11 @@
       "wrong": "Guessing file paths",
       "right": "Use search_memory or ask user",
       "reason": "Memory stores indexed filesystem, use it"
+    },
+    {
+      "wrong": "Using start_local_server + open_browser for previews",
+      "right": "Workers write to ~/Lia-Hub/shared/outputs/, gallery displays automatically",
+      "reason": "Connect's web UI has a built-in gallery. localhost servers open random tabs and break UX."
     }
   ]
 }

package/dist/orchestrator.js

@@ -122,6 +122,15 @@ You have a personal hub at ~/Lia-Hub/ for organizing your work:
 - **~/Lia-Hub/notebook-a/WORKER-LOG.md** - Track all workers you spawn
 - **~/Lia-Hub/shared/outputs/** - Where workers save their outputs
 
+ASSET PREVIEWS & GALLERY:
+The Connect web UI has a built-in gallery that shows worker outputs automatically.
+⛔ NEVER use start_local_server or open_browser for previews
+⛔ NEVER ask workers to start servers on localhost
+⛔ NEVER open localhost URLs - they won't work for remote users
+✅ Workers write files to ~/Lia-Hub/shared/outputs/
+✅ Gallery displays assets in-app as workers complete
+✅ Use open_browser ONLY for external websites (not localhost)
+
 BEFORE STARTING COMPLEX WORK:
 1. Check CLAUDE.md for user instructions
 2. Read LANDMARKS.md for current context
@@ -844,13 +853,13 @@ Be specific about what you want done.`,
             },
             {
                 name: 'open_browser',
-                description: 'Open a URL or file in the user\'s default browser. Use for opening localhost servers, web pages, or local HTML files.',
+                description: 'Open a URL in the user\'s default browser. ⚠️ ONLY for external websites (https://). NEVER for localhost or asset previews - the Connect gallery handles those in-app.',
                 input_schema: {
                     type: 'object',
                     properties: {
                         url: {
                             type: 'string',
-                            description: 'URL to open (e.g., http://localhost:8080, https://example.com, or file path)'
+                            description: 'URL to open (https://example.com). NEVER use localhost URLs.'
                         }
                     },
                     required: ['url']
@@ -858,7 +867,7 @@ Be specific about what you want done.`,
             },
             {
                 name: 'start_local_server',
-                description: 'Start a persistent HTTP server to serve a web project. Server runs in background and survives after this call. Use before open_browser for local web projects.',
+                description: '⚠️ DEPRECATED for previews. The Connect gallery shows worker outputs in-app. Only use this for specific development needs, never for previewing worker outputs.',
                 input_schema: {
                     type: 'object',
                     properties: {
@@ -1287,6 +1296,14 @@ Be specific about what you want done.`,
      */
     async executeOpenBrowser(url) {
         try {
+            // Block localhost URLs - gallery handles asset previews in-app
+            if (url.includes('localhost') || url.includes('127.0.0.1') || url.match(/:80[0-9]{2}/)) {
+                console.log(`[ORCHESTRATOR] Blocked localhost URL: ${url}`);
+                return {
+                    success: false,
+                    output: `⛔ BLOCKED: Cannot open localhost URLs. The Connect gallery displays worker outputs in-app automatically. Workers should save files to ~/Lia-Hub/shared/outputs/ and the gallery will show them.`
+                };
+            }
             // Use 'open' on macOS, 'xdg-open' on Linux, 'start' on Windows
             const platform = process.platform;
             let command;
@@ -1312,6 +1329,8 @@ Be specific about what you want done.`,
      * Start a persistent HTTP server
      */
     async executeStartServer(directory, port = 8080) {
+        // Warn that this shouldn't be used for previews
+        console.log(`[ORCHESTRATOR] ⚠️ start_local_server called - consider using gallery for previews instead`);
         try {
             // First, check if something is already running on this port
             try {
@@ -1319,7 +1338,7 @@ Be specific about what you want done.`,
                 if (existing) {
                     return {
                         success: true,
-                        output: `Server already running on port ${port}. URL: http://localhost:${port}`
+                        output: `⚠️ Note: For previewing worker outputs, the Connect gallery shows them in-app automatically. Server already running on port ${port}.`
                     };
                 }
             }
@@ -1341,7 +1360,7 @@ Be specific about what you want done.`,
                 console.log(`[ORCHESTRATOR] Started server on port ${port} for ${directory}`);
                 return {
                     success: true,
-                    output: `Started HTTP server on http://localhost:${port} serving ${directory}`
+                    output: `Started HTTP server on port ${port}. ⚠️ Remember: For previewing worker outputs, the Connect gallery shows them in-app automatically - no server needed.`
                 };
             }
             catch {

package/dist/prompts/worker-system.d.ts

@@ -8,7 +8,7 @@
  * Core worker identity and rules
  * This is the foundation every worker receives
  */
-export declare const WORKER_IDENTITY = "## Worker Identity\nYou are a Claude Code CLI worker executing a delegated task.\nYou report to the Master Orchestrator.\n\n## Critical Rules\n1. Do NOT open browsers or start servers\n2. Do NOT ask questions - just do the work\n3. Output files to the shared workspace unless specified\n4. Report file paths you create at the end\n5. Be concise and efficient";
+export declare const WORKER_IDENTITY = "## Worker Identity\nYou are a Claude Code CLI worker executing a delegated task.\nYou report to the Master Orchestrator.\n\n## CRITICAL - NEVER DO THESE:\n- NEVER open browsers (no 'open' command, no browser tools)\n- NEVER start servers (no 'npm run dev', no 'python -m http.server', etc.)\n- NEVER use localhost URLs\n- NEVER ask questions - just do the work\n- NEVER try to preview your work - the gallery handles that automatically\n\n## Asset System (Automatic Previews)\nFiles you save are automatically:\n1. Detected by the preview worker\n2. Thumbnailed (images) and metadata extracted\n3. Displayed in the Connect web UI gallery\n\nYOU DON'T NEED TO:\n- Start servers to preview\n- Open browsers\n- Generate thumbnails yourself\nJust save files and the gallery shows them instantly.\n\n## What You SHOULD Do:\n1. Create/edit files as needed\n2. Save outputs to the shared workspace\n3. Report file paths you create at the end\n4. Be concise and efficient";
 /**
  * Output format workers should follow
  */

package/dist/prompts/worker-system.js

@@ -13,12 +13,30 @@ export const WORKER_IDENTITY = `## Worker Identity
 You are a Claude Code CLI worker executing a delegated task.
 You report to the Master Orchestrator.
 
-## Critical Rules
-1. Do NOT open browsers or start servers
-2. Do NOT ask questions - just do the work
-3. Output files to the shared workspace unless specified
-4. Report file paths you create at the end
-5. Be concise and efficient`;
+## CRITICAL - NEVER DO THESE:
+- NEVER open browsers (no 'open' command, no browser tools)
+- NEVER start servers (no 'npm run dev', no 'python -m http.server', etc.)
+- NEVER use localhost URLs
+- NEVER ask questions - just do the work
+- NEVER try to preview your work - the gallery handles that automatically
+
+## Asset System (Automatic Previews)
+Files you save are automatically:
+1. Detected by the preview worker
+2. Thumbnailed (images) and metadata extracted
+3. Displayed in the Connect web UI gallery
+
+YOU DON'T NEED TO:
+- Start servers to preview
+- Open browsers
+- Generate thumbnails yourself
+Just save files and the gallery shows them instantly.
+
+## What You SHOULD Do:
+1. Create/edit files as needed
+2. Save outputs to the shared workspace
+3. Report file paths you create at the end
+4. Be concise and efficient`;
 /**
  * Output format workers should follow
  */
@@ -110,10 +128,19 @@ export function buildWorkerPrompt(task, options = {}) {
  * Lighter version for quick operations
  */
 export function getQuickWorkerPrompt(task, context) {
+    const sharedPath = getSharedOutputPath();
     let prompt = task;
     if (context) {
         prompt = `Context: ${context}\n\nTask: ${task}`;
     }
-    prompt += `\n\nBe concise. Output results directly. Do NOT open browsers or start servers - just create files and report paths.`;
+    prompt += `
+
+Save outputs to: ${sharedPath}
+
+CRITICAL RESTRICTIONS:
+- NEVER open browsers (no 'open' command)
+- NEVER start servers (no localhost)
+- NEVER try to preview - gallery shows files automatically
+Just create files and report paths. Be concise.`;
     return prompt;
 }

package/dist/websocket.d.ts

@@ -7,14 +7,19 @@
  * - Supports interruption and progress updates
  */
 import type { WorkerStatus } from './orchestrator.js';
+import { AssetResponse } from './core/asset-api.js';
 export type MessageHandler = (message: WebSocketMessage) => Promise<void>;
 export type StreamHandler = (chunk: string) => void;
 export interface WebSocketMessage {
-    type: 'message' | 'interrupt' | 'ping' | 'pong' | 'connected';
+    type: 'message' | 'interrupt' | 'ping' | 'pong' | 'connected' | 'asset_request';
     id?: string;
     content?: string;
     timestamp?: number;
     apiKey?: string;
+    requestId?: string;
+    assetId?: string;
+    groupId?: string;
+    viewId?: string;
 }
 export interface StreamingResponse {
     send: (chunk: string) => void;
@@ -67,7 +72,7 @@ export declare class AgentWebSocket {
      */
     sendGalleryCommand(command: 'open' | 'close' | 'focus_worker' | 'open_asset' | 'back', workerId?: string, assetIndex?: number): void;
     /**
-     * Send gallery workers with their assets
+     * Send gallery workers with their assets (legacy)
      */
     sendGalleryWorkers(workers: Array<{
         id: string;
@@ -85,6 +90,14 @@ export declare class AgentWebSocket {
             }>;
         }>;
     }>): void;
+    /**
+     * Send full gallery state (new fast-path system)
+     */
+    sendGalleryState(): void;
+    /**
+     * Send asset response
+     */
+    sendAssetResponse(response: AssetResponse): void;
     /**
      * Check if connected
      */
@@ -95,6 +108,10 @@ export declare class AgentWebSocket {
     close(): void;
     private handleMessage;
     private sendToServer;
+    /**
+     * Handle asset requests (fast-path, no LLM)
+     */
+    private handleAssetRequest;
     private startPingInterval;
     private stopPingInterval;
     private attemptReconnect;