@crowdlisten/harness 1.0.0

package/dist/server-factory.js

@@ -0,0 +1,41 @@
+/**
+ * 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";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { handleTool, TOOLS } from "./tools.js";
+const SERVER_NAME = "crowdlisten/harness";
+const SERVER_VERSION = "0.6.0";
+/**
+ * Creates and configures an MCP Server with all tool handlers registered.
+ * The caller is responsible for connecting a transport (stdio or HTTP).
+ */
+export function createMcpServer(opts) {
+    const { supabase: sb, userId } = opts;
+    const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: TOOLS,
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: toolArgs } = request.params;
+        try {
+            const result = await handleTool(sb, userId, name, (toolArgs || {}));
+            return { content: [{ type: "text", text: result }] };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ error: message }) },
+                ],
+                isError: true,
+            };
+        }
+    });
+    return server;
+}
+export { SERVER_NAME, SERVER_VERSION };

package/dist/suggestions.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Proactive Skill Pack Suggestions — keyword heuristics on tool results.
+ *
+ * After each tool call, scans the result text for keywords that map to
+ * inactive packs. Suggests activation with cooldown to avoid noise.
+ */
+export interface Suggestion {
+    pack_id: string;
+    reason: string;
+    activate_command: string;
+}
+/**
+ * Check if a suggestion should be made based on tool result text.
+ * Returns a suggestion or null.
+ */
+export declare function checkSuggestion(resultText: string, activePacks: string[], proactiveSuggestionsEnabled: boolean): Suggestion | null;

package/dist/suggestions.js

@@ -0,0 +1,72 @@
+/**
+ * Proactive Skill Pack Suggestions — keyword heuristics on tool results.
+ *
+ * After each tool call, scans the result text for keywords that map to
+ * inactive packs. Suggests activation with cooldown to avoid noise.
+ */
+const HEURISTIC_RULES = [
+    {
+        keywords: ["social", "reddit", "twitter", "tiktok", "youtube", "instagram", "platform"],
+        pack: "social-listening",
+        reason: "Your work mentions social platforms. Activate social-listening to search across 7 platforms.",
+    },
+    {
+        keywords: ["analysis", "sentiment", "insight", "opinion", "audience", "cluster"],
+        pack: "audience-analysis",
+        reason: "Your work involves analysis. Activate audience-analysis for AI-powered content analysis and opinion clustering.",
+    },
+    {
+        keywords: ["knowledge", "learning", "context", "decision", "pattern"],
+        pack: "knowledge",
+        reason: "Your work involves knowledge management. Activate the knowledge pack to query decisions and record learnings.",
+    },
+    {
+        keywords: ["plan", "task", "milestone", "roadmap", "backlog"],
+        pack: "planning",
+        reason: "Your work involves planning. Activate the planning pack for task management and execution tracking.",
+    },
+    {
+        keywords: ["spec", "requirement", "feature", "implementation", "acceptance"],
+        pack: "spec-delivery",
+        reason: "Your work involves specifications. Activate spec-delivery to browse and implement specs from analysis.",
+    },
+    {
+        keywords: ["session", "agent", "parallel", "coordinate", "delegate"],
+        pack: "sessions",
+        reason: "Your work involves multi-agent coordination. Activate sessions to coordinate parallel agent sessions.",
+    },
+];
+// ─── Cooldown ───────────────────────────────────────────────────────────────
+const COOLDOWN_MS = 5 * 60 * 1000; // 5 minutes
+const lastSuggested = new Map();
+// ─── Public API ─────────────────────────────────────────────────────────────
+/**
+ * Check if a suggestion should be made based on tool result text.
+ * Returns a suggestion or null.
+ */
+export function checkSuggestion(resultText, activePacks, proactiveSuggestionsEnabled) {
+    if (!proactiveSuggestionsEnabled)
+        return null;
+    const lower = resultText.toLowerCase();
+    const now = Date.now();
+    for (const rule of HEURISTIC_RULES) {
+        // Skip if pack already active
+        if (activePacks.includes(rule.pack))
+            continue;
+        // Skip if on cooldown
+        const lastTime = lastSuggested.get(rule.pack);
+        if (lastTime && now - lastTime < COOLDOWN_MS)
+            continue;
+        // Check if any keyword matches
+        const matched = rule.keywords.some((kw) => lower.includes(kw));
+        if (matched) {
+            lastSuggested.set(rule.pack, now);
+            return {
+                pack_id: rule.pack,
+                reason: rule.reason,
+                activate_command: `activate_skill_pack({ pack_id: '${rule.pack}' })`,
+            };
+        }
+    }
+    return null;
+}

