plugin-agent-orchestrator 1.0.19 → 1.0.21

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

@@ -1,160 +1,160 @@
-import { parseJsonText } from '../skill-hub/utils/json-fields';
-
-export function createSkillExecuteTool(plugin: any) {
-  return {
-    scope: 'CUSTOM',
-    execution: 'backend',
-    defaultPermission: 'ASK',
-
-    introduction: {
-      title: 'Skill Hub - Universal Skill Executor',
-      about:
-        'A universal gateway to execute predefined specialized skills (data processing, complex calculations, file generation, etc.) inside a secure Python/Node.js sandbox.',
-    },
-
-    definition: {
-      name: 'skill_hub_execute',
-      description: `A universal gateway to execute various predefined specialized skills (e.g., data transformation, calculations, document/presentation generation) in an isolated sandbox.
-HOW TO USE THIS TOOL:
-1. If you don't know the exact 'skillName' or its required 'input' schema, first call this tool with { "action": "list" } to discover all available skills.
-2. For complex workflow skills, call { "action": "describe", "skillName": "<exact_skill_name>" } to load the full instructions before execution.
-3. To run a skill, call this tool with { "action": "execute", "skillName": "<exact_skill_name>", "input": { <parameters> } }.
-CRITICAL: Do NOT guess or hallucinate the 'input' object. You MUST strictly provide the parameters matching the JSON schema defined for that specific skill.
-The skill's output may contain text results, structured JSON data, or download URLs for generated files.
-IMPORTANT: If the skill returns file download URLs, you MUST format them as clickable Markdown links (e.g., [Download filename.ext](/api/attachments/...)) in your final response to the user.`,
-      schema: {
-        type: 'object',
-        properties: {
-          action: {
-            type: 'string',
-            enum: ['list', 'describe', 'execute'],
-            description: '"list" to see available skills, "describe" to load full instructions, "execute" to run one',
-          },
-          skillName: {
-            type: 'string',
-            description: 'Skill name (required for "execute" action)',
-          },
-          input: {
-            type: 'object',
-            description: 'Input parameters matching the skill inputSchema',
-          },
-        },
-        required: ['action'],
-      },
-    },
-
-    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
-      if (args.action === 'list') {
-        const skills = await plugin.db.getRepository('skillDefinitions').find({
-          filter: { enabled: true },
-          fields: ['name', 'title', 'description', 'language', 'inputSchema', 'instructions', 'storageType'],
-        });
-
-        const skillList = skills.map((s: any) => ({
-          name: s.get('name'),
-          title: s.get('title'),
-          description: s.get('description'),
-          language: s.get('language'),
-          inputSchema: parseJsonText(s.get('inputSchema'), null),
-          hasInstructions: !!s.get('instructions') || s.get('storageType') === 'plugin',
-          storageType: s.get('storageType'),
-        }));
-
-        return {
-          status: 'success',
-          content: JSON.stringify({ skills: skillList }),
-        };
-      }
-
-      // Action: describe one skill with full workflow instructions
-      if (args.action === 'describe') {
-        if (!args.skillName) {
-          return { status: 'error', content: 'Missing skillName parameter' };
-        }
-
-        const skill = await plugin.db.getRepository('skillDefinitions').findOne({
-          filter: { name: args.skillName, enabled: true },
-        });
-
-        if (!skill) {
-          return {
-            status: 'error',
-            content: `Skill "${args.skillName}" not found or disabled`,
-          };
-        }
-
-        const instructions =
-          typeof plugin.getSkillInstructions === 'function'
-            ? await plugin.getSkillInstructions(skill)
-            : skill.get('instructions');
-
-        return {
-          status: 'success',
-          content: JSON.stringify({
-            name: skill.get('name'),
-            title: skill.get('title'),
-            description: skill.get('description'),
-            language: skill.get('language'),
-            inputSchema: parseJsonText(skill.get('inputSchema'), null),
-            packages: parseJsonText(skill.get('packages'), []),
-            storageType: skill.get('storageType'),
-            storageUrl: skill.get('storageUrl'),
-            instructions,
-          }),
-        };
-      }
-
-      // Action: execute skill
-      if (args.action === 'execute') {
-        if (!args.skillName) {
-          return { status: 'error', content: 'Missing skillName parameter' };
-        }
-
-        const skill = await plugin.db.getRepository('skillDefinitions').findOne({
-          filter: { name: args.skillName, enabled: true },
-        });
-
-        if (!skill) {
-          return {
-            status: 'error',
-            content: `Skill "${args.skillName}" not found or disabled`,
-          };
-        }
-
-        try {
-          const result = await plugin.executeSkill(skill, args.input || {}, ctx);
-
-          return {
-            status: result.status === 'succeeded' ? 'success' : 'error',
-            content: JSON.stringify({
-              message:
-                result.status === 'succeeded'
-                  ? `Executed successfully. ${result.files?.length || 0} file(s) generated.`
-                  : `Failed: ${result.stderr}`,
-              stdout: result.stdout,
-              stderr: result.stderr,
-              files: result.files,
-              execId: result.execId,
-              agentLoopRunId: result.agentLoopRunId,
-              agentLoopStepId: result.agentLoopStepId,
-              durationMs: result.durationMs,
-            }),
-          };
-        } catch (error) {
-          return {
-            status: 'error',
-            content: `Execution error: ${error instanceof Error ? error.message : String(error)}`,
-          };
-        }
-      }
-
-      return {
-        status: 'error',
-        content: `Unknown action "${args.action}". Use "list", "describe", or "execute".`,
-      };
-    },
-  };
-}
+import { parseJsonText } from '../skill-hub/utils/json-fields';
+
+export function createSkillExecuteTool(plugin: any) {
+  return {
+    scope: 'CUSTOM',
+    execution: 'backend',
+    defaultPermission: 'ASK',
+
+    introduction: {
+      title: 'Skill Hub - Universal Skill Executor',
+      about:
+        'A universal gateway to execute predefined specialized skills (data processing, complex calculations, file generation, etc.) inside a secure Python/Node.js sandbox.',
+    },
+
+    definition: {
+      name: 'skill_hub_execute',
+      description: `A universal gateway to execute various predefined specialized skills (e.g., data transformation, calculations, document/presentation generation) in an isolated sandbox.
+HOW TO USE THIS TOOL:
+1. If you don't know the exact 'skillName' or its required 'input' schema, first call this tool with { "action": "list" } to discover all available skills.
+2. For complex workflow skills, call { "action": "describe", "skillName": "<exact_skill_name>" } to load the full instructions before execution.
+3. To run a skill, call this tool with { "action": "execute", "skillName": "<exact_skill_name>", "input": { <parameters> } }.
+CRITICAL: Do NOT guess or hallucinate the 'input' object. You MUST strictly provide the parameters matching the JSON schema defined for that specific skill.
+The skill's output may contain text results, structured JSON data, or download URLs for generated files.
+IMPORTANT: If the skill returns file download URLs, you MUST format them as clickable Markdown links (e.g., [Download filename.ext](/api/attachments/...)) in your final response to the user.`,
+      schema: {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['list', 'describe', 'execute'],
+            description: '"list" to see available skills, "describe" to load full instructions, "execute" to run one',
+          },
+          skillName: {
+            type: 'string',
+            description: 'Skill name (required for "execute" action)',
+          },
+          input: {
+            type: 'object',
+            description: 'Input parameters matching the skill inputSchema',
+          },
+        },
+        required: ['action'],
+      },
+    },
+
+    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
+      if (args.action === 'list') {
+        const skills = await plugin.db.getRepository('skillDefinitions').find({
+          filter: { enabled: true },
+          fields: ['name', 'title', 'description', 'language', 'inputSchema', 'instructions', 'storageType'],
+        });
+
+        const skillList = skills.map((s: any) => ({
+          name: s.get('name'),
+          title: s.get('title'),
+          description: s.get('description'),
+          language: s.get('language'),
+          inputSchema: parseJsonText(s.get('inputSchema'), null),
+          hasInstructions: !!s.get('instructions') || s.get('storageType') === 'plugin',
+          storageType: s.get('storageType'),
+        }));
+
+        return {
+          status: 'success',
+          content: JSON.stringify({ skills: skillList }),
+        };
+      }
+
+      // Action: describe one skill with full workflow instructions
+      if (args.action === 'describe') {
+        if (!args.skillName) {
+          return { status: 'error', content: 'Missing skillName parameter' };
+        }
+
+        const skill = await plugin.db.getRepository('skillDefinitions').findOne({
+          filter: { name: args.skillName, enabled: true },
+        });
+
+        if (!skill) {
+          return {
+            status: 'error',
+            content: `Skill "${args.skillName}" not found or disabled`,
+          };
+        }
+
+        const instructions =
+          typeof plugin.getSkillInstructions === 'function'
+            ? await plugin.getSkillInstructions(skill)
+            : skill.get('instructions');
+
+        return {
+          status: 'success',
+          content: JSON.stringify({
+            name: skill.get('name'),
+            title: skill.get('title'),
+            description: skill.get('description'),
+            language: skill.get('language'),
+            inputSchema: parseJsonText(skill.get('inputSchema'), null),
+            packages: parseJsonText(skill.get('packages'), []),
+            storageType: skill.get('storageType'),
+            storageUrl: skill.get('storageUrl'),
+            instructions,
+          }),
+        };
+      }
+
+      // Action: execute skill
+      if (args.action === 'execute') {
+        if (!args.skillName) {
+          return { status: 'error', content: 'Missing skillName parameter' };
+        }
+
+        const skill = await plugin.db.getRepository('skillDefinitions').findOne({
+          filter: { name: args.skillName, enabled: true },
+        });
+
+        if (!skill) {
+          return {
+            status: 'error',
+            content: `Skill "${args.skillName}" not found or disabled`,
+          };
+        }
+
+        try {
+          const result = await plugin.executeSkill(skill, args.input || {}, ctx);
+
+          return {
+            status: result.status === 'succeeded' ? 'success' : 'error',
+            content: JSON.stringify({
+              message:
+                result.status === 'succeeded'
+                  ? `Executed successfully. ${result.files?.length || 0} file(s) generated.`
+                  : `Failed: ${result.stderr}`,
+              stdout: result.stdout,
+              stderr: result.stderr,
+              files: result.files,
+              execId: result.execId,
+              agentLoopRunId: result.agentLoopRunId,
+              agentLoopStepId: result.agentLoopStepId,
+              durationMs: result.durationMs,
+            }),
+          };
+        } catch (error) {
+          return {
+            status: 'error',
+            content: `Execution error: ${error instanceof Error ? error.message : String(error)}`,
+          };
+        }
+      }
+
+      return {
+        status: 'error',
+        content: `Unknown action "${args.action}". Use "list", "describe", or "execute".`,
+      };
+    },
+  };
+}

