plugin-agent-orchestrator 1.0.21 → 1.0.23

package/src/server/__tests__/code-validator.test.ts

@@ -0,0 +1,63 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { CodeValidator, CodeValidationError } from '../services/CodeValidator';
+
+const validator = new CodeValidator();
+
+describe('CodeValidator.validate — dangerous patterns', () => {
+  it('blocks node child_process and dynamic require', () => {
+    expect(() => validator.validate(`require('child_process')`, 'node')).toThrow(CodeValidationError);
+    expect(() => validator.validate(`const m = 'fs'; require(m);`, 'node')).toThrow(CodeValidationError);
+  });
+
+  it('blocks node indirect eval / Function constructor / dynamic import', () => {
+    expect(() => validator.validate(`eval('1+1')`, 'node')).toThrow(CodeValidationError);
+    expect(() => validator.validate(`new Function('return 1')()`, 'node')).toThrow(CodeValidationError);
+    expect(() => validator.validate(`import('fs')`, 'node')).toThrow(CodeValidationError);
+    expect(() => validator.validate(`process.binding('spawn_sync')`, 'node')).toThrow(CodeValidationError);
+  });
+
+  it('blocks python subprocess / socket / importlib / getattr bypass', () => {
+    expect(() => validator.validate(`import subprocess`, 'python')).toThrow(CodeValidationError);
+    expect(() => validator.validate(`import socket`, 'python')).toThrow(CodeValidationError);
+    expect(() => validator.validate(`import importlib`, 'python')).toThrow(CodeValidationError);
+    expect(() => validator.validate(`getattr(os, 'sys' + 'tem')('id')`, 'python')).toThrow(CodeValidationError);
+    expect(() => validator.validate(`__import__('os')`, 'python')).toThrow(CodeValidationError);
+  });
+
+  it('allows benign code', () => {
+    expect(() => validator.validate(`const fs = require('fs'); fs.writeFileSync('x', '1');`, 'node')).not.toThrow();
+    expect(() => validator.validate(`import json\nprint(json.dumps({'a': 1}))`, 'python')).not.toThrow();
+  });
+});
+
+describe('CodeValidator.validateImports — allowlist', () => {
+  afterEach(() => {
+    delete process.env.SKILL_HUB_ALLOW_ANY_IMPORT;
+  });
+
+  it('blocks stdlib network modules even when whitelist is empty (exfiltration hole)', () => {
+    // urllib / ftplib are stdlib (no install needed) and must NOT pass on empty whitelist.
+    expect(() => validator.validateImports(`import urllib.request`, 'python', [])).toThrow(CodeValidationError);
+    expect(() => validator.validateImports(`import ftplib`, 'python', [])).toThrow(CodeValidationError);
+  });
+
+  it('allows builtins on empty whitelist', () => {
+    expect(() => validator.validateImports(`import json`, 'python', [])).not.toThrow();
+  });
+
+  it('allows whitelisted package and maps PyPI→import name', () => {
+    expect(() => validator.validateImports(`import requests`, 'python', ['requests'])).not.toThrow();
+    expect(() => validator.validateImports(`from docx import Document`, 'python', ['python-docx'])).not.toThrow();
+  });
+
+  it('blocks non-whitelisted node package but allows builtins', () => {
+    expect(() => validator.validateImports(`require('lodash')`, 'node', [])).toThrow(CodeValidationError);
+    expect(() => validator.validateImports(`require('lodash')`, 'node', ['lodash'])).not.toThrow();
+    expect(() => validator.validateImports(`require('path')`, 'node', [])).not.toThrow();
+  });
+
+  it('honours SKILL_HUB_ALLOW_ANY_IMPORT escape hatch on empty whitelist', () => {
+    process.env.SKILL_HUB_ALLOW_ANY_IMPORT = 'true';
+    expect(() => validator.validateImports(`import urllib.request`, 'python', [])).not.toThrow();
+  });
+});

