clementine-agent 1.9.0 → 1.10.0

package/dist/agent/assistant.js

@@ -379,13 +379,20 @@ const AUTO_MEMORY_PROMPT = `You are a memory extraction agent. Your ONLY job is
 
 {current_memory}
 
+## Current User Model (already known — DO NOT re-extract these)
+
+{current_user_model}
+
 ## Where to save what (memory routing):
 
 **Always-in-context core memory** (use the user_model tool — these stay top-of-mind in every future session):
 - **Lasting facts about ${OWNER}** (role, location, identifiers, durable preferences, communication style) → user_model(action="append", slot="user_facts", content=...)
 - **Active goals/intents** (what ${OWNER} is trying to accomplish right now) → user_model(action="append", slot="goals", content=...)
 - **Key people/projects** (recurring relationships) → user_model(action="append", slot="relationships", content=...)
-- Use action="replace" instead of "append" if you're updating an existing fact rather than adding a new one. Slots are capped at 2000 chars — older content rolls off on append.
+- **DEFAULT to action="append"** — it adds the new fact alongside what's already there.
+- Only use action="replace" when CORRECTING an existing fact, and you MUST include the FULL slot content (everything from "Current User Model" above, with the correction applied). \`replace\` overwrites the entire slot — passing only the new fact wipes everything else.
+- Never use action="clear" from this extractor. Clearing is a deliberate user action, not a memory-extraction outcome.
+- Slots are capped at 2000 chars — older content rolls off on append automatically.
 
 **Vault notes** (use memory_write/note_create — durable but retrieved on demand):
 - **People mentioned** — names, relationships, context → create or update person notes in 02-People/
@@ -1632,12 +1639,13 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
         };
     }
     // ── Build SDK Options ─────────────────────────────────────────────
-    buildOptions(opts = {}) {
+    async buildOptions(opts = {}) {
         const { isHeartbeat = false, cronTier = null, maxTurns = null, model = null, enableTeams = true, retrievalContext = '', profile = null, sessionKey = null, streaming = false, isPlanStep = false, isUnleashed = false, sourceOverride, disableAllTools = false, verboseLevel, abortController, effort, maxBudgetUsd, thinking, outputFormat, stallGuard, intentClassification, } = opts;
         let allowedTools = [
             'Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep',
             'WebSearch', 'WebFetch',
             mcpTool('working_memory'),
+            mcpTool('user_model'),
             mcpTool('memory_read'),
             mcpTool('memory_write'),
             mcpTool('memory_search'),
@@ -1920,6 +1928,22 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
             }
         }
         catch { /* non-fatal — run with just Clementine's own server */ }
+        // Composio toolkits — each connected toolkit becomes an in-process MCP
+        // server (mcp__gmail__*, mcp__slack__*, …). Profile-level allowlist
+        // (profile.allowedComposioToolkits) constrains which toolkits this agent
+        // sees; omit it to surface every active connection.
+        let composioMcpServers = {};
+        if (!disableAllTools && !isPlanStep) {
+            try {
+                const { buildComposioMcpServers } = await import('../integrations/composio/mcp-bridge.js');
+                const allowList = profile?.allowedComposioToolkits;
+                composioMcpServers = await buildComposioMcpServers(allowList);
+            }
+            catch (err) {
+                // Composio is purely additive — never block the agent if it fails.
+                logger.debug({ err }, 'Composio MCP servers unavailable');
+            }
+        }
         // Permission mode: always 'bypassPermissions' — this is a daemon/harness with no interactive
         // terminal, so 'auto' mode (which requires plan support + human approval) doesn't apply.
         const effectivePermissionMode = 'bypassPermissions';
@@ -1965,6 +1989,7 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
                     },
                 },
                 ...externalMcpServers,
+                ...composioMcpServers,
             },
             ...(abortController ? { abortController } : {}),
             maxTurns: effectiveMaxTurns,
@@ -2594,7 +2619,7 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
         let contradictionRetried = false;
         try {
             for (let attempt = 0; attempt <= PersonalAssistant.RATE_LIMIT_MAX_RETRIES; attempt++) {
-                const sdkOptions = this.buildOptions({ model, maxTurns: maxTurnsOverride ?? null, retrievalContext, profile, sessionKey, streaming: !!onText, verboseLevel, abortController, stallGuard, intentClassification, effort: intentClassification?.suggestedEffort });
+                const sdkOptions = await this.buildOptions({ model, maxTurns: maxTurnsOverride ?? null, retrievalContext, profile, sessionKey, streaming: !!onText, verboseLevel, abortController, stallGuard, intentClassification, effort: intentClassification?.suggestedEffort });
                 // If a project matched, switch cwd so the agent gets its tools/CLAUDE.md
                 if (matchedProject) {
                     sdkOptions.cwd = matchedProject.path;
@@ -3683,10 +3708,23 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
                     // Non-fatal — proceed without corrections
                 }
             }
+            // Render current user_model state so the extractor can: (a) skip
+            // re-extracting facts already there, (b) safely use action="replace"
+            // by passing the full slot content with a correction applied. Scoped
+            // to the active agent — Clementine sees global slots, hired agents
+            // see their own per-agent slots.
+            let currentUserModel = '(empty — no slots populated yet)';
+            try {
+                const rendered = this.memoryStore?.renderUserModel?.(profile?.slug ?? null);
+                if (rendered && rendered.trim())
+                    currentUserModel = rendered;
+            }
+            catch { /* non-fatal */ }
             const memPrompt = AUTO_MEMORY_PROMPT
                 .replace('{user_message}', userMessage)
                 .replace('{assistant_response}', truncatedResponse)
                 .replace('{current_memory}', currentMemory || '(empty — no existing memory yet)')
+                .replace('{current_user_model}', currentUserModel)
                 .replace('{recent_corrections}', correctionsText);
             const userMessageSnippet = userMessage.slice(0, 500);
             const stream = query({
@@ -3706,6 +3744,13 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
                         mcpTool('task_add'),
                         mcpTool('note_take'),
                         mcpTool('memory_read'),
+                        // Auto-extractor needs user_model to populate the always-in-context
+                        // core slots (user_facts, goals, relationships, agent_persona).
+                        // The MCP server boots with CLEMENTINE_TEAM_AGENT=<slug>, so writes
+                        // are scoped to the active agent automatically — Clementine's
+                        // sessions populate global slots, hired-agent sessions populate
+                        // that agent's per-agent slots.
+                        mcpTool('user_model'),
                     ],
                     mcpServers: {
                         [TOOLS_SERVER]: {
@@ -3823,7 +3868,7 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
     // ── Heartbeat / Cron ──────────────────────────────────────────────
     async heartbeat(standingInstructions, changesSummary = '', timeContext = '', dedupContext = '', profile) {
         setInteractionSource('autonomous');
-        const sdkOptions = this.buildOptions({
+        const sdkOptions = await this.buildOptions({
             isHeartbeat: true,
             enableTeams: false,
             model: MODELS.haiku,
@@ -3893,7 +3938,7 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
         // Don't mutate the global — pass source through the closure instead
         // Per-step stall guard so concurrent steps don't cross-contaminate
         const stepGuard = new StallGuard();
-        const sdkOptions = this.buildOptions({
+        const sdkOptions = await this.buildOptions({
             isHeartbeat: false,
             cronTier: tier,
             maxTurns,
@@ -3958,7 +4003,7 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
         // not chat text — pass mode='cron' so high_effort_low_output guard is
         // disabled. Loop detection and circular-reasoning checks stay active.
         const cronGuard = new StallGuard('cron');
-        const sdkOptions = this.buildOptions({
+        const sdkOptions = await this.buildOptions({
             isHeartbeat: true,
             cronTier: tier,
             maxTurns: maxTurns ?? (tier >= 2 ? 30 : 15),
@@ -4445,7 +4490,7 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
             _setActiveQueryContext({ job: jobName, source: 'unleashed', agentSlug });
             // Unleashed phases run side-effect-heavy work; same logic as cron mode.
             const phaseGuard = new StallGuard('unleashed');
-            const sdkOptions = this.buildOptions({
+            const sdkOptions = await this.buildOptions({
                 isHeartbeat: true,
                 cronTier: tier,
                 maxTurns: turnsPerPhase,
@@ -4802,7 +4847,7 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
             logger.info({ taskName, phase }, `Team task: starting phase ${phase}`);
             setInteractionSource('autonomous');
             const teamGuard = new StallGuard();
-            const sdkOptions = this.buildOptions({
+            const sdkOptions = await this.buildOptions({
                 isHeartbeat: true,
                 cronTier: 2, // Give full tool access (Bash, Write, Edit)
                 maxTurns: turnsPerPhase,

package/dist/cli/dashboard.js

@@ -4386,6 +4386,132 @@ If the tool returns nothing or errors, return an empty array \`[]\`.`,
             res.status(500).json({ error: String(err) });
         }
     });