package/dist/telemetry.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Telemetry — Opt-in usage tracking with three privacy tiers.
+ *
+ * Storage: ~/.crowdlisten/telemetry.jsonl (append-only, one JSON line per event)
+ *
+ * Tiers:
+ *  - "off": no recording
+ *  - "anonymous": local-only, no installationId
+ *  - "community": includes installationId for aggregate insights
+ */
+import type { UserState, TelemetryLevel } from "./context/user-state.js";
+export interface TelemetryEvent {
+    ts: string;
+    event: "tool_call";
+    tool: string;
+    pack: string;
+    duration_ms: number;
+    success: boolean;
+    installationId?: string;
+}
+/**
+ * Record a telemetry event. Respects the user's telemetry level.
+ */
+export declare function recordEvent(event: Omit<TelemetryEvent, "ts" | "installationId">, level: TelemetryLevel, installationId?: string): void;
+/**
+ * Check if there's a pending onboarding step.
+ * Returns the step name or null if all complete.
+ */
+export declare function shouldOnboard(state: UserState): string | null;
+/**
+ * Get onboarding prompt content for a step.
+ */
+export declare function getOnboardingPrompt(step: string): {
+    title: string;
+    message: string;
+} | null;
+/**
+ * Build the tool-to-pack mapping from the registry at init time.
+ * Used by both telemetry (to tag events) and suggestions.
+ */
+export declare function buildToolPackMap(packs: Array<{
+    id: string;
+    toolNames: string[];
+}>): Map<string, string>;

package/dist/telemetry.js

@@ -0,0 +1,93 @@
+/**
+ * Telemetry — Opt-in usage tracking with three privacy tiers.
+ *
+ * Storage: ~/.crowdlisten/telemetry.jsonl (append-only, one JSON line per event)
+ *
+ * Tiers:
+ *  - "off": no recording
+ *  - "anonymous": local-only, no installationId
+ *  - "community": includes installationId for aggregate insights
+ */
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+const BASE_DIR = path.join(os.homedir(), ".crowdlisten");
+const TELEMETRY_FILE = path.join(BASE_DIR, "telemetry.jsonl");
+// ─── Onboarding Steps ───────────────────────────────────────────────────────
+const ONBOARDING_STEPS = ["telemetry", "proactive", "learnings"];
+const ONBOARDING_PROMPTS = {
+    telemetry: {
+        title: "Usage Telemetry",
+        message: "CrowdListen can track tool usage to improve suggestions over time. " +
+            "Choose a privacy level:\n" +
+            "- **off**: No tracking (default)\n" +
+            "- **anonymous**: Local-only usage stats, never shared\n" +
+            "- **community**: Anonymous aggregate stats help improve CrowdListen for everyone\n\n" +
+            "Set with: set_preferences({ telemetry: 'off' | 'anonymous' | 'community' })",
+    },
+    proactive: {
+        title: "Proactive Skill Suggestions",
+        message: "CrowdListen can suggest relevant skill packs based on your usage patterns. " +
+            "This is enabled by default. Disable with: set_preferences({ proactive_suggestions: false })",
+    },
+    learnings: {
+        title: "Cross-Project Learnings",
+        message: "CrowdListen can persist insights and patterns across projects, so learnings from one project " +
+            "help in future work. Disabled by default.\n\n" +
+            "Enable with: set_preferences({ cross_project_learnings: true })",
+    },
+};
+// ─── Functions ──────────────────────────────────────────────────────────────
+function ensureDir() {
+    if (!fs.existsSync(BASE_DIR)) {
+        fs.mkdirSync(BASE_DIR, { recursive: true });
+    }
+}
+/**
+ * Record a telemetry event. Respects the user's telemetry level.
+ */
+export function recordEvent(event, level, installationId) {
+    if (level === "off")
+        return;
+    ensureDir();
+    const record = {
+        ...event,
+        ts: new Date().toISOString(),
+    };
+    // Only include installationId at community tier
+    if (level === "community" && installationId) {
+        record.installationId = installationId;
+    }
+    fs.appendFileSync(TELEMETRY_FILE, JSON.stringify(record) + "\n");
+}
+/**
+ * Check if there's a pending onboarding step.
+ * Returns the step name or null if all complete.
+ */
+export function shouldOnboard(state) {
+    for (const step of ONBOARDING_STEPS) {
+        if (!state.onboardingCompleted.includes(step)) {
+            return step;
+        }
+    }
+    return null;
+}
+/**
+ * Get onboarding prompt content for a step.
+ */
+export function getOnboardingPrompt(step) {
+    return ONBOARDING_PROMPTS[step] || null;
+}
+/**
+ * Build the tool-to-pack mapping from the registry at init time.
+ * Used by both telemetry (to tag events) and suggestions.
+ */
+export function buildToolPackMap(packs) {
+    const map = new Map();
+    for (const pack of packs) {
+        for (const tool of pack.toolNames) {
+            map.set(tool, pack.id);
+        }
+    }
+    return map;
+}

