strapi-plugin-ai-sdk 0.6.7 → 0.6.9

package/dist/_chunks/{App-31DoeBYs.js → App-C_BH5Ir4.js}

@@ -6,7 +6,7 @@ const reactRouterDom = require("react-router-dom");
 const designSystem = require("@strapi/design-system");
 const react = require("react");
 const styled = require("styled-components");
-const index = require("./index-tCUlQhF4.js");
+const index = require("./index-DCEjJ0as.js");
 const icons = require("@strapi/icons");
 const Markdown = require("react-markdown");
 const remarkGfm = require("remark-gfm");
@@ -688,6 +688,21 @@ const ToolCallHeader = styled__default.default.button`
     background: #dcdce4;
   }
 `;
+const Spinner = styled__default.default.span`
+  display: inline-block;
+  width: 12px;
+  height: 12px;
+  border: 2px solid #a5a5ba;
+  border-top-color: #4945ff;
+  border-radius: 50%;
+  animation: spin 0.8s linear infinite;
+  margin-left: auto;
+  flex-shrink: 0;
+
+  @keyframes spin {
+    to { transform: rotate(360deg); }
+  }
+`;
 const ToolCallContent = styled__default.default.pre`
   margin: 0;
   padding: 8px 12px;
@@ -739,7 +754,7 @@ function ToolCallDisplay({ toolCall }) {
         "Tool: ",
         toolCall.toolName
       ] }),
-      toolCall.output !== void 0 && /* @__PURE__ */ jsxRuntime.jsx("span", { style: { marginLeft: "auto", fontWeight: 400, opacity: 0.6 }, children: "completed" })
+      toolCall.output === void 0 ? /* @__PURE__ */ jsxRuntime.jsx(Spinner, {}) : /* @__PURE__ */ jsxRuntime.jsx("span", { style: { marginLeft: "auto", fontWeight: 400, opacity: 0.6 }, children: "completed" })
     ] }),
     contentLinks.length > 0 && /* @__PURE__ */ jsxRuntime.jsx(ContentLinksRow, { children: contentLinks.map((link) => /* @__PURE__ */ jsxRuntime.jsx(ContentLinkChip, { to: link.to, children: link.label }, link.to)) }),
     expanded && /* @__PURE__ */ jsxRuntime.jsx(ToolCallContent, { children: toolCall.output === void 0 ? "Waiting for result..." : JSON.stringify(toolCall.output, null, 2) })
@@ -846,6 +861,29 @@ const TypingDots = styled__default.default.span`
     40% { transform: scale(1); opacity: 1; }
   }
 `;
+const ThinkingIndicator = styled__default.default.div`
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  margin-top: 8px;
+  padding: 6px 0;
+  font-size: 12px;
+  color: #666687;
+`;
+const ThinkingSpinner = styled__default.default.span`
+  display: inline-block;
+  width: 14px;
+  height: 14px;
+  border: 2px solid #dcdce4;
+  border-top-color: #4945ff;
+  border-radius: 50%;
+  animation: spin 0.8s linear infinite;
+  flex-shrink: 0;
+
+  @keyframes spin {
+    to { transform: rotate(360deg); }
+  }
+`;
 const EmptyState = styled__default.default.div`
   display: flex;
   flex-direction: column;
@@ -884,8 +922,11 @@ const MessageList = react.forwardRef(
         /* @__PURE__ */ jsxRuntime.jsx(designSystem.Typography, { variant: "beta", textColor: "neutral400", children: "AI Chat" }),
         /* @__PURE__ */ jsxRuntime.jsx(designSystem.Box, { paddingTop: 2, children: /* @__PURE__ */ jsxRuntime.jsx(designSystem.Typography, { variant: "omega", textColor: "neutral500", children: "Send a message to start the conversation" }) })
       ] }),
-      messages.map((message) => {
+      messages.map((message, index2) => {
         const displayContent = message.role === "assistant" && message.content ? autoLinkContentTypeUids(message.content) : message.content;
+        const isLastMessage = index2 === messages.length - 1;
+        const hasToolsRunning = message.toolCalls?.some((tc) => tc.output === void 0) ?? false;
+        const showThinking = isLoading && isLastMessage && message.role === "assistant" && displayContent && hasToolsRunning;
         return /* @__PURE__ */ jsxRuntime.jsxs(MessageRow, { $isUser: message.role === "user", children: [
           message.role === "assistant" && /* @__PURE__ */ jsxRuntime.jsx(SparkleIcon, { children: /* @__PURE__ */ jsxRuntime.jsx(icons.Sparkle, {}) }),
           /* @__PURE__ */ jsxRuntime.jsxs(MessageBubble, { $isUser: message.role === "user", children: [
@@ -897,7 +938,11 @@ const MessageList = react.forwardRef(
               /* @__PURE__ */ jsxRuntime.jsx("span", {}),
               /* @__PURE__ */ jsxRuntime.jsx("span", {})
             ] }),
-            message.toolCalls?.filter((tc) => !HIDDEN_TOOLS.has(tc.toolName)).map((tc) => /* @__PURE__ */ jsxRuntime.jsx(ToolCallDisplay, { toolCall: tc }, tc.toolCallId))
+            message.toolCalls?.filter((tc) => !HIDDEN_TOOLS.has(tc.toolName)).map((tc) => /* @__PURE__ */ jsxRuntime.jsx(ToolCallDisplay, { toolCall: tc }, tc.toolCallId)),
+            showThinking && /* @__PURE__ */ jsxRuntime.jsxs(ThinkingIndicator, { children: [
+              /* @__PURE__ */ jsxRuntime.jsx(ThinkingSpinner, {}),
+              "Working on it…"
+            ] })
           ] })
         ] }, message.id);
       }),