package/src/server/__tests__/skill-execute.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createSkillExecuteTool } from '../tools/skill-execute';
+
+describe('createSkillExecuteTool', () => {
+  it('bridges ToolsRuntime onto ctx.runtime while executing a skill', async () => {
+    const runtime = { toolCallId: 'tool-1', writer: vi.fn() };
+    const ctx: { runtime?: typeof runtime } = {};
+    const skill = { get: vi.fn((name: string) => (name === 'name' ? 'demo' : undefined)) };
+    const executeSkill = vi.fn(async (_skill, _input, executeCtx) => {
+      expect(executeCtx.runtime).toBe(runtime);
+      return {
+        status: 'succeeded',
+        files: [],
+      };
+    });
+    const plugin = {
+      app: { logger: { info: vi.fn() } },
+      db: {
+        getRepository: vi.fn(() => ({
+          findOne: vi.fn(async () => skill),
+        })),
+      },
+      executeSkill,
+    };
+
+    const tool = createSkillExecuteTool(plugin);
+    const result = await tool.invoke(ctx, { action: 'execute', skillName: 'demo', input: { ok: true } }, runtime);
+
+    expect(result.status).toBe('success');
+    expect(executeSkill).toHaveBeenCalledOnce();
+    expect(ctx.runtime).toBeUndefined();
+  });
+});

package/src/server/__tests__/skill-settings.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest';
+import { normalizeAIEmployeeSkillSettings } from '../utils/skill-settings';
+
+describe('normalizeAIEmployeeSkillSettings', () => {
+  it('moves legacy object tool bindings from skills to tools', () => {
+    const result = normalizeAIEmployeeSkillSettings({
+      skills: [{ name: 'orchestrator_plan_goal', autoCall: false }, 'crm-research'],
+      tools: [],
+    });
+
+    expect(result.changed).toBe(true);
+    expect(result.skillSettings.skills).toEqual(['crm-research']);
+    expect(result.skillSettings.tools).toEqual([{ name: 'orchestrator_plan_goal', autoCall: false }]);
+  });
+
+  it('moves orchestrator tool names stored as skill strings to tools', () => {
+    const result = normalizeAIEmployeeSkillSettings({
+      skills: ['delegate_lead_to_researcher', 'crm-research'],
+    });
+
+    expect(result.changed).toBe(true);
+    expect(result.skillSettings.skills).toEqual(['crm-research']);
+    expect(result.skillSettings.tools).toEqual([{ name: 'delegate_lead_to_researcher', autoCall: false }]);
+  });
+
+  it('keeps current tool bindings and avoids duplicate migrated tools', () => {
+    const result = normalizeAIEmployeeSkillSettings({
+      skills: [{ name: 'dispatch_subagents_lead', autoCall: true }],
+      tools: [{ name: 'dispatch_subagents_lead', autoCall: false }],
+    });
+
+    expect(result.changed).toBe(true);
+    expect(result.skillSettings.skills).toEqual([]);
+    expect(result.skillSettings.tools).toEqual([{ name: 'dispatch_subagents_lead', autoCall: false }]);
+  });
+
+  it('moves browser and drawio tools stored as skill strings to tools', () => {
+    const result = normalizeAIEmployeeSkillSettings({
+      skills: ['browser_open_url', 'drawio-edit-diagram', 'crm-research'],
+    });
+
+    expect(result.changed).toBe(true);
+    expect(result.skillSettings.skills).toEqual(['crm-research']);
+    expect(result.skillSettings.tools).toEqual([
+      { name: 'browser_open_url', autoCall: false },
+      { name: 'drawio-edit-diagram', autoCall: false },
+    ]);
+  });
+
+  it('moves Skill Hub tool bindings from skills to tools', () => {
+    const result = normalizeAIEmployeeSkillSettings({
+      skills: ['skill_hub_execute', { name: 'skill_hub_generate_report', autoCall: true }],
+      tools: [],
+    });
+
+    expect(result.changed).toBe(true);
+    expect(result.skillSettings.skills).toEqual([]);
+    expect(result.skillSettings.tools).toEqual([
+      { name: 'skill_hub_execute', autoCall: false },
+      { name: 'skill_hub_generate_report', autoCall: true },
+    ]);
+  });
+});

package/src/server/migrations/20260615000000-normalize-ai-employee-tool-bindings.ts