package/dist/tools/registry.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Skill Pack Registry — Progressive Disclosure
+ *
+ * Groups tools into logical skill packs following the GitHub MCP Server pattern.
+ * Start with ~4 discovery tools, activate packs on demand, fire tools/list_changed.
+ *
+ * Pattern: 85-98% token savings vs static tool lists.
+ */
+export interface SkillPack {
+    id: string;
+    name: string;
+    description: string;
+    toolNames: string[];
+    isVirtual?: boolean;
+    skillMdPath?: string;
+}
+export interface SkillPackInfo {
+    id: string;
+    name: string;
+    description: string;
+    toolCount: number;
+    status: "active" | "available";
+    isVirtual: boolean;
+}
+/**
+ * Register a tool definition. Called during server init.
+ */
+export declare function registerTool(tool: any): void;
+/**
+ * Register an array of tool definitions.
+ */
+export declare function registerTools(tools: any[]): void;
+/**
+ * Built-in skill packs grouping tools into logical units.
+ */
+export declare function initializeRegistry(skillsDir: string): void;
+/**
+ * Get tool definitions for a set of active pack IDs.
+ * Core pack tools are always included.
+ */
+export declare function getToolsForPacks(activePackIds: string[]): any[];
+/**
+ * Get tool definitions for a single pack.
+ */
+export declare function getPackTools(packId: string): any[];
+/**
+ * List all packs with their metadata and active status.
+ */
+export declare function listPacks(activePackIds: string[]): SkillPackInfo[];
+/**
+ * Check if a pack exists.
+ */
+export declare function hasPack(packId: string): boolean;
+/**
+ * Get a pack by ID.
+ */
+export declare function getPack(packId: string): SkillPack | undefined;
+/**
+ * Get the SKILL.md content for a virtual pack.
+ */
+export declare function getSkillMdContent(packId: string): string | null;
+/**
+ * Check if a tool name belongs to the insights module.
+ */
+export declare function isInsightsTool(name: string): boolean;

package/dist/tools/registry.js

