plugin-agent-orchestrator 1.0.15 → 1.0.16

package/README.md

@@ -7,6 +7,7 @@ Hierarchical Multi-Agent orchestration for NocoBase AI Employees. Enables Leader
 - **Hierarchical Delegation**: Allows AI Leader agents to break down complex tasks and assign them to specialized sub-agents.
 - **Seamless Integration**: Plugs directly into the existing AI Employee framework.
 - **Execution Tracking**: Monitor sub-agent task execution and responses within the main chat interface.
+- **External RAG Search**: Exposes `external_rag_search` so leaders and sub-agents can retrieve context from NocoBase knowledge bases, including external RAG services.
 
 ## Usage
 1. Enable the plugin in the NocoBase Plugin Manager.
@@ -14,3 +15,98 @@ Hierarchical Multi-Agent orchestration for NocoBase AI Employees. Enables Leader
 3. Configure a primary "Leader" agent.
 4. Add available "Sub-Agents" as tools or skills to the Leader agent.
 5. Interact with the Leader agent; it will automatically delegate tasks when necessary.
+
+## External RAG / Embedding service
+
+Recommended approach: keep source ownership in NocoBase and move chunking, embedding, vector storage, and retrieval to an external lightweight RAG service. This plugin should not own vector infrastructure directly. It delegates search to `plugin-knowledge-base`, which already supports knowledge bases of type `EXTERNAL_RAG`.
+
+### Architecture
+
+1. NocoBase stores the source metadata:
+   - uploaded file attachment id, filename, storage id, URL, owner/role access, or
+   - datasource/collection/record id for database-backed knowledge.
+2. The external RAG service owns:
+   - document fetching or receiving source payloads,
+   - parsing/chunking,
+   - embedding,
+   - vector index,
+   - retrieval.
+3. NocoBase creates a knowledge base with `type = EXTERNAL_RAG` and `options` such as:
+   - `ragProvider: "external-http"`
+   - `ragApiUrl: "https://rag.example.com/search"`
+   - `ragApiKey`
+   - `ragNamespace`
+   - `ragTopK`
+   - `ragScoreThreshold`
+4. Agents use the `external_rag_search` tool. The tool calls `plugin-knowledge-base.searchKnowledgeBases()`, so access control and mixed local/external search remain centralized.
+
+### External search contract
+
+The built-in `external-http` strategy expects:
+
+```http
+POST /search
+Authorization: Bearer <ragApiKey>
+Content-Type: application/json
+```
+
+```json
+{
+  "query": "search text",
+  "topK": 5,
+  "scoreThreshold": 0.3,
+  "namespace": "optional-kb-namespace",
+  "filter": {}
+}
+```
+
+Response:
+
+```json
+{
+  "results": [
+    {
+      "id": "chunk-or-source-id",
+      "content": "matched text",
+      "score": 0.82,
+      "metadata": {
+        "fileId": "123",
+        "filename": "contract.pdf",
+        "collection": "orders",
+        "recordId": "456",
+        "sourceUrl": "/api/attachments/123:download"
+      }
+    }
+  ]
+}
+```
+
+The important rule is that every result should return enough metadata for NocoBase to resolve the original source: `fileId`/`filename` for files, or `collection`/`recordId` for datasource records.
+
+### Lightweight open-source service target
+
+For a small but useful deployment, use a standalone service with:
+
+- Qdrant or LanceDB for vector search.
+- FastAPI or Express for `/ingest`, `/delete`, and `/search`.
+- A small embedding model such as `BAAI/bge-small-en-v1.5`, `intfloat/multilingual-e5-small`, or another model matching the deployment language.
+- A namespace per NocoBase knowledge base.
+
+Minimum API surface:
+
+- `POST /ingest`: receive `{ namespace, source, content | fileUrl | storageRef, metadata }`.
+- `POST /delete`: receive `{ namespace, sourceId }`.
+- `POST /search`: implement the contract above.
+
+For NocoBase datasource knowledge, send each record as a source document with metadata `{ collection, recordId, fields, updatedAt }`; the RAG service chunks and embeds the selected text fields, then returns `collection` and `recordId` in search results.
+
+### E5/OpenAI-compatible embedding
+
+If the external RAG service uses an E5 family model behind an OpenAI-compatible `/v1/embeddings` API, configure the NocoBase knowledge base with `ragProvider: "e5-http"`. `plugin-knowledge-base` will read the selected embedding LLM service and forward its `baseURL`, `apiKey`, and model to the RAG service.
+
+- embed user queries as `query: <question>`;
+- embed document chunks as `passage: <chunk>`;
+- use the same model for ingest and search;
+- recreate the vector collection when changing models or vector dimensions.
+
+The RAG service still owns chunking, embedding calls, vector storage, and metadata mapping. NocoBase owns the LLM service configuration and search authorization path.

package/dist/server/collections/agent-execution-spans.d.ts

@@ -5,5 +5,5 @@
  * keeps its own sandbox execution records; this collection stores the flow
  * relationship and links to those records when applicable.
  */
-declare const _default: any;
+declare const _default: import("@nocobase/database").CollectionOptions;
 export default _default;

