clementine-agent 1.12.4 → 1.13.0

package/dist/agent/assistant.js

@@ -1566,24 +1566,30 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
             }
             catch { /* non-fatal */ }
         }
-        // Composio tool preference — when a Composio toolkit has an active
-        // connection AND a Claude Desktop equivalent exists, the agent tends to
-        // default to the Claude Desktop tool (mcp__claude_ai_*) because those
-        // names appear in Claude's training and feel familiar. The Composio
-        // versions (mcp__<slug>__*) usually have broader scope (full inbox vs.
-        // limited preview, write access vs. read-only, etc.), so we explicitly
-        // steer toward them when present. Only emitted when at least one
-        // connection is live — otherwise it's noise.
-        if (composioConnectedSlugs.length > 0) {
-            const slugs = composioConnectedSlugs.slice().sort().join(', ');
-            volatileParts.push(`## Composio Tools (Preferred)\n\n` +
-                `Connected Composio toolkits: ${slugs}.\n\n` +
-                `**Always prefer the Composio tool over the Claude Desktop equivalent** when both are available for the same service:\n` +
-                `- For Outlook/email: use \`mcp__outlook__*\` (NOT \`mcp__claude_ai_Microsoft_365__*\`)\n` +
-                `- For Gmail: use \`mcp__gmail__*\` (NOT \`mcp__claude_ai_Gmail__*\`)\n` +
-                `- For Google Drive: use \`mcp__googledrive__*\` (NOT \`mcp__claude_ai_Google_Drive__*\`)\n` +
-                `- For Google Calendar/Sheets/Docs/Slack/Notion/etc.: same pattern — Composio first.\n\n` +
-                `Why: Composio tools have broader scope (full inbox/file access, write capabilities) and are tied to OAuth tokens you control directly. Use Claude Desktop tools only as fallback when no Composio equivalent is connected.`);
+        // Tool source preferences — only emit a prompt instruction when:
+        //   1. A service has BOTH Composio AND Claude Desktop sources connected
+        //      (a real conflict the agent could disambiguate the wrong way), AND
+        //   2. The user has explicitly picked a preference for that service.
+        //
+        // No conflict → 0 chars. Conflict but no user preference → silent
+        // default (Composio), still 0 chars. Only configured preferences cost
+        // tokens, and only the affected services are listed (~50 chars each).
+        // Compare to the previous hardcoded block which was ~700 chars on
+        // every turn regardless.
+        if (!isAutonomous) {
+            try {
+                const { loadToolPreferences, computeAvailability, buildPromptInstruction } = require('../integrations/tool-preferences.js');
+                const { loadClaudeIntegrations } = require('./mcp-bridge.js');
+                const composioSet = new Set(composioConnectedSlugs);
+                const cdIntegrations = loadClaudeIntegrations();
+                const cdActive = new Set(Object.values(cdIntegrations).filter(i => i.connected).map(i => i.name));
+                const prefs = loadToolPreferences();
+                const availability = computeAvailability(composioSet, cdActive, prefs.preferences);
+                const instruction = buildPromptInstruction(availability, prefs.preferences);
+                if (instruction)
+                    volatileParts.push(instruction);
+            }
+            catch { /* non-fatal — agent runs without the preference rule */ }
         }
         // Conversational context — same signals the insight engine surfaces
         // proactively (Phase 10), but injected directly into the agent's prompt

package/dist/cli/dashboard.js

@@ -4570,6 +4570,66 @@ If the tool returns nothing or errors, return an empty array \`[]\`.`,
             res.status(500).json({ error: String(err) });
         }
     });
