@crowdlisten/harness 1.0.0

package/dist/insights/vision/VisionExtractor.d.ts

@@ -0,0 +1,46 @@
+/**
+ * VisionExtractor — standalone vision-based content extraction.
+ *
+ * Given any URL, opens a browser, takes a screenshot, sends to an LLM
+ * (Claude → Gemini → OpenAI fallback), and returns structured Post[] or Comment[].
+ *
+ * This is NOT a filter/verifier — it's a full extractor that reads the screenshot
+ * and returns structured data directly.
+ *
+ * Usage:
+ *   const vision = new VisionExtractor();
+ *   const result = await vision.extract('https://tiktok.com/...', { mode: 'posts' });
+ */
+import { Post, Comment } from '../core/interfaces/SocialMediaPlatform.js';
+export interface VisionExtractionOptions {
+    mode: 'posts' | 'comments' | 'raw';
+    limit?: number;
+    scrollCount?: number;
+}
+export interface VisionExtractionResult {
+    posts?: Post[];
+    comments?: Comment[];
+    raw?: string;
+    provider: string;
+    url: string;
+}
+export declare class VisionExtractor {
+    /**
+     * Check if any vision provider is configured.
+     */
+    isAvailable(): boolean;
+    /**
+     * Extract structured content from any URL using vision.
+     */
+    extract(url: string, options: VisionExtractionOptions): Promise<VisionExtractionResult>;
+    private detectPlatform;
+    private buildPrompt;
+    /**
+     * Try LLM providers in order: Claude → Gemini → OpenAI
+     */
+    private askLLM;
+    private askClaude;
+    private askGemini;
+    private askOpenAI;
+    private parseResponse;
+}

package/dist/insights/vision/VisionExtractor.js

