clementine-agent 1.0.0

package/dist/agent/insight-engine.js

@@ -0,0 +1,225 @@
+/**
+ * Clementine TypeScript — Insight Engine.
+ *
+ * Proactive conversation initiation: runs during heartbeat ticks to
+ * identify events or patterns the user should know about. Generates
+ * urgency-rated insights and dispatches via NotificationDispatcher.
+ *
+ * Throttling: max 3 proactive messages per day, minimum 2-hour cooldown.
+ * Adapts based on user acknowledgment (doubles cooldown after 3 ignored).
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import pino from 'pino';
+import { GOALS_DIR, BASE_DIR } from '../config.js';
+const logger = pino({ name: 'clementine.insight-engine' });
+const BASE_COOLDOWN_MS = 2 * 60 * 60 * 1000; // 2 hours
+const MAX_DAILY_INSIGHTS = 3;
+const UNACKED_THRESHOLD = 3; // double cooldown after this many ignored
+/**
+ * Check if it's too soon to send another proactive message.
+ */
+export function canSendInsight(state) {
+    const today = new Date().toISOString().slice(0, 10);
+    // Reset daily count on new day
+    if (state.currentDate !== today) {
+        state.sentToday = [];
+        state.currentDate = today;
+        // Don't reset cooldownMultiplier — that persists across days
+    }
+    // Daily limit
+    if (state.sentToday.length >= MAX_DAILY_INSIGHTS) {
+        return false;
+    }
+    // Cooldown check
+    if (state.lastSentAt) {
+        const elapsed = Date.now() - new Date(state.lastSentAt).getTime();
+        const cooldown = BASE_COOLDOWN_MS * state.cooldownMultiplier;
+        if (elapsed < cooldown) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Record that a proactive message was sent.
+ */
+export function recordInsightSent(state) {
+    const now = new Date().toISOString();
+    state.sentToday.push(now);
+    state.lastSentAt = now;
+    state.unackedCount++;
+}
+/**
+ * Record that the user acknowledged a proactive message (replied to it).
+ * Resets the unacked counter and lowers cooldown.
+ */
+export function recordInsightAcked(state) {
+    state.unackedCount = 0;
+    state.cooldownMultiplier = 1;
+}
+/**
+ * Check if cooldown should be increased due to ignored messages.
+ */
+export function maybeIncreaseCooldown(state) {
+    if (state.unackedCount >= UNACKED_THRESHOLD) {
+        state.cooldownMultiplier = Math.min(state.cooldownMultiplier * 2, 8); // cap at 16 hours
+        state.unackedCount = 0; // reset counter after adjustment
+        logger.info({ multiplier: state.cooldownMultiplier }, 'Proactive message cooldown increased — messages going unacknowledged');
+    }
+}
+/**
+ * Gather raw signals for insight generation (no LLM call — pure data).
+ * Returns structured event summaries that can be passed to an LLM for urgency rating.
+ */
+export function gatherInsightSignals(gateway) {
+    const signals = [];
+    const twoHoursAgo = new Date(Date.now() - 2 * 60 * 60 * 1000).toISOString();
+    // 1. Check for goal progress/failures
+    try {
+        const progressDir = path.join(GOALS_DIR, 'progress');
+        if (existsSync(progressDir)) {
+            const files = readdirSync(progressDir).filter(f => f.endsWith('.progress.jsonl'));
+            for (const file of files.slice(0, 5)) {
+                const lines = readFileSync(path.join(progressDir, file), 'utf-8').trim().split('\n').filter(Boolean);
+                const recent = lines.slice(-3);
+                for (const line of recent) {
+                    try {
+                        const entry = JSON.parse(line);
+                        if (new Date(entry.timestamp) > new Date(twoHoursAgo)) {
+                            if (entry.status === 'error') {
+                                signals.push(`Goal work session failed: ${entry.focus} (${entry.resultSnippet?.slice(0, 100)})`);
+                            }
+                            else if (entry.status === 'progress') {
+                                signals.push(`Goal progress: ${entry.focus}`);
+                            }
+                        }
+                    }
+                    catch {
+                        continue;
+                    }
+                }
+            }
+        }
+    }
+    catch { /* non-fatal */ }
+    // 2. Check for cron job failures
+    try {
+        const runLogDir = path.join(BASE_DIR, 'cron', 'run-log');
+        if (existsSync(runLogDir)) {
+            const logFiles = readdirSync(runLogDir).filter(f => f.endsWith('.jsonl')).slice(0, 10);
+            for (const file of logFiles) {
+                const lines = readFileSync(path.join(runLogDir, file), 'utf-8').trim().split('\n').filter(Boolean);
+                const lastLine = lines[lines.length - 1];
+                if (!lastLine)
+                    continue;
+                try {
+                    const entry = JSON.parse(lastLine);
+                    if (new Date(entry.timestamp) > new Date(twoHoursAgo) && entry.status === 'error') {
+                        signals.push(`Cron job "${entry.jobName || file.replace('.jsonl', '')}" failed: ${(entry.error || '').slice(0, 100)}`);
+                    }
+                }
+                catch {
+                    continue;
+                }
+            }
+        }
+    }
+    catch { /* non-fatal */ }
+    // 3. Check recent activity for patterns worth surfacing
+    try {
+        const activity = gateway.getRecentActivity(twoHoursAgo);
+        const sessionCount = new Set(activity.map(a => a.sessionKey)).size;
+        if (sessionCount === 0) {
+            // No recent activity — could note quiet period if there are pending goals
+            try {
+                if (existsSync(GOALS_DIR)) {
+                    const goals = readdirSync(GOALS_DIR).filter(f => f.endsWith('.json'));
+                    const activeHighPriority = goals.filter(f => {
+                        try {
+                            const g = JSON.parse(readFileSync(path.join(GOALS_DIR, f), 'utf-8'));
+                            return g.status === 'active' && g.priority === 'high';
+                        }
+                        catch {
+                            return false;
+                        }
+                    });
+                    if (activeHighPriority.length > 0) {
+                        signals.push(`Quiet period: ${activeHighPriority.length} high-priority goal(s) active but no recent user interaction`);
+                    }
+                }
+            }
+            catch { /* non-fatal */ }
+        }
+    }
+    catch { /* non-fatal */ }
+    // 4. Check advisor events (model escalations, circuit breakers)
+    try {
+        const eventsPath = path.join(BASE_DIR, 'cron', 'advisor-events.jsonl');
+        if (existsSync(eventsPath)) {
+            const lines = readFileSync(eventsPath, 'utf-8').trim().split('\n').filter(Boolean);
+            const recent = lines.slice(-5);
+            for (const line of recent) {
+                try {
+                    const evt = JSON.parse(line);
+                    if (new Date(evt.timestamp) > new Date(twoHoursAgo)) {
+                        if (evt.type === 'circuit-breaker') {
+                            signals.push(`Circuit breaker tripped for "${evt.jobName}": ${evt.detail}`);
+                        }
+                        else if (evt.type === 'escalation') {
+                            signals.push(`Job "${evt.jobName}" escalated: ${evt.detail}`);
+                        }
+                    }
+                }
+                catch {
+                    continue;
+                }
+            }
+        }
+    }
+    catch { /* non-fatal */ }
+    return signals;
+}
+/**
+ * Build a prompt for urgency rating (to be sent to a lightweight LLM).
+ * Returns null if there are no signals worth evaluating.
+ */
+export function buildInsightPrompt(signals) {
+    if (signals.length === 0)
+        return null;
+    return (`You are a proactive assistant analyzing recent events for your owner.\n\n` +
+        `## Recent Events\n${signals.map(s => `- ${s}`).join('\n')}\n\n` +
+        `## Task\n` +
+        `Based on these events, determine if the user should be notified.\n\n` +
+        `Rate urgency 1-5:\n` +
+        `1 = trivial (don't notify)\n` +
+        `2 = low (don't notify)\n` +
+        `3 = informational (batch into next check-in)\n` +
+        `4 = important (notify during active hours)\n` +
+        `5 = critical (notify immediately)\n\n` +
+        `If urgency >= 3, write a brief, conversational message (1-3 sentences) for the user.\n\n` +
+        `Output ONLY JSON:\n` +
+        `{ "urgency": <1-5>, "message": "<text or null>", "source": "<which event triggered this>" }`);
+}
+/**
+ * Parse the LLM response into an InsightResult.
+ */
+export function parseInsightResponse(response) {
+    try {
+        const jsonMatch = response.match(/\{[\s\S]*\}/);
+        if (!jsonMatch)
+            return null;
+        const parsed = JSON.parse(jsonMatch[0]);
+        if (!parsed.urgency || parsed.urgency < 3 || !parsed.message)
+            return null;
+        return {
+            message: parsed.message,
+            urgency: parsed.urgency,
+            source: parsed.source || 'unknown',
+        };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=insight-engine.js.map

package/dist/agent/intent-classifier.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Clementine TypeScript — Intent Classifier & Response Strategy Router.
+ *
+ * Lightweight heuristic classifier that determines message intent BEFORE
+ * the main SDK query, enabling dynamic tuning of maxTurns, effort level,
+ * and response formatting guidance.
+ */
+export type IntentType = 'question' | 'task' | 'feedback' | 'casual' | 'followup' | 'correction';
+export type ResponseStrategy = 'brief-answer' | 'structured-response' | 'plan-and-execute' | 'acknowledge-and-adapt' | 'conversational';
+export interface IntentClassification {
+    type: IntentType;
+    confidence: number;
+    suggestedStrategy: ResponseStrategy;
+    /** Suggested maxTurns for this intent type */
+    suggestedMaxTurns: number;
+    /** Suggested effort level for the SDK */
+    suggestedEffort: 'low' | 'medium' | 'high';
+}
+/**
+ * Classify a user message's intent using heuristics.
+ *
+ * @param text - The user's raw message
+ * @param recentExchanges - Recent conversation history for followup detection
+ */
+export declare function classifyIntent(text: string, recentExchanges?: Array<{
+    user: string;
+    assistant: string;
+}>): IntentClassification;
+/**
+ * Generate system prompt guidance text based on the response strategy.
+ * Injected into the system prompt to steer the agent's response style.
+ */
+export declare function getStrategyGuidance(strategy: ResponseStrategy): string;
+/**
+ * Generate a follow-up suggestion prompt suffix based on completed work.
+ *
+ * @param toolCallCount - Number of tool calls made during the query
+ * @param responseLength - Length of the response text
+ * @param hasActiveGoals - Whether there are relevant active goals
+ * @param pendingWorkItems - Number of pending items in the work queue
+ */
+export declare function buildFollowUpContext(opts: {
+    toolCallCount: number;
+    responseLength: number;
+    hasActiveGoals: boolean;
+    pendingWorkItems: number;
+}): string | null;
+//# sourceMappingURL=intent-classifier.d.ts.map

package/dist/agent/intent-classifier.js

@@ -0,0 +1,214 @@
+/**
+ * Clementine TypeScript — Intent Classifier & Response Strategy Router.
+ *
+ * Lightweight heuristic classifier that determines message intent BEFORE
+ * the main SDK query, enabling dynamic tuning of maxTurns, effort level,
+ * and response formatting guidance.
+ */
+// ── Constants ─────────────────────────────────────────────────────────
+const QUESTION_STARTERS = /^(what|who|where|when|why|how|is|are|was|were|do|does|did|can|could|would|should|will|which|have|has|tell me)\b/i;
+const ACTION_VERBS = /\b(create|write|send|update|deploy|build|fix|add|remove|delete|install|configure|set up|draft|schedule|implement|refactor|change|move|rename|edit|modify|generate|make|run|execute|push|pull|check|review|analyze|search|find|fetch|get|list|show)\b/i;
+const FEEDBACK_POSITIVE = /^(thanks|thank you|ty|thx|great|perfect|nice|awesome|love it|good job|well done|excellent|looks good|lgtm|cool|sweet|beautiful|brilliant|exactly|yes|yep|yeah|correct|right|ok)\b/i;
+const FEEDBACK_NEGATIVE = /^(no|nope|wrong|not right|that's not|that isn't|ugh|nah|bad|incorrect|stop|don't|actually no|wait no)\b/i;
+const CORRECTION_PATTERNS = /\b(actually|instead|rather|not that|I meant|I said|what I wanted|correction|try again|redo|no I|that's wrong)\b/i;
+const CASUAL_PATTERNS = /^(hi|hey|hello|good morning|good afternoon|good evening|sup|yo|what's up|howdy|morning|gm|gn|good night)\b/i;
+// ── Classifier ────────────────────────────────────────────────────────
+/**
+ * Classify a user message's intent using heuristics.
+ *
+ * @param text - The user's raw message
+ * @param recentExchanges - Recent conversation history for followup detection
+ */
+export function classifyIntent(text, recentExchanges) {
+    const trimmed = text.trim();
+    const wordCount = trimmed.split(/\s+/).length;
+    const endsWithQuestion = trimmed.endsWith('?');
+    const hasRecentContext = (recentExchanges?.length ?? 0) > 0;
+    // Score each intent type
+    const scores = {
+        question: 0,
+        task: 0,
+        feedback: 0,
+        casual: 0,
+        followup: 0,
+        correction: 0,
+    };
+    // ── Question signals ──
+    if (endsWithQuestion)
+        scores.question += 0.4;
+    if (QUESTION_STARTERS.test(trimmed))
+        scores.question += 0.35;
+    if (wordCount < 15 && endsWithQuestion)
+        scores.question += 0.15;
+    // ── Task signals ──
+    if (ACTION_VERBS.test(trimmed))
+        scores.task += 0.35;
+    if (wordCount > 20)
+        scores.task += 0.1; // Longer messages tend to be tasks
+    if (trimmed.includes('\n') || trimmed.includes('```'))
+        scores.task += 0.15; // Multi-line or code blocks
+    if (/\b(please|can you|could you|I need|I want)\b/i.test(trimmed))
+        scores.task += 0.2;
+    // If it has action verbs AND doesn't end with ?, lean toward task over question
+    if (ACTION_VERBS.test(trimmed) && !endsWithQuestion)
+        scores.task += 0.15;
+    // ── Feedback signals ──
+    if (FEEDBACK_POSITIVE.test(trimmed))
+        scores.feedback += 0.5;
+    if (FEEDBACK_NEGATIVE.test(trimmed))
+        scores.feedback += 0.4;
+    if (wordCount <= 5)
+        scores.feedback += 0.15; // Short messages are often feedback
+    // ── Casual signals ──
+    if (CASUAL_PATTERNS.test(trimmed))
+        scores.casual += 0.6;
+    if (wordCount <= 3 && !endsWithQuestion && !ACTION_VERBS.test(trimmed))
+        scores.casual += 0.2;
+    // ── Correction signals ──
+    if (CORRECTION_PATTERNS.test(trimmed) && hasRecentContext)
+        scores.correction += 0.5;
+    if (FEEDBACK_NEGATIVE.test(trimmed) && hasRecentContext && wordCount > 5) {
+        scores.correction += 0.3; // Negative feedback + more detail = likely correction
+        scores.feedback -= 0.2; // Reduce feedback score
+    }
+    // ── Followup signals ──
+    if (hasRecentContext) {
+        const lastAssistant = recentExchanges[recentExchanges.length - 1]?.assistant ?? '';
+        // References to previous response content
+        if (/\b(that|this|it|those|these|the one|above|earlier)\b/i.test(trimmed)) {
+            scores.followup += 0.25;
+        }
+        // Short messages in active conversation are likely followups
+        if (wordCount < 10 && !CASUAL_PATTERNS.test(trimmed)) {
+            scores.followup += 0.15;
+        }
+        // If the assistant asked a question and the user responds briefly
+        if (lastAssistant.endsWith('?') && wordCount < 20) {
+            scores.followup += 0.3;
+        }
+    }
+    // ── Pick winner ──
+    let bestType = 'question';
+    let bestScore = 0;
+    for (const [type, score] of Object.entries(scores)) {
+        if (score > bestScore) {
+            bestType = type;
+            bestScore = score;
+        }
+    }
+    // Default fallback: if no strong signal, classify based on simple heuristics
+    if (bestScore < 0.2) {
+        if (endsWithQuestion)
+            bestType = 'question';
+        else if (wordCount > 15)
+            bestType = 'task';
+        else
+            bestType = 'question'; // Safe default
+        bestScore = 0.3;
+    }
+    const confidence = Math.min(bestScore, 1);
+    return {
+        type: bestType,
+        confidence,
+        suggestedStrategy: intentToStrategy(bestType),
+        suggestedMaxTurns: intentToMaxTurns(bestType),
+        suggestedEffort: intentToEffort(bestType),
+    };
+}
+// ── Strategy Mapping ──────────────────────────────────────────────────
+function intentToStrategy(intent) {
+    switch (intent) {
+        case 'question': return 'brief-answer';
+        case 'task': return 'plan-and-execute';
+        case 'feedback': return 'acknowledge-and-adapt';
+        case 'casual': return 'conversational';
+        case 'followup': return 'brief-answer';
+        case 'correction': return 'acknowledge-and-adapt';
+    }
+}
+function intentToMaxTurns(intent) {
+    switch (intent) {
+        case 'question': return 8;
+        case 'task': return 15;
+        case 'feedback': return 3;
+        case 'casual': return 3;
+        case 'followup': return 8;
+        case 'correction': return 10;
+    }
+}
+function intentToEffort(intent) {
+    switch (intent) {
+        case 'question': return 'medium';
+        case 'task': return 'high';
+        case 'feedback': return 'low';
+        case 'casual': return 'low';
+        case 'followup': return 'medium';
+        case 'correction': return 'medium';
+    }
+}
+// ── Response Strategy Guidance ────────────────────────────────────────
+/**
+ * Generate system prompt guidance text based on the response strategy.
+ * Injected into the system prompt to steer the agent's response style.
+ */
+export function getStrategyGuidance(strategy) {
+    switch (strategy) {
+        case 'brief-answer':
+            return `## Response Style: Direct Answer
+Respond concisely — 1-3 sentences for simple questions, a short paragraph with key details for complex ones.
+If you know the answer, give it immediately — no preamble.
+If you need to look something up, say what you're checking and why ("Let me check memory for that — I think we discussed it last week"), then share what you found.`;
+        case 'structured-response':
+            return `## Response Style: Structured
+Use headers, bullet points, or numbered lists for clarity.
+Start with a brief summary, then provide details.
+Include a "Next Steps" or "Summary" section at the end if applicable.`;
+        case 'plan-and-execute':
+            return `## Response Style: Agentic Execution
+This is a task — work through it like a capable assistant who owns the outcome.
+
+**Assess scope first**: Before diving in, quickly assess whether this is a 2-minute task or a 20-minute job.
+- **Simple task** (one file, one API call, one edit): Just do it. No need to explain the plan.
+- **Multi-step task** (several items to process, research + action, multiple files): Tell the user what you're going to do, then use sub-agents (Agent tool) to parallelize the work. Example: "This touches 3 accounts — I'll spin up research on each in parallel and have results in a few minutes."
+- **Complex/long task**: Offer to run it in the background: "This is going to take some real work. Want me to kick it off in deep mode? I'll keep you posted as I go."
+
+**During execution**: Narrate findings and decisions, not tool calls. If something unexpected happens, explain what you're doing about it.
+**End**: Summarize what you did and suggest natural next steps.
+
+**Parallelization**: When processing multiple items (prospects, files, accounts), ALWAYS use the Agent tool to spawn sub-agents that work in parallel. Don't process 10 things one at a time when you can batch them across 3-5 sub-agents.`;
+        case 'acknowledge-and-adapt':
+            return `## Response Style: Adaptive
+The user is giving feedback or correcting you. Acknowledge it briefly and naturally.
+If it's positive feedback: a brief "glad that worked" type response. Don't be effusive.
+If it's a correction: acknowledge what was wrong, explain briefly what you understand now, then fix it or adjust. Show that you understood the correction, don't just say "sorry."`;
+        case 'conversational':
+            return `## Response Style: Casual
+Keep it natural and brief. Match the user's energy.
+No tool calls needed. Just be conversational.
+If there's relevant context from recent work or pending items, briefly mention it.`;
+    }
+}
+/**
+ * Generate a follow-up suggestion prompt suffix based on completed work.
+ *
+ * @param toolCallCount - Number of tool calls made during the query
+ * @param responseLength - Length of the response text
+ * @param hasActiveGoals - Whether there are relevant active goals
+ * @param pendingWorkItems - Number of pending items in the work queue
+ */
+export function buildFollowUpContext(opts) {
+    // Only suggest follow-ups after substantive work
+    if (opts.toolCallCount < 5 || opts.responseLength < 200)
+        return null;
+    const parts = [];
+    if (opts.hasActiveGoals) {
+        parts.push('There are active goals that may relate to this work.');
+    }
+    if (opts.pendingWorkItems > 0) {
+        parts.push(`There are ${opts.pendingWorkItems} pending work items in the queue.`);
+    }
+    if (parts.length === 0)
+        return null;
+    return `\n\n[POST_WORK_CONTEXT: ${parts.join(' ')} Consider suggesting 1-2 natural next steps as questions, if they'd be genuinely useful. Don't force it.]`;
+}
+//# sourceMappingURL=intent-classifier.js.map

package/dist/agent/link-extractor.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Clementine TypeScript — Proactive link understanding.
+ *
+ * Extracts URLs from user messages, fetches their content, and returns
+ * readable text so the agent has context without needing a tool call.
+ */
+export interface LinkContext {
+    url: string;
+    title: string;
+    content: string;
+    error?: string;
+}
+/**
+ * Extract and fetch URLs found in the given text.
+ * Returns content for up to LINK_EXTRACT_MAX_URLS unique URLs.
+ * Never throws — errors are captured per-URL.
+ */
+export declare function extractLinks(text: string): Promise<LinkContext[]>;
+//# sourceMappingURL=link-extractor.d.ts.map

package/dist/agent/link-extractor.js

@@ -0,0 +1,90 @@
+/**
+ * Clementine TypeScript — Proactive link understanding.
+ *
+ * Extracts URLs from user messages, fetches their content, and returns
+ * readable text so the agent has context without needing a tool call.
+ */
+import { LINK_EXTRACT_MAX_URLS, LINK_EXTRACT_MAX_CHARS } from '../config.js';
+import { PRIVATE_URL_PATTERNS } from './hooks.js';
+// Match https:// URLs, skip common image/video/audio extensions
+const URL_RE = /https?:\/\/[^\s<>"')\]]+/gi;
+const SKIP_EXT_RE = /\.(png|jpg|jpeg|gif|webp|svg|ico|mp4|mp3|wav|webm|avi|mov|pdf)(\?[^\s]*)?$/i;
+/** Strip HTML tags of a given type (including content). */
+function stripTags(html, ...tags) {
+    let result = html;
+    for (const tag of tags) {
+        result = result.replace(new RegExp(`<${tag}[\\s>][\\s\\S]*?</${tag}>`, 'gi'), '');
+    }
+    return result;
+}
+/** Extract the <title> text from HTML. */
+function extractTitle(html) {
+    const match = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(html);
+    return match ? match[1].replace(/\s+/g, ' ').trim() : '';
+}
+/** Check if a URL targets a private/internal network. */
+function isPrivateUrl(url) {
+    return PRIVATE_URL_PATTERNS.some(p => p.test(url));
+}
+async function fetchLink(url) {
+    if (isPrivateUrl(url)) {
+        return { url, title: '', content: '', error: 'private/internal URL blocked' };
+    }
+    try {
+        const response = await fetch(url, {
+            headers: { 'User-Agent': 'Clementine/1.0' },
+            signal: AbortSignal.timeout(10_000),
+            redirect: 'follow',
+        });
+        if (!response.ok) {
+            return { url, title: '', content: '', error: `HTTP ${response.status}` };
+        }
+        const contentType = response.headers.get('content-type') ?? '';
+        if (!contentType.includes('text/html') && !contentType.includes('text/plain')) {
+            return { url, title: '', content: '', error: `unsupported content-type: ${contentType}` };
+        }
+        const html = await response.text();
+        const title = extractTitle(html);
+        // Strip non-content tags, then all remaining HTML
+        let text = stripTags(html, 'script', 'style', 'nav', 'footer', 'header', 'aside');
+        text = text.replace(/<[^>]+>/g, ' ');
+        // Collapse whitespace
+        text = text.replace(/[ \t]+/g, ' ').replace(/\n{3,}/g, '\n\n').trim();
+        // Truncate
+        if (text.length > LINK_EXTRACT_MAX_CHARS) {
+            text = text.slice(0, LINK_EXTRACT_MAX_CHARS) + '…';
+        }
+        return { url, title, content: text };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { url, title: '', content: '', error: message };
+    }
+}
+/**
+ * Extract and fetch URLs found in the given text.
+ * Returns content for up to LINK_EXTRACT_MAX_URLS unique URLs.
+ * Never throws — errors are captured per-URL.
+ */
+export async function extractLinks(text) {
+    const matches = text.match(URL_RE);
+    if (!matches)
+        return [];
+    // Deduplicate and filter
+    const seen = new Set();
+    const urls = [];
+    for (const raw of matches) {
+        // Strip trailing punctuation that's likely not part of the URL
+        const url = raw.replace(/[.,;:!?)]+$/, '');
+        if (seen.has(url) || SKIP_EXT_RE.test(url))
+            continue;
+        seen.add(url);
+        urls.push(url);
+        if (urls.length >= LINK_EXTRACT_MAX_URLS)
+            break;
+    }
+    if (!urls.length)
+        return [];
+    return Promise.all(urls.map(fetchLink));
+}
+//# sourceMappingURL=link-extractor.js.map

package/dist/agent/mcp-bridge.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Clementine TypeScript — MCP Server Bridge.
+ *
+ * Discovers external MCP servers from Claude Desktop config, Claude Code
+ * settings, and user-managed config. Merges them into the SDK mcpServers
+ * option alongside Clementine's own MCP server.
+ */
+import type { ManagedMcpServer } from '../types.js';
+/** Discover all available MCP servers from Claude Desktop, Claude Code, and user config. */
+export declare function discoverMcpServers(): ManagedMcpServer[];
+/** Get enabled MCP servers as SDK-compatible config, filtered by allowed list. */
+export declare function getMcpServersForAgent(allowedMcpServers?: string[]): Record<string, any>;
+export declare function loadUserMcpServers(): Record<string, any>;
+export declare function saveUserMcpServers(servers: Record<string, any>): void;
+export declare function upsertMcpServer(name: string, config: Partial<ManagedMcpServer>): void;
+export declare function removeMcpServer(name: string): void;
+export interface PermissionStatus {
+    server: string;
+    resource: string;
+    granted: boolean;
+    settingsLabel: string;
+}
+/** Check macOS permissions for extensions that need them. Returns only servers with permission issues. */
+export declare function checkPermissions(): PermissionStatus[];
+/** Run permission checks on startup and log warnings for any issues. */
+export declare function checkPermissionsOnStartup(): void;
+/** Get a user-friendly error message when a tool fails due to permissions. */
+export declare function getPermissionErrorMessage(serverName: string): string | null;
+export interface ClaudeIntegration {
+    /** Integration name, e.g. "Microsoft_365" */
+    name: string;
+    /** Human-friendly label */
+    label: string;
+    /** Tools discovered for this integration */
+    tools: string[];
+    /** When first seen */
+    firstSeen: string;
+    /** When last used */
+    lastUsed: string;
+    /** Whether the user has it connected (true if we've seen it work) */
+    connected: boolean;
+}
+/**
+ * Check if a tool name is a Claude Desktop integration tool.
+ * Format: mcp__claude_ai_<IntegrationName>__<tool_name>
+ */
+export declare function isClaudeDesktopTool(toolName: string): boolean;
+/** Load persisted integrations from disk. */
+export declare function loadClaudeIntegrations(): Record<string, ClaudeIntegration>;
+/**
+ * Record a Claude Desktop integration tool use.
+ * Call this whenever a mcp__claude_ai_* tool is seen in a tool_use block.
+ */
+export declare function recordClaudeIntegrationUse(toolName: string): void;
+/** Get all discovered Claude Desktop integrations as a list. */
+export declare function getClaudeIntegrations(): ClaudeIntegration[];
+/**
+ * Bootstrap integrations from the audit log.
+ * Call once on startup to seed the integrations file from historical data.
+ */
+export declare function bootstrapClaudeIntegrationsFromAuditLog(auditLogPath: string): void;
+//# sourceMappingURL=mcp-bridge.d.ts.map