clementine-agent 1.18.169 → 1.18.171

package/dist/agent/background-tasks.js

@@ -113,6 +113,14 @@ export function markRunning(id, opts) {
     safeWrite(pathFor(id, opts), task);
     return task;
 }
+function writeFullResultFile(id, result, opts) {
+    if (result.length <= RESULT_TRUNCATE_BYTES)
+        return undefined;
+    const file = path.join(dirFor(opts), `${id}.result.md`);
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, result);
+    return file;
+}
 /** Transition to 'done' with final result. */
 export function markDone(id, result, deliverableNote, opts) {
     const task = loadBackgroundTask(id, opts);
@@ -122,9 +130,14 @@ export function markDone(id, result, deliverableNote, opts) {
         return task;
     task.status = 'done';
     task.completedAt = new Date().toISOString();
+    const resultPath = writeFullResultFile(id, result, opts);
+    if (resultPath)
+        task.resultPath = resultPath;
     task.result = result;
     if (deliverableNote)
         task.deliverableNote = deliverableNote;
+    else if (resultPath)
+        task.deliverableNote = resultPath;
     safeWrite(pathFor(id, opts), task);
     return task;
 }

package/dist/agent/chat-skill-resolver.d.ts

@@ -0,0 +1,117 @@
+/**
+ * chat-skill-resolver — match a chat message against the skill catalog,
+ * extract the MCP servers / toolkits the matched skills imply, and
+ * produce a system-prompt block listing them as "Relevant Skills."
+ *
+ * Why this exists (1.18.170)
+ * ──────────────────────────
+ * Before this module, the modern chat path (`router.ts → runAgent`) did
+ * three things in order:
+ *   1. Build extra MCP servers from `routeToolSurface(userText)` — a
+ *      regex-bundle matcher over 19 fixed bundles in `tool-router.ts`.
+ *   2. Build vault context (SOUL.md / MEMORY.md / AGENTS.md).
+ *   3. Call runAgent with the assembled pieces.
+ *
+ * Step 1 has a fundamental gap: anything outside the 19 hardcoded
+ * bundles (Salesforce, HubSpot, Asana, ClickUp, Airtable, an installed
+ * CLI like `sf`) silently fails to route. The model gets no Salesforce
+ * tools loaded even when the user just connected the Salesforce MCP.
+ *
+ * Clementine already auto-generates one skill per MCP tool whenever a
+ * server's schema is fetched (`auto-skills.ts` → `~/.clementine/vault/
+ * 00-System/skills/auto/<server>/<tool>.md`). Those auto-skills include
+ * server-aware triggers ("salesforce", "my salesforce", "query records
+ * salesforce", …) and a `mcp__<server>__<tool>` reference in their body.
+ *
+ * The legacy chat path (`assistant.ts:1487-1538`) already searched the
+ * skill catalog and injected a "## Relevant Skill" block — but that
+ * code lives in the deprecated PersonalAssistant.query() path. The
+ * modern runAgent path skipped it entirely.
+ *
+ * This module ports + extends the legacy behavior:
+ *   • Top-3 match aggregation (not just top-1) — handles category queries
+ *     like "salesforce" where many tool-specific auto-skills match
+ *     similarly. The parent sees all 3 bodies and picks the right tool.
+ *   • Extracts `mcp__<server>__<tool>` references from every matched
+ *     skill's body. Used to widen `buildExtraMcpForRunAgent` so the
+ *     right Composio toolkits / claude.ai integrations load even though
+ *     "Salesforce" isn't in the regex-bundle list.
+ *   • Extracts `clementine.tools.allow` from user-authored skills (the
+ *     auto-skills don't set this field but human-authored ones often do).
+ *   • Auto-skills get a small penalty in `searchSkills` already (-0.5)
+ *     so user-authored skills outrank them at parity — preserved here.
+ *
+ * Not a sandbox: we never *restrict* tools based on matched skills (the
+ * SDK still receives the parent's full allowedTools). We only widen the
+ * MCP server selection. Hard tool-scope enforcement happens via the
+ * `runSkill` primitive (`run-skill.ts:300`), not chat.
+ *
+ * Failure mode: this module never throws. A match search that errors
+ * (corrupt skill file, missing dir, etc.) returns empty results and the
+ * caller proceeds with `routeToolSurface` alone — i.e. today's behavior.
+ */
+import { type SkillMatch } from './skill-extractor.js';
+import type { AgentProfile } from '../types.js';
+import type { MemoryStore } from '../memory/store.js';
+export interface ResolveSkillsOptions {
+    /** Active hired-agent profile, when set. Used for agent-scoped skill
+     *  priority (matches the legacy boost). */
+    profile?: AgentProfile | null;
+    /** Optional memory store — used to read the user's suppression list
+     *  ("never auto-match this skill again"). */
+    memoryStore?: MemoryStore | null;
+    /** Override the top-K aggregation cap. Defaults to 3. */
+    limit?: number;
+    /** Override the minimum match score. Defaults to 4. */
+    minScore?: number;
+}
+export interface ResolvedSkillContext {
+    /** Match records from searchSkills, filtered to those above minScore
+     *  and capped at `limit`. Length 0 means no skill matched — the
+     *  caller should fall back to today's behavior (regex bundles only). */
+    matches: SkillMatch[];
+    /** MCP server slugs referenced by any matched skill's body. Caller
+     *  unions this with `route.externalMcpServers` and `route.composioToolkits`. */
+    hintedMcpServers: string[];
+    /** Tools declared under `clementine.tools.allow` on matched skills.
+     *  Caller can use these to widen the SDK's `allowedTools` if the
+     *  matched skill expects access beyond the chat default. */
+    hintedTools: string[];
+    /** Pre-rendered "## Relevant Skills" markdown block, ready to append
+     *  to the system prompt. Empty when `matches.length === 0`. */
+    promptBlock: string;
+    /** Diagnostics for log/telemetry. */
+    diagnostics: {
+        queryChars: number;
+        candidatesConsidered: number;
+        matchesAboveThreshold: number;
+        topScore: number;
+        mcpRefsExtracted: number;
+    };
+}
+/** Extract the `mcp__<server>__<tool>` server-name component from a
+ *  match's body content + frontmatter. Returns the set of server slugs. */
+declare function extractMcpServersFromMatch(match: SkillMatch): string[];
+/** Extract `clementine.tools.allow` from a match's frontmatter.
+ *  Returns the list of declared tool names (or [] if none). */
+declare function extractAllowedToolsFromMatch(match: SkillMatch): string[];
+/**
+ * Render the system-prompt block injected for the matched skills.
+ * Single-match keeps the legacy `## Relevant Skill: <title>` shape;
+ * multi-match nests them under `## Relevant Skills` with per-skill
+ * subheadings. Tools-required warnings (legacy `assistant.ts:1504-1513`)
+ * are NOT included here — they belong to the run-time tool policy
+ * check, not the prompt context.
+ */
+declare function renderPromptBlock(matches: SkillMatch[]): string;
+/**
+ * Match a user message against the skill catalog and return the routing
+ * hints + prompt block the chat path should layer on top of the static
+ * `routeToolSurface` decision.
+ *
+ * Never throws — telemetry / matching errors degrade gracefully to
+ * empty hints, and the caller proceeds with today's behavior.
+ */
+export declare function resolveSkillsForChat(userMessage: string, opts?: ResolveSkillsOptions): ResolvedSkillContext;
+export { extractMcpServersFromMatch, extractAllowedToolsFromMatch, renderPromptBlock };
+//# sourceMappingURL=chat-skill-resolver.d.ts.map

package/dist/agent/chat-skill-resolver.js

@@ -0,0 +1,282 @@
+/**
+ * chat-skill-resolver — match a chat message against the skill catalog,
+ * extract the MCP servers / toolkits the matched skills imply, and
+ * produce a system-prompt block listing them as "Relevant Skills."
+ *
+ * Why this exists (1.18.170)
+ * ──────────────────────────
+ * Before this module, the modern chat path (`router.ts → runAgent`) did
+ * three things in order:
+ *   1. Build extra MCP servers from `routeToolSurface(userText)` — a
+ *      regex-bundle matcher over 19 fixed bundles in `tool-router.ts`.
+ *   2. Build vault context (SOUL.md / MEMORY.md / AGENTS.md).
+ *   3. Call runAgent with the assembled pieces.
+ *
+ * Step 1 has a fundamental gap: anything outside the 19 hardcoded
+ * bundles (Salesforce, HubSpot, Asana, ClickUp, Airtable, an installed
+ * CLI like `sf`) silently fails to route. The model gets no Salesforce
+ * tools loaded even when the user just connected the Salesforce MCP.
+ *
+ * Clementine already auto-generates one skill per MCP tool whenever a
+ * server's schema is fetched (`auto-skills.ts` → `~/.clementine/vault/
+ * 00-System/skills/auto/<server>/<tool>.md`). Those auto-skills include
+ * server-aware triggers ("salesforce", "my salesforce", "query records
+ * salesforce", …) and a `mcp__<server>__<tool>` reference in their body.
+ *
+ * The legacy chat path (`assistant.ts:1487-1538`) already searched the
+ * skill catalog and injected a "## Relevant Skill" block — but that
+ * code lives in the deprecated PersonalAssistant.query() path. The
+ * modern runAgent path skipped it entirely.
+ *
+ * This module ports + extends the legacy behavior:
+ *   • Top-3 match aggregation (not just top-1) — handles category queries
+ *     like "salesforce" where many tool-specific auto-skills match
+ *     similarly. The parent sees all 3 bodies and picks the right tool.
+ *   • Extracts `mcp__<server>__<tool>` references from every matched
+ *     skill's body. Used to widen `buildExtraMcpForRunAgent` so the
+ *     right Composio toolkits / claude.ai integrations load even though
+ *     "Salesforce" isn't in the regex-bundle list.
+ *   • Extracts `clementine.tools.allow` from user-authored skills (the
+ *     auto-skills don't set this field but human-authored ones often do).
+ *   • Auto-skills get a small penalty in `searchSkills` already (-0.5)
+ *     so user-authored skills outrank them at parity — preserved here.
+ *
+ * Not a sandbox: we never *restrict* tools based on matched skills (the
+ * SDK still receives the parent's full allowedTools). We only widen the
+ * MCP server selection. Hard tool-scope enforcement happens via the
+ * `runSkill` primitive (`run-skill.ts:300`), not chat.
+ *
+ * Failure mode: this module never throws. A match search that errors
+ * (corrupt skill file, missing dir, etc.) returns empty results and the
+ * caller proceeds with `routeToolSurface` alone — i.e. today's behavior.
+ */
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { existsSync } from 'node:fs';
+import matter from 'gray-matter';
+import pino from 'pino';
+import { searchSkills } from './skill-extractor.js';
+const logger = pino({ name: 'clementine.chat-skill-resolver' });
+// ── Tunables ──────────────────────────────────────────────────────────
+/** Default minimum score to consider a skill match real. Mirrors the
+ *  legacy `assistant.ts:1492` threshold. Skill auto-match is heuristic;
+ *  this filter keeps weak matches from injecting unrelated tooling. */
+const DEFAULT_MIN_SCORE = 4;
+/** Default top-K matches to aggregate. Single-tool requests usually
+ *  return one strong match; category requests ("salesforce") return
+ *  several similarly-scored auto-skills. Top-3 covers both. Raising
+ *  this bloats the system prompt without much routing benefit. */
+const DEFAULT_TOP_K = 3;
+/** Cap per-skill body excerpt in the injected prompt. The full body is
+ *  often a multi-KB args table for an MCP tool — fine if the user
+ *  needs to look at it, wasteful for routing context. Mirrors
+ *  `assistant.ts:1501` which sliced at 800 chars. */
+const PER_SKILL_BODY_CHARS = 1000;
+/** Same MCP_TOOL_REF pattern used in `run-skill.ts:153` / `tool-router.ts:172`.
+ *  Matches `mcp__<server>__<tool>` references inside skill body text. */
+const MCP_TOOL_REF = /mcp__([A-Za-z0-9-]+(?:_[A-Za-z0-9-]+)*)__[A-Za-z0-9_-]+/g;
+// ── Skill discovery support ──────────────────────────────────────────
+/**
+ * Find a matched skill's frontmatter on disk. `SkillMatch` carries
+ * `name` + `skillDir` but not the full frontmatter — and we need
+ * `clementine.tools.allow` + the explicit `tool:` field from auto-skills.
+ *
+ * Walks `<skillDir>` looking for any file whose basename or folder
+ * matches `name`. Returns null on any failure; the caller already has
+ * the matched body content from searchSkills and that's enough for
+ * MCP-ref extraction. The frontmatter read here is opportunistic.
+ */
+function readMatchFrontmatter(match) {
+    // The match's `skillDir` is the SEARCH root. Auto-skills live nested
+    // under `<skillDir>/auto/<server>/<tool>.md`; user skills can be flat
+    // (`<skillDir>/<slug>.md`) or folder-form (`<skillDir>/<slug>/SKILL.md`).
+    const slug = match.name;
+    const candidates = [
+        join(match.skillDir, `${slug}.md`),
+        join(match.skillDir, slug, 'SKILL.md'),
+    ];
+    // For auto-skill slugs like `auto-dataforseo-…`, also try the nested
+    // path that the slug encodes. This is a best-effort lookup; on miss
+    // we just skip frontmatter and use the body alone.
+    if (slug.startsWith('auto-')) {
+        const parts = slug.slice(5).split('-');
+        if (parts.length >= 2) {
+            const server = parts[0];
+            const rest = parts.slice(1).join('-');
+            candidates.push(join(match.skillDir, 'auto', server, `${rest}.md`));
+        }
+    }
+    for (const p of candidates) {
+        try {
+            if (!existsSync(p))
+                continue;
+            const raw = readFileSync(p, 'utf-8');
+            const parsed = matter(raw);
+            return parsed.data;
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    return null;
+}
+/** Extract the `mcp__<server>__<tool>` server-name component from a
+ *  match's body content + frontmatter. Returns the set of server slugs. */
+function extractMcpServersFromMatch(match) {
+    const servers = new Set();
+    // From body text — works for auto-skills (which list the tool name
+    // in their "## Tool call" section) and user skills that paste tool
+    // refs into their instructions.
+    MCP_TOOL_REF.lastIndex = 0;
+    let m;
+    while ((m = MCP_TOOL_REF.exec(match.content)) !== null) {
+        servers.add(m[1]);
+    }
+    // From frontmatter — auto-skills have `tool: mcp__<server>__<name>` AND
+    // `server: <name>` set explicitly. Either is authoritative.
+    const fm = readMatchFrontmatter(match);
+    if (fm) {
+        if (typeof fm.server === 'string' && fm.server.trim()) {
+            servers.add(fm.server.trim());
+        }
+        if (typeof fm.tool === 'string') {
+            const mm = MCP_TOOL_REF.exec(fm.tool);
+            if (mm)
+                servers.add(mm[1]);
+            MCP_TOOL_REF.lastIndex = 0;
+        }
+    }
+    return [...servers];
+}
+/** Extract `clementine.tools.allow` from a match's frontmatter.
+ *  Returns the list of declared tool names (or [] if none). */
+function extractAllowedToolsFromMatch(match) {
+    const fm = readMatchFrontmatter(match);
+    if (!fm)
+        return [];
+    const clementine = fm.clementine;
+    const allow = clementine?.tools?.allow;
+    if (!Array.isArray(allow))
+        return [];
+    return allow.filter((t) => typeof t === 'string' && t.length > 0);
+}
+// ── Prompt rendering ──────────────────────────────────────────────────
+/**
+ * Render the system-prompt block injected for the matched skills.
+ * Single-match keeps the legacy `## Relevant Skill: <title>` shape;
+ * multi-match nests them under `## Relevant Skills` with per-skill
+ * subheadings. Tools-required warnings (legacy `assistant.ts:1504-1513`)
+ * are NOT included here — they belong to the run-time tool policy
+ * check, not the prompt context.
+ */
+function renderPromptBlock(matches) {
+    if (matches.length === 0)
+        return '';
+    if (matches.length === 1) {
+        const s = matches[0];
+        return `## Relevant Skill: ${s.title}\n\n${s.content.slice(0, PER_SKILL_BODY_CHARS)}`;
+    }
+    const parts = ['## Relevant Skills', ''];
+    parts.push(`Top ${matches.length} skill matches for this request, ordered by relevance. ` +
+        `Use these as a guide for which tools to call. If multiple skills suggest the same MCP server, ` +
+        `prefer the highest-scored one's procedure.\n`);
+    for (let i = 0; i < matches.length; i++) {
+        const s = matches[i];
+        parts.push(`### ${i + 1}. ${s.title}`, '');
+        parts.push(s.content.slice(0, PER_SKILL_BODY_CHARS));
+        parts.push('');
+    }
+    return parts.join('\n');
+}
+// ── Public entry point ────────────────────────────────────────────────
+/**
+ * Match a user message against the skill catalog and return the routing
+ * hints + prompt block the chat path should layer on top of the static
+ * `routeToolSurface` decision.
+ *
+ * Never throws — telemetry / matching errors degrade gracefully to
+ * empty hints, and the caller proceeds with today's behavior.
+ */
+export function resolveSkillsForChat(userMessage, opts = {}) {
+    const queryChars = userMessage.length;
+    const empty = {
+        matches: [],
+        hintedMcpServers: [],
+        hintedTools: [],
+        promptBlock: '',
+        diagnostics: {
+            queryChars,
+            candidatesConsidered: 0,
+            matchesAboveThreshold: 0,
+            topScore: 0,
+            mcpRefsExtracted: 0,
+        },
+    };
+    if (!userMessage || !userMessage.trim())
+        return empty;
+    const limit = Math.max(1, opts.limit ?? DEFAULT_TOP_K);
+    const minScore = opts.minScore ?? DEFAULT_MIN_SCORE;
+    const suppressedNames = opts.memoryStore?.getSkillsToSuppress?.(opts.profile?.slug);
+    let candidates = [];
+    try {
+        candidates = searchSkills(userMessage, 
+        // Ask for a bit more than `limit` so we can filter by minScore and
+        // still hit the cap when the distribution has a tail of weak hits.
+        Math.max(limit + 2, 5), opts.profile?.slug, { ...(suppressedNames ? { suppressedNames } : {}) });
+    }
+    catch (err) {
+        logger.debug({ err }, 'chat-skill-resolver: searchSkills failed (non-fatal)');
+        return empty;
+    }
+    const matches = candidates
+        .filter((m) => m.score >= minScore)
+        .slice(0, limit);
+    if (matches.length === 0) {
+        return {
+            ...empty,
+            diagnostics: {
+                queryChars,
+                candidatesConsidered: candidates.length,
+                matchesAboveThreshold: 0,
+                topScore: candidates[0]?.score ?? 0,
+                mcpRefsExtracted: 0,
+            },
+        };
+    }
+    const mcpServerSet = new Set();
+    const toolSet = new Set();
+    for (const m of matches) {
+        for (const s of extractMcpServersFromMatch(m))
+            mcpServerSet.add(s);
+        for (const t of extractAllowedToolsFromMatch(m))
+            toolSet.add(t);
+    }
+    const result = {
+        matches,
+        hintedMcpServers: [...mcpServerSet],
+        hintedTools: [...toolSet],
+        promptBlock: renderPromptBlock(matches),
+        diagnostics: {
+            queryChars,
+            candidatesConsidered: candidates.length,
+            matchesAboveThreshold: matches.length,
+            topScore: matches[0].score,
+            mcpRefsExtracted: mcpServerSet.size,
+        },
+    };
+    logger.info({
+        matches: matches.map(m => ({ name: m.name, score: Number(m.score.toFixed(2)) })),
+        hintedMcpServers: result.hintedMcpServers,
+        hintedToolCount: result.hintedTools.length,
+        queryChars,
+    }, 'chat-skill-resolver: skills matched');
+    return result;
+}
+// Re-export the helpers so tests can target them directly.
+export { extractMcpServersFromMatch, extractAllowedToolsFromMatch, renderPromptBlock };
+// Silence lint for the dirname import — kept for future use when the
+// matcher needs the parent folder of a matched skill (e.g. to surface
+// bundled attachments in the prompt). Removing the import would be a
+// pre-emptive cleanup but the file is already tagged for follow-up work.
+void dirname;
+//# sourceMappingURL=chat-skill-resolver.js.map

package/dist/agent/complex-task-detector.d.ts

@@ -0,0 +1,9 @@
+export interface ComplexTaskRecommendation {
+    score: number;
+    reasons: string[];
+    suggestedMaxMinutes: number;
+    plan: string[];
+    queueImmediately: boolean;
+}
+export declare function detectComplexTaskForBackground(text: string): ComplexTaskRecommendation | null;
+//# sourceMappingURL=complex-task-detector.d.ts.map

package/dist/agent/complex-task-detector.js

@@ -0,0 +1,118 @@
+const SKILL_AUTHORING_RE = /\b(create|make|build|draft|write|teach|save|update)\b.{0,40}\b(skill|SKILL\.md)\b|\bskill[- ]creator\b/i;
+const EXPLICIT_BACKGROUND_RE = /\b(background|deep mode|keep working|don't stop|dont stop|autonomous|long[- ]running|run overnight|take your time)\b/i;
+const COMPLEX_WORK_RE = /\b(audit|research|analy[sz]e|review|scrape|crawl|extract|enrich|compile|compare|verify|cross[- ]check|triage|reconcile|draft|generate|update|sync|report back|write back)\b/i;
+const BATCH_RE = /\b(all|every|each|bulk|batch|list of|contacts?|leads?|accounts?|tasks?|tickets?|records?|rows?|pages?|repos?|projects?)\b/i;
+const SIDE_EFFECT_RE = /\b(update|write|create|draft|send|post|comment|reply|upload|append|sync|mark|close|move)\b/i;
+const MULTI_STEP_RE = /\b(and then|then|after that|finally|from .* to |against .* and |across|compile .* into|check .* then)\b/i;
+const SYSTEM_KEYWORDS = [
+    'asana',
+    'salesforce',
+    'google sheet',
+    'google sheets',
+    'sheet',
+    'sheets',
+    'dataforseo',
+    'hubspot',
+    'notion',
+    'github',
+    'gmail',
+    'outlook',
+    'slack',
+    'discord',
+    'website',
+    'websites',
+    'crm',
+    'spreadsheet',
+    'csv',
+    'airtable',
+    'linear',
+    'jira',
+];
+function countSystemMentions(text) {
+    const lower = text.toLowerCase();
+    let count = 0;
+    for (const keyword of SYSTEM_KEYWORDS) {
+        if (lower.includes(keyword))
+            count++;
+    }
+    return count;
+}
+function estimatedMinutes(score, systemCount) {
+    if (score >= 8 || systemCount >= 4)
+        return 90;
+    if (score >= 6 || systemCount >= 3)
+        return 60;
+    return 30;
+}
+function buildPlan(text, systemCount) {
+    const lower = text.toLowerCase();
+    const plan = [];
+    plan.push('Confirm the exact scope, filters, and write/send permissions before making side-effecting changes.');
+    if (systemCount > 0) {
+        plan.push('Connect to the named systems with official MCP/API/CLI tools and use the narrowest reliable query.');
+    }
+    else {
+        plan.push('Gather the source material with the available project, file, web, memory, or CLI tools.');
+    }
+    if (BATCH_RE.test(text)) {
+        plan.push('Process records in batches, track counts, and keep skipped/error records separate.');
+    }
+    if (lower.includes('enrich') || lower.includes('dataforseo')) {
+        plan.push('Enrich only qualified records and keep the signal used for each output row or draft.');
+    }
+    if (SIDE_EFFECT_RE.test(text)) {
+        plan.push('Create drafts or updates first; only send or commit irreversible changes after explicit approval.');
+    }
+    plan.push('Return a concise final report with counts, changed locations, failures, and recommended next action.');
+    return plan.slice(0, 6);
+}
+export function detectComplexTaskForBackground(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return null;
+    if (SKILL_AUTHORING_RE.test(trimmed))
+        return null;
+    const systemCount = countSystemMentions(trimmed);
+    const reasons = [];
+    let score = 0;
+    if (EXPLICIT_BACKGROUND_RE.test(trimmed)) {
+        score += 4;
+        reasons.push('explicit background/deep-work wording');
+    }
+    if (COMPLEX_WORK_RE.test(trimmed)) {
+        score += 2;
+        reasons.push('multi-step work verb');
+    }
+    if (BATCH_RE.test(trimmed)) {
+        score += 2;
+        reasons.push('batch or many-record scope');
+    }
+    if (SIDE_EFFECT_RE.test(trimmed)) {
+        score += 1;
+        reasons.push('write/draft/update side effects');
+    }
+    if (MULTI_STEP_RE.test(trimmed)) {
+        score += 1;
+        reasons.push('multi-step sequencing');
+    }
+    if (systemCount >= 2) {
+        score += Math.min(4, systemCount);
+        reasons.push(`${systemCount} named systems or data surfaces`);
+    }
+    if (trimmed.length > 450) {
+        score += 1;
+        reasons.push('long detailed request');
+    }
+    const queueImmediately = EXPLICIT_BACKGROUND_RE.test(trimmed) && score >= 5;
+    const shouldOffer = queueImmediately || score >= 5 || (systemCount >= 2 && (BATCH_RE.test(trimmed) || SIDE_EFFECT_RE.test(trimmed)));
+    if (!shouldOffer)
+        return null;
+    return {
+        score,
+        reasons,
+        suggestedMaxMinutes: estimatedMinutes(score, systemCount),
+        plan: buildPlan(trimmed, systemCount),
+        queueImmediately,
+    };
+}
+//# sourceMappingURL=complex-task-detector.js.map

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

@@ -24,6 +24,19 @@ export interface BuildExtraMcpOptions {
     /** When true, build the FULL surface (no bundle filtering, no dedup).
      *  Used by admin/debug callers; not the cron-path default. */
     fullSurface?: boolean;
+    /**
+     * Additional MCP server slugs that should be considered "in scope" beyond
+     * what `routeToolSurface(scopeText)` produced. The chat path (1.18.170)
+     * derives these from `mcp__<server>__<tool>` references on auto-matched
+     * skills — see `chat-skill-resolver.ts`. The same slug is tried as both a
+     * Composio toolkit and an external MCP server name, mirroring the
+     * `explicit_mcp` handling in `tool-router.ts:223-234` so whichever source
+     * is actually connected mounts and the other no-ops.
+     *
+     * Profile-level allowlists still WIN over these hints — a hint cannot
+     * loosen a profile-restricted agent's tool surface.
+     */
+    skillHintedMcpServers?: string[];
 }
 export interface BuildExtraMcpResult {
     /** Map of additional MCP servers to merge into runAgent's mcpServers. */

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

@@ -44,6 +44,36 @@ export async function buildExtraMcpForRunAgent(opts = {}) {
             reason: 'full_surface',
         }
         : routeToolSurface(opts.scopeText ?? '');
+    // 1b. Widen with skill-hinted MCP servers (1.18.170). Each hint slug is
+    //     tried as both an external MCP server name and a Composio toolkit;
+    //     unmatched/disconnected ones no-op below at server-construction time.
+    //     We don't touch `route` when `fullSurface` is set — nothing to widen.
+    if (!opts.fullSurface && opts.skillHintedMcpServers && opts.skillHintedMcpServers.length > 0) {
+        const ext = new Set(Array.isArray(route.externalMcpServers) ? route.externalMcpServers : []);
+        const com = new Set(Array.isArray(route.composioToolkits) ? route.composioToolkits : []);
+        for (const slug of opts.skillHintedMcpServers) {
+            const trimmed = slug.trim();
+            if (!trimmed)
+                continue;
+            if (trimmed.startsWith('claude_ai_')) {
+                ext.add(trimmed.slice('claude_ai_'.length));
+            }
+            else {
+                ext.add(trimmed);
+                com.add(trimmed);
+            }
+        }
+        // Keep the existing reason union ('empty' | 'matched' | 'full_surface').
+        // The widening just lifts an 'empty' route into 'matched' once we've
+        // added any skill-derived server. Diagnostics about skill_hint
+        // contribution flow via the caller's log line.
+        route = {
+            ...route,
+            externalMcpServers: [...ext],
+            composioToolkits: [...com],
+            reason: ext.size > 0 || com.size > 0 ? 'matched' : route.reason,
+        };
+    }
     // 2. Build Composio MCP servers, honoring profile allowlist when set.
     let composioMcpServers = {};
     try {