@@ -0,0 +1,39 @@
+import { Migration } from '@nocobase/server';
+import { normalizeAIEmployeeSkillSettings } from '../utils/skill-settings';
+
+export default class NormalizeAIEmployeeToolBindings extends Migration {
+  on = 'afterLoad';
+  appVersion = '>=0.1.0';
+
+  async up() {
+    const repo = (this as unknown as { db: { getRepository: (name: string) => any }; app?: any }).db.getRepository(
+      'aiEmployees',
+    );
+    if (!repo) return;
+
+    const rows = await repo.find({});
+    let updated = 0;
+
+    for (const row of rows) {
+      const skillSettings = row.get?.('skillSettings') ?? row.skillSettings;
+      const normalized = normalizeAIEmployeeSkillSettings(skillSettings);
+      if (!normalized.changed) continue;
+
+      await row.update({
+        skillSettings: normalized.skillSettings,
+      });
+      updated += 1;
+    }
+
+    if (updated > 0) {
+      (this as unknown as { app?: { logger?: { info?: (message: string) => void } } }).app?.logger?.info?.(
+        `[AgentOrchestrator] Normalized AI employee tool bindings (${updated}).`,
+      );
+    }
+  }
+
+  async down() {
+    // No rollback: this only moves tool-shaped entries from skillSettings.skills
+    // into the current NocoBase skillSettings.tools shape.
+  }
+}

package/src/server/plugin.ts

@@ -8,6 +8,8 @@ import { registerAgentLoopResource } from './resources/agent-loop';
 import { getRunEventBus } from './services/RunEventBus';
 import SkillHubSubFeature from './skill-hub/plugin';
 import { AgentLoopService } from './services/AgentLoopService';
