plugin-agent-orchestrator 1.0.0

package/src/server/collections/orchestrator-config.ts

@@ -0,0 +1,49 @@
+import { defineCollection } from '@nocobase/database';
+
+export default defineCollection({
+  name: 'orchestratorConfig',
+  title: 'Orchestrator Config',
+  fields: [
+    {
+      name: 'id',
+      type: 'bigInt',
+      autoIncrement: true,
+      primaryKey: true,
+    },
+    {
+      name: 'leaderUsername',
+      type: 'string',
+      allowNull: false,
+      comment: 'AI Employee username that acts as the Leader/Orchestrator',
+    },
+    {
+      name: 'subAgentUsername',
+      type: 'string',
+      allowNull: false,
+      comment: 'AI Employee username that acts as the Sub-Agent',
+    },
+    {
+      name: 'enabled',
+      type: 'boolean',
+      defaultValue: true,
+    },
+    {
+      name: 'maxDepth',
+      type: 'integer',
+      defaultValue: 1,
+      comment: 'Maximum delegation depth (1 = leader can call sub, sub cannot call further)',
+    },
+    {
+      name: 'timeout',
+      type: 'integer',
+      defaultValue: 120000,
+      comment: 'Timeout in ms for sub-agent execution',
+    },
+  ],
+  indexes: [
+    {
+      unique: true,
+      fields: ['leaderUsername', 'subAgentUsername'],
+    },
+  ],
+});

package/src/server/collections/orchestrator-logs.ts

@@ -0,0 +1,99 @@
+import { defineCollection } from '@nocobase/database';
+
+/**
+ * Stores delegation execution logs for Swarm Tracing (Phase 5).
+ *
+ * Since createReactAgent doesn't create aiConversation records,
+ * we log delegation events to a dedicated table for observability.
+ */
+export default defineCollection({
+  name: 'orchestratorLogs',
+  title: 'Orchestrator Logs',
+  fields: [
+    {
+      name: 'id',
+      type: 'bigInt',
+      autoIncrement: true,
+      primaryKey: true,
+    },
+    {
+      name: 'leaderUsername',
+      type: 'string',
+      allowNull: false,
+      comment: 'The AI Employee that initiated the delegation',
+    },
+    {
+      name: 'subAgentUsername',
+      type: 'string',
+      allowNull: false,
+      comment: 'The AI Employee that executed the delegated task',
+    },
+    {
+      name: 'toolName',
+      type: 'string',
+      comment: 'The tool name used for delegation (e.g., delegate_to_sql_expert)',
+    },
+    {
+      name: 'task',
+      type: 'text',
+      comment: 'The task description sent to the sub-agent',
+    },
+    {
+      name: 'result',
+      type: 'text',
+      comment: 'The sub-agent result content',
+    },
+    {
+      name: 'status',
+      type: 'string',
+      comment: 'success or error',
+    },
+    {
+      name: 'depth',
+      type: 'integer',
+      defaultValue: 0,
+      comment: 'Delegation depth level (0 = first-level delegation)',
+    },
+    {
+      name: 'durationMs',
+      type: 'integer',
+      comment: 'Execution duration in milliseconds',
+    },
+    {
+      name: 'error',
+      type: 'text',
+      comment: 'Error message if status is error',
+    },
+    {
+      name: 'userId',
+      type: 'bigInt',
+      comment: 'The user who triggered the leader conversation',
+    },
+    {
+      name: 'createdAt',
+      type: 'date',
+      interface: 'createdAt',
+      field: 'createdAt',
+      uiSchema: {
+        type: 'datetime',
+        title: '{{t("Created at")}}',
+        'x-component': 'DatePicker',
+        'x-component-props': { showTime: true },
+        'x-read-pretty': true,
+      },
+    },
+    {
+      name: 'updatedAt',
+      type: 'date',
+      interface: 'updatedAt',
+      field: 'updatedAt',
+      uiSchema: {
+        type: 'datetime',
+        title: '{{t("Updated at")}}',
+        'x-component': 'DatePicker',
+        'x-component-props': { showTime: true },
+        'x-read-pretty': true,
+      },
+    },
+  ],
+});