+    // ── Composio (1000+ third-party services via OAuth broker) ────
+    app.get('/api/composio/status', (_req, res) => {
+        res.json({ enabled: Boolean(process.env.COMPOSIO_API_KEY) });
+    });
+    app.get('/api/composio/toolkits', async (_req, res) => {
+        try {
+            if (!process.env.COMPOSIO_API_KEY) {
+                res.json({ enabled: false, toolkits: [] });
+                return;
+            }
+            const c = await import('../integrations/composio/client.js');
+            const [connected, configured, meta] = await Promise.all([
+                c.listConnectedToolkits(),
+                c.listToolkitSlugsWithAuthConfig(),
+                c.listToolkitMeta(),
+            ]);
+            const connectionsBySlug = new Map();
+            for (const conn of connected) {
+                const arr = connectionsBySlug.get(conn.slug) ?? [];
+                arr.push(conn);
+                connectionsBySlug.set(conn.slug, arr);
+            }
+            for (const arr of connectionsBySlug.values()) {
+                arr.sort((a, b) => (a.createdAt ?? '').localeCompare(b.createdAt ?? ''));
+            }
+            const toView = (conn) => ({
+                id: conn.connectionId,
+                status: conn.status,
+                alias: conn.alias ?? null,
+                accountLabel: conn.accountLabel ?? null,
+                accountEmail: conn.accountEmail ?? null,
+                accountName: conn.accountName ?? null,
+                accountAvatarUrl: conn.accountAvatarUrl ?? null,
+                createdAt: conn.createdAt ?? null,
+            });
+            const curated = c.CURATED_TOOLKITS.map(t => {
+                const m = meta.get(t.slug);
+                const conns = connectionsBySlug.get(t.slug) ?? [];
+                return {
+                    slug: t.slug,
+                    displayName: t.displayName,
+                    authMode: t.authMode,
+                    hasAuthConfig: configured.has(t.slug),
+                    logoUrl: m?.logo ?? null,
+                    description: m?.description ?? null,
+                    toolCount: m?.toolsCount ?? null,
+                    connections: conns.map(toView),
+                };
+            });
+            const extras = [...connectionsBySlug.entries()]
+                .filter(([slug]) => !c.CURATED_TOOLKITS.some(t => t.slug === slug))
+                .map(([slug, conns]) => {
+                const m = meta.get(slug);
+                // Non-curated: infer auth mode. If a custom auth config exists,
+                // user set it up themselves (BYO). Otherwise it must be managed.
+                const authMode = configured.has(slug) ? 'byo' : 'managed';
+                return {
+                    slug,
+                    displayName: m?.name ?? c.displayNameFor(slug),
+                    authMode,
+                    hasAuthConfig: configured.has(slug),
+                    logoUrl: m?.logo ?? null,
+                    description: m?.description ?? null,
+                    toolCount: m?.toolsCount ?? null,
+                    connections: conns.map(toView),
+                };
+            });
+            res.json({ enabled: true, toolkits: [...curated, ...extras] });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err) });
+        }
+    });
+    app.post('/api/composio/toolkits/:slug/authorize', async (req, res) => {
+        const slug = req.params.slug;
+        const alias = typeof req.body?.alias === 'string' ? req.body.alias : undefined;
+        try {
+            const c = await import('../integrations/composio/client.js');
+            const result = await c.authorizeToolkit(slug, alias ? { alias } : undefined);
+            res.json(result);
+        }
+        catch (err) {
+            const c = await import('../integrations/composio/client.js');
+            if (err instanceof c.ComposioNeedsAuthConfigError) {
+                res.status(409).json({
+                    error: err.message,
+                    needsAuthConfig: true,
+                    toolkit: slug,
+                    setupUrl: 'https://platform.composio.dev/auth-configs',
+                });
+                return;
+            }
+            res.status(500).json({ error: String(err) });
+        }
+    });
+    app.post('/api/composio/toolkits/:slug/disconnect', async (req, res) => {
+        const connectionId = typeof req.body?.connectionId === 'string' ? req.body.connectionId : '';
+        if (!connectionId) {
+            res.status(400).json({ error: 'connectionId required in body' });
+            return;
+        }
+        try {
+            const c = await import('../integrations/composio/client.js');
+            await c.disconnectToolkit(connectionId);
+            res.json({ ok: true });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err) });
+        }
+    });
+    app.post('/api/composio/connections/:id/rename', async (req, res) => {
+        const id = req.params.id;
+        const alias = typeof req.body?.alias === 'string' ? req.body.alias.trim() : '';
+        if (!alias) {
+            res.status(400).json({ error: 'alias required in body' });
+            return;
+        }
+        try {
+            const c = await import('../integrations/composio/client.js');
+            await c.renameConnection(id, alias);
+            res.json({ ok: true });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err) });
+        }
+    });
     // ── CRON CRUD routes ──────────────────────────────────────────
     app.get('/api/projects', (_req, res) => {
         try {
@@ -4968,6 +5094,13 @@ If the tool returns nothing or errors, return an empty array \`[]\`.`,
                 { key: 'MS_USER_EMAIL', label: 'User Email', hint: 'Email address for mail/calendar access' },
             ],
         },
+        {
+            label: 'Composio',
+            keys: [
+                { key: 'COMPOSIO_API_KEY', label: 'API Key', hint: 'Get one at https://app.composio.dev → Developers. Unlocks 1000+ services (Gmail, Slack, Notion, …) for the agent.', type: 'password' },
+                { key: 'COMPOSIO_USER_ID', label: 'User ID', hint: 'Optional — keys all connections under this Composio user. Defaults to "clementine-default".' },
+            ],
+        },
         {
             label: 'Salesforce',
             keys: [
@@ -5088,13 +5221,22 @@ If the tool returns nothing or errors, return an empty array \`[]\`.`,
                 const { setEnable1MContext } = await import('../config.js');
                 setEnable1MContext(value.toLowerCase() === 'true');
             }
+            // Composio: mutate process.env in-place + drop singleton so the very
+            // next /api/composio/* call picks up the new key without a daemon
+            // restart. Without this, "Save key → Connect Gmail" would 503 until
+            // the user restarted, which defeats the dashboard-config UX.
+            if (key === 'COMPOSIO_API_KEY' || key === 'COMPOSIO_USER_ID') {
+                process.env[key] = value;
+                const { resetComposioClient } = await import('../integrations/composio/client.js');
+                resetComposioClient();
+            }
             res.json({ ok: true, message: `Updated ${key}` });
         }
         catch (err) {
             res.status(500).json({ error: String(err) });
         }
     });