package/dist/_chunks/{App-k5doNU8o.mjs → App-DKyCb0BY.mjs}

@@ -4,7 +4,7 @@ import { Link, useNavigate, Routes, Route } from "react-router-dom";
 import { Box, Typography, TextInput, Button, Main, SearchForm, Searchbar, Table, Thead, Tr, Th, Tbody, Td, Flex, Pagination, Modal, Field, Textarea, SingleSelect, SingleSelectOption } from "@strapi/design-system";
 import { useState, useEffect, useCallback, forwardRef, useRef, useMemo } from "react";
 import styled from "styled-components";
-import { P as PLUGIN_ID } from "./index-C6UZ9D-c.mjs";
+import { P as PLUGIN_ID } from "./index-BV9DET_M.mjs";
 import { Plus, Trash, Sparkle, ArrowLeft, Pencil } from "@strapi/icons";
 import Markdown from "react-markdown";
 import remarkGfm from "remark-gfm";
@@ -682,6 +682,21 @@ const ToolCallHeader = styled.button`
     background: #dcdce4;
   }
 `;
+const Spinner = styled.span`
+  display: inline-block;
+  width: 12px;
+  height: 12px;
+  border: 2px solid #a5a5ba;
+  border-top-color: #4945ff;
+  border-radius: 50%;
+  animation: spin 0.8s linear infinite;
+  margin-left: auto;
+  flex-shrink: 0;
+
+  @keyframes spin {
+    to { transform: rotate(360deg); }
+  }
+`;
 const ToolCallContent = styled.pre`
   margin: 0;
   padding: 8px 12px;
@@ -733,7 +748,7 @@ function ToolCallDisplay({ toolCall }) {
         "Tool: ",
         toolCall.toolName
       ] }),
-      toolCall.output !== void 0 && /* @__PURE__ */ jsx("span", { style: { marginLeft: "auto", fontWeight: 400, opacity: 0.6 }, children: "completed" })
+      toolCall.output === void 0 ? /* @__PURE__ */ jsx(Spinner, {}) : /* @__PURE__ */ jsx("span", { style: { marginLeft: "auto", fontWeight: 400, opacity: 0.6 }, children: "completed" })
     ] }),
     contentLinks.length > 0 && /* @__PURE__ */ jsx(ContentLinksRow, { children: contentLinks.map((link) => /* @__PURE__ */ jsx(ContentLinkChip, { to: link.to, children: link.label }, link.to)) }),
     expanded && /* @__PURE__ */ jsx(ToolCallContent, { children: toolCall.output === void 0 ? "Waiting for result..." : JSON.stringify(toolCall.output, null, 2) })
@@ -840,6 +855,29 @@ const TypingDots = styled.span`
     40% { transform: scale(1); opacity: 1; }
   }
 `;
+const ThinkingIndicator = styled.div`
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  margin-top: 8px;
+  padding: 6px 0;
+  font-size: 12px;
+  color: #666687;
+`;
+const ThinkingSpinner = styled.span`
+  display: inline-block;
+  width: 14px;
+  height: 14px;
+  border: 2px solid #dcdce4;
+  border-top-color: #4945ff;
+  border-radius: 50%;
+  animation: spin 0.8s linear infinite;
+  flex-shrink: 0;
+
+  @keyframes spin {
+    to { transform: rotate(360deg); }
+  }
+`;
 const EmptyState = styled.div`
   display: flex;
   flex-direction: column;
@@ -878,8 +916,11 @@ const MessageList = forwardRef(
         /* @__PURE__ */ jsx(Typography, { variant: "beta", textColor: "neutral400", children: "AI Chat" }),
         /* @__PURE__ */ jsx(Box, { paddingTop: 2, children: /* @__PURE__ */ jsx(Typography, { variant: "omega", textColor: "neutral500", children: "Send a message to start the conversation" }) })
       ] }),
