plugin-agent-orchestrator 1.0.17 → 1.0.19

package/src/server/services/AgentLoopRepository.ts

@@ -0,0 +1,194 @@
+function toPlain(record: any) {
+  return record?.toJSON?.() || record;
+}
+
+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;
+}
+
+export class AgentLoopRepository {
+  constructor(private readonly plugin: any) {}
+
+  get db() {
+    return this.plugin.db;
+  }
+
+  async getRun(runId: string | number) {
+    const run = await this.db.getRepository('agentLoopRuns').findOne({
+      filter: { id: runId },
+    });
+    return run ? toPlain(run) : null;
+  }
+
+  async requireRun(runId: string | number) {
+    const run = await this.getRun(runId);
+    if (!run) {
+      throw new Error(`Agent loop run "${runId}" was not found.`);
+    }
+    return run;
+  }
+
+  async createRun(values: any) {
+    const run = await this.db.getRepository('agentLoopRuns').create({
+      values,
+    });
+    return toPlain(run);
+  }
+
+  async updateRun(runId: string | number, values: any) {
+    await this.db.getRepository('agentLoopRuns').update({
+      filterByTk: runId,
+      values,
+    });
+  }
+
+  async getStep(stepId: string | number) {
+    const step = await this.db.getRepository('agentLoopSteps').findOne({
+      filter: { id: stepId },
+    });
+    return step ? toPlain(step) : null;
+  }
+
+  async requireStep(stepId: string | number) {
+    const step = await this.getStep(stepId);
+    if (!step) {
+      throw new Error(`Agent loop step "${stepId}" was not found.`);
+    }
+    return step;
+  }
+
+  async createStep(values: any) {
+    const step = await this.db.getRepository('agentLoopSteps').create({
+      values,
+    });
+    return toPlain(step);
+  }
+
+  async updateStep(stepId: string | number, values: any) {
+    await this.db.getRepository('agentLoopSteps').update({
+      filterByTk: stepId,
+      values,
+    });
+  }
+
+  async getSteps(runId: string | number) {
+    const steps = await this.db.getRepository('agentLoopSteps').find({
+      filter: { runId },
+      sort: ['index', 'createdAt'],
+      pageSize: 1000,
+    });
+    return steps.map(toPlain);
+  }
+
+  async createEvent(values: any) {
+    const record = await this.db.getRepository('agentLoopEvents').create({
+      values: {
+        ...values,
+        content: trimText(values.content || '', 10000),
+        payload: values.payload || {},
+        createdAt: new Date(),
+      },
+    });
+    return toPlain(record);
+  }
+
+  async getEvents(runId: string | number) {
+    const events = await this.db.getRepository('agentLoopEvents').find({
+      filter: { runId },
+      sort: ['createdAt'],
+      pageSize: 500,
+    });
+    return events.map(toPlain);
+  }
+
+  async getLinkedSpans(runId: string | number, rootRunId?: string) {
+    const repo = this.db.getRepository('agentExecutionSpans');
+    if (!repo) return [];
+    const filters = [];
+    if (rootRunId) filters.push({ rootRunId });
+    filters.push({ 'metadata.agentLoopRunId': String(runId) });
+    try {
+      const rows = await repo.find({
+        filter: { $or: filters },
+        sort: ['createdAt'],
+        pageSize: 1000,
+      });
+      return rows.map(toPlain);
+    } catch {
+      if (!rootRunId) return [];
+      const rows = await repo.find({
+        filter: { rootRunId },
+        sort: ['createdAt'],
+        pageSize: 1000,
+      });
+      return rows.map(toPlain);
+    }
+  }
+
+  async getLinkedSkillExecutions(runId: string | number, steps: any[]) {
+    const ids = Array.from(
+      new Set(
+        steps
+          .map((step) => step.skillExecutionId)
+          .filter(Boolean)
+          .map(String),
+      ),
+    );
+    const repo = this.db.getRepository('skillExecutions');
+    if (!repo) return [];
+    const filters: any[] = [{ agentLoopRunId: String(runId) }];
+    if (ids.length) {
+      filters.push({ id: { $in: ids } });
+    }
+    const rows = await repo.find({
+      filter: { $or: filters },
+      sort: ['createdAt'],
+      pageSize: 1000,
+    });
+    return rows.map(toPlain);
+  }
+
+  async lockRun(runId: string | number, lockName: string, durationMs: number): Promise<boolean> {
+    const repo = this.db.getRepository('agentLoopRuns');
+    if (!repo) return false;
+    const now = new Date();
+    const Op = repo.model.sequelize.Sequelize.Op;
+
+    const result = await repo.model.update(
+      {
+        lockedBy: lockName,
+        lockedUntil: new Date(now.getTime() + durationMs),
+      },
+      {
+        where: {
+          id: runId,
+          [Op.or]: [
+            { lockedBy: null },
+            { lockedUntil: { [Op.lt]: now.toISOString() } },
+            { lockedBy: lockName }
+          ]
+        }
+      }
+    );
+
+    const affectedCount = Array.isArray(result) ? result[0] : Number(result || 0);
+    return affectedCount > 0;
+  }
+
+  async unlockRun(runId: string | number) {
+    await this.updateRun(runId, {
+      lockedBy: null,
+      lockedUntil: null,
+    });
+  }
+}