@@ -0,0 +1,236 @@
+/**
+ * VisionExtractor — standalone vision-based content extraction.
+ *
+ * Given any URL, opens a browser, takes a screenshot, sends to an LLM
+ * (Claude → Gemini → OpenAI fallback), and returns structured Post[] or Comment[].
+ *
+ * This is NOT a filter/verifier — it's a full extractor that reads the screenshot
+ * and returns structured data directly.
+ *
+ * Usage:
+ *   const vision = new VisionExtractor();
+ *   const result = await vision.extract('https://tiktok.com/...', { mode: 'posts' });
+ */
+import { getBrowserPool } from '../browser/BrowserPool.js';
+export class VisionExtractor {
+    /**
+     * Check if any vision provider is configured.
+     */
+    isAvailable() {
+        return !!(process.env.ANTHROPIC_API_KEY ||
+            process.env.GEMINI_API_KEY ||
+            process.env.OPENAI_API_KEY);
+    }
+    /**
+     * Extract structured content from any URL using vision.
+     */
+    async extract(url, options) {
+        const { mode, limit = 10, scrollCount = 3 } = options;
+        if (!this.isAvailable()) {
+            throw new Error('Vision extraction requires at least one LLM API key.\n' +
+                'Set ANTHROPIC_API_KEY, GEMINI_API_KEY, or OPENAI_API_KEY.');
+        }
+        const pool = getBrowserPool();
+        const platform = this.detectPlatform(url);
+        const page = await pool.acquire(platform);
+        try {
+            await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 20000 });
+            // Wait for content to load
+            try {
+                await page.waitForLoadState('networkidle', { timeout: 10000 });
+            }
+            catch {
+                // networkidle timeout is non-fatal
+            }
+            // Scroll to load more content
+            for (let i = 0; i < scrollCount; i++) {
+                await page.evaluate(() => window.scrollBy(0, window.innerHeight));
+                await page.waitForTimeout(1500);
+            }
+            // Take full-page screenshot
+            const screenshotBuffer = await page.screenshot({ fullPage: true });
+            const screenshotBase64 = screenshotBuffer.toString('base64');
+            const prompt = this.buildPrompt(mode, url, limit);
+            const { text, provider } = await this.askLLM(screenshotBase64, prompt);
+            return this.parseResponse(text, provider, url, mode);
+        }
+        finally {
+            await pool.release(page);
+        }
+    }
+    detectPlatform(url) {
+        if (url.includes('tiktok.com'))
+            return 'tiktok';
+        if (url.includes('instagram.com'))
+            return 'instagram';
+        if (url.includes('x.com') || url.includes('twitter.com'))
+            return 'twitter';
+        if (url.includes('xiaohongshu.com'))
+            return 'xiaohongshu';
+        if (url.includes('reddit.com'))
+            return 'reddit';
+        if (url.includes('youtube.com'))
+            return 'youtube';
+        return 'twitter'; // default profile
+    }
+    buildPrompt(mode, url, limit) {
+        if (mode === 'raw') {
+            return (`This is a screenshot of ${url}.\n\n` +
+                `Extract ALL visible text content from this page. Return it as plain text, preserving the structure ` +
+                `(headings, paragraphs, lists). Do not add interpretation — just extract what you see.`);
+        }
+        if (mode === 'comments') {
+            return (`This is a screenshot of ${url}.\n\n` +
+                `Extract up to ${limit} visible comments/replies from this page.\n` +
+                `Return ONLY this JSON — no explanation, no markdown:\n` +
+                `{"comments": [\n` +
+                `  {"id": "1", "author": "username", "text": "comment text", "likes": 0},\n` +
+                `  ...\n` +
+                `]}\n\n` +
+                `For each comment, extract the author username, full comment text, and like count (0 if not visible).` +
+                ` Return exactly the JSON format above.`);
+        }
+        // mode === 'posts'
+        return (`This is a screenshot of ${url}.\n\n` +
+            `Extract up to ${limit} visible posts/content items from this page.\n` +
+            `Return ONLY this JSON — no explanation, no markdown:\n` +
+            `{"posts": [\n` +
+            `  {"id": "1", "author": "username", "content": "post text", "likes": 0, "comments": 0, "shares": 0, "url": ""},\n` +
+            `  ...\n` +
+            `]}\n\n` +
+            `For each post, extract: author username, content/caption text, engagement metrics (likes, comments, shares — 0 if not visible), ` +
+            `and URL if visible. Return exactly the JSON format above.`);
+    }
+    /**
+     * Try LLM providers in order: Claude → Gemini → OpenAI
+     */
+    async askLLM(screenshotBase64, prompt) {
+        if (process.env.ANTHROPIC_API_KEY) {
+            try {
+                const text = await this.askClaude(screenshotBase64, prompt);
+                return { text, provider: 'claude' };
+            }
+            catch (err) {
+                console.warn(`[VisionExtractor] Claude failed: ${err}. Trying next...`);
+            }
+        }
+        if (process.env.GEMINI_API_KEY) {
+            try {
+                const text = await this.askGemini(screenshotBase64, prompt);
+                return { text, provider: 'gemini' };
+            }
+            catch (err) {
+                console.warn(`[VisionExtractor] Gemini failed: ${err}. Trying next...`);
+            }
+        }
+        if (process.env.OPENAI_API_KEY) {
+            try {
+                const text = await this.askOpenAI(screenshotBase64, prompt);
+                return { text, provider: 'openai' };
+            }
+            catch (err) {
+                console.warn(`[VisionExtractor] OpenAI failed: ${err}`);
+            }
+        }
+        throw new Error('All vision providers failed. Check API keys and try again.');
+    }
+    async askClaude(screenshotBase64, prompt) {
+        const Anthropic = (await import('@anthropic-ai/sdk')).default;
+        const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+        const response = await client.messages.create({
+            model: 'claude-sonnet-4-6',
+            max_tokens: 4096,
+            messages: [{
+                    role: 'user',
+                    content: [
+                        { type: 'image', source: { type: 'base64', media_type: 'image/png', data: screenshotBase64 } },
+                        { type: 'text', text: prompt },
+                    ],
+                }],
+        });
+        return response.content
+            .filter((block) => block.type === 'text')
+            .map((block) => block.text)
+            .join('');
+    }
+    async askGemini(screenshotBase64, prompt) {
+        const { GoogleGenerativeAI } = await import('@google/generative-ai');
+        const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);
+        const model = genAI.getGenerativeModel({ model: 'gemini-2.0-flash' });
+        const result = await model.generateContent([
+            { inlineData: { mimeType: 'image/png', data: screenshotBase64 } },
+            { text: prompt },
+        ]);
+        return result.response.text();
+    }
+    async askOpenAI(screenshotBase64, prompt) {
+        const OpenAI = (await import('openai')).default;
+        const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+        const response = await client.chat.completions.create({
+            model: 'gpt-4o-mini',
+            max_tokens: 4096,
+            messages: [{
+                    role: 'user',
+                    content: [
+                        { type: 'image_url', image_url: { url: `data:image/png;base64,${screenshotBase64}` } },
+                        { type: 'text', text: prompt },
+                    ],
+                }],
+        });
+        return response.choices[0]?.message?.content || '';
+    }
+    parseResponse(text, provider, url, mode) {
+        if (mode === 'raw') {
+            return { raw: text, provider, url };
+        }
+        try {
+            const jsonMatch = text.match(/\{[\s\S]*\}/);
+            if (!jsonMatch) {
+                console.warn(`[VisionExtractor] No JSON found in ${provider} response. Returning raw.`);
+                return { raw: text, provider, url };
+            }
+            const parsed = JSON.parse(jsonMatch[0]);
+            const platform = this.detectPlatform(url);
+            if (mode === 'comments' && Array.isArray(parsed.comments)) {
+                const comments = parsed.comments.map((c, i) => ({
+                    id: c.id || `vision_comment_${i}`,
+                    author: {
+                        id: c.author || '',
+                        username: c.author || '',
+                        displayName: c.author || '',
+                    },
+                    text: c.text || '',
+                    timestamp: new Date(),
+                    likes: c.likes || 0,
+                }));
+                return { comments, provider, url };
+            }
+            if (mode === 'posts' && Array.isArray(parsed.posts)) {
+                const posts = parsed.posts.map((p, i) => ({
+                    id: p.id || `vision_post_${i}`,
+                    platform: platform,
+                    author: {
+                        id: p.author || '',
+                        username: p.author || '',
+                        displayName: p.author || '',
+                    },
+                    content: p.content || '',
+                    engagement: {
+                        likes: p.likes || 0,
+                        comments: p.comments || 0,
+                        shares: p.shares || 0,
+                        views: p.views || 0,
+                    },
+                    timestamp: new Date(),
+                    url: p.url || url,
+                    hashtags: (p.content || '').match(/#\w+/g)?.map((h) => h.slice(1)) || [],
+                }));
+                return { posts, provider, url };
+            }
+        }
+        catch (err) {
+            console.warn(`[VisionExtractor] Failed to parse ${provider} response as JSON:`, err);
+        }
+        return { raw: text, provider, url };
+    }
+}