package/src/server/types.ts

@@ -0,0 +1,55 @@
+// ── Shared types for Agent Orchestrator ──────────────────────────────────
+
+export interface TokenUsage {
+  inputTokens: number;
+  outputTokens: number;
+  totalTokens: number;
+  cost: number;
+}
+
+export interface BudgetConfig {
+  budgetMaxTokens?: number;
+  budgetMaxCost?: number;
+}
+
+export interface BudgetCheckResult {
+  allowed: boolean;
+  reason?: string;
+}
+
+export interface CircuitState {
+  failures: number;
+  lastFailureTime: number;
+  state: 'closed' | 'open' | 'half-open';
+}
+
+export interface TraceEvent {
+  type: string;
+  at: string;
+  title: string;
+  content?: string;
+  toolName?: string;
+  args?: any;
+  status?: string;
+}
+
+export interface DelegationLogData {
+  id?: number | string;
+  leaderUsername: string;
+  subAgentUsername: string;
+  toolName: string;
+  task: string;
+  context?: string;
+  result: string;
+  status: string;
+  depth: number;
+  durationMs: number;
+  error?: string;
+  trace?: TraceEvent[];
+  messages?: any[];
+  userId?: number | string;
+}
+
+export type CtxSnapshot = {
+  userId?: number;
+};