-    app.delete('/api/settings/:key', (req, res) => {
+    app.delete('/api/settings/:key', async (req, res) => {
         try {
             const { key } = req.params;
             if (!existsSync(ENV_PATH)) {
@@ -5105,6 +5247,13 @@ If the tool returns nothing or errors, return an empty array \`[]\`.`,
             const re = new RegExp(`^${key}=.*\n?`, 'm');
             content = content.replace(re, '');
             writeFileSync(ENV_PATH, content);
+            // Hot-reload mirror of the PUT handler — drop process.env entry +
+            // reset Composio client so removal takes effect without a restart.
+            if (key === 'COMPOSIO_API_KEY' || key === 'COMPOSIO_USER_ID') {
+                delete process.env[key];
+                const { resetComposioClient } = await import('../integrations/composio/client.js');
+                resetComposioClient();
+            }
             res.json({ ok: true, message: `Removed ${key}` });
         }
         catch (err) {
@@ -12698,8 +12847,8 @@ if('serviceWorker' in navigator){navigator.serviceWorker.getRegistrations().then
 
         <!-- User Model — MemGPT-style core memory blocks always loaded into context -->
         <div class="tab-pane" id="tab-intelligence-user-model">
-          <div style="color:var(--muted,#888);margin-bottom:12px;font-size:13px">
-            What the agent always knows about you. These slots load into every conversation's context (above retrieved memory). Edit directly to correct or steer.
+          <div style="color:var(--muted,#888);margin-bottom:12px;font-size:13px;max-width:760px">
+            <strong style="color:var(--text)">Always-in-context core memory.</strong> Four small slots (capped at 2000 chars each) that load into <em>every</em> conversation — distinct from MEMORY.md and the chunk store. The agent appends here automatically as you talk; you can also edit directly to correct or steer. Use the Scope dropdown to view per-agent slots (each hired agent maintains their own).
           </div>
           <div style="display:flex;gap:8px;margin-bottom:12px;align-items:center;flex-wrap:wrap">
             <label style="font-size:13px;color:var(--text-secondary)">Scope:</label>
@@ -14325,6 +14474,15 @@ if('serviceWorker' in navigator){navigator.serviceWorker.getRegistrations().then
           </p>
         </div>
         <div class="tab-pane" id="tab-settings-integrations">
+          <div class="card" style="margin-bottom:20px">
+            <div class="card-header" style="display:flex;align-items:center;justify-content:space-between">
+              <span>Connections (via Composio)</span>
+              <span style="font-size:11px;color:var(--text-muted)">1000+ services — OAuth handled by Composio</span>
+            </div>
+            <div class="card-body" style="padding:16px" id="composio-connections">
+              <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>
@@ -15640,7 +15798,7 @@ function switchTab(group, tab) {
     if (tab === 'learning' && typeof refreshSelfImprove === 'function') refreshSelfImprove();
   }
   if (group === 'settings') {
-    if (tab === 'integrations') refreshSalesforce();
+    if (tab === 'integrations') { refreshSalesforce(); refreshComposioConnections(); }
     if (tab === 'remote') refreshRemoteAccess();
     if (tab === 'security') refreshAuthSessions();
     if (tab === 'projects' && typeof refreshProjects === 'function') refreshProjects();
@@ -19160,7 +19318,20 @@ async function loadUserModel() {
       relationships: 'People, projects, channels they regularly interact with.',
       agent_persona: 'For multi-agent: this agent\\'s self-identity in its working relationship with the user.',
     };
+    // First-run hint: when every slot is empty, show a single explainer
+    // banner above the (still editable) textareas so the user understands
+    // both what this is and how to populate it. Suppressed once anything
+    // is in place — at that point the metadata on each card is enough.
+    var allEmpty = d.blocks.every(function(b) { return !(b.content || '').trim(); });
     var html = '<div style="display:flex;flex-direction:column;gap:14px">';
+    if (allEmpty) {
+      html += '<div class="card" style="padding:14px;border-left:3px solid var(--accent,#f59e0b);background:var(--bg-input,#1a1a1a)">' +
+        '<div style="font-weight:600;margin-bottom:6px">No core memory yet for this scope</div>' +
+        '<div style="font-size:12px;color:var(--text-secondary);line-height:1.5">' +
+          'These slots auto-populate as you chat — the agent extracts durable facts about you (your role, active goals, recurring people/projects) and appends them after each exchange. ' +
+          'You can also seed from existing memory in one click, or type directly into any slot below and click Save.' +
+        '</div></div>';
+    }
     for (var i = 0; i < d.blocks.length; i++) {
       var b = d.blocks[i];
       var label = labelMap[b.slot] || b.slot;
@@ -25561,6 +25732,147 @@ async function refreshClaudeIntegrations(preloaded) {
   }
 }
 
+async function refreshComposioConnections() {
+  var container = document.getElementById('composio-connections');
+  if (!container) return;
+  try {
+    var r = await apiFetch('/api/composio/toolkits');
+    var d = await r.json();
+    if (!d.enabled) {
+      container.innerHTML =
+        '<div style="padding:8px 4px">' +
+        '<div style="font-size:13px;margin-bottom:12px">Composio gives Clementine OAuth access to 1000+ services (Gmail, Slack, Notion, GitHub, …) from any channel — Telegram, Discord, dashboard chat. The agent never sees the credentials.</div>' +
+        '<div style="font-size:12px;color:var(--text-secondary);margin-bottom:8px">Get your free API key at <a href="https://app.composio.dev/developers" target="_blank" style="color:var(--accent)">app.composio.dev/developers</a>, then paste it here:</div>' +
+        '<div style="display:flex;gap:8px;align-items:center">' +
+        '<input type="password" id="composio-key-input" placeholder="cak_..." style="flex:1;padding:8px 10px;border:1px solid var(--border);border-radius:6px;background:var(--bg-input);color:var(--text-primary);font-size:13px;font-family:monospace">' +
+        '<button class="btn btn-sm btn-primary" onclick="saveComposioApiKey()" style="font-size:12px">Save & Activate</button>' +
+        '</div>' +
+        '<div id="composio-key-status" style="font-size:11px;color:var(--text-muted);margin-top:8px"></div>' +
+        '</div>';
+      var input = document.getElementById('composio-key-input');
+      if (input) input.addEventListener('keydown', function(e) { if (e.key === 'Enter') saveComposioApiKey(); });
+      return;
+    }
+    var toolkits = d.toolkits || [];
+    if (toolkits.length === 0) {
+      container.innerHTML = '<div class="empty-state" style="padding:16px">No toolkits available. Check that your Composio API key is valid.</div>';
+      return;
+    }
+
+    var html = '<div style="display:grid;grid-template-columns:repeat(auto-fill,minmax(220px,1fr));gap:12px">';
+    toolkits.forEach(function(t) {
+      var connected = (t.connections || []).filter(function(c) { return c.status === 'ACTIVE'; });
+      var pending = (t.connections || []).filter(function(c) { return c.status !== 'ACTIVE'; });
+      var isConnected = connected.length > 0;
+      var statusColor = isConnected ? 'var(--green)' : (pending.length > 0 ? 'var(--yellow,#f59e0b)' : 'var(--text-muted)');
+      var byo = t.authMode === 'byo' && !t.hasAuthConfig;
+
+      html += '<div style="border:1px solid var(--border);border-radius:8px;padding:12px;background:var(--bg-secondary);display:flex;flex-direction:column;gap:8px">';
+      html += '<div style="display:flex;align-items:center;gap:10px">';
+      if (t.logoUrl) {
+        html += '<img src="' + esc(t.logoUrl) + '" alt="" style="width:24px;height:24px;border-radius:4px;background:#fff;padding:2px;flex-shrink:0;object-fit:contain">';
+      } else {
+        html += '<div style="width:24px;height:24px;border-radius:4px;background:var(--bg-tertiary);flex-shrink:0"></div>';
+      }
+      html += '<div style="flex:1;min-width:0">';
+      html += '<div style="font-size:13px;font-weight:600;color:var(--text-primary);white-space:nowrap;overflow:hidden;text-overflow:ellipsis">' + esc(t.displayName) + '</div>';
+      html += '<div style="font-size:10px;color:var(--text-muted)">' + (isConnected ? connected.length + ' account' + (connected.length !== 1 ? 's' : '') : 'Not connected') + '</div>';
+      html += '</div>';
+      html += '<span style="width:8px;height:8px;border-radius:50%;background:' + statusColor + ';flex-shrink:0"></span>';
+      html += '</div>';
+
+      if (connected.length > 0) {
+        html += '<div style="display:flex;flex-direction:column;gap:4px">';
+        connected.forEach(function(c) {
+          var label = c.alias || c.accountLabel || c.accountEmail || c.accountName || 'connected';
+          html += '<div style="display:flex;align-items:center;gap:6px;font-size:11px">';
+          html += '<span style="flex:1;color:var(--text-secondary);white-space:nowrap;overflow:hidden;text-overflow:ellipsis">' + esc(label) + '</span>';
+          html += '<button class="btn-sm" onclick="disconnectComposio(\\'' + esc(t.slug) + '\\',\\'' + esc(c.id) + '\\')" style="font-size:10px;padding:2px 6px;background:transparent;border:1px solid var(--border);color:var(--text-muted);border-radius:4px;cursor:pointer">Disconnect</button>';
+          html += '</div>';
+        });
+        html += '</div>';
+      }
+
+      if (byo) {
+        html += '<div style="font-size:10px;color:var(--yellow,#f59e0b);background:rgba(245,158,11,0.08);padding:6px 8px;border-radius:4px;line-height:1.4">Needs a BYO OAuth app — <a href="https://platform.composio.dev/auth-configs" target="_blank" style="color:inherit;text-decoration:underline">set up in Composio</a> first.</div>';
+      }
+
+      html += '<button class="btn btn-sm btn-primary" onclick="connectComposio(\\'' + esc(t.slug) + '\\')" style="font-size:11px">' + (isConnected ? '+ Add another account' : 'Connect') + '</button>';
+      html += '</div>';
+    });
+    html += '</div>';
+    container.innerHTML = html;
+  } catch (e) {
+    container.innerHTML = '<div class="empty-state" style="color:var(--red);padding:16px">Failed to load Composio toolkits: ' + esc(String(e)) + '</div>';
+  }
+}
+
+async function saveComposioApiKey() {
+  var input = document.getElementById('composio-key-input');
+  var status = document.getElementById('composio-key-status');
+  if (!input) return;
+  var key = (input.value || '').trim();
+  if (!key) { if (status) { status.textContent = 'Enter a key first.'; status.style.color = 'var(--red)'; } return; }
+  if (status) { status.textContent = 'Saving…'; status.style.color = 'var(--text-muted)'; }
+  try {
+    await apiJson('PUT', '/api/settings/COMPOSIO_API_KEY', { value: key });
+    if (status) { status.textContent = 'Saved. Loading toolkits…'; status.style.color = 'var(--green)'; }
+    toast('Composio API key saved', 'success');
+    setTimeout(refreshComposioConnections, 400);
+  } catch (e) {
+    if (status) { status.textContent = 'Failed to save: ' + e; status.style.color = 'var(--red)'; }
+    toast('Failed to save key: ' + e, 'error');
+  }
+}
+
+async function connectComposio(slug) {
+  try {
+    var res = await fetch('/api/composio/toolkits/' + encodeURIComponent(slug) + '/authorize', {
+      method: 'POST',
+      credentials: 'same-origin',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({}),
+    });
+    var d = await res.json();
+    if (res.status === 409 && d.needsAuthConfig) {
+      toast('This toolkit needs a BYO OAuth app — opening Composio dashboard.', 'warn');
+      window.open(d.setupUrl, '_blank');
+      return;
+    }
+    if (!res.ok) { toast('Connect failed: ' + (d.error || res.status), 'error'); return; }
+    if (d.redirectUrl) {
+      window.open(d.redirectUrl, '_blank');
+      toast('Opened ' + slug + ' authorization in a new tab. Refresh after approving.', 'info');
+      // Soft poll to catch the new connection without forcing a manual refresh.
+      setTimeout(refreshComposioConnections, 5000);
+      setTimeout(refreshComposioConnections, 15000);
+      setTimeout(refreshComposioConnections, 30000);
+    } else {
+      toast('Connected ' + slug, 'success');
+      refreshComposioConnections();
+    }
+  } catch (e) { toast('Connect failed: ' + e, 'error'); }
+}
+
+async function disconnectComposio(slug, connectionId) {
+  if (!confirm('Disconnect this ' + slug + ' account?')) return;
+  try {
+    var res = await fetch('/api/composio/toolkits/' + encodeURIComponent(slug) + '/disconnect', {
+      method: 'POST',
+      credentials: 'same-origin',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ connectionId: connectionId }),
+    });
+    if (!res.ok) {
+      var d = await res.json().catch(function() { return {}; });
+      toast('Disconnect failed: ' + (d.error || res.status), 'error');
+      return;
+    }
+    toast('Disconnected', 'success');
+    refreshComposioConnections();
+  } catch (e) { toast('Disconnect failed: ' + e, 'error'); }
+}
+
 async function refreshMcpServers() {
   var container = document.getElementById('mcp-servers-list');
   if (!container) return;

package/dist/cli/setup.js

@@ -176,6 +176,18 @@ const FEATURES = [
             },
         ],
     },
+    {
+        value: 'composio',
+        name: 'Composio (1000+ services — Gmail, Slack, Notion, GitHub, …)',
+        credentials: [
+            {
+                key: 'COMPOSIO_API_KEY',
+                label: 'Composio API key',
+                help: `Sign up at ${CYAN}https://app.composio.dev${DIM} (free tier) and copy your key from Developers > API Keys.\n  After setup, manage connections in the dashboard: Settings > Integrations.`,
+                masked: true,
+            },
+        ],
+    },
     {
         value: 'outlook',
         name: 'Outlook (Microsoft Graph — email + calendar)',
@@ -598,6 +610,7 @@ export async function runSetup() {
         { header: 'Voice', keys: ['GROQ_API_KEY', 'ELEVENLABS_API_KEY', 'ELEVENLABS_VOICE_ID'] },
         { header: 'Video', keys: ['GOOGLE_API_KEY'] },
         { header: 'Outlook (Microsoft Graph)', keys: ['MS_TENANT_ID', 'MS_CLIENT_ID', 'MS_CLIENT_SECRET', 'MS_USER_EMAIL'] },
+        { header: 'Composio (1000+ services broker)', keys: ['COMPOSIO_API_KEY', 'COMPOSIO_USER_ID'] },
         { header: 'Workspace', keys: ['WORKSPACE_DIRS'] },
         { header: 'Security', keys: ['ALLOW_ALL_USERS'] },
     ];

package/dist/config/integrations-registry.js

@@ -189,6 +189,19 @@ export const INTEGRATIONS = [
             { envVar: 'GOOGLE_API_KEY', label: 'Gemini API key', required: true, docUrl: 'https://aistudio.google.com/apikey', persistent: true },
         ],
     },
+    // ── Multi-service broker ──────────────────────────────────────────
+    {
+        slug: 'composio',
+        label: 'Composio',
+        description: 'OAuth + tool execution for 1000+ services (Gmail, Slack, Notion, GitHub, …). Connect toolkits in Settings → Integrations.',
+        kind: 'api-key',
+        docUrl: 'https://app.composio.dev/developers',
+        capabilities: ['Gmail', 'Google Calendar/Drive/Docs', 'Slack', 'Notion', 'GitHub', 'Linear', 'HubSpot', 'Salesforce', 'and 1000+ more'],
+        requirements: [
+            { envVar: 'COMPOSIO_API_KEY', label: 'Composio API key', required: true, docUrl: 'https://app.composio.dev/developers', persistent: true },
+            { envVar: 'COMPOSIO_USER_ID', label: 'User ID for Composio connections (defaults to clementine-default)', required: false, persistent: true },
+        ],
+    },
     // ── Payments ──────────────────────────────────────────────────────
     {
         slug: 'stripe',

package/dist/integrations/composio/client.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Composio integration — client + connection management.
+ *
+ * Composio brokers OAuth and tool execution for 1000+ third-party services
+ * (Gmail, Slack, Notion, Linear, GitHub, …). Users authenticate once via
+ * Composio's hosted OAuth flow; Composio holds the tokens and refreshes them
+ * automatically. Clementine never sees the credentials.
+ *
+ * This module owns everything except the per-toolkit MCP server construction
+ * (see ./mcp-bridge.ts) and the dashboard endpoints (see cli/dashboard.ts).
+ *
+ * Disabled gracefully when COMPOSIO_API_KEY is not set — every public function
+ * returns an empty result, never throws.
+ */
+import { Composio } from '@composio/core';
+import { ClaudeAgentSDKProvider } from '@composio/claude-agent-sdk';
+export type ToolkitAuthMode = 'managed' | 'byo';
+export interface CuratedToolkit {
+    slug: string;
+    displayName: string;
+    /** "managed" = Composio hosts the OAuth app — click Connect, it works.
+     *  "byo"     = User must register their own OAuth app on the toolkit's
+     *              dev portal and add it as an Auth Config in Composio first. */
+    authMode: ToolkitAuthMode;
+}
+export declare const CURATED_TOOLKITS: CuratedToolkit[];
+export declare function getComposio(): Composio<ClaudeAgentSDKProvider> | null;
+export declare function isComposioEnabled(): boolean;
+/**
+ * Discard the cached client + identity cache so the next call to getComposio()
+ * picks up a freshly-set COMPOSIO_API_KEY without a daemon restart. Called by
+ * the dashboard PUT /api/settings/COMPOSIO_API_KEY handler.
+ */
+export declare function resetComposioClient(): void;
+export declare function clementineUserId(): string;
+export declare function displayNameFor(slug: string): string;
+export interface ConnectedToolkit {
+    slug: string;
+    connectionId: string;
+    status: string;
+    alias?: string;
+    accountLabel?: string;
+    accountEmail?: string;
+    accountName?: string;
+    accountAvatarUrl?: string;
+    createdAt?: string;
+}
+export declare function listConnectedToolkits(): Promise<ConnectedToolkit[]>;
+export interface ToolkitMeta {
+    slug: string;
+    name: string;
+    logo?: string;
+    description?: string;
+    toolsCount?: number;
+}
+export declare function listToolkitMeta(): Promise<Map<string, ToolkitMeta>>;
+export declare function listToolkitSlugsWithAuthConfig(): Promise<Set<string>>;
+export declare class ComposioNeedsAuthConfigError extends Error {
+    readonly slug: string;
+    readonly underlying: string;
+    constructor(slug: string, underlying: string);
+}
+export declare function authorizeToolkit(slug: string, opts?: {
+    callbackUrl?: string;
+    alias?: string;
+}): Promise<{
+    redirectUrl: string | null;
+    connectionId: string;
+}>;
+export declare function disconnectToolkit(connectionId: string): Promise<void>;
+export declare function renameConnection(connectionId: string, alias: string): Promise<void>;
+//# sourceMappingURL=client.d.ts.map

package/dist/integrations/composio/client.js

@@ -0,0 +1,387 @@
+/**
+ * Composio integration — client + connection management.
+ *
+ * Composio brokers OAuth and tool execution for 1000+ third-party services
+ * (Gmail, Slack, Notion, Linear, GitHub, …). Users authenticate once via
+ * Composio's hosted OAuth flow; Composio holds the tokens and refreshes them
+ * automatically. Clementine never sees the credentials.
+ *
+ * This module owns everything except the per-toolkit MCP server construction
+ * (see ./mcp-bridge.ts) and the dashboard endpoints (see cli/dashboard.ts).
+ *
+ * Disabled gracefully when COMPOSIO_API_KEY is not set — every public function
+ * returns an empty result, never throws.
+ */
+import { Composio } from '@composio/core';
+import { ClaudeAgentSDKProvider } from '@composio/claude-agent-sdk';
+import pino from 'pino';
+const logger = pino({ name: 'clementine.composio' });
+// Curated set surfaced in the dashboard. Composio exposes 1000+ — rendering
+// them all is noisy. Users can still connect anything by editing this list.
+export const CURATED_TOOLKITS = [
+    { slug: 'gmail', displayName: 'Gmail', authMode: 'managed' },
+    { slug: 'googlecalendar', displayName: 'Google Calendar', authMode: 'managed' },
+    { slug: 'googledrive', displayName: 'Google Drive', authMode: 'managed' },
+    { slug: 'googlesheets', displayName: 'Google Sheets', authMode: 'managed' },
+    { slug: 'googledocs', displayName: 'Google Docs', authMode: 'managed' },
+    { slug: 'slack', displayName: 'Slack', authMode: 'managed' },
+    { slug: 'github', displayName: 'GitHub', authMode: 'managed' },
+    { slug: 'linear', displayName: 'Linear', authMode: 'managed' },
+    { slug: 'notion', displayName: 'Notion', authMode: 'managed' },
+    { slug: 'hubspot', displayName: 'HubSpot', authMode: 'managed' },
+    { slug: 'salesforce', displayName: 'Salesforce', authMode: 'managed' },
+    { slug: 'discord', displayName: 'Discord', authMode: 'managed' },
+    { slug: 'trello', displayName: 'Trello', authMode: 'managed' },
+    { slug: 'asana', displayName: 'Asana', authMode: 'managed' },
+    { slug: 'jira', displayName: 'Jira', authMode: 'managed' },
+    { slug: 'airtable', displayName: 'Airtable', authMode: 'managed' },
+    { slug: 'figma', displayName: 'Figma', authMode: 'managed' },
+    { slug: 'dropbox', displayName: 'Dropbox', authMode: 'managed' },
+    { slug: 'stripe', displayName: 'Stripe', authMode: 'managed' },
+    { slug: 'supabase', displayName: 'Supabase', authMode: 'managed' },
+    { slug: 'linkedin', displayName: 'LinkedIn', authMode: 'managed' },
+    { slug: 'twitter', displayName: 'Twitter / X', authMode: 'byo' },
+];
+const DISPLAY_NAME_BY_SLUG = new Map(CURATED_TOOLKITS.map(t => [t.slug, t.displayName]));
+let singleton = null;
+export function getComposio() {
+    if (singleton)
+        return singleton;
+    const apiKey = process.env.COMPOSIO_API_KEY;
+    if (!apiKey)
+        return null;
+    singleton = new Composio({
+        apiKey,
+        provider: new ClaudeAgentSDKProvider(),
+    });
+    return singleton;
+}
+export function isComposioEnabled() {
+    return Boolean(process.env.COMPOSIO_API_KEY);
+}
+/**
+ * Discard the cached client + identity cache so the next call to getComposio()
+ * picks up a freshly-set COMPOSIO_API_KEY without a daemon restart. Called by
+ * the dashboard PUT /api/settings/COMPOSIO_API_KEY handler.
+ */
+export function resetComposioClient() {
+    singleton = null;
+    identityCache.clear();
+    toolkitMetaCache = null;
+}
+// Single-tenant by default. All connections are keyed under COMPOSIO_USER_ID;
+// override if the same Composio account is shared with another tool.
+export function clementineUserId() {
+    return process.env.COMPOSIO_USER_ID ?? 'clementine-default';
+}
+export function displayNameFor(slug) {
+    return DISPLAY_NAME_BY_SLUG.get(slug) ?? humanize(slug);
+}
+function humanize(slug) {
+    return slug
+        .split(/[-_]/g)
+        .filter(Boolean)
+        .map(p => p.charAt(0).toUpperCase() + p.slice(1))
+        .join(' ');
+}
+function str(v) {
+    return typeof v === 'string' && v.trim() ? v.trim() : undefined;
+}
+function decodeJwtPayload(jwt) {
+    try {
+        const parts = jwt.split('.');
+        if (parts.length < 2)
+            return null;
+        const payload = parts[1];
+        const padded = payload + '==='.slice((payload.length + 3) % 4);
+        const b64 = padded.replace(/-/g, '+').replace(/_/g, '/');
+        return JSON.parse(Buffer.from(b64, 'base64').toString('utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+// Composio's connected-account state is shaped per toolkit. Pull whatever
+// human identity we can find — OAuth id_tokens (Google et al.) carry
+// email/name/picture; other toolkits stash shop, subdomain, account_id.
+function extractAccountIdentity(state, data) {
+    const s = (state && typeof state === 'object' ? state : {}) ?? {};
+    const d = (data && typeof data === 'object' ? data : {}) ?? {};
+    const out = {};
+    const idToken = str(s.id_token) ?? str(d.id_token);
+    if (idToken) {
+        const payload = decodeJwtPayload(idToken);
+        if (payload) {
+            out.email = str(payload.email);
+            out.name = str(payload.name) ?? str(payload.given_name);
+            out.avatarUrl = str(payload.picture);
+        }
+    }
+    for (const src of [d, s]) {
+        const profile = (src.user_info && typeof src.user_info === 'object' ? src.user_info : null) ??
+            (src.profile && typeof src.profile === 'object' ? src.profile : null);
+        if (profile) {
+            out.email = out.email ?? str(profile.email);
+            out.name = out.name ?? str(profile.name) ?? str(profile.display_name);
+            out.avatarUrl = out.avatarUrl ?? str(profile.picture) ?? str(profile.avatar_url);
+        }
+        out.email = out.email ?? str(src.email);
+        out.name = out.name ?? str(src.name) ?? str(src.display_name);
+        out.avatarUrl = out.avatarUrl ?? str(src.avatar_url) ?? str(src.picture);
+    }
+    const fallback = str(s.shop) ??
+        str(s.subdomain) ??
+        str(s.domain) ??
+        str(s.account_id) ??
+        str(s.site_name) ??
+        str(d.shop) ??
+        str(d.subdomain);
+    out.label = out.email ?? out.name ?? fallback;
+    return out;
+}
+function genericProfileParse(d) {
+    const first = (...candidates) => {
+        for (const c of candidates)
+            if (typeof c === 'string' && c.trim())
+                return c.trim();
+        return undefined;
+    };
+    const nested = (key) => (d[key] && typeof d[key] === 'object' ? d[key] : {});
+    const viewer = nested('viewer');
+    const user = nested('user');
+    const team = nested('team');
+    const profile = nested('profile');
+    const email = first(d.email, user.email, viewer.email, profile.email);
+    const name = first(d.name, d.login, d.display_name, user.name, viewer.name, profile.name, team.name);
+    const avatar = first(d.avatar_url, d.avatarUrl, d.picture, user.avatar_url, viewer.avatarUrl, profile.image);
+    return { email, name, avatarUrl: avatar, label: email ?? name };
+}
+const WHOAMI_BY_TOOLKIT = {
+    gmail: {
+        tool: 'GMAIL_GET_PROFILE',
+        arguments: { user_id: 'me' },
+        parse: d => {
+            const email = typeof d.emailAddress === 'string' ? d.emailAddress : undefined;
+            return { email, label: email };
+        },
+    },
+    github: { tool: 'GITHUB_GET_THE_AUTHENTICATED_USER', arguments: {}, parse: genericProfileParse },
+    linear: { tool: 'LINEAR_GET_CURRENT_USER', arguments: {}, parse: genericProfileParse },
+    notion: { tool: 'NOTION_GET_ABOUT_ME', arguments: {}, parse: genericProfileParse },
+    slack: { tool: 'SLACK_FETCH_TEAM_INFO', arguments: {}, parse: genericProfileParse },
+    hubspot: { tool: 'HUBSPOT_GET_ACCOUNT_INFO', arguments: {}, parse: genericProfileParse },
+    stripe: { tool: 'STRIPE_GET_ACCOUNT', arguments: {}, parse: genericProfileParse },
+};
+const identityCache = new Map();
+const IDENTITY_TTL_MS = 15 * 60 * 1000;
+async function fetchToolkitIdentity(composio, slug, connectedAccountId) {
+    const spec = WHOAMI_BY_TOOLKIT[slug];
+    if (!spec)
+        return {};
+    try {
+        const result = await composio.tools.execute(spec.tool, {
+            userId: clementineUserId(),
+            // Without this, Composio picks the user's *default* connection for the
+            // toolkit, so multiple Gmail accounts end up labeled with the same email.
+            ...(connectedAccountId ? { connectedAccountId } : {}),
+            arguments: spec.arguments,
+            // Composio requires either a pinned toolkit version or this flag.
+            // Skipping pin so a toolkit bump doesn't break identity silently —
+            // misses fall through to fallback chain below.
+            dangerouslySkipVersionCheck: true,
+        });
+        if (!result.successful || !result.data)
+            return {};
+        return spec.parse(result.data);
+    }
+    catch (err) {
+        logger.warn({ err, slug }, 'whoami fetch failed');
+        return {};
+    }
+}
+async function getIdentityFor(composio, id, slug, seed) {
+    if (seed.label)
+        return seed;
+    const cached = identityCache.get(id);
+    if (cached && Date.now() - cached.at < IDENTITY_TTL_MS)
+        return cached.identity;
+    let identity = {};
+    try {
+        const full = await composio.connectedAccounts.get(id);
+        identity = extractAccountIdentity(full.state, full.data);
+    }
+    catch (err) {
+        logger.warn({ err, id }, 'failed to fetch full connection for identity');
+    }
+    if (!identity.label) {
+        const whoami = await fetchToolkitIdentity(composio, slug, id);
+        if (whoami.label)
+            identity = { ...identity, ...whoami };
+    }
+    identityCache.set(id, { at: Date.now(), identity });
+    return identity;
+}
+export async function listConnectedToolkits() {
+    const composio = getComposio();
+    if (!composio)
+        return [];
+    try {
+        const resp = await composio.connectedAccounts.list({ userIds: [clementineUserId()] });
+        const enriched = await Promise.all(resp.items.map(async (it) => {
+            const seed = extractAccountIdentity(it.state, it.data);
+            const identity = it.status === 'ACTIVE'
+                ? await getIdentityFor(composio, it.id, it.toolkit.slug, seed)
+                : seed;
+            return {
+                slug: it.toolkit.slug,
+                connectionId: it.id,
+                status: it.status,
+                alias: it.alias ?? undefined,
+                accountLabel: identity.label,
+                accountEmail: identity.email,
+                accountName: identity.name,
+                accountAvatarUrl: identity.avatarUrl,
+                createdAt: it.createdAt,
+            };
+        }));
+        return enriched;
+    }
+    catch (err) {
+        logger.error({ err }, 'listConnectedToolkits failed');
+        return [];
+    }
+}
+let toolkitMetaCache = null;
+async function fetchAllToolkitMeta() {
+    const composio = getComposio();
+    if (!composio)
+        return new Map();
+    const out = new Map();
+    try {
+        const resp = await composio.toolkits.get({ limit: 500 });
+        const items = Array.isArray(resp) ? resp : (resp.items ?? []);
+        for (const it of items) {
+            out.set(it.slug, {
+                slug: it.slug,
+                name: it.name,
+                logo: it.meta?.logo,
+                description: it.meta?.description,
+                toolsCount: it.meta?.toolsCount,
+            });
+        }
+        // Backfill curated toolkits the list endpoint omitted (e.g. MCP-only ones).
+        await Promise.all(CURATED_TOOLKITS.filter(t => !out.has(t.slug)).map(async (t) => {
+            try {
+                const full = (await composio.toolkits.get(t.slug));
+                out.set(full.slug, {
+                    slug: full.slug,
+                    name: full.name,
+                    logo: full.meta?.logo,
+                    description: full.meta?.description,
+                    toolsCount: full.meta?.toolsCount,
+                });
+            }
+            catch (err) {
+                logger.debug({ err, slug: t.slug }, 'meta backfill failed');
+            }
+        }));
+    }
+    catch (err) {
+        logger.error({ err }, 'fetchAllToolkitMeta failed');
+    }
+    return out;
+}
+export async function listToolkitMeta() {
+    if (!toolkitMetaCache) {
+        toolkitMetaCache = fetchAllToolkitMeta().catch(err => {
+            logger.error({ err }, 'listToolkitMeta failed');
+            toolkitMetaCache = null;
+            return new Map();
+        });
+    }
+    return toolkitMetaCache;
+}
+export async function listToolkitSlugsWithAuthConfig() {
+    const composio = getComposio();
+    if (!composio)
+        return new Set();
+    try {
+        const resp = await composio.authConfigs.list({ limit: 200 });
+        return new Set(resp.items.map(it => it.toolkit.slug));
+    }
+    catch (err) {
+        logger.error({ err }, 'listToolkitSlugsWithAuthConfig failed');
+        return new Set();
+    }
+}
+// ── Authorize / disconnect ─────────────────────────────────────────────
+export class ComposioNeedsAuthConfigError extends Error {
+    slug;
+    underlying;
+    constructor(slug, underlying) {
+        super(`Toolkit "${slug}" needs an auth config — Composio doesn't host a managed OAuth app for it. ` +
+            `Add it via the Composio Dashboard: Toolkits → search ${slug} → Add to project → paste your OAuth credentials. ` +
+            `https://platform.composio.dev/auth-configs`);
+        this.slug = slug;
+        this.underlying = underlying;
+        this.name = 'ComposioNeedsAuthConfigError';
+    }
+}
+export async function authorizeToolkit(slug, opts) {
+    const composio = getComposio();
+    if (!composio)
+        throw new Error('COMPOSIO_API_KEY not set');
+    // 1. Find or create an auth config. session.authorize() doesn't auto-create
+    //    so we have to pass authConfigId explicitly to connectedAccounts.initiate.
+    let authConfigId;
+    const existingConfig = (await composio.authConfigs.list({ toolkit: slug })).items[0];
+    if (existingConfig) {
+        authConfigId = existingConfig.id;
+    }
+    else {
+        try {
+            const created = await composio.authConfigs.create(slug, {
+                type: 'use_composio_managed_auth',
+                name: `${displayNameFor(slug)} Auth Config`,
+            });
+            authConfigId = created.id;
+        }
+        catch (err) {
+            // 400 → Composio doesn't host a managed OAuth app for this toolkit;
+            // user must register their own via the Composio dashboard.
+            const status = err?.status;
+            if (status === 400) {
+                throw new ComposioNeedsAuthConfigError(slug, String(err));
+            }
+            throw err;
+        }
+    }
+    // 2. Initiate the connection. allowMultiple if there's already an active
+    //    connection so we add another account instead of replacing.
+    const existing = (await listConnectedToolkits()).filter(c => c.slug === slug && c.status === 'ACTIVE');
+    const conn = await composio.connectedAccounts.initiate(clementineUserId(), authConfigId, {
+        ...(existing.length > 0 ? { allowMultiple: true } : {}),
+        ...(opts?.callbackUrl ? { callbackUrl: opts.callbackUrl } : {}),
+        ...(opts?.alias ? { alias: opts.alias } : {}),
+    });
+    return { redirectUrl: conn.redirectUrl ?? null, connectionId: conn.id };
+}
+export async function disconnectToolkit(connectionId) {
+    const composio = getComposio();
+    if (!composio)
+        throw new Error('COMPOSIO_API_KEY not set');
+    await composio.connectedAccounts.delete(connectionId);
+    identityCache.delete(connectionId);
+}
+export async function renameConnection(connectionId, alias) {
+    const composio = getComposio();
+    if (!composio)
+        throw new Error('COMPOSIO_API_KEY not set');
+    // The Composio high-level wrapper only exposes status updates; alias
+    // rename lives on the raw client's PATCH endpoint, which is marked
+    // protected. Bridge through `as any` — this is a small, well-scoped escape
+    // hatch and the alternative (bypassing the wrapper entirely) loses retry
+    // and auth handling.
+    await composio.client.connectedAccounts.patch(connectionId, { alias });
+}
+//# sourceMappingURL=client.js.map

package/dist/integrations/composio/mcp-bridge.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Composio MCP bridge — converts Composio toolkits into in-process SDK MCP
+ * servers that the Claude Agent SDK's `query()` can spawn directly.
+ *
+ * Why per-toolkit servers (instead of one big "composio" server)?
+ *   - Per-agent scoping. A scheduler-bot doesn't need GitHub tools; spawning
+ *     a Calendar-only sub-agent shouldn't drag in 200 tools across 20
+ *     toolkits.
+ *   - Tool-name namespacing. Each MCP server registers its tools under its
+ *     own name, so we get `mcp__gmail__GMAIL_SEND_EMAIL` not
+ *     `mcp__composio__GMAIL_SEND_EMAIL` collisions across toolkits.
+ *   - Concurrency. Composio's TS provider opens one session per server, so
+ *     having one server per toolkit lets unrelated toolkits load in parallel.
+ *
+ * Returns an empty map when COMPOSIO_API_KEY is unset, so the agent path
+ * always works — Composio is purely additive.
+ */
+import type { McpSdkServerConfigWithInstance } from '@anthropic-ai/claude-agent-sdk';
+/**
+ * Build SDK MCP server configs for the given toolkit slugs (or all active
+ * connected toolkits when omitted). Each toolkit becomes one MCP server.
+ */
+export declare function buildComposioMcpServers(slugs?: string[]): Promise<Record<string, McpSdkServerConfigWithInstance>>;
+//# sourceMappingURL=mcp-bridge.d.ts.map

package/dist/integrations/composio/mcp-bridge.js

@@ -0,0 +1,75 @@
+/**
+ * Composio MCP bridge — converts Composio toolkits into in-process SDK MCP
+ * servers that the Claude Agent SDK's `query()` can spawn directly.
+ *
+ * Why per-toolkit servers (instead of one big "composio" server)?
+ *   - Per-agent scoping. A scheduler-bot doesn't need GitHub tools; spawning
+ *     a Calendar-only sub-agent shouldn't drag in 200 tools across 20
+ *     toolkits.
+ *   - Tool-name namespacing. Each MCP server registers its tools under its
+ *     own name, so we get `mcp__gmail__GMAIL_SEND_EMAIL` not
+ *     `mcp__composio__GMAIL_SEND_EMAIL` collisions across toolkits.
+ *   - Concurrency. Composio's TS provider opens one session per server, so
+ *     having one server per toolkit lets unrelated toolkits load in parallel.
+ *
+ * Returns an empty map when COMPOSIO_API_KEY is unset, so the agent path
+ * always works — Composio is purely additive.
+ */
+import { createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk';
+import pino from 'pino';
+import { clementineUserId, getComposio, listConnectedToolkits, } from './client.js';
+const logger = pino({ name: 'clementine.composio.mcp' });
+/**
+ * Build SDK MCP server configs for the given toolkit slugs (or all active
+ * connected toolkits when omitted). Each toolkit becomes one MCP server.
+ */
+export async function buildComposioMcpServers(slugs) {
+    const composio = getComposio();
+    if (!composio)
+        return {};
+    const connected = await listConnectedToolkits();
+    const activeSlugs = new Set(connected.filter(c => c.status === 'ACTIVE').map(c => c.slug));
+    const targetSlugs = slugs?.length
+        ? slugs.filter(s => activeSlugs.has(s))
+        : [...activeSlugs];
+    if (targetSlugs.length === 0)
+        return {};
+    const out = {};
+    // Build serially to avoid hammering Composio with parallel session opens
+    // on every agent query. Sessions are cached upstream by Composio's SDK,
+    // so repeat calls within a process are cheap after the first hit.
+    for (const slug of targetSlugs) {
+        try {
+            out[slug] = await buildOne(composio, slug, connected);
+        }
+        catch (err) {
+            logger.warn({ err, slug }, 'failed to build Composio MCP server — skipping');
+        }
+    }
+    return out;
+}
+async function buildOne(composio, slug, connected) {
+    // If 2+ active connections for this toolkit, force Composio to require
+    // explicit account selection per tool call — otherwise it silently picks
+    // the default (newest) account.
+    const activeCount = connected.filter(c => c.slug === slug && c.status === 'ACTIVE').length;
+    // Look up auth config explicitly. Without this, composio.create() tries to
+    // auto-create one and 400s for BYO toolkits (Twitter etc.) that don't have
+    // a managed OAuth app available.
+    const authConfig = (await composio.authConfigs.list({ toolkit: slug })).items[0];
+    const session = await composio.create(clementineUserId(), {
+        toolkits: [slug],
+        manageConnections: false,
+        ...(authConfig ? { authConfigs: { [slug]: authConfig.id } } : {}),
+        ...(activeCount >= 2
+            ? { multiAccount: { enable: true, requireExplicitSelection: true } }
+            : {}),
+    });
+    const tools = await session.tools();
+    return createSdkMcpServer({
+        name: slug,
+        version: '0.1.0',
+        tools,
+    });
+}
+//# sourceMappingURL=mcp-bridge.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",
@@ -23,6 +23,8 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.119",
     "@anthropic-ai/sdk": "^0.91.0",
+    "@composio/claude-agent-sdk": "^0.8.1",
+    "@composio/core": "^0.8.1",
     "@inquirer/prompts": "^7.0.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@slack/bolt": "^4.2.0",