package/src/server/index.ts

@@ -0,0 +1 @@
+export { default } from './plugin';

package/src/server/plugin.ts

@@ -0,0 +1,46 @@
+import { Plugin } from '@nocobase/server';
+import path from 'path';
+import { createDelegateToolsProvider } from './tools/delegate-task';
+import { registerTracingResource } from './resources/tracing';
+
+export class PluginAgentOrchestratorServer extends Plugin {
+  async afterAdd() {}
+
+  async beforeLoad() {
+    // Import collection definitions
+    this.db.import({ directory: path.resolve(__dirname, 'collections') });
+  }
+
+  async load() {
+    // --- ACL ---
+    this.app.acl.registerSnippet({
+      name: `pm.${this.name}`,
+      actions: ['orchestratorConfig:*'],
+    });
+
+    // --- 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.app.aiManager.toolsManager;
+    toolsManager.registerDynamicTools(createDelegateToolsProvider(this));
+
+    // --- Register Tracing Resource (Phase 5) ---
+    // Custom read-only resource for the Swarm Tracing admin page.
+    registerTracingResource(this);
+
+    // 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() {
+    // No seed data needed on first install
+  }
+
+  async afterEnable() {}
+  async afterDisable() {}
+  async remove() {}
+}
+
+export default PluginAgentOrchestratorServer;

package/src/server/resources/tracing.ts

@@ -0,0 +1,91 @@
+import { Plugin } from '@nocobase/server';
+
+/**
+ * Custom resource for the Swarm Tracing admin UI (Phase 5).
+ * Queries the dedicated orchestratorLogs collection instead of
+ * filtering aiConversations by JSONB (P2 fix: DB-engine agnostic).
+ */
+export function registerTracingResource(plugin: Plugin) {
+  const app = plugin.app;
+
+  app.resource({
+    name: 'orchestratorTracing',
+    actions: {
+      /**
+       * List all delegation execution logs.
+       */
+      async list(ctx, next) {
+        const repo = ctx.db.getRepository('orchestratorLogs');
+        const { page = 1, pageSize = 50, sort = ['-createdAt'] } = ctx.action.params;
+
+        try {
+          const [rows, count] = await repo.findAndCount({
+            sort,
+            offset: (Number(page) - 1) * Number(pageSize),
+            limit: Number(pageSize),
+          });
+
+          ctx.body = {
+            data: rows.map((row: any) => ({
+              id: row.id,
+              leaderUsername: row.leaderUsername,
+              subAgentUsername: row.subAgentUsername,
+              toolName: row.toolName,
+              task: row.task,
+              result: row.result,
+              status: row.status,
+              depth: row.depth,
+              durationMs: row.durationMs,
+              error: row.error,
+              userId: row.userId,
+              createdAt: row.createdAt,
+            })),
+            meta: {
+              count,
+              page: Number(page),
+              pageSize: Number(pageSize),
+              totalPage: Math.ceil(count / Number(pageSize)),
+            },
+          };
+        } catch (e) {
+          ctx.log.error('[AgentOrchestrator] Tracing list error', e);
+          ctx.body = { data: [], meta: { count: 0 } };
+        }
+
+        await next();
+      },
+
+      /**
+       * Get a single delegation log by ID.
+       */
+      async get(ctx, next) {
+        const { filterByTk } = ctx.action.params;
+
+        if (!filterByTk) {
+          ctx.throw(400, 'id is required');
+          return;
+        }
+
+        try {
+          const repo = ctx.db.getRepository('orchestratorLogs');
+          const log = await repo.findOne({
+            filter: { id: filterByTk },
+          });
+
+          ctx.body = { data: log };
+        } catch (e) {
+          ctx.log.error('[AgentOrchestrator] Tracing get error', e);
+          ctx.body = { data: null };
+        }
+
+        await next();
+      },
+    },
+  });
+
+  // ACL: allow admin access to tracing endpoints
+  app.acl.registerSnippet({
+    name: `pm.${plugin.name}.tracing`,
+    actions: ['orchestratorTracing:list', 'orchestratorTracing:get'],
+  });
+}

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