+    // ── Tool source preferences ─────────────────────────────────
+    // When a service is reachable from multiple MCP sources (Composio + Claude
+    // Desktop), let the user pick which one. See src/integrations/tool-preferences.ts
+    // for design notes.
+    app.get('/api/tool-preferences', async (_req, res) => {
+        try {
+            const tp = await import('../integrations/tool-preferences.js');
+            const composio = await import('../integrations/composio/client.js');
+            const mcp = await import('../agent/mcp-bridge.js');
+            const prefs = tp.loadToolPreferences();
+            const composioSlugs = composio.isComposioEnabled()
+                ? new Set((await composio.listConnectedToolkits()).filter(c => c.status === 'ACTIVE').map(c => c.slug))
+                : new Set();
+            const cdActive = new Set(Object.values(mcp.loadClaudeIntegrations()).filter(i => i.connected).map(i => i.name));
+            const availability = tp.computeAvailability(composioSlugs, cdActive, prefs.preferences);
+            res.json({
+                preferences: prefs.preferences,
+                services: availability.map(a => ({
+                    id: a.service.id,
+                    label: a.service.label,
+                    composio: a.service.composioSlug
+                        ? { slug: a.service.composioSlug, available: a.composioAvailable }
+                        : null,
+                    claudeDesktop: a.service.claudeDesktopName
+                        ? { name: a.service.claudeDesktopName, available: a.claudeDesktopAvailable }
+                        : null,
+                    hasConflict: a.hasConflict,
+                    effective: a.effective,
+                })),
+            });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err) });
+        }
+    });
+    app.put('/api/tool-preferences', async (req, res) => {
+        try {
+            const body = req.body;
+            const incoming = body?.preferences;
+            if (!incoming || typeof incoming !== 'object') {
+                res.status(400).json({ error: 'preferences (object) required in body' });
+                return;
+            }
+            const tp = await import('../integrations/tool-preferences.js');
+            const valid = {};
+            const knownIds = new Set(tp.KNOWN_SERVICES.map(s => s.id));
+            for (const [id, source] of Object.entries(incoming)) {
+                if (!knownIds.has(id))
+                    continue;
+                if (source === 'composio' || source === 'claude-desktop' || source === 'off') {
+                    valid[id] = source;
+                }
+            }
+            tp.saveToolPreferences({ preferences: valid });
+            res.json({ ok: true, preferences: valid });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err) });
+        }
+    });
     // ── CRON CRUD routes ──────────────────────────────────────────
     app.get('/api/projects', (_req, res) => {
         try {
@@ -14546,6 +14606,15 @@ if('serviceWorker' in navigator){navigator.serviceWorker.getRegistrations().then
               <div class="empty-state">Loading...</div>
             </div>
           </div>
+          <div class="card" style="margin-bottom:20px">
+            <div class="card-header" style="display:flex;align-items:center;justify-content:space-between">
+              <span>Tool Source Preferences</span>
+              <span style="font-size:11px;color:var(--text-muted)">Pick which source the agent uses when a service has multiple</span>
+            </div>
+            <div class="card-body" style="padding:16px" id="tool-preferences">
+              <div class="empty-state">Loading...</div>
+            </div>
+          </div>
           <div class="card" style="margin-bottom:20px">
             <div class="card-header" style="display:flex;align-items:center;justify-content:space-between">
               <span>Claude Desktop Integrations</span>
@@ -15869,7 +15938,7 @@ function switchTab(group, tab) {
   }
   if (group === 'settings') {
     if (tab === 'general' && typeof refreshSettings === 'function') refreshSettings();
-    if (tab === 'integrations') { refreshSalesforce(); refreshComposioConnections(); }
+    if (tab === 'integrations') { refreshSalesforce(); refreshComposioConnections(); refreshToolPreferences(); }
     if (tab === 'remote') refreshRemoteAccess();
     if (tab === 'security') refreshAuthSessions();
     if (tab === 'projects' && typeof refreshProjects === 'function') refreshProjects();
@@ -25940,6 +26009,89 @@ function renderComposioCatalog(query) {
   setTimeout(function() { var s = document.getElementById('composio-search'); if (s) { s.focus(); s.setSelectionRange(s.value.length, s.value.length); } }, 0);
 }
 
+async function refreshToolPreferences() {
+  var container = document.getElementById('tool-preferences');
+  if (!container) return;
+  try {
+    var r = await apiFetch('/api/tool-preferences');
+    var d = await r.json();
+    var services = d.services || [];
+    var prefs = d.preferences || {};
+    // Seed the click-handler's working copy with what's currently saved,
+    // so single-click edits merge instead of replacing the whole object.
+    window._toolPrefs = Object.assign({}, prefs);
+
+    var conflicts = services.filter(function(s) { return s.hasConflict; });
+    var single = services.filter(function(s) { return !s.hasConflict && s.effective; });
+    var none = services.filter(function(s) { return !s.effective; });
+
+    var html = '';
+    if (conflicts.length === 0 && single.length === 0) {
+      html += '<div style="font-size:13px;color:var(--text-muted);line-height:1.6">No services connected yet from either Composio or Claude Desktop. Once you connect something, it\\'ll appear here.</div>';
+      container.innerHTML = html;
+      return;
+    }
+
+    if (conflicts.length > 0) {
+      html += '<div style="font-size:12px;color:var(--text-secondary);margin-bottom:12px;line-height:1.5">'
+        + '<strong>' + conflicts.length + ' service' + (conflicts.length === 1 ? ' has' : 's have') + ' multiple sources connected.</strong> '
+        + 'Pick which one the agent should use. Default (no selection) = Composio.'
+        + '</div>';
+      html += '<div style="display:flex;flex-direction:column;gap:10px;margin-bottom:14px">';
+      conflicts.forEach(function(s) {
+        var picked = prefs[s.id] || 'composio';
+        html += '<div style="display:flex;align-items:center;gap:12px;padding:10px 12px;border:1px solid var(--border);border-radius:6px;background:var(--bg-secondary)">';
+        html += '<div style="flex:1;font-size:13px;font-weight:500">' + esc(s.label) + '</div>';
+        html += '<div style="display:flex;gap:6px">';
+        ['composio','claude-desktop','off'].forEach(function(opt) {
+          var selected = picked === opt;
+          var label = opt === 'composio' ? 'Composio' : (opt === 'claude-desktop' ? 'Claude Desktop' : 'Off');
+          html += '<button onclick="setToolPreference(\\'' + esc(s.id) + '\\',\\'' + opt + '\\')" '
+            + 'style="padding:4px 10px;font-size:11px;border-radius:4px;cursor:pointer;border:1px solid '
+            + (selected ? 'var(--accent)' : 'var(--border)') + ';'
+            + 'background:' + (selected ? 'var(--accent)' : 'transparent') + ';'
+            + 'color:' + (selected ? '#fff' : 'var(--text-secondary)') + '">' + esc(label) + '</button>';
+        });
+        html += '</div>';
+        html += '</div>';
+      });
+      html += '</div>';
+    }
+
+    if (single.length > 0) {
+      html += '<div style="font-size:11px;color:var(--text-muted);margin-bottom:6px;text-transform:uppercase;letter-spacing:0.5px">Single source — using automatically</div>';
+      html += '<div style="display:flex;flex-wrap:wrap;gap:6px;margin-bottom:8px">';
+      single.forEach(function(s) {
+        var srcLabel = s.effective === 'composio' ? 'Composio' : (s.effective === 'claude-desktop' ? 'Claude Desktop' : 'Off');
+        html += '<span style="display:inline-flex;align-items:center;gap:6px;padding:4px 10px;font-size:11px;background:var(--bg-secondary);border:1px solid var(--border);border-radius:12px">'
+          + esc(s.label) + ' <span style="color:var(--text-muted);font-size:10px">via ' + esc(srcLabel) + '</span>'
+          + '</span>';
+      });
+      html += '</div>';
+    }
+
+    container.innerHTML = html;
+  } catch (e) {
+    container.innerHTML = '<div class="empty-state" style="color:var(--red);padding:8px">Failed to load tool preferences: ' + esc(String(e)) + '</div>';
+  }
+}
+
+async function setToolPreference(serviceId, source) {
+  try {
+    // Get current prefs, merge in the change, send back. Server validates
+    // each entry, so we don't need to pre-filter unknown IDs.
+    var current = window._toolPrefs || {};
+    current[serviceId] = source;
+    window._toolPrefs = current;
+    await apiFetch('/api/tool-preferences', {
+      method: 'PUT',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ preferences: current }),
+    });
+    refreshToolPreferences();
+  } catch (e) { toast('Failed to save preference: ' + e, 'error'); }
+}
+
 async function saveComposioApiKey() {
   var input = document.getElementById('composio-key-input');
   var status = document.getElementById('composio-key-status');

package/dist/integrations/tool-preferences.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Tool source preferences — when a service has tools available from
+ * multiple MCP sources (e.g., Composio's outlook AND Claude Desktop's
+ * Microsoft 365), let the user pick which one the agent should use.
+ *
+ * Storage: ~/.clementine/tool-preferences.json
+ *
+ * Design decisions:
+ * - Only services with multiple available sources show up. No noise.
+ * - When a conflict exists but the user hasn't picked, silently default
+ *   to Composio (broader scope, OAuth tokens you control).
+ * - When no conflict exists (one or zero sources), no preference is
+ *   needed and no system-prompt clutter is emitted.
+ * - The mapping between Composio slugs and Claude Desktop integration
+ *   names lives here (small, bounded — only services where Claude
+ *   Desktop has a connector).
+ */
+export type ToolSource = 'composio' | 'claude-desktop' | 'off';
+/**
+ * Canonical service registry. Each entry maps a stable service ID to its
+ * Composio toolkit slug (if any) and Claude Desktop integration name (if
+ * any). Adding a new service = one line here.
+ */
+export interface ServiceDefinition {
+    /** Stable canonical ID — what the user sees and what we key prefs by. */
+    id: string;
+    /** Friendly name for the dashboard. */
+    label: string;
+    /** Composio toolkit slug, if Composio offers this service. */
+    composioSlug?: string;
+    /** Claude Desktop integration name (matches mcp__claude_ai_<name>__*). */
+    claudeDesktopName?: string;
+}
+export declare const KNOWN_SERVICES: ServiceDefinition[];
+export interface ToolPreferences {
+    version: 1;
+    /** id → chosen source. Missing = use silent default (composio when conflict). */
+    preferences: Record<string, ToolSource>;
+    updatedAt?: string;
+}
+export declare function loadToolPreferences(): ToolPreferences;
+export declare function saveToolPreferences(prefs: Omit<ToolPreferences, 'version' | 'updatedAt'>): void;
+export interface ServiceAvailability {
+    service: ServiceDefinition;
+    composioAvailable: boolean;
+    claudeDesktopAvailable: boolean;
+    /** True when both sources are connected — preference matters. */
+    hasConflict: boolean;
+    /** Effective source: user pref if set, else "composio" when conflict, else
+     *  whichever single source is connected, else null. */
+    effective: ToolSource | null;
+}
+/**
+ * Walk every known service and compute availability + effective preference.
+ * Pure function — caller passes in what's connected.
+ */
+export declare function computeAvailability(composioConnectedSlugs: Set<string>, claudeDesktopActiveNames: Set<string>, preferences: Record<string, ToolSource>): ServiceAvailability[];
+/**
+ * Build the system-prompt instruction listing which tool source the agent
+ * should use for each service. Only includes services where:
+ *   - There IS a conflict (both sources connected), AND
+ *   - The user has explicitly picked a non-default preference, OR
+ *   - The user picked 'off' (so we tell the agent NOT to use it)
+ *
+ * Returns empty string when no instruction is needed — that's the goal:
+ * silent default, zero prompt overhead, until the user actually configures.
+ */
+export declare function buildPromptInstruction(availability: ServiceAvailability[], preferences: Record<string, ToolSource>): string;
+//# sourceMappingURL=tool-preferences.d.ts.map

package/dist/integrations/tool-preferences.js

@@ -0,0 +1,114 @@
+/**
+ * Tool source preferences — when a service has tools available from
+ * multiple MCP sources (e.g., Composio's outlook AND Claude Desktop's
+ * Microsoft 365), let the user pick which one the agent should use.
+ *
+ * Storage: ~/.clementine/tool-preferences.json
+ *
+ * Design decisions:
+ * - Only services with multiple available sources show up. No noise.
+ * - When a conflict exists but the user hasn't picked, silently default
+ *   to Composio (broader scope, OAuth tokens you control).
+ * - When no conflict exists (one or zero sources), no preference is
+ *   needed and no system-prompt clutter is emitted.
+ * - The mapping between Composio slugs and Claude Desktop integration
+ *   names lives here (small, bounded — only services where Claude
+ *   Desktop has a connector).
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { BASE_DIR } from '../config.js';
+const PREFS_FILE = path.join(BASE_DIR, 'tool-preferences.json');
+export const KNOWN_SERVICES = [
+    { id: 'outlook', label: 'Outlook / Microsoft 365', composioSlug: 'outlook', claudeDesktopName: 'Microsoft_365' },
+    { id: 'gmail', label: 'Gmail', composioSlug: 'gmail', claudeDesktopName: 'Gmail' },
+    { id: 'googledrive', label: 'Google Drive', composioSlug: 'googledrive', claudeDesktopName: 'Google_Drive' },
+    { id: 'googlecalendar', label: 'Google Calendar', composioSlug: 'googlecalendar', claudeDesktopName: 'Google_Calendar' },
+    { id: 'googlesheets', label: 'Google Sheets', composioSlug: 'googlesheets', claudeDesktopName: 'Google_Workspace' },
+    { id: 'slack', label: 'Slack', composioSlug: 'slack', claudeDesktopName: 'Slack' },
+    { id: 'notion', label: 'Notion', composioSlug: 'notion', claudeDesktopName: 'Notion' },
+    { id: 'github', label: 'GitHub', composioSlug: 'github', claudeDesktopName: 'GitHub' },
+    { id: 'linear', label: 'Linear', composioSlug: 'linear', claudeDesktopName: 'Linear' },
+];
+const EMPTY_PREFS = { version: 1, preferences: {} };
+export function loadToolPreferences() {
+    try {
+        if (!existsSync(PREFS_FILE))
+            return { ...EMPTY_PREFS, preferences: {} };
+        const data = JSON.parse(readFileSync(PREFS_FILE, 'utf-8'));
+        if (data?.version !== 1 || typeof data.preferences !== 'object') {
+            return { ...EMPTY_PREFS, preferences: {} };
+        }
+        return data;
+    }
+    catch {
+        return { ...EMPTY_PREFS, preferences: {} };
+    }
+}
+export function saveToolPreferences(prefs) {
+    const out = {
+        version: 1,
+        preferences: prefs.preferences,
+        updatedAt: new Date().toISOString(),
+    };
+    writeFileSync(PREFS_FILE, JSON.stringify(out, null, 2), { mode: 0o600 });
+}
+/**
+ * Walk every known service and compute availability + effective preference.
+ * Pure function — caller passes in what's connected.
+ */
+export function computeAvailability(composioConnectedSlugs, claudeDesktopActiveNames, preferences) {
+    return KNOWN_SERVICES.map(service => {
+        const composioAvailable = !!service.composioSlug && composioConnectedSlugs.has(service.composioSlug);
+        const claudeDesktopAvailable = !!service.claudeDesktopName && claudeDesktopActiveNames.has(service.claudeDesktopName);
+        const hasConflict = composioAvailable && claudeDesktopAvailable;
+        let effective = null;
+        const userPref = preferences[service.id];
+        if (userPref === 'off') {
+            effective = 'off';
+        }
+        else if (hasConflict) {
+            effective = userPref ?? 'composio'; // default to composio when conflict + no pref
+        }
+        else if (composioAvailable) {
+            effective = 'composio';
+        }
+        else if (claudeDesktopAvailable) {
+            effective = 'claude-desktop';
+        }
+        return { service, composioAvailable, claudeDesktopAvailable, hasConflict, effective };
+    });
+}
+/**
+ * Build the system-prompt instruction listing which tool source the agent
+ * should use for each service. Only includes services where:
+ *   - There IS a conflict (both sources connected), AND
+ *   - The user has explicitly picked a non-default preference, OR
+ *   - The user picked 'off' (so we tell the agent NOT to use it)
+ *
+ * Returns empty string when no instruction is needed — that's the goal:
+ * silent default, zero prompt overhead, until the user actually configures.
+ */
+export function buildPromptInstruction(availability, preferences) {
+    const lines = [];
+    for (const a of availability) {
+        if (!a.hasConflict)
+            continue;
+        const userPref = preferences[a.service.id];
+        if (!userPref)
+            continue; // no explicit pref → silent default, no prompt cost
+        if (userPref === 'off') {
+            lines.push(`- ${a.service.label}: do NOT use any of its tools (user disabled)`);
+        }
+        else if (userPref === 'composio' && a.service.composioSlug) {
+            lines.push(`- ${a.service.label}: use \`mcp__${a.service.composioSlug}__*\` (NOT \`mcp__claude_ai_${a.service.claudeDesktopName}__*\`)`);
+        }
+        else if (userPref === 'claude-desktop' && a.service.claudeDesktopName) {
+            lines.push(`- ${a.service.label}: use \`mcp__claude_ai_${a.service.claudeDesktopName}__*\` (NOT \`mcp__${a.service.composioSlug}__*\`)`);
+        }
+    }
+    if (lines.length === 0)
+        return '';
+    return `## Tool Source Preferences\n\n${lines.join('\n')}`;
+}
+//# sourceMappingURL=tool-preferences.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.12.4",
+  "version": "1.13.0",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",