package/src/server/services/AgentLoopService.ts

@@ -0,0 +1,161 @@
+import { AgentRegistryService } from './AgentRegistryService';
+import { AgentPlannerService } from './AgentPlannerService';
+import { AgentPlanValidator } from './AgentPlanValidator';
+import { AgentLoopRepository } from './AgentLoopRepository';
+import { AgentHarness } from './AgentHarness';
+import { AgentLoopController } from './AgentLoopController';
+
+export type AgentLoopRunStatus =
+  | 'planning'
+  | 'waiting_plan_approval'
+  | 'approved'
+  | 'running'
+  | 'waiting_user'
+  | 'needs_replan'
+  | 'succeeded'
+  | 'failed'
+  | 'rejected'
+  | 'canceled';
+export type AgentLoopStepStatus = 'pending' | 'running' | 'waiting_user' | 'succeeded' | 'failed' | 'skipped';
+export type AgentLoopStepType = 'reasoning' | 'skill' | 'tool' | 'sub_agent' | 'verification';
+export type AgentLoopStepDependencyPolicy = 'require_success' | 'allow_skipped';
+
+export type AgentLoopPolicy = {
+  maxIterations: number;
+  maxStepAttempts: number;
+  allowReplan: boolean;
+  requireVerification: boolean;
+  stopOnApprovalRequired: boolean;
+};
+
+export type AgentLoopPlanStepInput = {
+  id?: string;
+  key?: string;
+  planKey?: string;
+  parentStepId?: string | number;
+  title?: string;
+  description?: string;
+  type?: AgentLoopStepType;
+  target?: string;
+  input?: any;
+  dependsOn?: string[];
+  dependencyPolicy?: AgentLoopStepDependencyPolicy;
+  maxAttempts?: number;
+  metadata?: any;
+};
+
+export class AgentLoopService {
+  public readonly registryService: AgentRegistryService;
+  public readonly plannerService: AgentPlannerService;
+  public readonly validator: AgentPlanValidator;
+  public readonly repository: AgentLoopRepository;
+  public readonly harness: AgentHarness;
+  public readonly controller: AgentLoopController;
+
+  constructor(private readonly plugin: any) {
+    this.registryService = new AgentRegistryService(plugin);
+    this.plannerService = new AgentPlannerService();
+    this.validator = new AgentPlanValidator();
+    this.repository = new AgentLoopRepository(plugin);
+    this.harness = new AgentHarness(plugin, this.registryService);
+    this.controller = new AgentLoopController(
+      this.registryService,
+      this.plannerService,
+      this.validator,
+      this.repository,
+      this.harness
+    );
+  }
+
+  get db() {
+    return this.plugin.db;
+  }
+
+  get app() {
+    return this.plugin.app;
+  }
+
+  async createRun(options: any) {
+    return this.controller.createRun(options);
+  }
+
+  async planGoal(options: any) {
+    return this.controller.planGoal(options);
+  }
+
+  async revisePlanGoal(runId: any, plan: any, options: any = {}) {
+    return this.controller.revisePlanGoal(runId, plan, options);
+  }
+
+  async approvePlanAndExecute(runId: any, options: any = {}) {
+    return this.controller.approvePlanAndExecute(runId, options);
+  }
+
+  async rejectPlan(runId: any, options: any = {}) {
+    return this.controller.rejectPlan(runId, options);
+  }
+
+  async requestPlanChanges(runId: any, options: any = {}) {
+    return this.controller.requestPlanChanges(runId, options);
+  }
+
+  async replacePlan(runId: any, plan: any, options: any = {}) {
+    return this.controller.replacePlan(runId, plan, options);
+  }
+
+  async replan(runId: any, plan: any, options: any = {}) {
+    return this.controller.replan(runId, plan, options);
+  }
+
+  async startStep(stepId: any, options: any = {}) {
+    return this.controller.startStep(stepId, options);
+  }
+
+  async completeStep(stepId: any, output: any, options: any = {}) {
+    return this.controller.completeStep(stepId, output, options);
+  }
+
+  async failStep(stepId: any, error: any, options: any = {}) {
+    return this.controller.failStep(stepId, error, options);
+  }
+
+  async skipStep(stepId: any, reason: any = 'Skipped', options: any = {}) {
+    return this.controller.skipStep(stepId, reason, options);
+  }
+
+  async requestApproval(stepId: any, approval: any, options: any = {}) {
+    return this.controller.requestApproval(stepId, approval, options);
+  }
+
+  async resumeRun(runId: any, options: any) {
+    return this.controller.resumeRun(runId, options);
+  }
+
+  async retryStep(stepId: any, options: any = {}) {
+    return this.controller.retryStep(stepId, options);
+  }
+
+  async finishRun(runId: any, finalAnswer: any, options: any = {}) {
+    return this.controller.finishRun(runId, finalAnswer, options);
+  }
+
+  async cancelRun(runId: any, options: any = {}) {
+    return this.controller.cancelRun(runId, options);
+  }
+
+  async executeApprovedPlan(runId: any, options: any = {}) {
+    return this.controller.executeApprovedPlan(runId, options);
+  }
+
+  async getRunSnapshot(runId: any) {
+    return this.controller.getRunSnapshot(runId);
+  }
+
+  async getRunDetail(runId: any) {
+    return this.controller.getRunDetail(runId);
+  }
+
+  async createEvent(values: any) {
+    return this.repository.createEvent(values);
+  }
+}