package/dist/server/collections/orchestrator-config.d.ts

@@ -1,2 +1,2 @@
-declare const _default: any;
+declare const _default: import("@nocobase/database").CollectionOptions;
 export default _default;

package/dist/server/collections/orchestrator-logs.d.ts

@@ -4,5 +4,5 @@
  * Since createReactAgent doesn't create aiConversation records,
  * we log delegation events to a dedicated table for observability.
  */
-declare const _default: any;
+declare const _default: import("@nocobase/database").CollectionOptions;
 export default _default;

package/dist/server/collections/skill-definitions.d.ts

@@ -1,2 +1,3 @@
+import { CollectionOptions } from '@nocobase/database';
 declare const _default: CollectionOptions;
 export default _default;

package/dist/server/collections/skill-executions.d.ts

@@ -1,2 +1,3 @@
+import { CollectionOptions } from '@nocobase/database';
 declare const _default: CollectionOptions;
 export default _default;

package/dist/server/collections/skill-worker-configs.d.ts

@@ -1,2 +1,3 @@
+import { CollectionOptions } from '@nocobase/database';
 declare const _default: CollectionOptions;
 export default _default;

package/dist/server/plugin.js

@@ -43,6 +43,7 @@ module.exports = __toCommonJS(plugin_exports);
 var import_server = require("@nocobase/server");
 var import_path = __toESM(require("path"));
 var import_delegate_task = require("./tools/delegate-task");