-      messages.map((message) => {
+      messages.map((message, index) => {
         const displayContent = message.role === "assistant" && message.content ? autoLinkContentTypeUids(message.content) : message.content;
+        const isLastMessage = index === messages.length - 1;
+        const hasToolsRunning = message.toolCalls?.some((tc) => tc.output === void 0) ?? false;
+        const showThinking = isLoading && isLastMessage && message.role === "assistant" && displayContent && hasToolsRunning;
         return /* @__PURE__ */ jsxs(MessageRow, { $isUser: message.role === "user", children: [
           message.role === "assistant" && /* @__PURE__ */ jsx(SparkleIcon, { children: /* @__PURE__ */ jsx(Sparkle, {}) }),
           /* @__PURE__ */ jsxs(MessageBubble, { $isUser: message.role === "user", children: [
@@ -891,7 +932,11 @@ const MessageList = forwardRef(
               /* @__PURE__ */ jsx("span", {}),
               /* @__PURE__ */ jsx("span", {})
             ] }),
-            message.toolCalls?.filter((tc) => !HIDDEN_TOOLS.has(tc.toolName)).map((tc) => /* @__PURE__ */ jsx(ToolCallDisplay, { toolCall: tc }, tc.toolCallId))
+            message.toolCalls?.filter((tc) => !HIDDEN_TOOLS.has(tc.toolName)).map((tc) => /* @__PURE__ */ jsx(ToolCallDisplay, { toolCall: tc }, tc.toolCallId)),
+            showThinking && /* @__PURE__ */ jsxs(ThinkingIndicator, { children: [
+              /* @__PURE__ */ jsx(ThinkingSpinner, {}),
+              "Working on it…"
+            ] })
           ] })
         ] }, message.id);
       }),

package/dist/_chunks/{index-C6UZ9D-c.mjs → index-BV9DET_M.mjs}

@@ -36,7 +36,7 @@ const index = {
         defaultMessage: PLUGIN_ID
       },
       Component: async () => {
-        const { App } = await import("./App-k5doNU8o.mjs");
+        const { App } = await import("./App-DKyCb0BY.mjs");
         return App;
       }
     });

package/dist/_chunks/{index-tCUlQhF4.js → index-DCEjJ0as.js}

@@ -37,7 +37,7 @@ const index = {
         defaultMessage: PLUGIN_ID
       },
       Component: async () => {
-        const { App } = await Promise.resolve().then(() => require("./App-31DoeBYs.js"));
+        const { App } = await Promise.resolve().then(() => require("./App-C_BH5Ir4.js"));
         return App;
       }
     });

package/dist/admin/index.js

@@ -1,3 +1,3 @@
 "use strict";
-const index = require("../_chunks/index-tCUlQhF4.js");
+const index = require("../_chunks/index-DCEjJ0as.js");
 module.exports = index.index;

package/dist/admin/index.mjs

@@ -1,4 +1,4 @@
-import { i } from "../_chunks/index-C6UZ9D-c.mjs";
+import { i } from "../_chunks/index-BV9DET_M.mjs";
 export {
   i as default
 };

package/dist/server/index.js