package/src/server/services/AgentPlanValidator.ts

@@ -0,0 +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);
+    }
+  }
+}

package/src/server/services/AgentPlannerService.ts

@@ -0,0 +1,93 @@
+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 {};
+}
+
+export class AgentPlannerService {
+  buildPlan(
+    goal: string,
+    plan: AgentLoopPlanStepInput[] | undefined,
+    options: { targetAgent?: string; harnessTag?: string; metadata?: any }
+  ): AgentLoopPlanStepInput[] {
+    if (Array.isArray(plan) && plan.length > 0) {
+      return plan.map((step, index) => ({
+        ...step,
+        planKey: normalizePlanKey(step, index),
+        type: normalizeStepType(step.type),
+        dependsOn: asArray(step.dependsOn).map(String),
+        metadata: {
+          ...asObject(step.metadata),
+          harnessTag: options.harnessTag || options.metadata?.harnessTag || 'default',
+        },
+      }));
+    }
+
+    const harnessTag = options.harnessTag || options.metadata?.harnessTag || 'default';
+    const steps: AgentLoopPlanStepInput[] = [
+      {
+        planKey: 'prepare_context',
+        title: 'Prepare execution context',
+        description: 'Review the user goal, available context, and constraints before execution.',
+        type: 'reasoning',
+        input: { goal },
+        metadata: { harnessTag },
+      },
+    ];
+
+    if (options.targetAgent) {
+      steps.push({
+        planKey: 'delegate_execution',
+        title: `Delegate execution to ${options.targetAgent}`,
+        description: goal,
+        type: 'sub_agent',
+        target: options.targetAgent,
+        input: { goal },
+        dependsOn: ['prepare_context'],
+        metadata: { harnessTag },
+      });
+    } else {
+      steps.push({
+        planKey: 'execute_goal',
+        title: 'Execute approved goal',
+        description: 'Execute the user goal in the leader harness using the available approved tools.',
+        type: 'reasoning',
+        input: { goal },
+        dependsOn: ['prepare_context'],
+        metadata: { harnessTag, controllerOnly: true },
+      });
+    }
+
+    steps.push({
+      planKey: 'verify_result',
+      title: 'Verify result',
+      description: 'Check that the completed work matches the approved goal and report evidence.',
+      type: 'verification',
+      input: { goal },
+      dependsOn: [steps[steps.length - 1].planKey || 'execute_goal'],
+      metadata: { harnessTag },
+    });
+    return steps;
+  }
+}