+import { isAdminUser, currentUserId } from './utils/ctx-utils';
+import { getAIToolsManager } from './utils/ai-manager';
 
 export class PluginAgentOrchestratorServer extends Plugin {
   skillHub: SkillHubSubFeature;
@@ -20,10 +22,10 @@ export class PluginAgentOrchestratorServer extends Plugin {
 
   async beforeLoad() {
     // Import collection definitions
-    (this as any).db.import({ directory: path.resolve(__dirname, 'collections') });
+    this.db.import({ directory: path.resolve(__dirname, 'collections') });
 
-    (this as any).db.addMigrations({
-      namespace: (this as any).name,
+    this.db.addMigrations({
+      namespace: this.name,
       directory: path.resolve(__dirname, 'migrations'),
       context: { plugin: this },
     });
@@ -33,8 +35,8 @@ export class PluginAgentOrchestratorServer extends Plugin {
     await this.skillHub.load();
 
     // --- ACL ---
-    (this as any).app.acl.registerSnippet({
-      name: `pm.${(this as any).name}`,
+    this.app.acl.registerSnippet({
+      name: `pm.${this.name}`,
       actions: [
         'orchestratorConfig:*',
         'orchestratorTracing:*',
@@ -53,11 +55,46 @@ export class PluginAgentOrchestratorServer extends Plugin {
       ],
     });
 
+    // Allow any logged-in user to read available skills and loop configs.
+    // This mirrors the plugin-ai pattern (acl.allow with 'loggedIn')
+    // so that non-admin users with AI roles can use skills without
+    // requiring manual snippet assignment per role.
+    // Create/update/destroy remain restricted to admin roles via the snippet above.
+    this.app.acl.allow('skillDefinitions', 'list', 'loggedIn');
+    this.app.acl.allow('skillDefinitions', 'get', 'loggedIn');
+    this.app.acl.allow('skillLoopConfigs', 'list', 'loggedIn');
+    this.app.acl.allow('skillLoopConfigs', 'get', 'loggedIn');
+    this.app.acl.allow('skillExecutions', 'list', 'loggedIn');
+    this.app.acl.allow('skillExecutions', 'get', 'loggedIn');
+    this.app.acl.allow('skillHub', 'test', 'loggedIn');
+    this.app.acl.allow('skillHub', 'download', 'loggedIn');
+    this.app.acl.allow('skillHub', 'listTemplates', 'loggedIn');
+
+    // Data scoping for skillExecutions: a logged-in non-admin user may only
+    // read their own executions. Rows hold inputArgs / stdout / output files,
+    // so an unscoped list/get would leak one user's data to another. Admins
+    // (root/admin roles) keep full visibility. This mirrors the owner/admin
+    // check enforced by skillHub:download.
+    this.app.resourceManager.use(
+      async (ctx, next) => {
+        const { resourceName, actionName } = ctx.action || {};
+        if (resourceName === 'skillExecutions' && (actionName === 'list' || actionName === 'get')) {
+          if (!isAdminUser(ctx)) {
+            const userId = currentUserId(ctx);
+            const ownerFilter = userId ? { triggeredById: userId } : { triggeredById: null };
+            ctx.action.mergeParams({ filter: ownerFilter });
+          }
+        }
+        await next();
+      },
+      { tag: 'orchestrator-skill-executions-scope', after: 'acl' },
+    );
+
     // --- 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;
+    const toolsManager = getAIToolsManager(this.app);
     toolsManager.registerTools(createOrchestratorPlanTools(this, this.agentLoopService));
     toolsManager.registerTools(createExternalRagSearchTool(this));
     toolsManager.registerDynamicTools(createDelegateToolsProvider(this));
@@ -66,7 +103,7 @@ export class PluginAgentOrchestratorServer extends Plugin {
     registerAgentLoopResource(this, this.agentLoopService);
 
     // --- Register SSE Event Stream Resource (Phase 6) ---
-    (this as any).app.resource({
+    this.app.resource({
       name: 'agentLoopEventsStream',
       actions: {
         async stream(ctx, next) {
@@ -76,6 +113,25 @@ export class PluginAgentOrchestratorServer extends Plugin {
             return;
           }
 
+          // Ownership check: a non-admin user may only stream events for a run
+          // they started. Run events can echo step inputs/outputs, so an
+          // unscoped stream would leak another user's run activity.
+          if (!isAdminUser(ctx)) {
+            const userId = currentUserId(ctx);
+            const run = await ctx.db.getRepository('agentLoopRuns').findOne({
+              filter: { id: runId },
+            });
+            if (!run) {
+              ctx.throw(404, 'Run not found.');
+              return;
+            }
+            const ownerId = run.get ? run.get('userId') : run.userId;
+            if (!userId || String(ownerId) !== String(userId)) {
+              ctx.throw(403, 'You cannot stream events for this run.');
+              return;
+            }
+          }
+
           ctx.type = 'text/event-stream';
           ctx.set('Cache-Control', 'no-cache');
           ctx.set('Connection', 'keep-alive');
@@ -123,15 +179,15 @@ export class PluginAgentOrchestratorServer extends Plugin {
     // --- 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({
+    this.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 repo = this.db.getRepository('orchestratorLogs');
+          const spansRepo = this.db.getRepository('agentExecutionSpans');
           const deletedLogs = repo
             ? await repo.destroy({
                 filter: { createdAt: { $lt: cutoff.toISOString() } },
@@ -142,11 +198,11 @@ export class PluginAgentOrchestratorServer extends Plugin {
                 filter: { createdAt: { $lt: cutoff.toISOString() } },
               })
             : 0;
-          (this as any).app.log.info(
+          this.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);
+          this.app.log.error('[AgentOrchestrator] Log retention job failed', e);
         }
       },
     });

package/src/server/services/AgentHarness.ts

@@ -7,10 +7,13 @@ import { ExecutionSpanService, setOrchestratorTraceContext } from './ExecutionSp
 import { AgentRegistryService } from './AgentRegistryService';
 import { TokenTracker, extractTokenUsage } from './TokenTracker';
 import { ContextAggregator } from './ContextAggregator';
-import { getCircuitBreaker } from './CircuitBreaker';
+import { getCircuitBreaker, subAgentCircuitKey } from './CircuitBreaker';
 import { toPlain, asObject, trimText, nowIso } from '../utils/ctx-utils';
+import { normalizeAIEmployeeSkillSettings } from '../utils/skill-settings';
 import { logDelegation as sharedLogDelegation } from '../utils/logging';
+import { getAIToolsManager, tryGetAIToolsManager } from '../utils/ai-manager';
 import { TraceEvent } from '../types';
+import type { ToolsRuntime } from '@nocobase/ai';
 
 const ORCHESTRATOR_DEPTH_KEY = '__orchestratorDepth';
 const ORCHESTRATOR_PATH_KEY = '__orchestratorPath';
@@ -31,9 +34,10 @@ export class AgentHarness {
   constructor(
     private readonly plugin: any,
     private readonly registryService: AgentRegistryService,
+    tokenTracker?: TokenTracker,
   ) {
     this.spanService = new ExecutionSpanService(plugin);
-    this.tokenTracker = new TokenTracker(plugin);
+    this.tokenTracker = tokenTracker || new TokenTracker(plugin);
     this.contextAggregator = new ContextAggregator(plugin);
   }
 
@@ -112,10 +116,11 @@ export class AgentHarness {
     );
 
     const circuitBreaker = getCircuitBreaker({ appLog: this.app });
+    const circuitKey = subAgentCircuitKey(run.leaderUsername, target);
 
     // ── Circuit breaker check before invoking sub-agent ──────────────
-    if (!circuitBreaker.isAllowed(target)) {
-      const state = circuitBreaker.getState(target);
+    if (!circuitBreaker.isAllowed(circuitKey)) {
+      const state = circuitBreaker.getState(circuitKey);
       throw new Error(
         `Sub-agent "${target}" circuit is open (${state?.failures || 0} failures). Retry after the recovery timeout.`,
       );
@@ -123,12 +128,12 @@ export class AgentHarness {
 
     try {
       const result = await this.invokeNamedTool(run, step, toolName, { task, context }, settings, options);
-      circuitBreaker.recordSuccess(target);
+      circuitBreaker.recordSuccess(circuitKey);
       return result;
     } catch (e: any) {
       // Don't count approval pauses as circuit failures
       if (e?.message !== 'requires_approval') {
-        circuitBreaker.recordFailure(target);
+        circuitBreaker.recordFailure(circuitKey);
       }
       throw e;
     }
@@ -157,7 +162,7 @@ export class AgentHarness {
       }
     }
 
-    const toolsManager = this.app?.aiManager?.toolsManager;
+    const toolsManager = tryGetAIToolsManager(this.app);
     const tool = await toolsManager?.getTools?.(toolName);
     if (!tool?.invoke) {
       throw new Error(`Tool "${toolName}" was not found or is missing standard invoke handler.`);
@@ -184,8 +189,18 @@ export class AgentHarness {
       ctx.state = { ...(ctx.state || {}), currentAIEmployee: run.leaderUsername };
     }
 
+    const previousRuntime = ctx.runtime;
+    const toolCallId = `agent-loop-${run.id}-${step.id}`;
+    const runtime: ToolsRuntime = {
+      toolCallId,
+      writer: (chunk: any) => {
+        this.app.log.trace(`[AgentHarness] Tool output:`, chunk);
+      },
+    };
+    ctx.runtime = runtime;
+
     try {
-      const result = await tool.invoke(ctx, args, `agent-loop-${run.id}-${step.id}`);
+      const result = await tool.invoke(ctx, args, runtime);
       if (result?.status === 'error') {
         throw new Error(result.content || `Tool "${toolName}" returned an error.`);
       }
@@ -195,6 +210,11 @@ export class AgentHarness {
         result,
       };
     } finally {
+      if (previousRuntime === undefined) {
+        delete ctx.runtime;
+      } else {
+        ctx.runtime = previousRuntime;
+      }
       if (previousEmployee === undefined) {
         delete ctx._currentAIEmployee;
       } else {
@@ -251,6 +271,7 @@ export class AgentHarness {
       agentLoopRunId,
       agentLoopStepId,
     } = options;
+    const effectiveRootRunId = rootRunId || `run_${Date.now()}`;
 
     const startTime = Date.now();
     const currentDepth = options.currentDepth ?? 0;
@@ -265,7 +286,7 @@ export class AgentHarness {
     ];
 
     const executionSpan = await this.spanService.create({
-      rootRunId: rootRunId || `run_${Date.now()}`,
+      rootRunId: effectiveRootRunId,
       parentSpanId,
       type: 'sub_agent',
       status: 'running',
@@ -323,24 +344,21 @@ export class AgentHarness {
       });
       const chatModel = provider.createModel();
 
-      const coreToolsManager = ctx.app.aiManager.toolsManager;
+      const coreToolsManager = getAIToolsManager(ctx.app);
       const allTools = await coreToolsManager.listTools();
 
-      const employeeSkills = (subAgentEmployee.skillSettings?.skills ?? [])
-        .map((s: any) =>
-          typeof s === 'string' ? { name: s, autoCall: false } : { name: s?.name, autoCall: s?.autoCall === true },
-        )
-        .filter((s: any) => Boolean(s.name));
-      const employeeSkillMap = new Map<string, any>(employeeSkills.map((s: any) => [s.name, s]));
+      const normalizedSkillSettings = normalizeAIEmployeeSkillSettings(subAgentEmployee.skillSettings).skillSettings;
+      const employeeTools = normalizedSkillSettings.tools.filter((tool) => Boolean(tool.name));
+      const employeeToolMap = new Map(employeeTools.map((tool) => [tool.name, tool]));
 
       const langchainTools: DynamicStructuredTool[] = [];
 
       for (const toolEntry of allTools) {
         const entryName = toolEntry.definition.name;
         if (!entryName) continue;
-        const employeeSkill = employeeSkillMap.get(entryName);
+        const employeeTool = employeeToolMap.get(entryName);
 
-        if (!employeeSkill || employeeSkill.autoCall !== true || toolEntry.defaultPermission !== 'ALLOW') {
+        if (!employeeTool || employeeTool.autoCall !== true || toolEntry.execution === 'frontend') {
           continue;
         }
 
@@ -362,7 +380,7 @@ export class AgentHarness {
               const toolStartedAt = Date.now();
               const isSkillHubTool = entryName === 'skill_hub_execute' || entryName.startsWith('skill_hub_');
               const toolSpan = await this.spanService.create({
-                rootRunId: rootRunId || `run_${Date.now()}`,
+                rootRunId: effectiveRootRunId,
                 parentSpanId: executionSpanId,
                 type: isSkillHubTool ? 'skill' : 'tool',
                 status: 'running',
@@ -381,7 +399,7 @@ export class AgentHarness {
               });
               const toolSpanId = toolSpan?.id ? String(toolSpan.id) : undefined;
               setOrchestratorTraceContext(invokeCtx, {
-                rootRunId,
+                rootRunId: effectiveRootRunId,
                 spanId: toolSpanId,
                 parentSpanId: executionSpanId,
                 toolCallId: `orch-${toolCallId}`,
@@ -400,8 +418,17 @@ export class AgentHarness {
                 args: toolArgs,
               });
 
+              const subToolCallId = `orch-${toolCallId}`;
+              const runtime: ToolsRuntime = {
+                toolCallId: subToolCallId,
+                writer: (chunk: any) => {
+                  this.app.log.trace(`[AgentHarness] Tool output:`, chunk);
+                },
+              };
+              invokeCtx.runtime = runtime;
+
               try {
-                const res = await toolEntry.invoke(invokeCtx, toolArgs, `orch-${toolCallId}`);
+                const res = await toolEntry.invoke(invokeCtx, toolArgs, runtime);
                 const output = trimText(res?.content ?? res?.result ?? res, 50000);
                 trace.push({
                   type: 'tool_result',
@@ -461,7 +488,7 @@ export class AgentHarness {
           const sessionId =
             ctx.action?.params?.values?.sessionId || ctx.action?.params?.sessionId || ctx.state?.sessionId;
           const contextSummary = await kbPlugin.sessionContext.buildSummary(
-            { rootRunId, ...(sessionId ? { sessionId } : {}) },
+            { rootRunId: effectiveRootRunId, ...(sessionId ? { sessionId } : {}) },
             6000,
           );
           if (contextSummary) {

package/src/server/services/AgentLoopController.ts

@@ -5,7 +5,7 @@ import { AgentLoopRepository } from './AgentLoopRepository';
 import { AgentHarness } from './AgentHarness';
 import { AgentLoopPolicy, AgentLoopPlanStepInput, AgentLoopRunStatus, AgentLoopStepStatus } from './AgentLoopService';
 import { TokenTracker } from './TokenTracker';
-import { getCircuitBreaker } from './CircuitBreaker';
+import { getCircuitBreaker, subAgentCircuitKey } from './CircuitBreaker';
 import { createHash } from 'crypto';
 import { asObject, asArray, trimText, normalizeStepType, normalizePlanKey } from '../utils/ctx-utils';
 
@@ -816,7 +816,7 @@ export class AgentLoopController {
       const target = step.target || '';
       if (target) {
         const circuitBreaker = getCircuitBreaker();
-        const state = circuitBreaker.getState(target);
+        const state = circuitBreaker.getState(subAgentCircuitKey(run.leaderUsername, target));
         const attempt = Number(step.attempt || 0);
 
         // Route away if: circuit is open, or 2+ failures and at least 1 retry already attempted
@@ -1044,7 +1044,13 @@ export class AgentLoopController {
           runningSteps.map((step: any) => this.harness.executeStep(snapshot.run, step, options)),
         );
 
-        // Process results — failures need individual backoff before retry
+        // Process results. Failed-but-retryable steps need a backoff before the
+        // next iteration picks them up again. We compute the LARGEST backoff in
+        // the batch and sleep once after the loop — never sum per-step sleeps.
+        // Summing held the run-lock for up to maxConcurrency × 60s (= the whole
+        // 5-minute lock when a full batch fails), starving other steps.
+        let batchBackoffMs = 0;
+        let approvalBreak = false;
         for (let i = 0; i < results.length; i++) {
           const runningStep = runningSteps[i];
           const result = results[i];
@@ -1063,6 +1069,7 @@ export class AgentLoopController {
                 { userId: options.userId, reason: 'Dynamic tool approval required by policy.' },
               );
               // Stop processing more results; remaining steps are left pending
+              approvalBreak = true;
               break;
             }
 
@@ -1075,17 +1082,21 @@ export class AgentLoopController {
               failedStep &&
               Number(failedStep.attempt || 0) < Number(failedStep.maxAttempts || policy.maxStepAttempts)
             ) {
-              // Exponential backoff before retry
+              // Exponential backoff — track the max; the step stays pending for retry.
               const attempt = Number(failedStep.attempt || 1);
               const baseDelay = 1000;
               const maxDelay = 60000;
               const delay = Math.min(baseDelay * Math.pow(2, attempt - 1), maxDelay);
-              await new Promise((resolve) => setTimeout(resolve, delay));
-              // Step remains pending for retry (failStep resets status back)
+              batchBackoffMs = Math.max(batchBackoffMs, delay);
             }
           }
         }
 
+        // Single consolidated backoff for the whole batch (bounded at maxDelay).
+        if (!approvalBreak && batchBackoffMs > 0) {
+          await new Promise((resolve) => setTimeout(resolve, batchBackoffMs));
+        }
+
         // Re-evaluate the plan — newly unblocked steps become eligible
         snapshot = await this.getRunSnapshot(runId);
 

package/src/server/services/AgentLoopService.ts

@@ -63,8 +63,8 @@ export class AgentLoopService {
     this.plannerService = new AgentPlannerService();
     this.validator = new AgentPlanValidator();
     this.repository = new AgentLoopRepository(plugin);
-    this.harness = new AgentHarness(plugin, this.registryService);
     const tokenTracker = new TokenTracker(plugin);
+    this.harness = new AgentHarness(plugin, this.registryService, tokenTracker);
     this.controller = new AgentLoopController(
       this.registryService,
       this.plannerService,

package/src/server/services/AgentPlannerService.ts

@@ -2,6 +2,16 @@ import { AgentLoopPlanStepInput } from './AgentLoopService';
 
 import { normalizeStepType, normalizePlanKey, asArray, asObject } from '../utils/ctx-utils';
 
+/**
+ * Deterministic, template-based plan builder. This service does NOT call an LLM:
+ * it either passes through a caller-provided plan or emits a fixed
+ * prepare → (delegate|execute) → verify skeleton.
+ *
+ * The run's `plannerModel` field is metadata only (records which model an
+ * upstream caller used to author a provided plan); it does not drive any
+ * generation here. If LLM-authored planning is added later, it belongs in a
+ * separate path — keep this builder deterministic so it stays test-stable.
+ */
 export class AgentPlannerService {
   buildPlan(
     goal: string,