@@ -297,7 +297,7 @@ const searchContentSchema = zod.z.object({
     'The content type UID to search, e.g. "api::article.article" or "plugin::users-permissions.user"'
   ),
   query: zod.z.string().optional().describe("Full-text search query string (searches across all searchable text fields)"),
-  filters: zod.z.record(zod.z.string(), zod.z.unknown()).optional().describe('Strapi filter object, e.g. { username: { $containsi: "john" } }'),
+  filters: zod.z.record(zod.z.string(), zod.z.unknown()).optional().describe('Strapi filter object. Scalar: { title: { $containsi: "hello" } }. Relation: { author: { name: { $eq: "John" } } }. ManyToMany: { contentTags: { title: { $eq: "tutorial" } } }. Operators: $eq, $ne, $containsi, $in, $gt, $lt, $gte, $lte, $null, $notNull.'),
   fields: zod.z.array(zod.z.string()).optional().describe("Specific fields to return. If omitted, returns all fields (large content fields stripped unless includeContent is true)."),
   sort: zod.z.string().optional().describe('Sort order, e.g. "createdAt:desc"'),
   page: zod.z.number().optional().default(1).describe("Page number (starts at 1)"),
@@ -307,7 +307,7 @@ const searchContentSchema = zod.z.object({
   populate: zod.z.union([zod.z.string(), zod.z.array(zod.z.string()), zod.z.record(zod.z.string(), zod.z.unknown())]).optional().describe('Relations to populate. Defaults to "*" (all). Can be a string, array, or object.'),
   includeContent: zod.z.boolean().optional().default(false).describe("When true, includes large content fields (content, blocks, body, etc.) in results. Default false to reduce context size.")
 });
-const searchContentDescription = 'Search and query any Strapi content type. Use listContentTypes first to discover available content types and their fields, then use this tool to query specific collections. Use sort (e.g. "createdAt:desc") and pageSize: 1 to get the latest entry. By default, large content fields are stripped from results — set includeContent to true or use fields to get full content.';
+const searchContentDescription = 'Search and query any Strapi content type. Use listContentTypes first to discover available content types and their fields, then use this tool to query specific collections. Use sort (e.g. "createdAt:desc") and pageSize: 1 to get the latest entry. By default, large content fields are stripped from results — set includeContent to true or use fields to get full content. To filter by a relation, nest the filter: { relationField: { fieldOnRelation: { $operator: "value" } } }.';
 function stripLargeFields(obj) {
   const stripped = {};
   for (const [key, value] of Object.entries(obj)) {
@@ -671,24 +671,33 @@ function getDisplayField(strapi, contentType) {
   }
   return "id";
 }
+const MANY_RELATIONS = /* @__PURE__ */ new Set(["oneToMany", "manyToMany"]);
 function resolveFieldPath(strapi, contentType, fieldPath) {
   const parts = fieldPath.split(".");
   const topField = parts[0];
   const attr = getAttribute(strapi, contentType, topField);
   if (!attr) {
-    return { resolvedPath: fieldPath, populate: [] };
+    return { resolvedPath: fieldPath, populate: [], isArray: false };
   }
   if (attr.type === "relation" && attr.target) {
+    const isArray = MANY_RELATIONS.has(attr.relation ?? "");
     if (parts.length === 1) {
       const displayField = getDisplayField(strapi, attr.target);
       return {
         resolvedPath: `${topField}.${displayField}`,
-        populate: [topField]
+        populate: [topField],
+        isArray,
+        selectField: displayField
       };
     }
-    return { resolvedPath: fieldPath, populate: [topField] };
+    return {
+      resolvedPath: fieldPath,
+      populate: [topField],
+      isArray,
+      selectField: parts.slice(1).join(".")
+    };
   }
-  return { resolvedPath: fieldPath, populate: [] };
+  return { resolvedPath: fieldPath, populate: [], isArray: false };
 }
 const MAX_PAGINATE = 1e3;
 const PAGE_SIZE = 100;
@@ -697,7 +706,7 @@ const aggregateContentSchema = zod.z.object({
   operation: zod.z.enum(["count", "countByField", "countByDateRange"]).describe(
     "count — total count; countByField — group by a field; countByDateRange — bucket by date"
   ),
-  filters: zod.z.record(zod.z.string(), zod.z.unknown()).optional().describe('Strapi filter object, e.g. { category: { name: "tech" } }'),
+  filters: zod.z.record(zod.z.string(), zod.z.unknown()).optional().describe('Strapi filter object. Scalar: { title: { $containsi: "hello" } }. Relation: { author: { name: { $eq: "John" } } }. ManyToMany: { contentTags: { title: { $eq: "tutorial" } } }.'),
   groupByField: zod.z.string().optional().describe('Field to group by for countByField. Just use the field name — relation fields are auto-resolved to their display name (e.g. "author", "category"). You can also use dot paths like "author.email" for a specific sub-field.'),
   dateField: zod.z.string().optional().default("createdAt").describe('Date field for countByDateRange (default: "createdAt")'),
   granularity: zod.z.enum(["day", "week", "month"]).optional().default("month").describe("Bucket granularity for countByDateRange"),
@@ -727,17 +736,30 @@ function resolveField(doc, fieldPath) {
   let current = doc;
   for (const part of parts) {
     if (current == null || typeof current !== "object") return void 0;
+    if (Array.isArray(current)) return void 0;
     current = current[part];
   }
   return current;
 }
-async function paginateAll(strapi, contentType, baseQuery) {
+function buildPopulate(resolved) {
+  if (resolved.populate.length === 0) return "*";
+  const populate = {};
+  for (const rel of resolved.populate) {
+    if (resolved.selectField) {
+      populate[rel] = { fields: [resolved.selectField] };
+    } else {
+      populate[rel] = true;
+    }
+  }
+  return populate;
+}
+async function paginateAll(strapi, contentType, baseQuery, populate = "*") {
   const docs = [];
   let page = 1;
   while (docs.length < MAX_PAGINATE) {
     const results = await strapi.documents(contentType).findMany({
       ...baseQuery,
-      populate: "*",
+      populate,
       page,
       pageSize: PAGE_SIZE
     });
@@ -752,22 +774,38 @@ const DISPLAY_CANDIDATES = ["name", "title", "username", "label", "slug", "email
 function toDisplayValue(raw) {
   if (raw == null) return "(empty)";
   if (typeof raw !== "object") return String(raw);
-  if (Array.isArray(raw)) {
-    if (raw.length === 0) return "(empty)";
-    return raw.map((item) => toDisplayValue(item)).join(", ");
-  }
   const obj = raw;
   for (const key of DISPLAY_CANDIDATES) {
     if (obj[key] != null) return String(obj[key]);
   }
   return obj.id != null ? String(obj.id) : "(empty)";
 }
-function groupDocs(docs, fieldPath) {
+function groupDocs(docs, resolved) {
   const counts = /* @__PURE__ */ new Map();
+  const topField = resolved.resolvedPath.split(".")[0];
+  const subPath = resolved.resolvedPath.split(".").slice(1).join(".");
   for (const doc of docs) {
-    const raw = resolveField(doc, fieldPath);
-    const value = toDisplayValue(raw);
-    counts.set(value, (counts.get(value) ?? 0) + 1);
+    if (resolved.isArray) {
+      const items = doc[topField];
+      if (!Array.isArray(items) || items.length === 0) {
+        counts.set("(empty)", (counts.get("(empty)") ?? 0) + 1);
+        continue;
+      }
+      for (const item of items) {
+        let value;
+        if (subPath && typeof item === "object" && item != null) {
+          const sub = resolveField(item, subPath);
+          value = sub != null ? String(sub) : toDisplayValue(item);
+        } else {
+          value = toDisplayValue(item);
+        }
+        counts.set(value, (counts.get(value) ?? 0) + 1);
+      }
+    } else {
+      const raw = resolveField(doc, resolved.resolvedPath);
+      const value = toDisplayValue(raw);
+      counts.set(value, (counts.get(value) ?? 0) + 1);
+    }
   }
   return Array.from(counts.entries()).map(([value, count]) => ({ value, count })).sort((a, b) => b.count - a.count);
 }
@@ -806,10 +844,11 @@ async function aggregateContent(strapi, params) {
       if (!groupByField) {
         throw new Error("groupByField is required for countByField operation");
       }
-      const { resolvedPath } = resolveFieldPath(strapi, contentType, groupByField);
-      const docs = await paginateAll(strapi, contentType, baseQuery);
-      const groups = groupDocs(docs, resolvedPath);
-      return { total: docs.length, groups, resolvedField: resolvedPath };
+      const resolved = resolveFieldPath(strapi, contentType, groupByField);
+      const populate = buildPopulate(resolved);
+      const docs = await paginateAll(strapi, contentType, baseQuery, populate);
+      const groups = groupDocs(docs, resolved);
+      return { total: docs.length, groups, resolvedField: resolved.resolvedPath };
     }
     case "countByDateRange": {
       const { dateField = "createdAt", granularity = "month" } = params;
@@ -2154,8 +2193,26 @@ function describeTools(tools) {
   return `Available tools:
 ${lines.join("\n")}`;
 }
-const DEFAULT_PREAMBLE = 'You are a Strapi CMS assistant. Use your tools to fulfill user requests. When asked to create or update content, use the appropriate tool — do not tell the user you cannot. When performing bulk operations (e.g. publish multiple items), call multiple tools in parallel in a single step rather than one at a time.\n\nFor analytics and counting questions (e.g. "how many", "count", "distribution", "trends", "breakdown"), use the aggregateContent tool instead of searchContent — it is faster and purpose-built for these queries. Present analytics results as markdown tables. After showing analytics results, suggest 2-3 follow-up questions the user might find useful under a "**You might also want to know:**" heading.';
-const DEFAULT_PUBLIC_PREAMBLE = 'You are a helpful public assistant for this website. Use your tools to answer questions about the site content. You cannot modify any content or perform administrative actions.\n\nFor analytics and counting questions (e.g. "how many", "count", "distribution", "trends", "breakdown"), use the aggregateContent tool instead of searchContent — it is faster and purpose-built for these queries. Present analytics results as markdown tables. After showing analytics results, suggest 2-3 follow-up questions the user might find useful under a "**You might also want to know:**" heading.';
+const DEFAULT_PREAMBLE = `You are a Strapi CMS assistant. Use your tools to fulfill user requests. When asked to create or update content, use the appropriate tool — do not tell the user you cannot. When performing bulk operations (e.g. publish multiple items), call multiple tools in parallel in a single step rather than one at a time.
+
+For analytics and counting questions (e.g. "how many", "count", "distribution", "trends", "breakdown"), use the aggregateContent tool instead of searchContent — it is faster and purpose-built for these queries. Present analytics results as markdown tables. After showing analytics results, suggest 2-3 follow-up questions the user might find useful under a "**You might also want to know:**" heading.
+
+Strapi filter syntax for searchContent and aggregateContent:
+- Scalar fields: { title: { $containsi: "hello" } }
+- Relation (manyToOne): { author: { name: { $eq: "John" } } }
+- Relation (manyToMany): { contentTags: { title: { $eq: "tutorial" } } }
+- Always nest relation filters as: { relationField: { fieldOnRelatedType: { $operator: value } } }
+- Never use flat dot-path syntax like "contentTags.title" in filters — always use nested objects.`;
+const DEFAULT_PUBLIC_PREAMBLE = `You are a helpful public assistant for this website. Use your tools to answer questions about the site content. You cannot modify any content or perform administrative actions.
+
+For analytics and counting questions (e.g. "how many", "count", "distribution", "trends", "breakdown"), use the aggregateContent tool instead of searchContent — it is faster and purpose-built for these queries. Present analytics results as markdown tables. After showing analytics results, suggest 2-3 follow-up questions the user might find useful under a "**You might also want to know:**" heading.
+
+Strapi filter syntax for searchContent and aggregateContent:
+- Scalar fields: { title: { $containsi: "hello" } }
+- Relation (manyToOne): { author: { name: { $eq: "John" } } }
+- Relation (manyToMany): { contentTags: { title: { $eq: "tutorial" } } }
+- Always nest relation filters as: { relationField: { fieldOnRelatedType: { $operator: value } } }
+- Never use flat dot-path syntax like "contentTags.title" in filters — always use nested objects.`;
 function composeSystemPrompt(config2, toolsDescription, override) {
   const base = override || config2?.systemPrompt || DEFAULT_PREAMBLE;
   if (base.includes("{tools}")) {

package/dist/server/index.mjs

@@ -277,7 +277,7 @@ const searchContentSchema = z.object({
     'The content type UID to search, e.g. "api::article.article" or "plugin::users-permissions.user"'
   ),
   query: z.string().optional().describe("Full-text search query string (searches across all searchable text fields)"),
-  filters: z.record(z.string(), z.unknown()).optional().describe('Strapi filter object, e.g. { username: { $containsi: "john" } }'),
+  filters: z.record(z.string(), z.unknown()).optional().describe('Strapi filter object. Scalar: { title: { $containsi: "hello" } }. Relation: { author: { name: { $eq: "John" } } }. ManyToMany: { contentTags: { title: { $eq: "tutorial" } } }. Operators: $eq, $ne, $containsi, $in, $gt, $lt, $gte, $lte, $null, $notNull.'),
   fields: z.array(z.string()).optional().describe("Specific fields to return. If omitted, returns all fields (large content fields stripped unless includeContent is true)."),
   sort: z.string().optional().describe('Sort order, e.g. "createdAt:desc"'),
   page: z.number().optional().default(1).describe("Page number (starts at 1)"),
@@ -287,7 +287,7 @@ const searchContentSchema = z.object({
   populate: z.union([z.string(), z.array(z.string()), z.record(z.string(), z.unknown())]).optional().describe('Relations to populate. Defaults to "*" (all). Can be a string, array, or object.'),
   includeContent: z.boolean().optional().default(false).describe("When true, includes large content fields (content, blocks, body, etc.) in results. Default false to reduce context size.")
 });
-const searchContentDescription = 'Search and query any Strapi content type. Use listContentTypes first to discover available content types and their fields, then use this tool to query specific collections. Use sort (e.g. "createdAt:desc") and pageSize: 1 to get the latest entry. By default, large content fields are stripped from results — set includeContent to true or use fields to get full content.';
+const searchContentDescription = 'Search and query any Strapi content type. Use listContentTypes first to discover available content types and their fields, then use this tool to query specific collections. Use sort (e.g. "createdAt:desc") and pageSize: 1 to get the latest entry. By default, large content fields are stripped from results — set includeContent to true or use fields to get full content. To filter by a relation, nest the filter: { relationField: { fieldOnRelation: { $operator: "value" } } }.';
 function stripLargeFields(obj) {
   const stripped = {};
   for (const [key, value] of Object.entries(obj)) {
@@ -651,24 +651,33 @@ function getDisplayField(strapi, contentType) {
   }
   return "id";
 }
+const MANY_RELATIONS = /* @__PURE__ */ new Set(["oneToMany", "manyToMany"]);
 function resolveFieldPath(strapi, contentType, fieldPath) {
   const parts = fieldPath.split(".");
   const topField = parts[0];
   const attr = getAttribute(strapi, contentType, topField);
   if (!attr) {
-    return { resolvedPath: fieldPath, populate: [] };
+    return { resolvedPath: fieldPath, populate: [], isArray: false };
   }
   if (attr.type === "relation" && attr.target) {
+    const isArray = MANY_RELATIONS.has(attr.relation ?? "");
     if (parts.length === 1) {
       const displayField = getDisplayField(strapi, attr.target);
       return {
         resolvedPath: `${topField}.${displayField}`,
-        populate: [topField]
+        populate: [topField],
+        isArray,
+        selectField: displayField
       };
     }
-    return { resolvedPath: fieldPath, populate: [topField] };
+    return {
+      resolvedPath: fieldPath,
+      populate: [topField],
+      isArray,
+      selectField: parts.slice(1).join(".")
+    };
   }
-  return { resolvedPath: fieldPath, populate: [] };
+  return { resolvedPath: fieldPath, populate: [], isArray: false };
 }
 const MAX_PAGINATE = 1e3;
 const PAGE_SIZE = 100;
@@ -677,7 +686,7 @@ const aggregateContentSchema = z.object({
   operation: z.enum(["count", "countByField", "countByDateRange"]).describe(
     "count — total count; countByField — group by a field; countByDateRange — bucket by date"
   ),
-  filters: z.record(z.string(), z.unknown()).optional().describe('Strapi filter object, e.g. { category: { name: "tech" } }'),
+  filters: z.record(z.string(), z.unknown()).optional().describe('Strapi filter object. Scalar: { title: { $containsi: "hello" } }. Relation: { author: { name: { $eq: "John" } } }. ManyToMany: { contentTags: { title: { $eq: "tutorial" } } }.'),
   groupByField: z.string().optional().describe('Field to group by for countByField. Just use the field name — relation fields are auto-resolved to their display name (e.g. "author", "category"). You can also use dot paths like "author.email" for a specific sub-field.'),
   dateField: z.string().optional().default("createdAt").describe('Date field for countByDateRange (default: "createdAt")'),
   granularity: z.enum(["day", "week", "month"]).optional().default("month").describe("Bucket granularity for countByDateRange"),
@@ -707,17 +716,30 @@ function resolveField(doc, fieldPath) {
   let current = doc;
   for (const part of parts) {
     if (current == null || typeof current !== "object") return void 0;
+    if (Array.isArray(current)) return void 0;
     current = current[part];
   }
   return current;
 }
-async function paginateAll(strapi, contentType, baseQuery) {
+function buildPopulate(resolved) {
+  if (resolved.populate.length === 0) return "*";
+  const populate = {};
+  for (const rel of resolved.populate) {
+    if (resolved.selectField) {
+      populate[rel] = { fields: [resolved.selectField] };
+    } else {
+      populate[rel] = true;
+    }
+  }
+  return populate;
+}
+async function paginateAll(strapi, contentType, baseQuery, populate = "*") {
   const docs = [];
   let page = 1;
   while (docs.length < MAX_PAGINATE) {
     const results = await strapi.documents(contentType).findMany({
       ...baseQuery,
-      populate: "*",
+      populate,
       page,
       pageSize: PAGE_SIZE
     });
@@ -732,22 +754,38 @@ const DISPLAY_CANDIDATES = ["name", "title", "username", "label", "slug", "email
 function toDisplayValue(raw) {
   if (raw == null) return "(empty)";
   if (typeof raw !== "object") return String(raw);
-  if (Array.isArray(raw)) {
-    if (raw.length === 0) return "(empty)";
-    return raw.map((item) => toDisplayValue(item)).join(", ");
-  }
   const obj = raw;
   for (const key of DISPLAY_CANDIDATES) {
     if (obj[key] != null) return String(obj[key]);
   }
   return obj.id != null ? String(obj.id) : "(empty)";
 }
-function groupDocs(docs, fieldPath) {
+function groupDocs(docs, resolved) {
   const counts = /* @__PURE__ */ new Map();
+  const topField = resolved.resolvedPath.split(".")[0];
+  const subPath = resolved.resolvedPath.split(".").slice(1).join(".");
   for (const doc of docs) {
-    const raw = resolveField(doc, fieldPath);
-    const value = toDisplayValue(raw);
-    counts.set(value, (counts.get(value) ?? 0) + 1);
+    if (resolved.isArray) {
+      const items = doc[topField];
+      if (!Array.isArray(items) || items.length === 0) {
+        counts.set("(empty)", (counts.get("(empty)") ?? 0) + 1);
+        continue;
+      }
+      for (const item of items) {
+        let value;
+        if (subPath && typeof item === "object" && item != null) {
+          const sub = resolveField(item, subPath);
+          value = sub != null ? String(sub) : toDisplayValue(item);
+        } else {
+          value = toDisplayValue(item);
+        }
+        counts.set(value, (counts.get(value) ?? 0) + 1);
+      }
+    } else {
+      const raw = resolveField(doc, resolved.resolvedPath);
+      const value = toDisplayValue(raw);
+      counts.set(value, (counts.get(value) ?? 0) + 1);
+    }
   }
   return Array.from(counts.entries()).map(([value, count]) => ({ value, count })).sort((a, b) => b.count - a.count);
 }
@@ -786,10 +824,11 @@ async function aggregateContent(strapi, params) {
       if (!groupByField) {
         throw new Error("groupByField is required for countByField operation");
       }
-      const { resolvedPath } = resolveFieldPath(strapi, contentType, groupByField);
-      const docs = await paginateAll(strapi, contentType, baseQuery);
-      const groups = groupDocs(docs, resolvedPath);
-      return { total: docs.length, groups, resolvedField: resolvedPath };
+      const resolved = resolveFieldPath(strapi, contentType, groupByField);
+      const populate = buildPopulate(resolved);
+      const docs = await paginateAll(strapi, contentType, baseQuery, populate);
+      const groups = groupDocs(docs, resolved);
+      return { total: docs.length, groups, resolvedField: resolved.resolvedPath };
     }
     case "countByDateRange": {
       const { dateField = "createdAt", granularity = "month" } = params;
@@ -2134,8 +2173,26 @@ function describeTools(tools) {
   return `Available tools:
 ${lines.join("\n")}`;
 }
-const DEFAULT_PREAMBLE = 'You are a Strapi CMS assistant. Use your tools to fulfill user requests. When asked to create or update content, use the appropriate tool — do not tell the user you cannot. When performing bulk operations (e.g. publish multiple items), call multiple tools in parallel in a single step rather than one at a time.\n\nFor analytics and counting questions (e.g. "how many", "count", "distribution", "trends", "breakdown"), use the aggregateContent tool instead of searchContent — it is faster and purpose-built for these queries. Present analytics results as markdown tables. After showing analytics results, suggest 2-3 follow-up questions the user might find useful under a "**You might also want to know:**" heading.';
-const DEFAULT_PUBLIC_PREAMBLE = 'You are a helpful public assistant for this website. Use your tools to answer questions about the site content. You cannot modify any content or perform administrative actions.\n\nFor analytics and counting questions (e.g. "how many", "count", "distribution", "trends", "breakdown"), use the aggregateContent tool instead of searchContent — it is faster and purpose-built for these queries. Present analytics results as markdown tables. After showing analytics results, suggest 2-3 follow-up questions the user might find useful under a "**You might also want to know:**" heading.';
+const DEFAULT_PREAMBLE = `You are a Strapi CMS assistant. Use your tools to fulfill user requests. When asked to create or update content, use the appropriate tool — do not tell the user you cannot. When performing bulk operations (e.g. publish multiple items), call multiple tools in parallel in a single step rather than one at a time.
+
+For analytics and counting questions (e.g. "how many", "count", "distribution", "trends", "breakdown"), use the aggregateContent tool instead of searchContent — it is faster and purpose-built for these queries. Present analytics results as markdown tables. After showing analytics results, suggest 2-3 follow-up questions the user might find useful under a "**You might also want to know:**" heading.
+
+Strapi filter syntax for searchContent and aggregateContent:
+- Scalar fields: { title: { $containsi: "hello" } }
+- Relation (manyToOne): { author: { name: { $eq: "John" } } }
+- Relation (manyToMany): { contentTags: { title: { $eq: "tutorial" } } }
+- Always nest relation filters as: { relationField: { fieldOnRelatedType: { $operator: value } } }
+- Never use flat dot-path syntax like "contentTags.title" in filters — always use nested objects.`;
+const DEFAULT_PUBLIC_PREAMBLE = `You are a helpful public assistant for this website. Use your tools to answer questions about the site content. You cannot modify any content or perform administrative actions.
+
+For analytics and counting questions (e.g. "how many", "count", "distribution", "trends", "breakdown"), use the aggregateContent tool instead of searchContent — it is faster and purpose-built for these queries. Present analytics results as markdown tables. After showing analytics results, suggest 2-3 follow-up questions the user might find useful under a "**You might also want to know:**" heading.
+
+Strapi filter syntax for searchContent and aggregateContent:
+- Scalar fields: { title: { $containsi: "hello" } }
+- Relation (manyToOne): { author: { name: { $eq: "John" } } }
+- Relation (manyToMany): { contentTags: { title: { $eq: "tutorial" } } }
+- Always nest relation filters as: { relationField: { fieldOnRelatedType: { $operator: value } } }
+- Never use flat dot-path syntax like "contentTags.title" in filters — always use nested objects.`;
 function composeSystemPrompt(config2, toolsDescription, override) {
   const base = override || config2?.systemPrompt || DEFAULT_PREAMBLE;
   if (base.includes("{tools}")) {

package/dist/server/src/tool-logic/index.d.ts

@@ -19,3 +19,4 @@ export type { RecallPublicMemoriesParams, RecallPublicMemoriesResult } from './r
 export { aggregateContent, aggregateContentSchema, aggregateContentDescription } from './aggregate-content';
 export type { AggregateContentParams, AggregateContentResult } from './aggregate-content';
 export { resolveFieldPath, getDisplayField, isRelation, getRelationTarget, getSchema } from './schema-utils';
+export type { ResolvedField } from './schema-utils';

package/dist/server/src/tool-logic/schema-utils.d.ts

@@ -35,17 +35,15 @@ export declare function getRelationTarget(strapi: Core.Strapi, contentType: stri
  * then falls back to the first string/text field, then 'id'.
  */
 export declare function getDisplayField(strapi: Core.Strapi, contentType: string): string;
-/**
- * Given a field path that the AI provided (e.g. "author", "category", "author.name"),
- * resolve it to the actual dot-path needed to extract a display value from a populated document.
- *
- * If the field is a relation with no sub-field specified, appends the best display field
- * from the target schema (e.g. "author" → "author.name").
- *
- * Returns the resolved path and any top-level relations that need populating.
- */
-export declare function resolveFieldPath(strapi: Core.Strapi, contentType: string, fieldPath: string): {
+export interface ResolvedField {
+    /** The dot-path to extract the display value (e.g. "author.name") */
     resolvedPath: string;
+    /** Top-level relations that must be populated */
     populate: string[];
-};
+    /** True if the relation is a *ToMany (value is an array of items) */
+    isArray: boolean;
+    /** The sub-field to select from the relation (for targeted populate) */
+    selectField?: string;
+}
+export declare function resolveFieldPath(strapi: Core.Strapi, contentType: string, fieldPath: string): ResolvedField;
 export {};

package/dist/server/src/tool-logic/search-content.d.ts

@@ -16,7 +16,7 @@ export declare const searchContentSchema: z.ZodObject<{
     populate: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
     includeContent: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 }, z.core.$strip>;
-export declare const searchContentDescription = "Search and query any Strapi content type. Use listContentTypes first to discover available content types and their fields, then use this tool to query specific collections. Use sort (e.g. \"createdAt:desc\") and pageSize: 1 to get the latest entry. By default, large content fields are stripped from results \u2014 set includeContent to true or use fields to get full content.";
+export declare const searchContentDescription = "Search and query any Strapi content type. Use listContentTypes first to discover available content types and their fields, then use this tool to query specific collections. Use sort (e.g. \"createdAt:desc\") and pageSize: 1 to get the latest entry. By default, large content fields are stripped from results \u2014 set includeContent to true or use fields to get full content. To filter by a relation, nest the filter: { relationField: { fieldOnRelation: { $operator: \"value\" } } }.";
 export interface SearchContentParams {
     contentType: string;
     query?: string;

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.6.7",
+  "version": "0.6.9",
   "keywords": [
     "strapi",
     "strapi-plugin",