package/src/server/services/AgentRegistryService.ts

@@ -0,0 +1,169 @@
+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;
+}
+
+export class AgentRegistryService {
+  constructor(private readonly plugin: any) {}
+
+  get db() {
+    return this.plugin.db;
+  }
+
+  async getHarnessProfile(tag: string) {
+    try {
+      const repo = this.db.getRepository('agentHarnessProfiles');
+      if (!repo) return null;
+      const profile = await repo.findOne({
+        filter: {
+          tag: tag || 'default',
+          enabled: true,
+        },
+      });
+      return profile ? toPlain(profile) : null;
+    } catch {
+      return null;
+    }
+  }
+
+  async getOrchestratorConfig(leaderUsername: string, subAgentUsername: string) {
+    try {
+      const repo = this.db.getRepository('orchestratorConfig');
+      if (!repo) return null;
+      const config = await repo.findOne({
+        filter: {
+          leaderUsername,
+          subAgentUsername,
+          enabled: true,
+        },
+      });
+      return config ? toPlain(config) : null;
+    } catch {
+      return null;
+    }
+  }
+
+  async getAIEmployee(username: string) {
+    try {
+      const repo = this.db.getRepository('aiEmployees');
+      if (!repo) return null;
+      const employee = await repo.findOne({
+        filter: { username },
+      });
+      return employee ? toPlain(employee) : null;
+    } catch {
+      return null;
+    }
+  }
+
+  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.`);
+    }
+
+    const hasModelSettings = (val: any): val is { llmService: string; model: string } => {
+      return Boolean(val?.llmService && val?.model);
+    };
+
+    let modelSettings = hasModelSettings(dynamicValues)
+      ? dynamicValues
+      : undefined;
+
+    if (!modelSettings) {
+      if (hasModelSettings(subAgent.modelSettings)) {
+        modelSettings = subAgent.modelSettings;
+      }
+    }
+
+    if (!modelSettings && leaderUsername) {
+      const leader = await this.getAIEmployee(leaderUsername);
+      if (leader && hasModelSettings(leader.modelSettings)) {
+        modelSettings = leader.modelSettings;
+      }
+    }
+
+    return modelSettings;
+  }
+
+  async isRegisteredDelegationTool(toolName: string): Promise<boolean> {
+    if (!toolName || (typeof toolName !== 'string')) return false;
+    if (!toolName.startsWith('delegate_') && !toolName.startsWith('dispatch_subagents_')) {
+      return false;
+    }
+
+    try {
+      const configRepo = this.db.getRepository('orchestratorConfig');
+      if (!configRepo) return false;
+
+      // 1. Check if it matches dispatch_subagents_${leader}
+      if (toolName.startsWith('dispatch_subagents_')) {
+        const leader = toolName.substring('dispatch_subagents_'.length);
+        const count = await configRepo.count({
+          filter: {
+            leaderUsername: leader,
+            enabled: true,
+          },
+        });
+        return count > 0;
+      }
+
+      // 2. Check if it matches delegate_${leader}_to_${subAgent}
+      if (toolName.startsWith('delegate_') && toolName.includes('_to_')) {
+        const parts = toolName.substring('delegate_'.length).split('_to_');
+        if (parts.length === 2) {
+          const [leader, subAgent] = parts;
+          const count = await configRepo.count({
+            filter: {
+              leaderUsername: leader,
+              subAgentUsername: subAgent,
+              enabled: true,
+            },
+          });
+          if (count > 0) return true;
+        }
+      }
+
+      // 3. Check legacy alias: delegate_to_${subAgent}
+      if (toolName.startsWith('delegate_to_')) {
+        const subAgent = toolName.substring('delegate_to_'.length);
+        const configs = await configRepo.find({
+          filter: {
+            subAgentUsername: subAgent,
+            enabled: true,
+          },
+        });
+        // Legacy alias is only registered if there is exactly one leader for this subAgent
+        if (configs?.length === 1) {
+          return true;
+        }
+      }
+
+      return false;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/server/services/ExecutionSpanService.ts

@@ -8,6 +8,8 @@ export type OrchestratorTraceContext = {
   leaderUsername?: string;
   employeeUsername?: string;
   toolName?: string;
+  agentLoopRunId?: string;
+  agentLoopStepId?: string;
 };
 
 type SpanValues = {