@@ -0,0 +1,256 @@
+/**
+ * Skill Pack Registry — Progressive Disclosure
+ *
+ * Groups tools into logical skill packs following the GitHub MCP Server pattern.
+ * Start with ~4 discovery tools, activate packs on demand, fire tools/list_changed.
+ *
+ * Pattern: 85-98% token savings vs static tool lists.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { INSIGHTS_TOOLS } from "../insights/index.js";
+// ─── Tool Definitions (imported from other modules) ─────────────────────────
+// We store tools in a flat map for lookup
+const toolMap = new Map();
+/**
+ * Register a tool definition. Called during server init.
+ */
+export function registerTool(tool) {
+    toolMap.set(tool.name, tool);
+}
+/**
+ * Register an array of tool definitions.
+ */
+export function registerTools(tools) {
+    for (const tool of tools) {
+        toolMap.set(tool.name, tool);
+    }
+}
+// ─── Pack Definitions ──────────────────────────────────────────────────────
+const packs = new Map();
+/**
+ * Built-in skill packs grouping tools into logical units.
+ */
+export function initializeRegistry(skillsDir) {
+    // Core — always on (5 tools)
+    packs.set("core", {
+        id: "core",
+        name: "Core",
+        description: "Discovery + memory — list skill packs, activate packs, save and recall context with semantic search",
+        toolNames: ["list_skill_packs", "activate_skill_pack", "save", "recall", "set_preferences"],
+    });
+    // Planning — task management
+    packs.set("planning", {
+        id: "planning",
+        name: "Planning & Tasks",
+        description: "Task management, planning, and execution tracking — create tasks, build plans, track progress",
+        toolNames: [
+            "list_tasks", "create_task", "get_task", "update_task",
+            "claim_task", "complete_task", "log_progress", "delete_task",
+            "create_plan", "get_plan", "update_plan",
+        ],
+    });
+    // Knowledge pack removed — consolidated into core save/recall
+    // Social listening — free tools
+    packs.set("social-listening", {
+        id: "social-listening",
+        name: "Social Listening",
+        description: "Search and retrieve content from social platforms — Reddit, Twitter, TikTok, YouTube, Instagram. Free, no API key needed.",
+        toolNames: [
+            "search_content", "get_content_comments", "get_trending_content",
+            "get_user_content", "get_platform_status", "health_check", "extract_url",
+        ],
+    });
+    // Audience analysis — paid tools
+    packs.set("audience-analysis", {
+        id: "audience-analysis",
+        name: "Audience Analysis",
+        description: "AI-powered content analysis, opinion clustering, insight extraction, and cross-platform research synthesis. Requires CROWDLISTEN_API_KEY.",
+        toolNames: [
+            "analyze_content", "cluster_opinions", "enrich_content",
+            "deep_analyze", "extract_insights", "research_synthesis",
+        ],
+    });
+    // Sessions — multi-agent coordination
+    packs.set("sessions", {
+        id: "sessions",
+        name: "Multi-Agent Sessions",
+        description: "Coordinate parallel agent sessions on shared tasks",
+        toolNames: ["start_session", "list_sessions", "update_session"],
+    });
+    // Setup — board management
+    packs.set("setup", {
+        id: "setup",
+        name: "Setup & Board Management",
+        description: "Project and board setup — list projects, create boards, migrate tasks",
+        toolNames: [
+            "get_or_create_global_board", "list_projects",
+            "list_boards", "create_board", "migrate_to_global_board",
+        ],
+    });
+    // Spec Delivery — actionable specs from crowd analysis
+    packs.set("spec-delivery", {
+        id: "spec-delivery",
+        name: "Spec Delivery",
+        description: "Actionable specs from crowd feedback — browse, inspect, and start implementing specs generated from analysis",
+        toolNames: ["get_specs", "get_spec_detail", "start_spec"],
+    });
+    // ── Agent-Proxied Packs (proxy to agent.crowdlisten.com) ────────────
+    // Analysis — run full audience analysis, continue, list results
+    packs.set("analysis", {
+        id: "analysis",
+        name: "Analysis Engine",
+        description: "Run audience analyses, continue with follow-ups, list results, generate specs. Requires CROWDLISTEN_API_KEY.",
+        toolNames: [
+            "run_analysis", "continue_analysis", "get_analysis",
+            "list_analyses", "generate_specs",
+        ],
+    });
+    // Content & Vectors — ingest, search, manage content
+    packs.set("content", {
+        id: "content",
+        name: "Content & Vectors",
+        description: "Ingest content for vector storage, semantic search, stats, deletion. Requires CROWDLISTEN_API_KEY.",
+        toolNames: ["ingest_content", "search_vectors", "get_content_stats", "delete_content"],
+    });
+    // Document Generation — PRDs from analysis
+    packs.set("generation", {
+        id: "generation",
+        name: "Document Generation",
+        description: "Generate PRDs from analysis results, update sections. Requires CROWDLISTEN_API_KEY.",
+        toolNames: ["generate_prd", "update_prd_section"],
+    });
+    // LLM Proxy — free completion and model listing
+    packs.set("llm", {
+        id: "llm",
+        name: "LLM Proxy",
+        description: "Free LLM completion proxy — no API key needed. List available models and run completions.",
+        toolNames: ["llm_complete", "list_llm_models"],
+    });
+    // Agent Network — register, discover, share
+    packs.set("agent-network", {
+        id: "agent-network",
+        name: "Agent Network",
+        description: "Register agents, discover capabilities, submit analysis results to the network.",
+        toolNames: ["register_agent", "get_capabilities", "submit_analysis"],
+    });
+    // Legacy — context extraction tools (hidden by default for existing users, replaced by remember/recall)
+    packs.set("legacy", {
+        id: "legacy",
+        name: "Legacy Context Extraction",
+        description: "Previous-gen context tools — process transcripts, discover skills, install skills. Replaced by remember/recall and list_skill_packs.",
+        toolNames: [
+            "process_transcript", "get_context_blocks", "recommend_skills",
+            "discover_skills", "search_skills", "install_skill",
+        ],
+    });
+    // ── Virtual SKILL.md Packs ────────────────────────────────────────────
+    // Each native skill directory becomes a virtual pack
+    if (fs.existsSync(skillsDir)) {
+        const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const skillMd = path.join(skillsDir, entry.name, "SKILL.md");
+            if (!fs.existsSync(skillMd))
+                continue;
+            packs.set(entry.name, {
+                id: entry.name,
+                name: entry.name.split("-").map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(" "),
+                description: `Skill workflow: ${entry.name}. Activate to load SKILL.md instructions.`,
+                toolNames: [],
+                isVirtual: true,
+                skillMdPath: skillMd,
+            });
+        }
+    }
+}
+// ─── Public API ─────────────────────────────────────────────────────────────
+/**
+ * Get tool definitions for a set of active pack IDs.
+ * Core pack tools are always included.
+ */
+export function getToolsForPacks(activePackIds) {
+    const toolNames = new Set();
+    // Core is always included
+    const corePack = packs.get("core");
+    if (corePack) {
+        for (const name of corePack.toolNames)
+            toolNames.add(name);
+    }
+    for (const packId of activePackIds) {
+        const pack = packs.get(packId);
+        if (!pack || pack.isVirtual)
+            continue;
+        for (const name of pack.toolNames)
+            toolNames.add(name);
+    }
+    const tools = [];
+    for (const name of toolNames) {
+        const tool = toolMap.get(name);
+        if (tool)
+            tools.push(tool);
+    }
+    return tools;
+}
+/**
+ * Get tool definitions for a single pack.
+ */
+export function getPackTools(packId) {
+    const pack = packs.get(packId);
+    if (!pack)
+        return [];
+    return pack.toolNames
+        .map(name => toolMap.get(name))
+        .filter(Boolean);
+}
+/**
+ * List all packs with their metadata and active status.
+ */
+export function listPacks(activePackIds) {
+    const result = [];
+    for (const pack of packs.values()) {
+        result.push({
+            id: pack.id,
+            name: pack.name,
+            description: pack.description,
+            toolCount: pack.toolNames.length,
+            status: activePackIds.includes(pack.id) || pack.id === "core" ? "active" : "available",
+            isVirtual: pack.isVirtual || false,
+        });
+    }
+    return result;
+}
+/**
+ * Check if a pack exists.
+ */
+export function hasPack(packId) {
+    return packs.has(packId);
+}
+/**
+ * Get a pack by ID.
+ */
+export function getPack(packId) {
+    return packs.get(packId);
+}
+/**
+ * Get the SKILL.md content for a virtual pack.
+ */
+export function getSkillMdContent(packId) {
+    const pack = packs.get(packId);
+    if (!pack?.isVirtual || !pack.skillMdPath)
+        return null;
+    try {
+        return fs.readFileSync(pack.skillMdPath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if a tool name belongs to the insights module.
+ */
+export function isInsightsTool(name) {
+    const insightsToolNames = new Set(INSIGHTS_TOOLS.map((t) => t.name));
+    return insightsToolNames.has(name);
+}