package/dist/learnings.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Cross-Project Learnings — JSONL-backed persistent insights.
+ *
+ * Storage: ~/.crowdlisten/learnings.jsonl (append-only)
+ *
+ * Confidence decay: 1 point per 30 days for observed/inferred sources.
+ * User-stated learnings never decay.
+ * Entries below confidence 1 are excluded from search results.
+ */
+export type LearningType = "pattern" | "pitfall" | "preference" | "architecture" | "tool" | "operational";
+export type LearningSource = "observed" | "user-stated" | "inferred";
+export interface Learning {
+    id: string;
+    ts: string;
+    skill: string;
+    type: LearningType;
+    key: string;
+    insight: string;
+    confidence: number;
+    source: LearningSource;
+    project?: string;
+    files?: string[];
+}
+export interface LearningWithDecay extends Learning {
+    effectiveConfidence: number;
+    ageInDays: number;
+}
+/**
+ * Log a new learning. Deduplicates by key — if a learning with the same key
+ * exists, the new one supersedes it (both remain in JSONL, search returns latest).
+ */
+export declare function logLearning(input: Omit<Learning, "id" | "ts">): Learning;
+/**
+ * Search learnings by keyword query. Returns results with decayed confidence,
+ * filtered to effective confidence >= 1, sorted by effective confidence desc.
+ */
+export declare function searchLearnings(query: string, opts?: {
+    crossProject?: boolean;
+    currentProject?: string;
+    limit?: number;
+}): LearningWithDecay[];
+/**
+ * Get stats about the learnings store.
+ */
+export declare function getLearningsStats(): {
+    total: number;
+    uniqueKeys: number;
+    byType: Record<string, number>;
+    bySource: Record<string, number>;
+};