package/src/server/utils/ctx-utils.ts

@@ -0,0 +1,118 @@
+// ── Shared context/state utility functions ─────────────────────────────
+
+/** Normalize a record to a plain JS object. */
+export function toPlain(record: any) {
+  return record?.toJSON?.() || record;
+}
+
+/** Coerce a value to a plain object (JSON parse if needed). */
+export function asObject(value: any) {
+  if (value && typeof value === 'object' && !Array.isArray(value)) return value;
+  if (typeof value === 'string' && value.trim()) {
+    try {
+      const parsed = JSON.parse(value);
+      return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+
+/** Coerce value to array. */
+export function asArray(value: any): any[] {
+  return Array.isArray(value) ? value : [];
+}
+
+/** Trim text to max length with ellipsis suffix. */
+export function trimText(value: any, max = 50000) {
+  let text = '';
+  if (typeof value === 'string') {
+    text = value;
+  } else if (value != null) {
+    try {
+      text = JSON.stringify(value);
+    } catch {
+      text = String(value);
+    }
+  }
+  return text.length > max ? `${text.slice(0, max)}\n...[truncated]` : text;
+}
+
+/** Get the current user id from ctx. */
+export function currentUserId(ctx: any) {
+  return ctx?.state?.currentUser?.id || ctx?.auth?.user?.id;
+}
+
+/** Get action params values from ctx. */
+export function valuesFromCtx(ctx: any) {
+  return ctx?.action?.params?.values || ctx?.request?.body || {};
+}
+
+/** Normalize raw employee username input (string | object → string | null). */
+export function normalizeEmployeeUsername(raw: any) {
+  if (!raw) return null;
+  if (typeof raw === 'string') return raw;
+  return raw.username || raw.aiEmployeeUsername || raw.name || null;
+}
+
+/** Resolve session id from args or ctx. */
+export function resolveSessionId(ctx: any, args: any) {
+  const v = valuesFromCtx(ctx);
+  return args?.sessionId || v.sessionId || ctx?.action?.params?.sessionId || ctx?.state?.sessionId;
+}
+
+/** Resolve message id from args or ctx. */
+export function resolveMessageId(ctx: any, args: any) {
+  const v = valuesFromCtx(ctx);
+  return args?.messageId || v.messageId || ctx?.action?.params?.messageId;
+}
+
+/** Resolve leader employee username from args, ctx state, or conversation record. */
+export async function resolveLeaderUsername(ctx: any, plugin: any, args: any) {
+  const v = valuesFromCtx(ctx);
+  const direct = normalizeEmployeeUsername(
+    args?.leaderUsername ||
+      ctx?._currentAIEmployee ||
+      ctx?.state?.currentAIEmployee ||
+      ctx?.runtime?.context?.currentAIEmployee ||
+      v.aiEmployee,
+  );
+  if (direct) return direct;
+
+  const sessionId = resolveSessionId(ctx, args);
+  if (!sessionId) return undefined;
+  try {
+    const repo = ctx?.db?.getRepository?.('aiConversations') || plugin.db.getRepository('aiConversations');
+    const conversation = await repo.findOne({ filter: { sessionId } });
+    return normalizeEmployeeUsername(conversation?.aiEmployeeUsername || conversation?.get?.('aiEmployeeUsername'));
+  } catch {
+    return undefined;
+  }
+}
+
+/** Snapshot ctx user id for later use (avoids stale ctx). */
+export function captureCtxSnapshot(ctx: any): { userId?: number } {
+  let userId: number | undefined;
+  try {
+    userId = ctx?.auth?.user?.id || ctx?.state?.currentUser?.id;
+  } catch {
+    // ctx already disposed
+  }
+  return { userId };
+}
+
+/** Normalize step type to a known value. */
+export function normalizeStepType(value: any) {
+  return ['reasoning', 'skill', 'tool', 'sub_agent', 'verification'].includes(value) ? value : 'tool';
+}
+
+/** Normalize plan key from step input. */
+export function normalizePlanKey(step: any, index: number) {
+  return String(step.planKey || step.key || step.id || `step_${index + 1}`);
+}
+
+/** Now ISO string. */
+export function nowIso() {
+  return new Date().toISOString();
+}

package/src/server/utils/logging.ts

@@ -0,0 +1,63 @@
+// ── Shared logging for delegation events ───────────────────────────────
+
+import { DelegationLogData } from '../types';
+import { trimText, toPlain } from './ctx-utils';
+
+/**
+ * Log (or update) a delegation event in the orchestratorLogs collection.
+ * Used by both delegate-task.ts and AgentHarness.ts.
+ */
+export async function logDelegation(ctx: any, plugin: any, data: DelegationLogData) {
+  try {
+    const logsRepo = plugin.db.getRepository('orchestratorLogs');
+    if (!logsRepo) {
+      plugin.app.log?.warn?.('[AgentOrchestrator] orchestratorLogs repository not found — skipping log');
+      return null;
+    }
+
+    let userId: number | string | undefined = data.userId;
+    if (userId == null) {
+      try {
+        userId = ctx?.auth?.user?.id || ctx?.state?.currentUser?.id;
+      } catch {
+        // ctx lifecycle ended
+      }
+    }
+
+    const values = {
+      leaderUsername: data.leaderUsername,
+      subAgentUsername: data.subAgentUsername,
+      toolName: data.toolName,
+      task: trimText(data.task, 10000),
+      context: trimText(data.context || '', 10000),
+      result: trimText(data.result || '', 50000),
+      status: data.status,
+      depth: data.depth,
+      durationMs: data.durationMs,
+      error: trimText(data.error || '', 10000),
+      trace: data.trace || [],
+      messages: data.messages || [],
+      userId,
+      updatedAt: new Date(),
+    };
+
+    if (data.id) {
+      await logsRepo.update({
+        filterByTk: data.id,
+        values,
+      });
+      return { id: data.id };
+    }
+
+    const record = await logsRepo.create({
+      values: {
+        ...values,
+        createdAt: new Date(),
+      },
+    });
+    return toPlain(record);
+  } catch (e) {
+    plugin.app.log?.warn?.('[AgentOrchestrator] Failed to log delegation event', e);
+    return null;
+  }
+}