@@ -0,0 +1,388 @@
+import { z } from 'zod';
+import { Context } from '@nocobase/actions';
+// @ts-ignore - subpath export types resolve at build time via NocoBase bundler
+import { createReactAgent } from '@langchain/langgraph/prebuilt';
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import type PluginAIServer from '@nocobase/plugin-ai/dist/server';
+import type { ToolsEntry } from '@nocobase/ai';
+
+/**
+ * Maximum delegation depth key stored in ctx metadata.
+ * Used to prevent circular/recursive delegation chains.
+ */
+const ORCHESTRATOR_DEPTH_KEY = '__orchestratorDepth';
+
+/**
+ * Creates one dynamic tool per configured sub-agent for a given leader.
+ * Uses Strategy B (Per-SubAgent Tool): each sub-agent becomes a separate tool
+ * with its own name and description, making LLM tool selection natural.
+ *
+ * Architecture:
+ * - Uses createReactAgent (public LangGraph API) for agent execution
+ * - Uses plugin-ai's getLLMService() for LLM model resolution
+ * - Uses core app.aiManager.toolsManager.listTools() for tool resolution
+ *   (same manager that AIEmployee uses — see ai-employee.ts:1286)
+ * - Depth enforcement via ctx metadata tracking
+ * - Per-leader scoping via invoke-time check (core ToolsOptions has no
+ *   leaderUsername field, so scoping is enforced in the invoke callback)
+ */
+export function createDelegateToolsProvider(plugin: any) {
+  return async (register: any) => {
+    try {
+      const configRepo = plugin.db.getRepository('orchestratorConfig');
+      if (!configRepo) return;
+
+      const configs = await configRepo.find({
+        filter: { enabled: true },
+      });
+      if (!configs?.length) return;
+
+      // Build a lookup: which leaders are allowed to use each delegate tool
+      // Multiple leaders may share the same sub-agent, but each leader must
+      // have an explicit rule.
+      const leadersByTool = new Map<string, Set<string>>();
+      for (const config of configs) {
+        const toolName = `delegate_to_${config.subAgentUsername.replace(/[^a-zA-Z0-9_-]/g, '_')}`;
+        if (!leadersByTool.has(toolName)) {
+          leadersByTool.set(toolName, new Set());
+        }
+        leadersByTool.get(toolName)!.add(config.leaderUsername);
+      }
+
+      // De-duplicate: register one tool per sub-agent (not per config row)
+      const seenSubAgents = new Set<string>();
+
+      for (const config of configs) {
+        const { leaderUsername, subAgentUsername, maxDepth, timeout } = config;
+
+        // Skip if we already registered this sub-agent's tool
+        if (seenSubAgents.has(subAgentUsername)) continue;
+        seenSubAgents.add(subAgentUsername);
+
+        // Fetch the sub-agent employee model for its description and LLM config
+        const subAgentEmployee = await plugin.db.getRepository('aiEmployees').findOne({
+          filter: { username: subAgentUsername },
+        });
+        if (!subAgentEmployee) continue;
+
+        const toolName = `delegate_to_${subAgentUsername.replace(/[^a-zA-Z0-9_-]/g, '_')}`;
+        const toolDescription = [
+          `Delegate a task to the AI Employee "${subAgentEmployee.nickname || subAgentUsername}".`,
+          subAgentEmployee.about ? `Specialist profile: ${subAgentEmployee.about.substring(0, 200)}` : '',
+          'The sub-agent will execute the task independently and return its final answer.',
+        ].filter(Boolean).join(' ');
+
+        // Capture the allowed leaders for this tool (for invoke-time scoping)
+        const allowedLeaders = leadersByTool.get(toolName)!;
+
+        register.registerTools({
+          scope: 'CUSTOM',
+          execution: 'backend',
+          defaultPermission: 'ALLOW',
+          silence: false,
+          introduction: {
+            title: `[Sub-Agent] ${subAgentEmployee.nickname || subAgentUsername}`,
+            about: toolDescription,
+          },
+          definition: {
+            name: toolName,
+            description: toolDescription,
+            schema: z.object({
+              task: z.string().describe('The detailed task description for the sub-agent to execute.'),
+              context: z.string().optional().describe('Optional additional context to help the sub-agent understand the task better.'),
+            }),
+          },
+          invoke: async (ctx: Context, args: { task: string; context?: string }, id: string) => {
+            // --- P2 FIX: Per-leader scoping at invoke time ---
+            // Core ToolsOptions doesn't support leaderUsername field, so
+            // we enforce scoping here by checking the calling employee.
+            const callingEmployee = (ctx as any)._currentAIEmployee?.username
+              || (ctx as any).state?.currentAIEmployee;
+            if (callingEmployee && !allowedLeaders.has(callingEmployee)) {
+              return {
+                status: 'error' as const,
+                content: `Employee "${callingEmployee}" is not authorized to delegate to "${subAgentUsername}". Configure an orchestration rule first.`,
+              };
+            }
+
+            return invokeDelegateTask(ctx, plugin, {
+              leaderUsername: callingEmployee || Array.from(allowedLeaders)[0] || '',
+              subAgentUsername,
+              subAgentEmployee,
+              task: args.task,
+              context: args.context,
+              maxDepth: maxDepth ?? 1,
+              timeout: timeout ?? 120000,
+              toolCallId: id,
+            });
+          },
+        });
+      }
+    } catch (e) {
+      plugin.app.log.error('[AgentOrchestrator] Failed to register delegate tools', e);
+    }
+  };
+}
+
+/**
+ * Core execution logic using createReactAgent (public LangGraph API).
+ *
+ * This approach mirrors plugin-sub-agent's proven pattern:
+ *  1. Get LLM model via aiPlugin.aiManager.getLLMService()
+ *  2. Resolve sub-agent's tools via core app.aiManager.toolsManager.listTools()
+ *  3. Build a standalone createReactAgent with the model + tools
+ *  4. Stream results and extract final AI message
+ *
+ * Tool resolution uses the CORE toolsManager (app.aiManager.toolsManager) —
+ * the same manager that AIEmployee.getToolsMap() uses (see ai-employee.ts:1286).
+ * This ensures tool names in skillSettings.skills[].name match correctly.
+ *
+ * skillSettings.skills shape (verified against ai-employee.ts:1028):
+ *   { name: string, autoCall: boolean }[]
+ */
+async function invokeDelegateTask(
+  ctx: Context,
+  plugin: any,
+  options: {
+    leaderUsername: string;
+    subAgentUsername: string;
+    subAgentEmployee: any;
+    task: string;
+    context?: string;
+    maxDepth: number;
+    timeout: number;
+    toolCallId: string;
+  },
+) {
+  const { leaderUsername, subAgentUsername, subAgentEmployee, task, context, maxDepth, timeout, toolCallId } = options;
+
+  // --- P1: Depth enforcement ---
+  const currentDepth: number = (ctx as any)[ORCHESTRATOR_DEPTH_KEY] ?? 0;
+  if (currentDepth >= maxDepth) {
+    return {
+      status: 'error' as const,
+      content: `Delegation depth limit reached (${currentDepth}/${maxDepth}). Sub-agent "${subAgentUsername}" cannot delegate further.`,
+    };
+  }
+
+  const startTime = Date.now();
+
+  try {
+    const aiPlugin = ctx.app.pm.get('ai') as PluginAIServer;
+    if (!aiPlugin) {
+      throw new Error('Plugin AI is not installed or enabled');
+    }
+
+    // --- Step 1: Resolve LLM model from sub-agent's employee config ---
+    const modelSettings = subAgentEmployee.modelSettings;
+    if (!modelSettings?.llmService || !modelSettings?.model) {
+      throw new Error(`Sub-agent "${subAgentUsername}" has no LLM model configured. Please configure a model in the AI Employee settings.`);
+    }
+
+    const { provider } = await aiPlugin.aiManager.getLLMService({
+      llmService: modelSettings.llmService,
+      model: modelSettings.model,
+    });
+    const chatModel = provider.createModel();
+
+    // --- Step 2: Resolve tools via CORE toolsManager ---
+    // Uses app.aiManager.toolsManager (same as AIEmployee.getToolsMap at ai-employee.ts:1286)
+    // NOT plugin-ai's local toolManager (which has a different grouped format).
+    const coreToolsManager = ctx.app.aiManager.toolsManager;
+    const allTools: ToolsEntry[] = await coreToolsManager.listTools();
+
+    // skillSettings.skills is { name: string, autoCall: boolean }[]
+    // (verified at ai-employee.ts:1028-1029)
+    const employeeSkills: string[] = (subAgentEmployee.skillSettings?.skills ?? [])
+      .map((s: any) => (typeof s === 'string' ? s : s.name))
+      .filter(Boolean);
+
+    const langchainTools: DynamicStructuredTool[] = [];
+
+    for (const toolEntry of allTools) {
+      const toolName = toolEntry.definition.name;
+      if (!toolName) continue;
+
+      // Only include tools that the sub-agent employee is configured to use.
+      // Also skip our own delegate_to_* tools to prevent circular delegation
+      // (belt-and-suspenders with the depth check above).
+      if (!employeeSkills.includes(toolName) || toolName.startsWith('delegate_to_')) {
+        continue;
+      }
+
+      langchainTools.push(
+        new DynamicStructuredTool({
+          name: toolName.replace(/[^a-zA-Z0-9_-]/g, '_'),
+          description: toolEntry.definition.description || toolName,
+          schema: (toolEntry.definition.schema || z.object({})) as any,
+          func: async (toolArgs) => {
+            // Forward the invoke with depth tracking
+            const invokeCtx = Object.create(ctx);
+            (invokeCtx as any)[ORCHESTRATOR_DEPTH_KEY] = currentDepth + 1;
+
+            const res = await toolEntry.invoke(invokeCtx, toolArgs, `orch-${toolCallId}`);
+            if (res?.status === 'error') {
+              throw new Error(`Tool <${toolName}> failed: ${res.content}`);
+            }
+            return typeof res?.content === 'string' ? res.content : JSON.stringify(res);
+          },
+        }),
+      );
+    }
+
+    // --- Step 3: Build the agent ---
+    const abortController = new AbortController();
+    const executor = createReactAgent({
+      llm: chatModel,
+      tools: langchainTools,
+    });
+
+    // --- Step 4: Construct messages ---
+    const systemPrompt = subAgentEmployee.chatSettings?.systemPrompt
+      || subAgentEmployee.bio
+      || `You are an AI assistant named "${subAgentEmployee.nickname || subAgentUsername}". ${subAgentEmployee.about || ''}`;
+
+    const combinedTask = context
+      ? `Task: ${task}\n\nContext Provided:\n${context}`
+      : `Task: ${task}`;
+
+    // --- Step 5: Execute with timeout + abort ---
+    // P3 FIX: AbortController signal cancels the in-flight stream on timeout,
+    // preventing continued token consumption after the timeout fires.
+    const invokePromise = executeAgent(executor, systemPrompt, combinedTask, abortController.signal);
+
+    const result = await Promise.race([
+      invokePromise,
+      createTimeout(timeout, subAgentUsername, abortController),
+    ]);
+
+    const content = (result as string) || 'Sub-agent completed the task but produced no output.';
+
+    // Log successful execution for tracing
+    await logDelegation(ctx, plugin, {
+      leaderUsername,
+      subAgentUsername,
+      task,
+      result: content,
+      status: 'success',
+      depth: currentDepth,
+      durationMs: Date.now() - startTime,
+    });
+
+    return {
+      status: 'success' as const,
+      content,
+    };
+  } catch (e) {
+    plugin.app.log.error(`[AgentOrchestrator] Sub-agent ${subAgentUsername} failed`, e);
+
+    // Log failed execution for tracing
+    await logDelegation(ctx, plugin, {
+      leaderUsername,
+      subAgentUsername,
+      task,
+      result: '',
+      status: 'error',
+      depth: currentDepth,
+      durationMs: Date.now() - startTime,
+      error: e.message,
+    }).catch(() => {}); // Don't let logging errors mask the real error
+
+    return {
+      status: 'error' as const,
+      content: `Sub-agent "${subAgentUsername}" failed: ${e.message}`,
+    };
+  }
+}
+
+/**
+ * Log a delegation event to the orchestratorLogs collection for observability.
+ */
+async function logDelegation(
+  ctx: Context,
+  plugin: any,
+  data: {
+    leaderUsername: string;
+    subAgentUsername: string;
+    task: string;
+    result: string;
+    status: string;
+    depth: number;
+    durationMs: number;
+    error?: string;
+  },
+) {
+  try {
+    const logsRepo = plugin.db.getRepository('orchestratorLogs');
+    if (!logsRepo) return;
+
+    await logsRepo.create({
+      values: {
+        leaderUsername: data.leaderUsername,
+        subAgentUsername: data.subAgentUsername,
+        toolName: `delegate_to_${data.subAgentUsername}`,
+        task: data.task.substring(0, 2000),
+        result: data.result.substring(0, 5000),
+        status: data.status,
+        depth: data.depth,
+        durationMs: data.durationMs,
+        error: data.error?.substring(0, 2000),
+        userId: ctx.auth?.user?.id || ctx.state?.currentUser?.id,
+      },
+    });
+  } catch (e) {
+    plugin.app.log.warn('[AgentOrchestrator] Failed to log delegation event', e);
+  }
+}
+
+/**
+ * Execute the agent and extract the final AI message content.
+ * Uses stream mode to collect all chunks, similar to plugin-sub-agent.
+ * Accepts an AbortSignal so the stream can be cancelled on timeout.
+ */
+async function executeAgent(
+  executor: any,
+  systemPrompt: string,
+  task: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  const streamOptions: any = { recursionLimit: 50, streamMode: 'messages' };
+  if (signal) {
+    streamOptions.signal = signal;
+  }
+
+  const stream = await executor.stream(
+    {
+      messages: [new SystemMessage(systemPrompt), new HumanMessage(task)],
+    },
+    streamOptions,
+  );
+
+  let aiContentCache = '';
+
+  for await (const chunk of stream) {
+    // Check abort between chunks
+    if (signal?.aborted) break;
+
+    const [message] = chunk;
+    if (message.getType() === 'ai' && message.content) {
+      aiContentCache += message.content.toString();
+    }
+  }
+
+  return aiContentCache || '';
+}
+
+/**
+ * Create a timeout promise that rejects after the specified duration.
+ * P3 FIX: Also triggers AbortController to cancel the in-flight stream.
+ */
+function createTimeout(ms: number, agentName: string, abortController?: AbortController): Promise<never> {
+  return new Promise((_, reject) =>
+    setTimeout(() => {
+      abortController?.abort();
+      reject(new Error(`Sub-agent "${agentName}" timed out after ${ms / 1000}s`));
+    }, ms),
+  );
+}