+var import_external_rag_search = require("./tools/external-rag-search");
 var import_tracing = require("./resources/tracing");
 var import_plugin = __toESM(require("./skill-hub/plugin"));
 class PluginAgentOrchestratorServer extends import_server.Plugin {
@@ -62,9 +63,18 @@ class PluginAgentOrchestratorServer extends import_server.Plugin {
     await this.skillHub.load();
     this.app.acl.registerSnippet({
       name: `pm.${this.name}`,
-      actions: ["orchestratorConfig:*", "orchestratorTracing:*", "agentExecutionSpans:*", "skillDefinitions:*", "skillExecutions:*", "skillHub:*", "skillWorkerConfigs:*"]
+      actions: [
+        "orchestratorConfig:*",
+        "orchestratorTracing:*",
+        "agentExecutionSpans:*",
+        "skillDefinitions:*",
+        "skillExecutions:*",
+        "skillHub:*",
+        "skillWorkerConfigs:*"
+      ]
     });
     const toolsManager = this.app.aiManager.toolsManager;
+    toolsManager.registerTools((0, import_external_rag_search.createExternalRagSearchTool)(this));
     toolsManager.registerDynamicTools((0, import_delegate_task.createDelegateToolsProvider)(this));
     (0, import_tracing.registerTracingResource)(this);
     this.app.cronJobManager.addJob({

package/dist/server/services/SkillManager.js

@@ -347,45 +347,6 @@ if table_data_raw and table_data_raw != '{{' + 'tableData}}':
 doc.build(story)
 print('Generated: report.pdf')
 `;
-const SEED_PPTX = `import os, json
-from pptx import Presentation
-from pptx.util import Inches, Pt
-from pptx.enum.text import PP_ALIGN
-
-title = json.loads('''{{title}}''') if '{{title}}'.startswith('"') else '{{title}}'
-subtitle_raw = '''{{subtitle}}'''
-subtitle = json.loads(subtitle_raw) if subtitle_raw.startswith('"') else subtitle_raw if subtitle_raw != '{{' + 'subtitle}}' else ''
-slides_data = json.loads('''{{slides}}''')
-
-prs = Presentation()
-prs.slide_width = Inches(13.333)
-prs.slide_height = Inches(7.5)
-
-# Title slide
-slide = prs.slides.add_slide(prs.slide_layouts[0])
-slide.shapes.title.text = title
-if subtitle and slide.placeholders[1]:
-    slide.placeholders[1].text = subtitle
-
-# Content slides
-for s in slides_data:
-    slide = prs.slides.add_slide(prs.slide_layouts[1])
-    slide.shapes.title.text = s.get('title', '')
-    body = slide.placeholders[1].text_frame
-    body.clear()
-    for i, bullet in enumerate(s.get('bullets', [])):
-        if i == 0:
-            body.paragraphs[0].text = bullet
-        else:
-            p = body.add_paragraph()
-            p.text = bullet
-        body.paragraphs[-1].font.size = Pt(18)
-
-output_dir = os.environ.get('OUTPUT_DIR', '/output')
-filepath = os.path.join(output_dir, 'presentation.pptx')
-prs.save(filepath)
-print('Generated: presentation.pptx')
-`;
 const SEED_CHART = `import os, json
 import matplotlib
 matplotlib.use('Agg')

package/dist/server/skill-hub/plugin.js

@@ -498,7 +498,7 @@ IMPORTANT: This skill requires human confirmation. Pass best-effort args; the us
                   filter: { id: skill.get("id"), enabled: true }
                 });
                 if (!latestSkill) {
-                  return { error: `Skill "${skill.get("name")}" is no longer available` };
+                  return { status: "error", content: `Skill "${skill.get("name")}" is no longer available` };
                 }
                 const result = await this.executeSkill(latestSkill, args, toolCtx);
                 return {
@@ -530,7 +530,7 @@ IMPORTANT: This skill requires human confirmation. Pass best-effort args; the us
           const cutoff = new Date(Date.now() - MAX_AGE_MS);
           const repo = this.db.getRepository("skillExecutions");
           const outdated = await repo.find({
-            where: { createdAt: { $lt: cutoff } }
+            filter: { createdAt: { $lt: cutoff } }
           });
           if (outdated.length > 0) {
             for (const record of outdated) {
@@ -579,7 +579,7 @@ IMPORTANT: This skill requires human confirmation. Pass best-effort args; the us
       const hours = config ? config.get("retentionHours") : 24;
       if (hours > 0) {
         const cutoff = new Date(Date.now() - hours * 60 * 60 * 1e3);
-        const results = await repo.find({ where: { createdAt: { $lt: cutoff } }, fields: ["id"] });
+        const results = await repo.find({ filter: { createdAt: { $lt: cutoff } }, fields: ["id"] });
         for (const rec of results) {
           await rec.destroy();
         }

package/dist/server/tools/delegate-task.js

@@ -554,7 +554,7 @@ function invalidateDelegateToolsCache() {
   registeredDelegateNamesByPlugin = /* @__PURE__ */ new WeakMap();
 }
 async function invokeDelegateTask(ctx, plugin, options) {
-  var _a, _b, _c, _d, _e;
+  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m;
   const {
     leaderUsername,
     subAgentUsername,
@@ -771,7 +771,27 @@ async function invokeDelegateTask(ctx, plugin, options) {
       llm: chatModel,
       tools: langchainTools
     });
-    const systemPrompt = ((_e = subAgentEmployee.chatSettings) == null ? void 0 : _e.systemPrompt) || subAgentEmployee.bio || `You are an AI assistant named "${subAgentEmployee.nickname || subAgentUsername}". ${subAgentEmployee.about || ""}`;
+    let systemPrompt = ((_e = subAgentEmployee.chatSettings) == null ? void 0 : _e.systemPrompt) || subAgentEmployee.bio || `You are an AI assistant named "${subAgentEmployee.nickname || subAgentUsername}". ${subAgentEmployee.about || ""}`;
+    try {
+      const kbPlugin = ctx.app.pm.get("plugin-knowledge-base");
+      if (kbPlugin == null ? void 0 : kbPlugin.sessionContext) {
+        const sessionId = ((_h = (_g = (_f = ctx.action) == null ? void 0 : _f.params) == null ? void 0 : _g.values) == null ? void 0 : _h.sessionId) || ((_j = (_i = ctx.action) == null ? void 0 : _i.params) == null ? void 0 : _j.sessionId) || ((_k = ctx.state) == null ? void 0 : _k.sessionId);
+        const contextSummary = await kbPlugin.sessionContext.buildSummary(
+          { rootRunId, ...sessionId ? { sessionId } : {} },
+          6e3
+        );
+        if (contextSummary) {
+          systemPrompt += `
+
+<shared_context>
+The following context was shared by other agents in this workflow. Use it to avoid redundant work:
+${contextSummary}
+</shared_context>`;
+        }
+      }
+    } catch (e) {
+      (_m = (_l = ctx.app.log) == null ? void 0 : _l.debug) == null ? void 0 : _m.call(_l, `[AgentOrchestrator] Shared context injection skipped: ${e.message}`);
+    }
     const combinedTask = context ? `Task: ${task}
 
 Context Provided:

package/dist/server/tools/external-rag-search.d.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+export declare function createExternalRagSearchTool(plugin: any): {
+    scope: "CUSTOM";
+    execution: "backend";
+    defaultPermission: "ALLOW";
+    introduction: {
+        title: string;
+        about: string;
+    };
+    definition: {
+        name: string;
+        description: string;
+        schema: z.ZodObject<{
+            query: z.ZodString;
+            knowledgeBaseIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            topK: z.ZodOptional<z.ZodNumber>;
+            scoreThreshold: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            query?: string;
+            knowledgeBaseIds?: string[];
+            topK?: number;
+            scoreThreshold?: number;
+        }, {
+            query?: string;
+            knowledgeBaseIds?: string[];
+            topK?: number;
+            scoreThreshold?: number;
+        }>;
+    };
+    invoke: (ctx: any, args: {
+        query?: string;
+        knowledgeBaseIds?: string[];
+        topK?: number;
+        scoreThreshold?: number;
+    }) => Promise<{
+        status: "error";
+        content: string;
+    } | {
+        status: "success";
+        content: string;
+    }>;
+};

package/dist/server/tools/external-rag-search.js

@@ -0,0 +1,140 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var external_rag_search_exports = {};
+__export(external_rag_search_exports, {
+  createExternalRagSearchTool: () => createExternalRagSearchTool
+});
+module.exports = __toCommonJS(external_rag_search_exports);
+var import_zod = require("zod");
+const TOOL_NAME = "external_rag_search";
+const MAX_CONTENT_LENGTH = 4e3;
+function truncate(value, max = MAX_CONTENT_LENGTH) {
+  const text = typeof value === "string" ? value : value == null ? "" : String(value);
+  return text.length > max ? `${text.slice(0, max)}...` : text;
+}
+function firstString(...values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) {
+      return value.trim();
+    }
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return String(value);
+    }
+  }
+  return void 0;
+}
+function normalizeResult(result) {
+  const metadata = (result == null ? void 0 : result.metadata) ?? {};
+  const sourceId = firstString(
+    result == null ? void 0 : result.id,
+    metadata.id,
+    metadata.sourceId,
+    metadata.documentId,
+    metadata.docId,
+    metadata.fileId,
+    metadata.recordId
+  );
+  const filename = firstString(metadata.filename, metadata.fileName, metadata.name, metadata.title, metadata.source);
+  return {
+    content: truncate(result == null ? void 0 : result.content),
+    score: Number((result == null ? void 0 : result.rerankScore) ?? (result == null ? void 0 : result.score) ?? (result == null ? void 0 : result.vectorScore) ?? 0),
+    knowledgeBaseId: result == null ? void 0 : result.knowledgeBaseId,
+    knowledgeBaseName: result == null ? void 0 : result.knowledgeBaseName,
+    source: {
+      id: sourceId,
+      filename,
+      url: firstString(metadata.url, metadata.fileUrl, metadata.sourceUrl),
+      collection: firstString(metadata.collection, metadata.collectionName),
+      recordId: firstString(metadata.recordId, metadata.rowId)
+    },
+    metadata
+  };
+}
+function createExternalRagSearchTool(plugin) {
+  return {
+    scope: "CUSTOM",
+    execution: "backend",
+    defaultPermission: "ALLOW",
+    introduction: {
+      title: "External RAG Search",
+      about: "Search NocoBase knowledge bases through plugin-knowledge-base, including EXTERNAL_RAG services that own chunking, embedding, and retrieval."
+    },
+    definition: {
+      name: TOOL_NAME,
+      description: `Search configured knowledge bases for relevant context. Use this before answering questions that require documents, files, or datasource-backed knowledge.
+
+The search may be served by an external RAG service. Results include content plus source identifiers such as id, filename, collection, and recordId when the external service provides them.`,
+      schema: import_zod.z.object({
+        query: import_zod.z.string().min(1).describe("Natural-language search query."),
+        knowledgeBaseIds: import_zod.z.array(import_zod.z.string().min(1)).optional().describe(
+          "Optional list of NocoBase knowledge base IDs to search. If omitted, all accessible KBs are searched."
+        ),
+        topK: import_zod.z.number().int().min(1).max(20).optional().describe("Maximum results to return. Default 5, max 20."),
+        scoreThreshold: import_zod.z.number().min(0).max(1).optional().describe("Minimum relevance score. Default is controlled by plugin-knowledge-base.")
+      })
+    },
+    invoke: async (ctx, args) => {
+      var _a, _b, _c, _d, _e;
+      const query = typeof (args == null ? void 0 : args.query) === "string" ? args.query.trim() : "";
+      if (!query) {
+        return { status: "error", content: "Missing required field: query." };
+      }
+      const kbPlugin = (_c = (_b = (_a = ctx == null ? void 0 : ctx.app) == null ? void 0 : _a.pm) == null ? void 0 : _b.get) == null ? void 0 : _c.call(_b, "plugin-knowledge-base");
+      if (!(kbPlugin == null ? void 0 : kbPlugin.searchKnowledgeBases)) {
+        return {
+          status: "error",
+          content: "plugin-knowledge-base is not installed or does not expose searchKnowledgeBases()."
+        };
+      }
+      try {
+        const results = await kbPlugin.searchKnowledgeBases(ctx, query, {
+          knowledgeBaseIds: Array.isArray(args.knowledgeBaseIds) ? args.knowledgeBaseIds.map(String) : void 0,
+          topK: args.topK,
+          scoreThreshold: args.scoreThreshold,
+          rerank: true
+        });
+        return {
+          status: "success",
+          content: JSON.stringify({
+            query,
+            results: (results ?? []).map(normalizeResult)
+          })
+        };
+      } catch (error) {
+        (_e = (_d = plugin.app.log) == null ? void 0 : _d.error) == null ? void 0 : _e.call(_d, "[AgentOrchestrator] external_rag_search failed", error);
+        return {
+          status: "error",
+          content: `External RAG search failed: ${(error == null ? void 0 : error.message) || String(error)}`
+        };
+      }
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createExternalRagSearchTool
+});

package/dist/server/tools/skill-execute.d.ts

@@ -29,7 +29,7 @@ export declare function createSkillExecuteTool(plugin: any): {
             required: string[];
         };
     };
-    invoke(args: Record<string, any>, options?: any): Promise<{
+    invoke(ctx: any, args: Record<string, any>, _id?: string): Promise<{
         status: string;
         content: string;
     }>;

package/dist/server/tools/skill-execute.js

@@ -69,9 +69,8 @@ IMPORTANT: If the skill returns file download URLs, you MUST format them as clic
         required: ["action"]
       }
     },
-    async invoke(args, options) {
+    async invoke(ctx, args, _id) {
       var _a;
-      const ctx = options == null ? void 0 : options.context;
       plugin.app.logger.info(`[skill-execute] Tool invoked with action: ${args.action}, skillName: ${args.skillName}`);
       if (args.action === "list") {
         const skills = await plugin.db.getRepository("skillDefinitions").find({

package/package.json

@@ -4,7 +4,7 @@
   "displayName.zh-CN": "代理协调器",
   "displayName.vi-VN": "Điều phối Agent",
   "description": "Hierarchical Multi-Agent orchestration for NocoBase AI Employees. Enables Leader agents to delegate tasks to Sub-Agent employees without modifying core plugin-ai.",
-  "version": "1.0.15",
+  "version": "1.0.16",
   "license": "Apache-2.0",
   "main": "dist/server/index.js",
   "keywords": [

package/src/server/plugin.ts

@@ -1,94 +1,104 @@
-import { Plugin } from '@nocobase/server';
-import path from 'path';
-import { createDelegateToolsProvider } from './tools/delegate-task';
-import { registerTracingResource } from './resources/tracing';
-import SkillHubSubFeature from './skill-hub/plugin';
-
-export class PluginAgentOrchestratorServer extends Plugin {
-  skillHub: SkillHubSubFeature;
-
-  async afterAdd() {
-    this.skillHub = new SkillHubSubFeature(this);
-  }
-
-  async beforeLoad() {
-    // Import collection definitions
-    (this as any).db.import({ directory: path.resolve(__dirname, 'collections') });
-
-    (this as any).db.addMigrations({
-      namespace: (this as any).name,
-      directory: path.resolve(__dirname, 'migrations'),
-      context: { plugin: this },
-    });
-  }
-
-  async load() {
-    await this.skillHub.load();
-
-    // --- ACL ---
-    (this as any).app.acl.registerSnippet({
-      name: `pm.${(this as any).name}`,
-      actions: ['orchestratorConfig:*', 'orchestratorTracing:*', 'agentExecutionSpans:*', 'skillDefinitions:*', 'skillExecutions:*', 'skillHub:*', 'skillWorkerConfigs:*'],
-    });
-
-    // --- Register Dynamic Tools ---
-    // Each configured sub-agent becomes a callable tool for its leader.
-    // Uses createReactAgent (LangGraph public API) instead of private AIEmployee class.
-    // Tools are registered via app.aiManager.toolsManager (public API from @nocobase/ai core).
-    const toolsManager = (this as any).app.aiManager.toolsManager;
-    toolsManager.registerDynamicTools(createDelegateToolsProvider(this));
-
-    // --- Register Tracing Resource (Phase 5) ---
-    // Custom read-only resource for the Swarm Tracing admin page.
-    registerTracingResource(this);
-
-    // --- Log Retention ---
-    // Daily prune of orchestratorLogs / agentExecutionSpans to keep tables bounded.
-    // Override window via env: ORCHESTRATOR_LOG_RETENTION_DAYS (default 30).
-    (this as any).app.cronJobManager.addJob({
-      cronTime: '0 30 2 * * *',
-      onTick: async () => {
-        try {
-          const days = Number(process.env.ORCHESTRATOR_LOG_RETENTION_DAYS || 30);
-          if (!Number.isFinite(days) || days <= 0) return;
-          const cutoff = new Date(Date.now() - days * 86400000);
-          const repo = (this as any).db.getRepository('orchestratorLogs');
-          const spansRepo = (this as any).db.getRepository('agentExecutionSpans');
-          const deletedLogs = repo
-            ? await repo.destroy({
-                filter: { createdAt: { $lt: cutoff.toISOString() } },
-              })
-            : 0;
-          const deletedSpans = spansRepo
-            ? await spansRepo.destroy({
-                filter: { createdAt: { $lt: cutoff.toISOString() } },
-              })
-            : 0;
-          (this as any).app.log.info(
-            `[AgentOrchestrator] Pruned ${deletedLogs} orchestratorLogs and ${deletedSpans} agentExecutionSpans rows older than ${days} day(s).`,
-          );
-        } catch (e) {
-          (this as any).app.log.error('[AgentOrchestrator] Log retention job failed', e);
-        }
-      },
-    });
-
-    // NOTE: The createReactAgent approach does NOT create aiConversation records,
-    // so there is no need for a middleware to hide "headless" conversations.
-    // If future versions need conversation logging, add it here.
-  }
-
-  async install() {
-    await this.skillHub.install();
-  }
-
-  async afterEnable() {}
-  async afterDisable() {}
-  async remove() {}
-  
-  async beforeStop() {
-    await this.skillHub.beforeStop();
-  }
-}
-
-export default PluginAgentOrchestratorServer;
+import { Plugin } from '@nocobase/server';
+import path from 'path';
+import { createDelegateToolsProvider } from './tools/delegate-task';
+import { createExternalRagSearchTool } from './tools/external-rag-search';
+import { registerTracingResource } from './resources/tracing';
+import SkillHubSubFeature from './skill-hub/plugin';
+
+export class PluginAgentOrchestratorServer extends Plugin {
+  skillHub: SkillHubSubFeature;
+
+  async afterAdd() {
+    this.skillHub = new SkillHubSubFeature(this);
+  }
+
+  async beforeLoad() {
+    // Import collection definitions
+    (this as any).db.import({ directory: path.resolve(__dirname, 'collections') });
+
+    (this as any).db.addMigrations({
+      namespace: (this as any).name,
+      directory: path.resolve(__dirname, 'migrations'),
+      context: { plugin: this },
+    });
+  }
+
+  async load() {
+    await this.skillHub.load();
+
+    // --- ACL ---
+    (this as any).app.acl.registerSnippet({
+      name: `pm.${(this as any).name}`,
+      actions: [
+        'orchestratorConfig:*',
+        'orchestratorTracing:*',
+        'agentExecutionSpans:*',
+        'skillDefinitions:*',
+        'skillExecutions:*',
+        'skillHub:*',
+        'skillWorkerConfigs:*',
+      ],
+    });
+
+    // --- Register Dynamic Tools ---
+    // Each configured sub-agent becomes a callable tool for its leader.
+    // Uses createReactAgent (LangGraph public API) instead of private AIEmployee class.
+    // Tools are registered via app.aiManager.toolsManager (public API from @nocobase/ai core).
+    const toolsManager = (this as any).app.aiManager.toolsManager;
+    toolsManager.registerTools(createExternalRagSearchTool(this));
+    toolsManager.registerDynamicTools(createDelegateToolsProvider(this));
+
+    // --- Register Tracing Resource (Phase 5) ---
+    // Custom read-only resource for the Swarm Tracing admin page.
+    registerTracingResource(this);
+
+    // --- Log Retention ---
+    // Daily prune of orchestratorLogs / agentExecutionSpans to keep tables bounded.
+    // Override window via env: ORCHESTRATOR_LOG_RETENTION_DAYS (default 30).
+    (this as any).app.cronJobManager.addJob({
+      cronTime: '0 30 2 * * *',
+      onTick: async () => {
+        try {
+          const days = Number(process.env.ORCHESTRATOR_LOG_RETENTION_DAYS || 30);
+          if (!Number.isFinite(days) || days <= 0) return;
+          const cutoff = new Date(Date.now() - days * 86400000);
+          const repo = (this as any).db.getRepository('orchestratorLogs');
+          const spansRepo = (this as any).db.getRepository('agentExecutionSpans');
+          const deletedLogs = repo
+            ? await repo.destroy({
+                filter: { createdAt: { $lt: cutoff.toISOString() } },
+              })
+            : 0;
+          const deletedSpans = spansRepo
+            ? await spansRepo.destroy({
+                filter: { createdAt: { $lt: cutoff.toISOString() } },
+              })
+            : 0;
+          (this as any).app.log.info(
+            `[AgentOrchestrator] Pruned ${deletedLogs} orchestratorLogs and ${deletedSpans} agentExecutionSpans rows older than ${days} day(s).`,
+          );
+        } catch (e) {
+          (this as any).app.log.error('[AgentOrchestrator] Log retention job failed', e);
+        }
+      },
+    });
+
+    // NOTE: The createReactAgent approach does NOT create aiConversation records,
+    // so there is no need for a middleware to hide "headless" conversations.
+    // If future versions need conversation logging, add it here.
+  }
+
+  async install() {
+    await this.skillHub.install();
+  }
+
+  async afterEnable() {}
+  async afterDisable() {}
+  async remove() {}
+
+  async beforeStop() {
+    await this.skillHub.beforeStop();
+  }
+}
+
+export default PluginAgentOrchestratorServer;

package/src/server/services/SkillManager.ts

@@ -1,11 +1,11 @@
-import { Database } from '@nocobase/database';
-import { stringifyJsonText } from '../skill-hub/utils/json-fields';
+import { Database } from '@nocobase/database';
+import { stringifyJsonText } from '../skill-hub/utils/json-fields';
 
 export class SkillManager {
   constructor(private db: Database) {}
 
   async seedDefaults() {
-    const repo = (this as any).db.getRepository('skillDefinitions');
+    const repo = this.db.getRepository('skillDefinitions');
 
     const seeds = [
       {
@@ -203,16 +203,16 @@ export class SkillManager {
 
     for (const seed of seeds) {
       try {
-        const count = await repo.count({ filter: { name: seed.name } });
-        if (count === 0) {
-          await repo.create({
-            values: {
-              ...seed,
-              inputSchema: stringifyJsonText(seed.inputSchema),
-              packages: stringifyJsonText(seed.packages, []),
-            },
-          });
-        }
+        const count = await repo.count({ filter: { name: seed.name } });
+        if (count === 0) {
+          await repo.create({
+            values: {
+              ...seed,
+              inputSchema: stringifyJsonText(seed.inputSchema),
+              packages: stringifyJsonText(seed.packages, []),
+            },
+          });
+        }
       } catch (err) {
         console.error(`[import-skill] Failed to insert ${seed.name}:`, err);
         // Skip if already exists (unique constraint on name)
@@ -330,46 +330,6 @@ doc.build(story)
 print('Generated: report.pdf')
 `;
 
-const SEED_PPTX = `import os, json
-from pptx import Presentation
-from pptx.util import Inches, Pt
-from pptx.enum.text import PP_ALIGN
-
-title = json.loads('''{{title}}''') if '{{title}}'.startswith('"') else '{{title}}'
-subtitle_raw = '''{{subtitle}}'''
-subtitle = json.loads(subtitle_raw) if subtitle_raw.startswith('"') else subtitle_raw if subtitle_raw != '{{' + 'subtitle}}' else ''
-slides_data = json.loads('''{{slides}}''')
-
-prs = Presentation()
-prs.slide_width = Inches(13.333)
-prs.slide_height = Inches(7.5)
-
-# Title slide
-slide = prs.slides.add_slide(prs.slide_layouts[0])
-slide.shapes.title.text = title
-if subtitle and slide.placeholders[1]:
-    slide.placeholders[1].text = subtitle
-
-# Content slides
-for s in slides_data:
-    slide = prs.slides.add_slide(prs.slide_layouts[1])
-    slide.shapes.title.text = s.get('title', '')
-    body = slide.placeholders[1].text_frame
-    body.clear()
-    for i, bullet in enumerate(s.get('bullets', [])):
-        if i == 0:
-            body.paragraphs[0].text = bullet
-        else:
-            p = body.add_paragraph()
-            p.text = bullet
-        body.paragraphs[-1].font.size = Pt(18)
-
-output_dir = os.environ.get('OUTPUT_DIR', '/output')
-filepath = os.path.join(output_dir, 'presentation.pptx')
-prs.save(filepath)
-print('Generated: presentation.pptx')
-`;
-
 const SEED_CHART = `import os, json
 import matplotlib
 matplotlib.use('Agg')

package/src/server/skill-hub/plugin.ts

@@ -543,7 +543,7 @@ export class SkillHubSubFeature {
                   filter: { id: skill.get('id'), enabled: true },
                 });
                 if (!latestSkill) {
-                  return { error: `Skill "${skill.get('name')}" is no longer available` };
+                  return { status: 'error', content: `Skill "${skill.get('name')}" is no longer available` };
                 }
                 const result = await this.executeSkill(latestSkill, args, toolCtx);
                 return {
@@ -582,7 +582,7 @@ export class SkillHubSubFeature {
           const repo = (this as any).db.getRepository('skillExecutions');
           
           const outdated = await repo.find({
-            where: { createdAt: { $lt: cutoff } }
+            filter: { createdAt: { $lt: cutoff } }
           });
           
           if (outdated.length > 0) {
@@ -638,7 +638,7 @@ export class SkillHubSubFeature {
       const hours = config ? config.get('retentionHours') : 24;
       if (hours > 0) {
         const cutoff = new Date(Date.now() - hours * 60 * 60 * 1000);
-        const results = await repo.find({ where: { createdAt: { $lt: cutoff } }, fields: ['id'] });
+        const results = await repo.find({ filter: { createdAt: { $lt: cutoff } }, fields: ['id'] });
         for (const rec of results) {
           await rec.destroy();
         }

package/src/server/tools/delegate-task.ts

@@ -1046,13 +1046,37 @@ async function invokeDelegateTask(
     });
 
     // --- Step 4: Construct messages ---
-    const systemPrompt =
+    let systemPrompt =
       subAgentEmployee.chatSettings?.systemPrompt ||
       subAgentEmployee.bio ||
       `You are an AI assistant named "${subAgentEmployee.nickname || subAgentUsername}". ${
         subAgentEmployee.about || ''
       }`;
 
+    // --- Step 4b: Inject shared context from Knowledge Base (soft dependency) ---
+    // If plugin-knowledge-base is installed, inject the session context summary
+    // so the sub-agent is aware of findings from previous agents in this run.
+    try {
+      const kbPlugin = ctx.app.pm.get('plugin-knowledge-base') as any;
+      if (kbPlugin?.sessionContext) {
+        const sessionId =
+          ctx.action?.params?.values?.sessionId ||
+          ctx.action?.params?.sessionId ||
+          ctx.state?.sessionId;
+
+        const contextSummary = await kbPlugin.sessionContext.buildSummary(
+          { rootRunId, ...(sessionId ? { sessionId } : {}) },
+          6000,
+        );
+        if (contextSummary) {
+          systemPrompt += `\n\n<shared_context>\nThe following context was shared by other agents in this workflow. Use it to avoid redundant work:\n${contextSummary}\n</shared_context>`;
+        }
+      }
+    } catch (e: any) {
+      // Graceful fallback — never block delegation due to context injection failure.
+      ctx.app.log?.debug?.(`[AgentOrchestrator] Shared context injection skipped: ${e.message}`);
+    }
+
     const combinedTask = context ? `Task: ${task}\n\nContext Provided:\n${context}` : `Task: ${task}`;
 
     // --- Step 5: Execute with timeout + abort ---

package/src/server/tools/external-rag-search.ts

@@ -0,0 +1,128 @@
+import { z } from 'zod';
+
+const TOOL_NAME = 'external_rag_search';
+const MAX_CONTENT_LENGTH = 4000;
+
+function truncate(value: unknown, max = MAX_CONTENT_LENGTH) {
+  const text = typeof value === 'string' ? value : value == null ? '' : String(value);
+  return text.length > max ? `${text.slice(0, max)}...` : text;
+}
+
+function firstString(...values: unknown[]) {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim()) {
+      return value.trim();
+    }
+    if (typeof value === 'number' && Number.isFinite(value)) {
+      return String(value);
+    }
+  }
+  return undefined;
+}
+
+function normalizeResult(result: any) {
+  const metadata = result?.metadata ?? {};
+  const sourceId = firstString(
+    result?.id,
+    metadata.id,
+    metadata.sourceId,
+    metadata.documentId,
+    metadata.docId,
+    metadata.fileId,
+    metadata.recordId,
+  );
+  const filename = firstString(metadata.filename, metadata.fileName, metadata.name, metadata.title, metadata.source);
+
+  return {
+    content: truncate(result?.content),
+    score: Number(result?.rerankScore ?? result?.score ?? result?.vectorScore ?? 0),
+    knowledgeBaseId: result?.knowledgeBaseId,
+    knowledgeBaseName: result?.knowledgeBaseName,
+    source: {
+      id: sourceId,
+      filename,
+      url: firstString(metadata.url, metadata.fileUrl, metadata.sourceUrl),
+      collection: firstString(metadata.collection, metadata.collectionName),
+      recordId: firstString(metadata.recordId, metadata.rowId),
+    },
+    metadata,
+  };
+}
+
+export function createExternalRagSearchTool(plugin: any) {
+  return {
+    scope: 'CUSTOM' as const,
+    execution: 'backend' as const,
+    defaultPermission: 'ALLOW' as const,
+
+    introduction: {
+      title: 'External RAG Search',
+      about:
+        'Search NocoBase knowledge bases through plugin-knowledge-base, including EXTERNAL_RAG services that own chunking, embedding, and retrieval.',
+    },
+
+    definition: {
+      name: TOOL_NAME,
+      description: `Search configured knowledge bases for relevant context. Use this before answering questions that require documents, files, or datasource-backed knowledge.
+
+The search may be served by an external RAG service. Results include content plus source identifiers such as id, filename, collection, and recordId when the external service provides them.`,
+      schema: z.object({
+        query: z.string().min(1).describe('Natural-language search query.'),
+        knowledgeBaseIds: z
+          .array(z.string().min(1))
+          .optional()
+          .describe(
+            'Optional list of NocoBase knowledge base IDs to search. If omitted, all accessible KBs are searched.',
+          ),
+        topK: z.number().int().min(1).max(20).optional().describe('Maximum results to return. Default 5, max 20.'),
+        scoreThreshold: z
+          .number()
+          .min(0)
+          .max(1)
+          .optional()
+          .describe('Minimum relevance score. Default is controlled by plugin-knowledge-base.'),
+      }),
+    },
+
+    invoke: async (
+      ctx: any,
+      args: { query?: string; knowledgeBaseIds?: string[]; topK?: number; scoreThreshold?: number },
+    ) => {
+      const query = typeof args?.query === 'string' ? args.query.trim() : '';
+      if (!query) {
+        return { status: 'error' as const, content: 'Missing required field: query.' };
+      }
+
+      const kbPlugin = ctx?.app?.pm?.get?.('plugin-knowledge-base');
+      if (!kbPlugin?.searchKnowledgeBases) {
+        return {
+          status: 'error' as const,
+          content: 'plugin-knowledge-base is not installed or does not expose searchKnowledgeBases().',
+        };
+      }
+
+      try {
+        const results = await kbPlugin.searchKnowledgeBases(ctx, query, {
+          knowledgeBaseIds: Array.isArray(args.knowledgeBaseIds) ? args.knowledgeBaseIds.map(String) : undefined,
+          topK: args.topK,
+          scoreThreshold: args.scoreThreshold,
+          rerank: true,
+        });
+
+        return {
+          status: 'success' as const,
+          content: JSON.stringify({
+            query,
+            results: (results ?? []).map(normalizeResult),
+          }),
+        };
+      } catch (error: any) {
+        plugin.app.log?.error?.('[AgentOrchestrator] external_rag_search failed', error);
+        return {
+          status: 'error' as const,
+          content: `External RAG search failed: ${error?.message || String(error)}`,
+        };
+      }
+    },
+  };
+}

package/src/server/tools/skill-execute.ts

@@ -42,8 +42,7 @@ IMPORTANT: If the skill returns file download URLs, you MUST format them as clic
       },
     },
 
-    async invoke(args: Record<string, any>, options?: any) {
-      const ctx = options?.context;
+    async invoke(ctx: any, args: Record<string, any>, _id?: string) {
       plugin.app.logger.info(`[skill-execute] Tool invoked with action: ${args.action}, skillName: ${args.skillName}`);
       
       // Action: list available skills