plugin-agent-orchestrator 1.0.19 → 1.0.21

package/src/server/services/AgentPlanValidator.ts

@@ -1,73 +1,73 @@
-import { AgentLoopPlanStepInput } from './AgentLoopService';
-
-function normalizeStepType(value: any) {
-  return ['reasoning', 'skill', 'tool', 'sub_agent', 'verification'].includes(value) ? value : 'tool';
-}
-
-function normalizePlanKey(step: any, index: number) {
-  return String(step.planKey || step.key || step.id || `step_${index + 1}`);
-}
-
-function asArray(value: any): any[] {
-  return Array.isArray(value) ? value : [];
-}
-
-const ORCHESTRATOR_CONTROLLER_MAX_STEPS = 100;
-
-export class AgentPlanValidator {
-  validate(plan: AgentLoopPlanStepInput[]) {
-    if (!Array.isArray(plan) || plan.length === 0) {
-      throw new Error('Plan must include at least one step.');
-    }
-    if (plan.length > ORCHESTRATOR_CONTROLLER_MAX_STEPS) {
-      throw new Error(`Plan cannot exceed ${ORCHESTRATOR_CONTROLLER_MAX_STEPS} steps.`);
-    }
-
-    const keys = new Set<string>();
-    const graph = new Map<string, string[]>();
-    for (let i = 0; i < plan.length; i++) {
-      const key = normalizePlanKey(plan[i], i).trim();
-      if (!key) {
-        throw new Error(`Plan step ${i + 1} has an empty planKey.`);
-      }
-      if (keys.has(key)) {
-        throw new Error(`Duplicate planKey "${key}" in plan.`);
-      }
-      const type = normalizeStepType(plan[i].type);
-      if (['tool', 'skill', 'sub_agent'].includes(type) && !plan[i].target) {
-        throw new Error(`Step "${key}" of type "${type}" must include a target.`);
-      }
-      keys.add(key);
-      graph.set(key, asArray(plan[i].dependsOn).map(String));
-    }
-
-    for (const [key, dependencies] of graph.entries()) {
-      for (const dependency of dependencies) {
-        if (!keys.has(dependency)) {
-          throw new Error(`Step "${key}" depends on unknown step "${dependency}".`);
-        }
-        if (dependency === key) {
-          throw new Error(`Step "${key}" cannot depend on itself.`);
-        }
-      }
-    }
-
-    const visiting = new Set<string>();
-    const visited = new Set<string>();
-    const visit = (key: string) => {
-      if (visited.has(key)) return;
-      if (visiting.has(key)) {
-        throw new Error(`Plan has a dependency cycle at "${key}".`);
-      }
-      visiting.add(key);
-      for (const dependency of graph.get(key) || []) {
-        visit(dependency);
-      }
-      visiting.delete(key);
-      visited.add(key);
-    };
-    for (const key of graph.keys()) {
-      visit(key);
-    }
-  }
-}
+import { AgentLoopPlanStepInput } from './AgentLoopService';
+
+function normalizeStepType(value: any) {
+  return ['reasoning', 'skill', 'tool', 'sub_agent', 'verification'].includes(value) ? value : 'tool';
+}
+
+function normalizePlanKey(step: any, index: number) {
+  return String(step.planKey || step.key || step.id || `step_${index + 1}`);
+}
+
+function asArray(value: any): any[] {
+  return Array.isArray(value) ? value : [];
+}
+
+const ORCHESTRATOR_CONTROLLER_MAX_STEPS = 100;
+
+export class AgentPlanValidator {
+  validate(plan: AgentLoopPlanStepInput[]) {
+    if (!Array.isArray(plan) || plan.length === 0) {
+      throw new Error('Plan must include at least one step.');
+    }
+    if (plan.length > ORCHESTRATOR_CONTROLLER_MAX_STEPS) {
+      throw new Error(`Plan cannot exceed ${ORCHESTRATOR_CONTROLLER_MAX_STEPS} steps.`);
+    }
+
+    const keys = new Set<string>();
+    const graph = new Map<string, string[]>();
+    for (let i = 0; i < plan.length; i++) {
+      const key = normalizePlanKey(plan[i], i).trim();
+      if (!key) {
+        throw new Error(`Plan step ${i + 1} has an empty planKey.`);
+      }
+      if (keys.has(key)) {
+        throw new Error(`Duplicate planKey "${key}" in plan.`);
+      }
+      const type = normalizeStepType(plan[i].type);
+      if (['tool', 'skill', 'sub_agent'].includes(type) && !plan[i].target) {
+        throw new Error(`Step "${key}" of type "${type}" must include a target.`);
+      }
+      keys.add(key);
+      graph.set(key, asArray(plan[i].dependsOn).map(String));
+    }
+
+    for (const [key, dependencies] of graph.entries()) {
+      for (const dependency of dependencies) {
+        if (!keys.has(dependency)) {
+          throw new Error(`Step "${key}" depends on unknown step "${dependency}".`);
+        }
+        if (dependency === key) {
+          throw new Error(`Step "${key}" cannot depend on itself.`);
+        }
+      }
+    }
+
+    const visiting = new Set<string>();
+    const visited = new Set<string>();
+    const visit = (key: string) => {
+      if (visited.has(key)) return;
+      if (visiting.has(key)) {
+        throw new Error(`Plan has a dependency cycle at "${key}".`);
+      }
+      visiting.add(key);
+      for (const dependency of graph.get(key) || []) {
+        visit(dependency);
+      }
+      visiting.delete(key);
+      visited.add(key);
+    };
+    for (const key of graph.keys()) {
+      visit(key);
+    }
+  }
+}