package/dist/learnings.js

@@ -0,0 +1,130 @@
+/**
+ * Cross-Project Learnings — JSONL-backed persistent insights.
+ *
+ * Storage: ~/.crowdlisten/learnings.jsonl (append-only)
+ *
+ * Confidence decay: 1 point per 30 days for observed/inferred sources.
+ * User-stated learnings never decay.
+ * Entries below confidence 1 are excluded from search results.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import * as crypto from "crypto";
+const BASE_DIR = path.join(os.homedir(), ".crowdlisten");
+const LEARNINGS_FILE = path.join(BASE_DIR, "learnings.jsonl");
+// ─── Helpers ────────────────────────────────────────────────────────────────
+function ensureDir() {
+    if (!fs.existsSync(BASE_DIR)) {
+        fs.mkdirSync(BASE_DIR, { recursive: true });
+    }
+}
+function daysSince(isoDate) {
+    const then = new Date(isoDate).getTime();
+    const now = Date.now();
+    return (now - then) / (1000 * 60 * 60 * 24);
+}
+/**
+ * Compute effective confidence with decay.
+ * User-stated learnings don't decay. Others lose 1 point per 30 days.
+ * Minimum effective confidence is 0 (entries below 1 are excluded from results).
+ */
+function computeEffectiveConfidence(learning) {
+    if (learning.source === "user-stated")
+        return learning.confidence;
+    const age = daysSince(learning.ts);
+    const decay = age / 30;
+    return Math.max(0, learning.confidence - decay);
+}
+/**
+ * Read all learnings from JSONL file.
+ */
+function readAllLearnings() {
+    if (!fs.existsSync(LEARNINGS_FILE))
+        return [];
+    try {
+        const raw = fs.readFileSync(LEARNINGS_FILE, "utf-8");
+        const lines = raw.trim().split("\n").filter(Boolean);
+        return lines.map((line) => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}
+// ─── Public API ─────────────────────────────────────────────────────────────
+/**
+ * Log a new learning. Deduplicates by key — if a learning with the same key
+ * exists, the new one supersedes it (both remain in JSONL, search returns latest).
+ */
+export function logLearning(input) {
+    ensureDir();
+    const learning = {
+        ...input,
+        id: crypto.randomUUID(),
+        ts: new Date().toISOString(),
+    };
+    fs.appendFileSync(LEARNINGS_FILE, JSON.stringify(learning) + "\n");
+    return learning;
+}
+/**
+ * Search learnings by keyword query. Returns results with decayed confidence,
+ * filtered to effective confidence >= 1, sorted by effective confidence desc.
+ */
+export function searchLearnings(query, opts) {
+    const limit = opts?.limit ?? 10;
+    const crossProject = opts?.crossProject ?? false;
+    const currentProject = opts?.currentProject;
+    const all = readAllLearnings();
+    const lower = query.toLowerCase();
+    // Deduplicate by key — keep the latest entry for each key
+    const byKey = new Map();
+    for (const l of all) {
+        byKey.set(l.key, l);
+    }
+    let results = [];
+    for (const learning of byKey.values()) {
+        // Filter by project scope
+        if (!crossProject && currentProject && learning.project && learning.project !== currentProject) {
+            continue;
+        }
+        // Keyword matching on key, insight, type, and skill
+        const searchable = [learning.key, learning.insight, learning.type, learning.skill]
+            .join(" ")
+            .toLowerCase();
+        if (!searchable.includes(lower))
+            continue;
+        const effectiveConfidence = computeEffectiveConfidence(learning);
+        // Exclude stale entries
+        if (effectiveConfidence < 1)
+            continue;
+        results.push({
+            ...learning,
+            effectiveConfidence: Math.round(effectiveConfidence * 10) / 10,
+            ageInDays: Math.round(daysSince(learning.ts)),
+        });
+    }
+    // Sort by effective confidence descending
+    results.sort((a, b) => b.effectiveConfidence - a.effectiveConfidence);
+    return results.slice(0, limit);
+}
+/**
+ * Get stats about the learnings store.
+ */
+export function getLearningsStats() {
+    const all = readAllLearnings();
+    const byKey = new Map();
+    for (const l of all)
+        byKey.set(l.key, l);
+    const byType = {};
+    const bySource = {};
+    for (const l of byKey.values()) {
+        byType[l.type] = (byType[l.type] || 0) + 1;
+        bySource[l.source] = (bySource[l.source] || 0) + 1;
+    }
+    return {
+        total: all.length,
+        uniqueKeys: byKey.size,
+        byType,
+        bySource,
+    };
+}

package/dist/openapi.d.ts

@@ -0,0 +1,29 @@
+/**
+ * OpenAPI 3.0 Spec Generator — auto-generates from MCP tool definitions
+ *
+ * Each MCP tool becomes a POST /tools/{name} endpoint.
+ * Tags group tools by their pack prefix (e.g., [Analysis], [Content]).
+ */
+interface OpenApiSpec {
+    openapi: string;
+    info: {
+        title: string;
+        version: string;
+        description: string;
+    };
+    servers: {
+        url: string;
+        description: string;
+    }[];
+    paths: Record<string, unknown>;
+    components: {
+        securitySchemes: Record<string, unknown>;
+    };
+    tags: {
+        name: string;
+        description: string;
+    }[];
+    security: Record<string, string[]>[];
+}
+export declare function generateOpenApiSpec(): OpenApiSpec;
+export {};

package/dist/openapi.js

@@ -0,0 +1,169 @@
+/**
+ * OpenAPI 3.0 Spec Generator — auto-generates from MCP tool definitions
+ *
+ * Each MCP tool becomes a POST /tools/{name} endpoint.
+ * Tags group tools by their pack prefix (e.g., [Analysis], [Content]).
+ */
+import { TOOLS } from "./tools.js";
+import { SERVER_VERSION } from "./server-factory.js";
+// Extract pack tag from tool description, e.g. "[Analysis] ..." → "analysis"
+function extractTag(description) {
+    const match = description.match(/^\[([^\]]+)\]/);
+    if (match)
+        return match[1].toLowerCase();
+    // Infer from description keywords
+    if (description.includes("[Setup]"))
+        return "setup";
+    if (description.includes("[Advanced]"))
+        return "sessions";
+    if (description.includes("[Context]"))
+        return "context";
+    // Default categorization
+    return "planning";
+}
+function tagDisplayName(tag) {
+    const names = {
+        analysis: "Analysis",
+        content: "Content & Vectors",
+        generation: "Document Generation",
+        llm: "LLM Proxy",
+        "agent network": "Agent Network",
+        setup: "Setup",
+        sessions: "Multi-Agent Sessions",
+        context: "Context Extraction",
+        planning: "Planning & Tasks",
+    };
+    return names[tag] || tag.charAt(0).toUpperCase() + tag.slice(1);
+}
+function tagDescription(tag) {
+    const descriptions = {
+        analysis: "Run audience analyses, extract themes and sentiment from social platforms",
+        content: "Ingest content, semantic vector search, manage content documents",
+        generation: "Generate PRDs and product documentation from analysis results",
+        llm: "Free LLM completion proxy — no API key required",
+        "agent network": "Register agents, discover capabilities, share analysis results",
+        setup: "Board and project management, initial configuration",
+        sessions: "Multi-agent parallel session coordination",
+        context: "Extract reusable context blocks from chat transcripts with PII redaction",
+        planning: "Task management, execution planning, knowledge base",
+    };
+    return descriptions[tag] || "";
+}
+export function generateOpenApiSpec() {
+    const paths = {};
+    const tagSet = new Set();
+    for (const tool of TOOLS) {
+        const tag = extractTag(tool.description);
+        tagSet.add(tag);
+        // Strip the [Pack] prefix from description for cleaner OpenAPI docs
+        const cleanDescription = tool.description.replace(/^\[[^\]]+\]\s*/, "");
+        const requestBody = {};
+        const schema = tool.inputSchema;
+        const hasProperties = schema.properties && Object.keys(schema.properties).length > 0;
+        if (hasProperties) {
+            requestBody.required = true;
+            requestBody.content = {
+                "application/json": {
+                    schema: {
+                        type: "object",
+                        properties: schema.properties,
+                        ...("required" in schema ? { required: schema.required } : {}),
+                    },
+                },
+            };
+        }
+        paths[`/tools/${tool.name}`] = {
+            post: {
+                operationId: tool.name,
+                summary: cleanDescription.split(".")[0] + ".",
+                description: cleanDescription,
+                tags: [tagDisplayName(tag)],
+                ...(hasProperties ? { requestBody } : {}),
+                responses: {
+                    "200": {
+                        description: "Tool result",
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    properties: {
+                                        content: {
+                                            type: "array",
+                                            items: {
+                                                type: "object",
+                                                properties: {
+                                                    type: { type: "string", example: "text" },
+                                                    text: { type: "string" },
+                                                },
+                                            },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    "401": { description: "API key required (paid tools)" },
+                    "500": { description: "Tool execution error" },
+                },
+            },
+        };
+    }
+    // Health endpoint
+    paths["/health"] = {
+        get: {
+            operationId: "health_check",
+            summary: "Health check",
+            tags: ["System"],
+            responses: {
+                "200": {
+                    description: "Server is healthy",
+                    content: {
+                        "application/json": {
+                            schema: {
+                                type: "object",
+                                properties: {
+                                    status: { type: "string", example: "ok" },
+                                    version: { type: "string", example: SERVER_VERSION },
+                                    tools: { type: "number" },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    };
+    const tags = [...tagSet].map((t) => ({
+        name: tagDisplayName(t),
+        description: tagDescription(t),
+    }));
+    tags.push({ name: "System", description: "Health and metadata endpoints" });
+    return {
+        openapi: "3.0.3",
+        info: {
+            title: "CrowdListen Harness API",
+            version: SERVER_VERSION,
+            description: "Audience intelligence, social listening, planning, and context extraction for AI agents. " +
+                "This API exposes the full CrowdListen tool surface as REST endpoints. " +
+                "Free tools (LLM, Agent Network) require no authentication. " +
+                "Paid tools (Analysis, Content, Generation) require a CROWDLISTEN_API_KEY.",
+        },
+        servers: [
+            { url: "https://mcp.crowdlisten.com", description: "Production" },
+            { url: "http://localhost:3848", description: "Local development" },
+        ],
+        paths,
+        components: {
+            securitySchemes: {
+                apiKey: {
+                    type: "apiKey",
+                    in: "header",
+                    name: "Authorization",
+                    description: 'Bearer token: CROWDLISTEN_API_KEY or Supabase JWT. Format: "Bearer <key>"',
+                },
+            },
+        },
+        tags,
+        security: [{ apiKey: [] }],
+    };
+}

package/dist/server-factory.d.ts

@@ -0,0 +1,20 @@
+/**
+ * MCP Server Factory — shared between stdio and HTTP transports
+ *
+ * Creates a configured MCP Server instance with tool handlers.
+ * Both stdio (CLI) and HTTP (remote) transports use this factory
+ * so the tool surface is identical regardless of transport.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+declare const SERVER_NAME = "crowdlisten/harness";
+declare const SERVER_VERSION = "0.6.0";
+export interface McpServerOptions {
+    supabase: any;
+    userId: string;
+}
+/**
+ * Creates and configures an MCP Server with all tool handlers registered.
+ * The caller is responsible for connecting a transport (stdio or HTTP).
+ */
+export declare function createMcpServer(opts: McpServerOptions): Server;
+export { SERVER_NAME, SERVER_VERSION };