clementine-agent 1.18.44 → 1.18.46

package/dist/agent/assistant.d.ts

@@ -277,6 +277,13 @@ export declare class PersonalAssistant {
     private memoryExtractionKey;
     private assessMemoryExtraction;
     private logMemoryExtractionSkip;
+    /**
+     * Public entry point for triggering auto-memory extraction after an
+     * exchange. Used by the new runAgent chat path (Phase 2 migration)
+     * so it can keep the existing memory-extraction behavior without
+     * having to recreate the surrounding plumbing.
+     */
+    triggerMemoryExtractionPostExchange(userMessage: string, assistantResponse: string, sessionKey?: string, profile?: AgentProfile): Promise<void>;
     private spawnMemoryExtraction;
     private static readonly MEMORY_TOOL_NAMES;
     private extractMemory;

package/dist/agent/assistant.js

@@ -4883,6 +4883,15 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
         }
         catch { /* telemetry only */ }
     }
+    /**
+     * Public entry point for triggering auto-memory extraction after an
+     * exchange. Used by the new runAgent chat path (Phase 2 migration)
+     * so it can keep the existing memory-extraction behavior without
+     * having to recreate the surrounding plumbing.
+     */
+    async triggerMemoryExtractionPostExchange(userMessage, assistantResponse, sessionKey, profile) {
+        return this.spawnMemoryExtraction(userMessage, assistantResponse, sessionKey, profile);
+    }
     async spawnMemoryExtraction(userMessage, assistantResponse, sessionKey, profile) {
         // Guard: skip memory extraction if the user message looks like injection
         const memScan = scanner.scan(userMessage);

package/dist/agent/run-agent-cron.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Clementine TypeScript — runAgent cron wrapper.
+ *
+ * Phase 3 of the SDK-canonical migration (see
+ * /Users/nathan.reynolds/.claude/plans/sdk-canonical-migration.md).
+ *
+ * Cron jobs need more than a bare runAgent() call: they get progress
+ * continuity, linked goals, delegated tasks, team context, success
+ * criteria, and matched skills injected ahead of the job prompt. This
+ * file owns that composition for the new (canonical SDK) path. The
+ * legacy assistant.ts:runCronJob keeps its inline equivalents so we
+ * can ship Phase 3 without touching legacy code.
+ *
+ * After Phase 3 verifies and we collapse the legacy path, the
+ * duplicated helpers here become the single source of truth.
+ */
+import type { AgentProfile } from '../types.js';
+import type { AgentManager } from './agent-manager.js';
+import type { MemoryStore } from '../memory/store.js';
+import { type RunAgentResult } from './run-agent.js';
+export interface RunAgentCronOptions {
+    /** Job name from CRON.md. Used for telemetry, progress lookup, skill match. */
+    jobName: string;
+    /** Job prompt body (the user-defined "do this" text). */
+    jobPrompt: string;
+    /** Cron tier. Drives effort + budget. */
+    tier?: number;
+    /** Optional max-turns cap (the SDK runs until done otherwise, bounded by maxBudget). */
+    maxTurns?: number;
+    /** Profile of the hired agent running this job (Sasha/Ross/Nora/etc). null = Clementine. */
+    profile?: AgentProfile | null;
+    /** Hired-agent registry — passed through to runAgent so subagent delegation works. */
+    agentManager?: AgentManager | null;
+    /** Memory store for cost logging + skill use tracking. */
+    memoryStore?: MemoryStore | null;
+    /** Per-job success criteria from CRON.md frontmatter. */
+    successCriteria?: string[];
+    /** Optional model override (rare — most jobs let the SDK default decide). */
+    model?: string;
+    /** Optional max-budget override. Default: tier-1 = $1, tier-2+ = $3. */
+    maxBudgetUsd?: number;
+    /** Optional working directory override (project-scoped jobs). */
+    workDir?: string;
+    /** Abort signal for cancellation. */
+    abortSignal?: AbortSignal;
+}
+export interface RunAgentCronResult extends RunAgentResult {
+    /** The final prompt that was sent to the agent (after context injection).
+     *  Useful for cron diagnostics + debugging. */
+    builtPrompt: string;
+    /** Diagnostics: which Composio + external servers were live for this run. */
+    composioConnected: string[];
+    externalConnected: string[];
+}
+/**
+ * Run a cron job via the canonical SDK runAgent path.
+ *
+ * Composes the same context blocks the legacy runCronJob injects
+ * (progress, goals, delegation, team, criteria, skills, fanout
+ * directive), wires Composio + external MCP via the dedup-aware
+ * helper, then calls runAgent.
+ *
+ * The SDK handles the loop, compaction, subagent fanout, prompt
+ * caching, retries — none of which we wrap manually anymore.
+ */
+export declare function runAgentCron(opts: RunAgentCronOptions): Promise<RunAgentCronResult>;
+//# sourceMappingURL=run-agent-cron.d.ts.map

package/dist/agent/run-agent-cron.js

@@ -0,0 +1,319 @@
+/**
+ * Clementine TypeScript — runAgent cron wrapper.
+ *
+ * Phase 3 of the SDK-canonical migration (see
+ * /Users/nathan.reynolds/.claude/plans/sdk-canonical-migration.md).
+ *
+ * Cron jobs need more than a bare runAgent() call: they get progress
+ * continuity, linked goals, delegated tasks, team context, success
+ * criteria, and matched skills injected ahead of the job prompt. This
+ * file owns that composition for the new (canonical SDK) path. The
+ * legacy assistant.ts:runCronJob keeps its inline equivalents so we
+ * can ship Phase 3 without touching legacy code.
+ *
+ * After Phase 3 verifies and we collapse the legacy path, the
+ * duplicated helpers here become the single source of truth.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import pino from 'pino';
+import { BASE_DIR, VAULT_DIR, CRON_PROGRESS_DIR, } from '../config.js';
+import { runAgent } from './run-agent.js';
+import { buildExtraMcpForRunAgent } from './run-agent-mcp.js';
+import { buildFanoutDirectiveForText, buildAlwaysOnParallelizationHint } from './fanout-policy.js';
+import { listAllGoals } from '../tools/shared.js';
+const CRON_PROGRESS_PENDING_MAX_ITEMS = 20;
+const CRON_PROGRESS_NOTES_MAX_CHARS = 2000;
+const logger = pino({ name: 'clementine.run-agent-cron' });
+const CRON_CONTEXT_ITEM_MAX = 80;
+function capContextItem(s) {
+    if (!s)
+        return '';
+    return s.length <= CRON_CONTEXT_ITEM_MAX ? s : s.slice(0, CRON_CONTEXT_ITEM_MAX - 3) + '...';
+}
+function capContextBlock(s, max) {
+    if (!s)
+        return '';
+    return s.length <= max ? s : s.slice(0, max - 3) + '...';
+}
+/**
+ * Build the previous-progress block from the cron progress JSON file.
+ * Lets the agent continue where the prior run left off without re-doing
+ * work it already completed.
+ */
+function buildProgressContext(jobName) {
+    try {
+        const safeJob = jobName.replace(/[^a-zA-Z0-9_-]/g, '_');
+        const progressFile = path.join(CRON_PROGRESS_DIR, `${safeJob}.json`);
+        if (!fs.existsSync(progressFile))
+            return '';
+        const progress = JSON.parse(fs.readFileSync(progressFile, 'utf-8'));
+        const parts = [`## Previous Progress (run #${progress.runCount}, ${progress.lastRunAt})`];
+        if (progress.completedItems?.length > 0) {
+            parts.push(`Completed: ${progress.completedItems.slice(-10).map(capContextItem).join(', ')}`);
+        }
+        if (progress.pendingItems?.length > 0) {
+            const pendingItems = progress.pendingItems.slice(0, CRON_PROGRESS_PENDING_MAX_ITEMS).map(capContextItem);
+            const suffix = progress.pendingItems.length > CRON_PROGRESS_PENDING_MAX_ITEMS
+                ? ` (${progress.pendingItems.length - CRON_PROGRESS_PENDING_MAX_ITEMS} more omitted)`
+                : '';
+            parts.push(`Pending: ${pendingItems.join(', ')}${suffix}`);
+        }
+        if (progress.notes) {
+            parts.push(`Notes: ${capContextBlock(progress.notes, CRON_PROGRESS_NOTES_MAX_CHARS)}`);
+        }
+        return parts.join('\n') + '\n\n' +
+            'Continue from where you left off. Use `cron_progress_write` at the end to save what you completed and what\'s pending.\n\n';
+    }
+    catch {
+        return '';
+    }
+}
+/** Build the linked-goals block for jobs that contribute to active goals. */
+function buildGoalContext(jobName) {
+    try {
+        const linkedGoals = listAllGoals()
+            .map(({ goal }) => goal)
+            .filter(g => g && g.status === 'active' && g.linkedCronJobs?.includes(jobName));
+        if (linkedGoals.length === 0)
+            return '';
+        const goalLines = linkedGoals.map(g => {
+            const goalRecord = g;
+            const nextAct = goalRecord.nextActions?.length ? ` Next: ${goalRecord.nextActions[0]}` : '';
+            const recentProgress = goalRecord.progressNotes?.length
+                ? ` Last progress: ${goalRecord.progressNotes[goalRecord.progressNotes.length - 1]}`
+                : '';
+            return `- **${goalRecord.title}** (${goalRecord.id}): ${goalRecord.description.slice(0, 100)}${nextAct}${recentProgress}`;
+        });
+        return `## Active Goals Linked to This Job\n${goalLines.join('\n')}\n\n` +
+            'After completing your work, update goal progress with `goal_update` if you made meaningful progress.\n\n';
+    }
+    catch {
+        return '';
+    }
+}
+/** Build the delegated-tasks block for hired agents that have pending team requests. */
+function buildDelegationContext(agentSlug) {
+    if (!agentSlug)
+        return '';
+    try {
+        const tasksDir = path.join(VAULT_DIR, '00-System', 'agents', agentSlug, 'tasks');
+        if (!fs.existsSync(tasksDir))
+            return '';
+        const taskFiles = fs.readdirSync(tasksDir).filter(f => f.endsWith('.json'));
+        const pendingTasks = taskFiles
+            .map(f => {
+            try {
+                return JSON.parse(fs.readFileSync(path.join(tasksDir, f), 'utf-8'));
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((t) => t !== null && t.status === 'pending');
+        if (pendingTasks.length === 0)
+            return '';
+        const taskLines = pendingTasks.map(t => `- [${t.id}] From ${t.fromAgent}: ${t.task.slice(0, 150)} (expected: ${t.expectedOutput.slice(0, 80)})`);
+        return `## Delegated Tasks Waiting\n${taskLines.join('\n')}\n\n` +
+            'Work on these delegated tasks in addition to your scheduled task. ' +
+            'Mark them in_progress/completed by editing the task JSON when done.\n\n';
+    }
+    catch {
+        return '';
+    }
+}
+/** Build the team-comms block: pending requests + recent messages for this agent. */
+function buildTeamContext(agentSlug) {
+    if (!agentSlug)
+        return '';
+    try {
+        const teamLogPath = path.join(BASE_DIR, 'logs', 'team-comms.jsonl');
+        if (!fs.existsSync(teamLogPath))
+            return '';
+        const teamLines = fs.readFileSync(teamLogPath, 'utf-8').trim().split('\n').filter(Boolean);
+        const recentForAgent = teamLines
+            .slice(-50)
+            .map(l => { try {
+            return JSON.parse(l);
+        }
+        catch {
+            return null;
+        } })
+            .filter((m) => m !== null && (m.toAgent === agentSlug || m.fromAgent === agentSlug))
+            .slice(-5);
+        const pendingRequests = recentForAgent.filter(m => m.protocol === 'request' && m.toAgent === agentSlug && !m.response);
+        if (pendingRequests.length === 0 && recentForAgent.length === 0)
+            return '';
+        const parts = ['## Team Context'];
+        if (pendingRequests.length > 0) {
+            parts.push('### REPLY NEEDED — Pending Requests');
+            for (const r of pendingRequests) {
+                parts.push(`- From ${r.fromAgent}: ${r.content.slice(0, 200)}`);
+            }
+            parts.push('Address these requests before your main task.');
+        }
+        if (recentForAgent.length > 0) {
+            parts.push('### Recent Team Messages');
+            for (const m of recentForAgent) {
+                const dir = m.fromAgent === agentSlug ? 'sent to' : 'from';
+                const other = m.fromAgent === agentSlug ? m.toAgent : m.fromAgent;
+                parts.push(`- ${dir} ${other}: ${m.content.slice(0, 100)}`);
+            }
+        }
+        return parts.join('\n') + '\n\n';
+    }
+    catch {
+        return '';
+    }
+}
+/** Build the success-criteria block from job spec. */
+function buildCriteriaContext(successCriteria) {
+    if (!successCriteria?.length)
+        return '';
+    return `## Success Criteria\nYour output will be verified against these criteria:\n` +
+        successCriteria.map(c => `- ${c}`).join('\n') + '\n\n';
+}
+/** Build the matched-skills block (procedures learned from prior successful runs). */
+async function buildSkillContext(jobName, jobPrompt, agentSlug, memoryStore) {
+    try {
+        const { searchSkills, recordSkillUse } = await import('./skill-extractor.js');
+        const skillQuery = jobName + ' ' + jobPrompt.slice(0, 200);
+        const suppressedNamesRaw = memoryStore
+            ?.getSkillsToSuppress?.(agentSlug);
+        const suppressedNames = Array.isArray(suppressedNamesRaw)
+            ? new Set(suppressedNamesRaw)
+            : (suppressedNamesRaw ?? undefined);
+        const matchedSkills = searchSkills(skillQuery, 2, agentSlug, { suppressedNames });
+        if (matchedSkills.length === 0)
+            return '';
+        const skillLines = matchedSkills.map(s => {
+            recordSkillUse(s.name);
+            memoryStore?.logSkillUse?.({
+                skillName: s.name,
+                sessionKey: `cron:${agentSlug ?? 'clementine'}:${jobName}`,
+                queryText: skillQuery,
+                score: s.score,
+                agentSlug: agentSlug ?? null,
+            });
+            let block = `### ${s.title}\n${s.content}`;
+            if (s.toolsUsed.length > 0)
+                block += `\n**Tools:** ${s.toolsUsed.join(', ')}`;
+            if (s.attachments.length > 0) {
+                const attDir = path.join(s.skillDir, s.name + '.files');
+                for (const attName of s.attachments.slice(0, 3)) {
+                    const attPath = path.join(attDir, attName);
+                    if (fs.existsSync(attPath)) {
+                        try {
+                            const content = fs.readFileSync(attPath, 'utf-8').slice(0, 2000);
+                            block += `\n#### ${attName}\n\`\`\`\n${content}\n\`\`\``;
+                        }
+                        catch { /* skip */ }
+                    }
+                }
+            }
+            return block;
+        });
+        return `## Learned Procedures (from past successful executions)\nFollow these proven approaches when applicable:\n\n${skillLines.join('\n\n')}\n\n`;
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Run a cron job via the canonical SDK runAgent path.
+ *
+ * Composes the same context blocks the legacy runCronJob injects
+ * (progress, goals, delegation, team, criteria, skills, fanout
+ * directive), wires Composio + external MCP via the dedup-aware
+ * helper, then calls runAgent.
+ *
+ * The SDK handles the loop, compaction, subagent fanout, prompt
+ * caching, retries — none of which we wrap manually anymore.
+ */
+export async function runAgentCron(opts) {
+    const tier = opts.tier ?? 1;
+    const agentSlug = opts.profile?.slug;
+    const ownerName = process.env.OWNER_NAME ?? 'the user';
+    // ── Compose context blocks (mirrors legacy runCronJob) ─────────────
+    const progressContext = buildProgressContext(opts.jobName);
+    const goalContext = buildGoalContext(opts.jobName);
+    const delegationContext = buildDelegationContext(agentSlug);
+    const teamContext = buildTeamContext(agentSlug);
+    const criteriaContext = buildCriteriaContext(opts.successCriteria);
+    const skillContext = await buildSkillContext(opts.jobName, opts.jobPrompt, agentSlug, opts.memoryStore);
+    // Sub-agent fanout directive — when the job description suggests
+    // multi-item work, prepend a hard-line fanout mandate.
+    const fanoutScope = `${opts.jobName}\n${opts.jobPrompt}\n${opts.profile?.description ?? ''}\n${opts.profile?.systemPromptBody ?? ''}`;
+    const { directive: fanoutDirective, report: fanoutReport } = buildFanoutDirectiveForText(fanoutScope);
+    if (fanoutReport.needsFanout) {
+        logger.info({
+            job: opts.jobName,
+            signals: fanoutReport.signals.map(s => s.pattern),
+        }, 'runAgentCron: fanout directive injected');
+    }
+    // Final prompt (matches legacy runCronJob's structure).
+    const builtPrompt = `[Scheduled task: ${opts.jobName}]\n\n` +
+        (fanoutDirective ? fanoutDirective + '\n\n' : '') +
+        buildAlwaysOnParallelizationHint() + '\n\n' +
+        progressContext +
+        goalContext +
+        skillContext +
+        delegationContext +
+        teamContext +
+        criteriaContext +
+        `${opts.jobPrompt}\n\n` +
+        `## How to respond\n` +
+        `You're sending this directly to ${ownerName} as a DM. ` +
+        `Write like you're texting a friend — casual, warm, concise. ` +
+        `Use their name naturally. No headers, bullet lists, or formal structure unless the content genuinely needs it. ` +
+        `Skip narrating your process ("I checked X, then Y..."). Just share the interesting stuff.\n\n` +
+        `If there's genuinely nothing worth mentioning (no new data, no changes, no alerts), ` +
+        `output ONLY: __NOTHING__\n` +
+        `But lean toward sharing something — a one-liner is better than silence. ` +
+        `"Quiet morning, inbox is clean" beats __NOTHING__ if you did check things.\n\n` +
+        `After finishing your work, you MUST write a final text response with your findings — ` +
+        `only that final message gets delivered.`;
+    // ── Wire Composio + external MCP servers (same dedup as legacy) ───
+    const mcp = await buildExtraMcpForRunAgent({
+        scopeText: [
+            opts.jobName,
+            opts.jobPrompt,
+            opts.profile?.description,
+            opts.profile?.systemPromptBody,
+        ].filter(Boolean).join('\n\n'),
+        profile: opts.profile,
+    });
+    // ── Run via canonical runAgent ────────────────────────────────────
+    const maxBudget = opts.maxBudgetUsd ?? (tier >= 2 ? 3.0 : 1.0);
+    const effort = tier >= 2 ? 'high' : 'medium';
+    logger.info({
+        job: opts.jobName,
+        tier,
+        profile: agentSlug,
+        composioConnected: mcp.composioConnected,
+        externalConnected: mcp.externalConnected,
+        droppedClaudeAi: mcp.droppedClaudeAi,
+        droppedComposio: mcp.droppedComposio,
+        promptChars: builtPrompt.length,
+    }, 'runAgentCron: dispatching to runAgent');
+    const result = await runAgent(builtPrompt, {
+        sessionKey: `cron:${opts.jobName}`,
+        source: 'cron',
+        profile: opts.profile,
+        agentManager: opts.agentManager,
+        memoryStore: opts.memoryStore,
+        model: opts.model,
+        effort,
+        maxBudgetUsd: maxBudget,
+        maxTurns: opts.maxTurns,
+        abortSignal: opts.abortSignal,
+        extraMcpServers: mcp.servers,
+    });
+    return {
+        ...result,
+        builtPrompt,
+        composioConnected: mcp.composioConnected,
+        externalConnected: mcp.externalConnected,
+    };
+}
+//# sourceMappingURL=run-agent-cron.js.map

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

@@ -0,0 +1,46 @@
+/**
+ * Clementine TypeScript — MCP server wiring helper for runAgent.
+ *
+ * Phase 3 of the SDK-canonical migration (see
+ * /Users/nathan.reynolds/.claude/plans/sdk-canonical-migration.md).
+ *
+ * runAgent always wires the Clementine MCP server. This helper builds
+ * the EXTRA MCP servers callers may need (Composio toolkits, external
+ * claude.ai integrations, browser-harness, etc.), applying the same
+ * service dedup logic from 1.18.34 so we don't load duplicates of the
+ * same service from two providers.
+ *
+ * The legacy assistant.ts:buildOptions path does roughly the same
+ * thing for chat/cron — this is the standalone equivalent.
+ */
+import type { AgentProfile } from '../types.js';
+export interface BuildExtraMcpOptions {
+    /** The text we're routing on (job prompt, user message, etc). Used to pick which
+     *  Composio toolkits + external servers are relevant via the existing bundle router. */
+    scopeText?: string;
+    /** Active agent profile. When set, profile.allowedMcpServers and
+     *  profile.allowedComposioToolkits override the bundle router's choices. */
+    profile?: AgentProfile | null;
+    /** When true, build the FULL surface (no bundle filtering, no dedup).
+     *  Used by admin/debug callers; not the cron-path default. */
+    fullSurface?: boolean;
+}
+export interface BuildExtraMcpResult {
+    /** Map of additional MCP servers to merge into runAgent's mcpServers. */
+    servers: Record<string, Record<string, unknown>>;
+    /** Diagnostics: which Composio toolkits / external servers ended up live. */
+    composioConnected: string[];
+    externalConnected: string[];
+    /** Diagnostics: which services were de-duped (we kept Composio over claude.ai etc). */
+    droppedClaudeAi: string[];
+    droppedComposio: string[];
+}
+/**
+ * Build the extra MCP servers (Composio + external) for a runAgent call.
+ *
+ * Mirrors the legacy assistant.ts:buildOptions chain but as a standalone
+ * function so the runAgent path doesn't depend on PersonalAssistant
+ * instance state.
+ */
+export declare function buildExtraMcpForRunAgent(opts?: BuildExtraMcpOptions): Promise<BuildExtraMcpResult>;
+//# sourceMappingURL=run-agent-mcp.d.ts.map

package/dist/agent/run-agent-mcp.js

@@ -0,0 +1,104 @@
+/**
+ * Clementine TypeScript — MCP server wiring helper for runAgent.
+ *
+ * Phase 3 of the SDK-canonical migration (see
+ * /Users/nathan.reynolds/.claude/plans/sdk-canonical-migration.md).
+ *
+ * runAgent always wires the Clementine MCP server. This helper builds
+ * the EXTRA MCP servers callers may need (Composio toolkits, external
+ * claude.ai integrations, browser-harness, etc.), applying the same
+ * service dedup logic from 1.18.34 so we don't load duplicates of the
+ * same service from two providers.
+ *
+ * The legacy assistant.ts:buildOptions path does roughly the same
+ * thing for chat/cron — this is the standalone equivalent.
+ */
+import pino from 'pino';
+import { routeToolSurface, applyServiceDedup } from './tool-router.js';
+import { loadClaudeIntegrations, getMcpServersForAgent } from './mcp-bridge.js';
+import { loadToolPreferences, KNOWN_SERVICES } from '../integrations/tool-preferences.js';
+const logger = pino({ name: 'clementine.run-agent-mcp' });
+/**
+ * Build the extra MCP servers (Composio + external) for a runAgent call.
+ *
+ * Mirrors the legacy assistant.ts:buildOptions chain but as a standalone
+ * function so the runAgent path doesn't depend on PersonalAssistant
+ * instance state.
+ */
+export async function buildExtraMcpForRunAgent(opts = {}) {
+    const result = {
+        servers: {},
+        composioConnected: [],
+        externalConnected: [],
+        droppedClaudeAi: [],
+        droppedComposio: [],
+    };
+    // 1. Route the tool surface based on scope text.
+    let route = opts.fullSurface
+        ? {
+            bundles: [],
+            externalMcpServers: undefined,
+            composioToolkits: undefined,
+            inheritFullClaudeEnv: true,
+            fullSurface: true,
+            reason: 'full_surface',
+        }
+        : routeToolSurface(opts.scopeText ?? '');
+    // 2. Build Composio MCP servers, honoring profile allowlist when set.
+    let composioMcpServers = {};
+    try {
+        const { buildComposioMcpServers } = await import('../integrations/composio/mcp-bridge.js');
+        const profileAllowList = opts.profile?.allowedComposioToolkits;
+        const composioAllow = Array.isArray(profileAllowList)
+            ? profileAllowList
+            : route.composioToolkits;
+        composioMcpServers = await buildComposioMcpServers(composioAllow);
+    }
+    catch (err) {
+        logger.debug({ err }, 'Composio MCP servers unavailable (non-fatal)');
+    }
+    // 3. Build external MCP servers (claude.ai integrations, etc).
+    let externalMcpServers = {};
+    try {
+        const profileAllowList = Array.isArray(opts.profile?.allowedMcpServers)
+            ? opts.profile?.allowedMcpServers
+            : undefined;
+        const externalAllow = profileAllowList ?? route.externalMcpServers;
+        externalMcpServers = getMcpServersForAgent(externalAllow);
+    }
+    catch (err) {
+        logger.debug({ err }, 'External MCP servers unavailable (non-fatal)');
+    }
+    // 4. Apply service dedup so Composio outlook + claude.ai Microsoft 365
+    //    don't both load (same logic as 1.18.34).
+    if (!opts.fullSurface) {
+        try {
+            const composioConnected = new Set(Object.keys(composioMcpServers));
+            const cdIntegrations = loadClaudeIntegrations();
+            const claudeDesktopActive = new Set(Object.values(cdIntegrations).filter(i => i.connected).map(i => i.name));
+            const prefs = loadToolPreferences();
+            const dedup = applyServiceDedup(route, {
+                composioConnected,
+                claudeDesktopActive,
+                preferences: prefs.preferences,
+                knownServices: KNOWN_SERVICES,
+            });
+            route = dedup.route;
+            result.droppedClaudeAi = dedup.droppedClaudeAi;
+            result.droppedComposio = dedup.droppedComposio;
+            for (const name of dedup.droppedClaudeAi)
+                delete externalMcpServers[name];
+            for (const slug of dedup.droppedComposio)
+                delete composioMcpServers[slug];
+        }
+        catch (err) {
+            logger.debug({ err }, 'Service dedup failed (non-fatal — using full surface)');
+        }
+    }
+    // 5. Merge into one map.
+    result.servers = { ...externalMcpServers, ...composioMcpServers };
+    result.composioConnected = Object.keys(composioMcpServers);
+    result.externalConnected = Object.keys(externalMcpServers);
+    return result;
+}
+//# sourceMappingURL=run-agent-mcp.js.map

package/dist/agent/run-agent.d.ts

@@ -66,6 +66,17 @@ export interface RunAgentOptions {
     allowedTools?: string[];
     /** Optional CLAUDE.md / project setting source. Defaults to ['project']. */
     settingSources?: ('project' | 'user' | 'local')[];
+    /** Additional MCP servers to merge with the always-on clementine-tools
+     *  server. Use to wire Composio + claude.ai integrations on chat-path
+     *  invocations that need Outlook/Salesforce/etc. */
+    extraMcpServers?: Record<string, {
+        type: 'stdio' | 'http' | 'sse';
+        command?: string;
+        args?: string[];
+        env?: Record<string, string>;
+        url?: string;
+        headers?: Record<string, string>;
+    }>;
 }
 export interface RunAgentResult {
     /** Final text response from the agent. */

package/dist/agent/run-agent.js

@@ -124,6 +124,9 @@ export async function runAgent(prompt, opts) {
     // list references mcp__clementine-tools__* that don't exist in the
     // session, and the agent falls back to reading raw JSON files.
     const subprocessEnv = buildRunAgentEnv();
+    // SDK accepts a Record<string, McpServerConfig> here. We cast on
+    // assignment because we mix the always-on Clementine stdio server
+    // with caller-supplied servers of various types.
     const mcpServers = {
         [TOOLS_SERVER]: {
             type: 'stdio',
@@ -136,6 +139,7 @@ export async function runAgent(prompt, opts) {
                 CLEMENTINE_INTERACTION_SOURCE: source === 'cron' || source === 'heartbeat' ? 'autonomous' : 'interactive',
             },
         },
+        ...(opts.extraMcpServers ?? {}),
     };
     // Apply 1M-context env normalization (existing infra)
     const sdkOptionsRaw = {
@@ -144,7 +148,9 @@ export async function runAgent(prompt, opts) {
             : { type: 'preset', preset: 'claude_code' },
         settingSources: opts.settingSources ?? ['project'],
         agents,
-        mcpServers,
+        // SDK's McpServerConfig is a union; cast at the boundary since
+        // callers can mix stdio + http + sse server shapes.
+        mcpServers: mcpServers,
         allowedTools,
         permissionMode: 'bypassPermissions',
         cwd: BASE_DIR,

package/dist/gateway/router.js

@@ -2088,6 +2088,79 @@ export class Gateway {
                     delete sessState.pendingInterrupt;
                 }
                 try {
+                    // ── Phase 2: opt-in canonical SDK chat path ──────────────────
+                    // When CLEMENTINE_USE_RUNAGENT_CHAT=1 is set, route through
+                    // the new runAgent() wrapper instead of the legacy
+                    // assistant.chat path. This is the SDK-canonical pattern
+                    // (one query() call, agents map for subagents, no
+                    // wrapper layers). Today's Phase 2 connects only the
+                    // Clementine MCP server — Composio/external integrations
+                    // come in Phase 3. Useful for testing the new path on
+                    // tool-light sessions like cron-fix or memory queries.
+                    //
+                    // The legacy path (default) keeps full Composio/external
+                    // routing + all post-response handlers, so this flag is
+                    // safe to leave off until we're ready.
+                    if (process.env.CLEMENTINE_USE_RUNAGENT_CHAT === '1'
+                        && this.isTrustedPersonalSession(sessionKey)
+                        && !sessState.pendingInterrupt) {
+                        const { runAgent } = await import('../agent/run-agent.js');
+                        logger.info({
+                            sessionKey: effectiveSessionKey,
+                            profile: resolvedProfile?.slug,
+                            path: 'runagent_chat',
+                        }, 'Phase 2: routing chat through runAgent');
+                        try {
+                            const runAgentResult = await runAgent(originalText, {
+                                sessionKey: effectiveSessionKey,
+                                source: 'chat',
+                                profile: resolvedProfile,
+                                agentManager: this.getAgentManager(),
+                                memoryStore: this.assistant.getMemoryStore?.() ?? null,
+                                onText: wrappedOnText,
+                                onToolActivity: ({ tool, input }) => {
+                                    toolActivityCount++;
+                                    if (wrappedOnToolActivity) {
+                                        return wrappedOnToolActivity(tool, input);
+                                    }
+                                    return undefined;
+                                },
+                                abortSignal: chatAc.signal,
+                            });
+                            clearTimeout(chatTimer);
+                            clearTimeout(hardWallTimer);
+                            // Mirror transcript so memory + recall continue working.
+                            const memoryStore = this.assistant.getMemoryStore?.();
+                            if (memoryStore) {
+                                try {
+                                    memoryStore.saveTurn(effectiveSessionKey, 'user', originalText);
+                                    memoryStore.saveTurn(effectiveSessionKey, 'assistant', runAgentResult.text);
+                                }
+                                catch (err) {
+                                    logger.debug({ err }, 'runAgent chat: transcript mirror failed (non-fatal)');
+                                }
+                            }
+                            // Fire auto-memory extraction in the background so
+                            // MEMORY.md continues to update like the legacy path.
+                            this.assistant
+                                .triggerMemoryExtractionPostExchange(originalText, runAgentResult.text, effectiveSessionKey, resolvedProfile)
+                                .catch(err => logger.debug({ err, sessionKey: effectiveSessionKey }, 'runAgent chat: auto-memory failed (non-fatal)'));
+                            logger.info({
+                                sessionKey: effectiveSessionKey,
+                                totalMs: Date.now() - tInnerStart,
+                                routedVia: 'runagent_chat',
+                                numTurns: runAgentResult.numTurns,
+                                cost: Number(runAgentResult.totalCostUsd.toFixed(4)),
+                                responseLen: runAgentResult.text.length,
+                            }, 'chat:latency');
+                            return runAgentResult.text;
+                        }
+                        catch (err) {
+                            logger.warn({ err, sessionKey: effectiveSessionKey }, 'runAgent chat path failed — falling back to legacy chat');
+                            // Fall through to the legacy chat path so the user
+                            // still gets a response.
+                        }
+                    }
                     // ── Pre-LLM plan routing (Gap #3 from orchestration audit) ──
                     // When the user's text clearly maps to multi-step parallel
                     // work, route through the orchestrator BEFORE the main agent
@@ -2529,6 +2602,53 @@ export class Gateway {
             const cronStart = Date.now();
             try {
                 let response;
+                // ── Phase 3: opt-in canonical SDK cron path ──────────────────
+                // CLEMENTINE_USE_RUNAGENT_CRON=1 routes the job through
+                // runAgentCron() — the canonical SDK pattern. Default OFF.
+                // Falls back to legacy on error so the job always completes.
+                const useRunAgentCron = process.env.CLEMENTINE_USE_RUNAGENT_CRON === '1';
+                if (useRunAgentCron && !opts?.disableAllTools) {
+                    try {
+                        const { runAgentCron } = await import('../agent/run-agent-cron.js');
+                        const profile = agentSlug && agentSlug !== 'clementine'
+                            ? this.getAgentManager().get(agentSlug) ?? null
+                            : null;
+                        logger.info({ jobName, agentSlug, tier, path: 'runagent_cron' }, 'Phase 3: routing cron through runAgentCron');
+                        const cronResult = await runAgentCron({
+                            jobName,
+                            jobPrompt,
+                            tier,
+                            maxTurns,
+                            profile,
+                            agentManager: this.getAgentManager(),
+                            memoryStore: this.assistant.getMemoryStore?.() ?? null,
+                            successCriteria,
+                            model,
+                            workDir,
+                        });
+                        response = cronResult.text;
+                        scanner.refreshIntegrity();
+                        events.emit('cron:complete', {
+                            jobName,
+                            mode: 'runagent',
+                            durationMs: Date.now() - cronStart,
+                            responseLength: response?.length ?? 0,
+                        });
+                        logger.info({
+                            jobName,
+                            cost: Number(cronResult.totalCostUsd.toFixed(4)),
+                            numTurns: cronResult.numTurns,
+                            composioConnected: cronResult.composioConnected.length,
+                            externalConnected: cronResult.externalConnected.length,
+                            durationMs: Date.now() - cronStart,
+                        }, 'runAgentCron: cron job complete');
+                        return response;
+                    }
+                    catch (err) {
+                        logger.warn({ err, jobName }, 'runAgentCron path failed — falling back to legacy cron path');
+                        // Fall through to legacy below.
+                    }
+                }
                 if (mode === 'unleashed') {
                     response = await this.assistant.runUnleashedTask(jobName, jobPrompt, tier, maxTurns, model, workDir, maxHours, agentSlug);
                 }

package/package.json

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