package/src/server/services/AgentPlannerService.ts

@@ -1,35 +1,12 @@
 import { AgentLoopPlanStepInput } from './AgentLoopService';
 
-function normalizeStepType(value: any) {
-  return ['reasoning', 'skill', 'tool', 'sub_agent', 'verification'].includes(value) ? value : 'tool';
-}
-
-function normalizePlanKey(step: any, index: number) {
-  return String(step.planKey || step.key || step.id || `step_${index + 1}`);
-}
-
-function asArray(value: any): any[] {
-  return Array.isArray(value) ? value : [];
-}
-
-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 {};
-}
+import { normalizeStepType, normalizePlanKey, asArray, asObject } from '../utils/ctx-utils';
 
 export class AgentPlannerService {
   buildPlan(
     goal: string,
     plan: AgentLoopPlanStepInput[] | undefined,
-    options: { targetAgent?: string; harnessTag?: string; metadata?: any }
+    options: { targetAgent?: string; harnessTag?: string; metadata?: any },
   ): AgentLoopPlanStepInput[] {
     if (Array.isArray(plan) && plan.length > 0) {
       return plan.map((step, index) => ({

package/src/server/services/AgentRegistryService.ts

@@ -1,25 +1,4 @@
-function toPlain(record: any) {
-  return record?.toJSON?.() || record;
-}
-
-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 {};
-}
-
-function normalizeEmployeeUsername(raw: any) {
-  if (!raw) return null;
-  if (typeof raw === 'string') return raw;
-  return raw.username || raw.aiEmployeeUsername || raw.name || null;
-}
+import { toPlain, asObject, normalizeEmployeeUsername } from '../utils/ctx-utils';
 
 export class AgentRegistryService {
   constructor(private readonly plugin: any) {}
@@ -74,11 +53,7 @@ export class AgentRegistryService {
     }
   }
 
-  async resolveModelSettings(
-    subAgentUsername: string,
-    leaderUsername?: string,
-    dynamicValues?: any
-  ) {
+  async resolveModelSettings(subAgentUsername: string, leaderUsername?: string, dynamicValues?: any) {
     const subAgent = await this.getAIEmployee(subAgentUsername);
     if (!subAgent) {
       throw new Error(`Sub-agent "${subAgentUsername}" was not found.`);
@@ -88,9 +63,7 @@ export class AgentRegistryService {
       return Boolean(val?.llmService && val?.model);
     };
 
-    let modelSettings = hasModelSettings(dynamicValues)
-      ? dynamicValues
-      : undefined;
+    let modelSettings = hasModelSettings(dynamicValues) ? dynamicValues : undefined;
 
     if (!modelSettings) {
       if (hasModelSettings(subAgent.modelSettings)) {
@@ -108,8 +81,44 @@ export class AgentRegistryService {
     return modelSettings;
   }
 
+  /**
+   * Find alternative sub-agents for the same leader, excluding a specific one.
+   * Used by the smart retry feature to route around a failing sub-agent.
+   */
+  async findAlternativeSubAgents(
+    leaderUsername: string,
+    excludeSubAgentUsername: string,
+  ): Promise<{ username: string; label: string }[]> {
+    try {
+      const repo = this.db.getRepository('orchestratorConfig');
+      if (!repo) return [];
+      const configs = await repo.find({
+        filter: {
+          leaderUsername,
+          enabled: true,
+          subAgentUsername: { $ne: excludeSubAgentUsername },
+        },
+      });
+      if (!configs || configs.length === 0) return [];
+
+      // Enrich with AI employee display names
+      const result: { username: string; label: string }[] = [];
+      for (const config of configs) {
+        const plain = toPlain(config);
+        const employee = await this.getAIEmployee(plain.subAgentUsername);
+        result.push({
+          username: plain.subAgentUsername,
+          label: employee?.nickname || employee?.username || plain.subAgentUsername,
+        });
+      }
+      return result;
+    } catch {
+      return [];
+    }
+  }
+
   async isRegisteredDelegationTool(toolName: string): Promise<boolean> {
-    if (!toolName || (typeof toolName !== 'string')) return false;
+    if (!toolName || typeof toolName !== 'string') return false;
     if (!toolName.startsWith('delegate_') && !toolName.startsWith('dispatch_subagents_')) {
       return false;
     }

package/src/server/services/CircuitBreaker.ts

@@ -0,0 +1,116 @@
+export interface CircuitState {
+  failures: number;
+  lastFailureTime: number;
+  state: 'closed' | 'open' | 'half-open';
+}
+
+/**
+ * CircuitBreakerRegistry — prevents cascading failures by tracking per-key
+ * failure rates and temporarily stopping calls when thresholds are exceeded.
+ *
+ * State machine: closed → open (after threshold failures) → half-open (after recoveryTimeout)
+ * half-open: allows 1 probe request; success → closed, failure → open.
+ */
+export class CircuitBreakerRegistry {
+  private readonly circuits = new Map<string, CircuitState>();
+
+  readonly threshold: number;
+  readonly recoveryTimeout: number;
+  readonly halfOpenMaxRequests: number;
+  private readonly appLog: any;
+
+  constructor(options?: { threshold?: number; recoveryTimeout?: number; halfOpenMaxRequests?: number; appLog?: any }) {
+    this.threshold = options?.threshold ?? 3;
+    this.recoveryTimeout = options?.recoveryTimeout ?? 30000;
+    this.halfOpenMaxRequests = options?.halfOpenMaxRequests ?? 1;
+    this.appLog = options?.appLog;
+  }
+
+  private getOrCreate(key: string): CircuitState {
+    let state = this.circuits.get(key);
+    if (!state) {
+      state = { failures: 0, lastFailureTime: 0, state: 'closed' };
+      this.circuits.set(key, state);
+    }
+    return state;
+  }
+
+  recordSuccess(key: string): void {
+    const state = this.getOrCreate(key);
+    if (state.state === 'half-open') {
+      state.state = 'closed';
+      state.failures = 0;
+      this.appLog?.debug?.(`[CircuitBreaker] "${key}" recovered → closed`);
+    } else if (state.state === 'closed' && state.failures > 0) {
+      // Decrement failure count on success (graceful recovery)
+      state.failures = Math.max(0, state.failures - 1);
+    }
+  }
+
+  recordFailure(key: string): void {
+    const state = this.getOrCreate(key);
+    state.failures += 1;
+    state.lastFailureTime = Date.now();
+
+    if (state.state === 'half-open') {
+      state.state = 'open';
+      this.appLog?.warn?.(`[CircuitBreaker] "${key}" half-open probe failed → open`);
+    } else if (state.state === 'closed' && state.failures >= this.threshold) {
+      state.state = 'open';
+      this.appLog?.warn?.(`[CircuitBreaker] "${key}" opened after ${state.failures} failures`);
+    }
+  }
+
+  isAllowed(key: string): boolean {
+    const state = this.getOrCreate(key);
+
+    if (state.state === 'closed') return true;
+
+    if (state.state === 'open') {
+      const elapsed = Date.now() - state.lastFailureTime;
+      if (elapsed >= this.recoveryTimeout) {
+        state.state = 'half-open';
+        this.appLog?.debug?.(`[CircuitBreaker] "${key}" open timeout elapsed → half-open`);
+        return true;
+      }
+      return false;
+    }
+
+    // half-open: allow limited probe requests
+    return this.halfOpenMaxRequests > 0;
+  }
+
+  getState(key: string): CircuitState | null {
+    return this.circuits.get(key) ?? null;
+  }
+
+  /** Reset a circuit back to closed state. */
+  reset(key: string): void {
+    const state = this.circuits.get(key);
+    if (state) {
+      state.state = 'closed';
+      state.failures = 0;
+      state.lastFailureTime = 0;
+    }
+  }
+
+  /** Get all circuit state keys (for monitoring/diagnostics). */
+  getKeys(): string[] {
+    return Array.from(this.circuits.keys());
+  }
+}
+
+// Singleton shared across the plugin
+let globalInstance: CircuitBreakerRegistry | null = null;
+
+export function getCircuitBreaker(options?: {
+  threshold?: number;
+  recoveryTimeout?: number;
+  halfOpenMaxRequests?: number;
+  appLog?: any;
+}): CircuitBreakerRegistry {
+  if (!globalInstance) {
+    globalInstance = new CircuitBreakerRegistry(options);
+  }
+  return globalInstance;
+}

package/src/server/services/ContextAggregator.ts

@@ -0,0 +1,239 @@
+import { AgentLoopPolicy } from './AgentLoopService';
+
+function trimText(text: string, maxLen: number): string {
+  if (text.length <= maxLen) return text;
+  return text.slice(0, maxLen) + '\n...[truncated]';
+}
+
+/**
+ * Estimate token count from text (rough: ~4 chars per token).
+ */
+function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+/**
+ * ContextAggregator — builds structured step context for sub-agent system prompts.
+ *
+ * Responsibilities:
+ * 1. Query completed steps of a run
+ * 2. Format them as structured XML context
+ * 3. Apply truncation/summarization based on policy
+ * 4. Inject into sub-agent system prompt
+ */
+export class ContextAggregator {
+  constructor(private readonly plugin: any) {}
+
+  get db() {
+    return this.plugin.db;
+  }
+
+  get app() {
+    return this.plugin.app;
+  }
+
+  /**
+   * Build a structured context string from completed steps of a run.
+   *
+   * @param runId - agentLoopRuns.id
+   * @param maxTokens - Maximum tokens for the context output (default 4000)
+   * @param options - Strategy options
+   */
+  async buildStepContext(
+    runId: string | number,
+    maxTokens?: number,
+    options?: {
+      strategy?: 'last_n' | 'all';
+      includeToolResults?: boolean;
+      includeStepOutputs?: boolean;
+    },
+  ): Promise<string> {
+    const effectiveMaxTokens = maxTokens || 4000;
+
+    let steps: any[];
+    try {
+      const repo = this.db.getRepository('agentLoopSteps');
+      if (!repo) return '';
+      steps = await repo.find({
+        filter: { runId },
+        sort: ['index', 'createdAt'],
+        pageSize: 500,
+      });
+    } catch {
+      return '';
+    }
+
+    if (!steps || steps.length === 0) return '';
+
+    const completedSteps = steps.filter((s: any) => s.status === 'succeeded' || s.status === 'failed');
+
+    if (completedSteps.length === 0) return '';
+
+    const config = {
+      strategy: options?.strategy || 'all',
+      includeToolResults: options?.includeToolResults ?? false,
+      includeStepOutputs: options?.includeStepOutputs ?? true,
+    };
+
+    let candidates = completedSteps;
+    if (config.strategy === 'last_n') {
+      // Take last 10 completed steps
+      const n = Math.min(10, completedSteps.length);
+      candidates = completedSteps.slice(-n);
+    }
+
+    const parts: string[] = [];
+
+    for (const step of candidates) {
+      const key = step.planKey || `step_${step.index || 0}`;
+      const type = step.type || 'unknown';
+      const target = step.target || '';
+      const title = step.title || key;
+      const status = step.status || 'unknown';
+
+      const lines: string[] = [];
+      lines.push(`<step key="${key}" type="${type}" target="${target}" status="${status}">`);
+      lines.push(`  <title>${this.escapeXml(title)}</title>`);
+
+      if (step.description) {
+        lines.push(`  <description>${this.escapeXml(trimText(step.description, 500))}</description>`);
+      }
+
+      if (config.includeStepOutputs && step.output) {
+        const outputStr = typeof step.output === 'string' ? step.output : this.safeStringify(step.output);
+        lines.push(`  <output>${this.escapeXml(trimText(outputStr, 2000))}</output>`);
+      }
+
+      if (config.includeToolResults && step.metadata?.toolResults) {
+        const toolStr = this.safeStringify(step.metadata.toolResults);
+        lines.push(`  <tool_results>${this.escapeXml(trimText(toolStr, 1500))}</tool_results>`);
+      }
+
+      if (step.error) {
+        lines.push(`  <error>${this.escapeXml(trimText(step.error, 1000))}</error>`);
+      }
+
+      lines.push('</step>');
+      parts.push(lines.join('\n'));
+    }
+
+    let context = `<previous_steps>\n${parts.join('\n\n')}\n</previous_steps>`;
+
+    // Truncate if exceeding token limit
+    if (estimateTokens(context) > effectiveMaxTokens) {
+      context = this.truncateToTokenLimit(context, effectiveMaxTokens);
+    }
+
+    return context;
+  }
+
+  /**
+   * Enrich a base system prompt with step context from the run.
+   * Fetches the run from DB to access policy settings (maxContextTokens, etc.).
+   *
+   * @param basePrompt - The original system prompt to enrich
+   * @param runId - agentLoopRuns.id
+   * @param _stepId - agentLoopSteps.id (reserved for future per-step context)
+   */
+  async enrichSystemPrompt(
+    basePrompt: string,
+    runId: string | number,
+    _stepId?: string | number,
+    options?: {
+      maxContextTokens?: number;
+      contextSummaryStrategy?: 'last_n' | 'all';
+      includeToolResults?: boolean;
+      includeStepOutputs?: boolean;
+    },
+  ): Promise<string> {
+    // Fetch run from DB to get policy settings
+    let run: any;
+    try {
+      const repo = this.db.getRepository('agentLoopRuns');
+      if (!repo) return basePrompt;
+      run = await repo.findOne({ filter: { id: runId } });
+      if (!run) return basePrompt;
+    } catch {
+      return basePrompt;
+    }
+
+    const policy = (run.policy || {}) as AgentLoopPolicy;
+    const maxCtxTokens = options?.maxContextTokens ?? policy.maxContextTokens ?? 4000;
+    const strategy = options?.contextSummaryStrategy ?? policy.contextSummaryStrategy ?? 'all';
+    const includeToolResults = options?.includeToolResults ?? policy.includeToolResults ?? false;
+    const includeStepOutputs = options?.includeStepOutputs ?? policy.includeStepOutputs ?? true;
+
+    const stepContext = await this.buildStepContext(runId, maxCtxTokens, {
+      strategy,
+      includeToolResults,
+      includeStepOutputs,
+    });
+
+    if (!stepContext) return basePrompt;
+
+    return `${basePrompt}\n\n<previous_steps_context>\n${stepContext}\n</previous_steps_context>`;
+  }
+
+  private truncateToTokenLimit(text: string, maxTokens: number): string {
+    // Simple truncation: remove step details until under limit
+    // Strategy: keep first and last steps, remove middle ones
+    const outerMatch = text.match(/<previous_steps>\n([\s\S]*)\n<\/previous_steps>/);
+    if (!outerMatch) return text;
+
+    const inner = outerMatch[1];
+    const stepBlocks = this.splitStepBlocks(inner);
+
+    if (stepBlocks.length <= 2) {
+      // Just truncate text
+      const maxChars = maxTokens * 4;
+      if (text.length <= maxChars) return text;
+      return text.slice(0, maxChars) + '\n...[truncated]\n</previous_steps>';
+    }
+
+    // Keep first 2 and last 2 steps
+    const keepFirst = stepBlocks.slice(0, 2);
+    const keepLast = stepBlocks.slice(-2);
+    const removed = stepBlocks.length - keepFirst.length - keepLast.length;
+
+    const rebuilt = [
+      '<previous_steps>',
+      ...keepFirst,
+      `  <!-- ... ${removed} intermediate step(s) omitted due to context limit ... -->`,
+      ...keepLast,
+      '</previous_steps>',
+    ].join('\n');
+
+    // If still over limit, do a simple text truncation
+    const maxChars = maxTokens * 4;
+    if (rebuilt.length <= maxChars) return rebuilt;
+
+    return rebuilt.slice(0, maxChars) + '\n...[truncated]\n</previous_steps>';
+  }
+
+  private splitStepBlocks(text: string): string[] {
+    const blocks: string[] = [];
+    const regex = /<step[\s\S]*?<\/step>/g;
+    let match;
+    while ((match = regex.exec(text)) !== null) {
+      blocks.push(match[0]);
+    }
+    return blocks;
+  }
+
+  private escapeXml(value: string): string {
+    return value
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&apos;');
+  }
+
+  private safeStringify(value: any): string {
+    try {
+      return JSON.stringify(value, null, 2);
+    } catch {
+      return String(value);
+    }
+  }
+}

package/src/server/services/ExecutionSpanService.ts

@@ -1,3 +1,5 @@
+import { toPlain } from '../utils/ctx-utils';
+
 export const ORCHESTRATOR_TRACE_CONTEXT_KEY = '__orchestratorTraceContext';
 
 export type OrchestratorTraceContext = {
@@ -33,10 +35,6 @@ type SpanValues = {
   userId?: string | number;
 };
 
-function toPlain(record: any) {
-  return record?.toJSON?.() || record;
-}
-
 export class ExecutionSpanService {
   constructor(private readonly plugin: any) {}