This commit is contained in:
Oleg Maslov
2026-09-02 10:14:22 +02:00
parent 0c3e2ead3b
commit b20b138fe4
771 changed files with 161561 additions and 9027 deletions

View File

@@ -9,8 +9,15 @@
import { EventEmitter } from 'events';
import type { ToolDefinition } from './tools.js';
import type { AgentLoopConfig, AgentResponse } from './agent-loop.js';
import type { HookRegistry } from './hooks.js';
import { filterSpawnToolNames, type SpawnSecurityContext } from './subagent-tools.js';
import { selectAgentRunBudget, type AgentRunBudgetPolicy } from './agent-run-budget.js';
import { HookRegistry, type HookEvent } from './hooks.js';
import {
filterSpawnToolNames,
guardSubAgentOutput,
type SpawnSecurityContext,
} from './subagent-tools.js';
import { detectTaskShape } from './task-shape.js';
import { filterAvailableTools, selectToolsForTurn } from './tool-filter.js';
export type WorkerStatus = 'pending' | 'running' | 'done' | 'failed';
@@ -53,6 +60,29 @@ export interface WorkflowTemplate {
aggregation: 'concatenate' | 'last' | 'synthesize';
}
export const MAX_WORKFLOW_STEPS = 32;
export const MAX_WORKFLOW_CONCURRENCY = 5;
export const MAX_WORKFLOW_TURNS = 96;
export const MAX_WORKFLOW_CONFIGURED_TOKEN_BUDGET = 1_000_000;
export type WorkflowLimitKind = 'steps' | 'turns' | 'tokens';
export class WorkflowLimitError extends Error {
constructor(
public readonly kind: WorkflowLimitKind,
public readonly actual: number,
public readonly limit: number,
) {
const label = kind === 'steps'
? 'worker'
: kind === 'turns'
? 'turn budget'
: 'configured token budget';
super(`Workflow ${label} limit exceeded: ${actual} > ${limit}`);
this.name = 'WorkflowLimitError';
}
}
export interface OrchestratorConfig {
availableTools: ToolDefinition[];
runLoop: (config: AgentLoopConfig) => Promise<AgentResponse>;
@@ -73,10 +103,24 @@ export interface OrchestratorConfig {
getSpawnSecurityContext?: () => SpawnSecurityContext | undefined;
}
interface WorkerExecutionPlan {
tools: ToolDefinition[];
runBudget: AgentRunBudgetPolicy;
maxTurns: number;
maxToolRounds: number;
securityContext?: SpawnSecurityContext;
}
interface WorkflowExecutionPlan {
stepPlans: Map<WorkflowStep, WorkerExecutionPlan>;
synthesisPlan?: WorkerExecutionPlan;
}
export class SubagentOrchestrator extends EventEmitter {
private config: OrchestratorConfig;
private workers: Map<string, WorkerState>;
private workflowCounter: number;
private workflowRunning: boolean;
private parentContext: string = '';
/** Role presets (same as subagent-tools for consistency, plus synthesizer/summarizer) */
@@ -96,6 +140,7 @@ export class SubagentOrchestrator extends EventEmitter {
this.config = config;
this.workers = new Map();
this.workflowCounter = 0;
this.workflowRunning = false;
}
/** Set parent agent context to inject into all worker prompts */
@@ -115,6 +160,13 @@ export class SubagentOrchestrator extends EventEmitter {
if (template.steps.length === 0) {
return { results: new Map(), aggregated: '' };
}
if (this.workflowRunning) {
throw new Error('A workflow is already running on this orchestrator instance');
}
this.workflowRunning = true;
try {
const executionPlan = this.preflightWorkflow(template);
// Reset workers for this workflow run
this.workers = new Map();
@@ -176,23 +228,39 @@ export class SubagentOrchestrator extends EventEmitter {
break;
}
const wave = await Promise.all(
ready.map((step) => this.runWorker(step, contextResults, stepWorkerIds.get(step.name))),
);
for (let index = 0; index < ready.length; index++) {
const step = ready[index];
const workerState = wave[index];
if (workerState.status === 'done' && workerState.result) {
contextResults.set(step.name, workerState.result);
for (let offset = 0; offset < ready.length; offset += MAX_WORKFLOW_CONCURRENCY) {
const batch = ready.slice(offset, offset + MAX_WORKFLOW_CONCURRENCY);
const batchStates = await Promise.all(
batch.map((step) => this.runWorker(
step,
contextResults,
executionPlan.stepPlans.get(step)!,
stepWorkerIds.get(step.name),
)),
);
for (let index = 0; index < batch.length; index++) {
const step = batch[index];
const workerState = batchStates[index];
if (workerState.status === 'done' && workerState.result) {
contextResults.set(step.name, workerState.result);
}
completed.add(step.name);
}
completed.add(step.name);
}
}
// Aggregate results
const aggregated = await this.aggregateResults(this.workers, template.aggregation, contextResults);
const aggregated = await this.aggregateResults(
this.workers,
template.aggregation,
contextResults,
executionPlan.synthesisPlan,
);
return { results: new Map(this.workers), aggregated };
return { results: new Map(this.workers), aggregated };
} finally {
this.workflowRunning = false;
}
}
/** Get all workers and their current status */
@@ -207,12 +275,126 @@ export class SubagentOrchestrator extends EventEmitter {
// ── Private helpers ──────────────────────────────────────────────────
private preflightWorkflow(template: WorkflowTemplate): WorkflowExecutionPlan {
const implicitWorkerCount = template.aggregation === 'synthesize' ? 1 : 0;
const workerCount = template.steps.length + implicitWorkerCount;
if (workerCount > MAX_WORKFLOW_STEPS) {
throw new WorkflowLimitError('steps', workerCount, MAX_WORKFLOW_STEPS);
}
const securityContext = this.config.getSpawnSecurityContext?.();
const stepPlans = new Map<WorkflowStep, WorkerExecutionPlan>();
const stepPlanList = template.steps.map((step) => {
const plan = this.buildWorkerExecutionPlan(step, securityContext);
stepPlans.set(step, plan);
return plan;
});
const synthesisPlan = template.aggregation === 'synthesize'
? this.buildWorkerExecutionPlan({
name: 'Synthesizer',
role: 'synthesizer',
task: 'Synthesize the completed worker results into a cohesive response.',
tools: [],
}, securityContext)
: undefined;
const plans = [...stepPlanList, ...(synthesisPlan ? [synthesisPlan] : [])];
const totalTurns = plans.reduce((sum, plan) => sum + plan.maxTurns, 0);
if (totalTurns > MAX_WORKFLOW_TURNS) {
throw new WorkflowLimitError('turns', totalTurns, MAX_WORKFLOW_TURNS);
}
const totalTokenBudget = plans.reduce(
(sum, plan) => sum + plan.runBudget.maxTokenBudget,
0,
);
if (totalTokenBudget > MAX_WORKFLOW_CONFIGURED_TOKEN_BUDGET) {
throw new WorkflowLimitError(
'tokens',
totalTokenBudget,
MAX_WORKFLOW_CONFIGURED_TOKEN_BUDGET,
);
}
return { stepPlans, synthesisPlan };
}
private buildWorkerExecutionPlan(
step: WorkflowStep,
securityContext?: SpawnSecurityContext,
): WorkerExecutionPlan {
const baseToolNames = step.tools
?? SubagentOrchestrator.ROLE_TOOL_PRESETS[step.role]
?? SubagentOrchestrator.ROLE_TOOL_PRESETS.analyst!;
const toolNames = filterSpawnToolNames(baseToolNames, securityContext);
const eligibleTools = filterAvailableTools(
this.config.availableTools.filter(tool => toolNames.includes(tool.name)),
);
const tools = selectToolsForTurn(eligibleTools, {
message: step.task,
preferredToolNames: toolNames,
fallbackToEligible: true,
}).tools;
const taskShape = detectTaskShape(step.task);
const runBudget = selectAgentRunBudget({
taskShape: taskShape.type,
complexity: taskShape.complexity,
selectedToolNames: tools.map(tool => tool.name),
});
const normalizedMaxTurns = Math.floor(step.maxTurns ?? 0);
const requestedMaxTurns = Number.isFinite(normalizedMaxTurns) && normalizedMaxTurns >= 1
? normalizedMaxTurns
: runBudget.maxTurns;
const maxTurns = Math.min(requestedMaxTurns, runBudget.maxTurns);
return {
tools,
runBudget,
maxTurns,
maxToolRounds: Math.min(runBudget.maxToolRounds, Math.max(0, maxTurns - 1)),
securityContext,
};
}
private makeWorkerId(name: string): string {
this.workflowCounter++;
return `worker-${this.workflowCounter}-${Date.now()}`;
}
private async runWorker(step: WorkflowStep, contextResults: Map<string, string>, existingId?: string): Promise<WorkerState> {
private combineWorkerHooks(
initialHooks?: HookRegistry,
liveHooks?: HookRegistry,
): HookRegistry | undefined {
const originalHooks = initialHooks ?? this.config.hooks;
if (!originalHooks) return liveHooks;
if (!liveHooks || liveHooks === originalHooks) return originalHooks;
const combinedHooks = new HookRegistry();
const workerEvents: HookEvent[] = [
'pre:tool',
'post:tool',
'pre:memory-write',
'post:memory-write',
];
for (const event of workerEvents) {
combinedHooks.on(event, async (context) => {
const originalResult = await originalHooks.fire(event, context);
if (originalResult.cancelled) {
return { cancel: true, reason: originalResult.reason };
}
const liveResult = await liveHooks.fire(event, context);
return liveResult.cancelled
? { cancel: true, reason: liveResult.reason }
: undefined;
});
}
return combinedHooks;
}
private async runWorker(
step: WorkflowStep,
contextResults: Map<string, string>,
executionPlan: WorkerExecutionPlan,
existingId?: string,
): Promise<WorkerState> {
const id = existingId ?? this.makeWorkerId(step.name);
// Reuse pre-created pending worker or create fresh
const workerState: WorkerState = this.workers.get(id) ?? {
@@ -230,13 +412,25 @@ export class SubagentOrchestrator extends EventEmitter {
this.workers.set(id, workerState);
this.emit('worker:status', { workerId: id, status: 'running', workerState });
// Resolve tools
const baseToolNames = step.tools ?? SubagentOrchestrator.ROLE_TOOL_PRESETS[step.role] ?? SubagentOrchestrator.ROLE_TOOL_PRESETS.analyst!;
// SEC: inherit the spawning request's governance denylist + persona allowlist
// so a workflow worker cannot escape the request's tool restrictions.
const secCtx = this.config.getSpawnSecurityContext?.();
const toolNames = filterSpawnToolNames(baseToolNames, secCtx);
const tools = this.config.availableTools.filter(t => toolNames.includes(t.name));
const {
tools: plannedTools,
runBudget,
maxTurns,
maxToolRounds,
securityContext,
} = executionPlan;
const liveSecurityContext = this.config.getSpawnSecurityContext?.();
const liveToolNames = filterSpawnToolNames(
plannedTools.map(tool => tool.name),
liveSecurityContext,
);
const liveToolSet = new Set(liveToolNames);
const tools = plannedTools.filter(tool => liveToolSet.has(tool.name));
const blockedTools = [...new Set([
...(securityContext?.blockedTools ?? []),
...(liveSecurityContext?.blockedTools ?? []),
])];
const hooks = this.combineWorkerHooks(securityContext?.hooks, liveSecurityContext?.hooks);
// Build system prompt with optional context from previous steps
const systemPrompt = this.buildWorkerContext(step, contextResults);
@@ -249,21 +443,24 @@ export class SubagentOrchestrator extends EventEmitter {
systemPrompt,
tools,
messages: [{ role: 'user', content: step.task }],
maxTurns: step.maxTurns ?? 50,
...runBudget,
maxTurns,
maxToolRounds,
stream: false,
signal: this.config.signal,
// SEC: worker loops respect the request's approval gate + governance
// denylist. The executeToolCall critical floor still fail-closes
// destructive ops even when no gate is wired.
hooks: secCtx?.hooks ?? this.config.hooks,
governancePolicies: secCtx?.blockedTools?.length
? { blockedTools: [...secCtx.blockedTools] }
hooks,
governancePolicies: blockedTools.length > 0
? { blockedTools }
: undefined,
});
const response = guardSubAgentOutput(result.content, 'result');
workerState.status = 'done';
workerState.completedAt = Date.now();
workerState.result = result.content;
workerState.result = response;
workerState.toolsUsed = result.toolsUsed;
workerState.usage = { inputTokens: result.usage.inputTokens, outputTokens: result.usage.outputTokens };
@@ -271,7 +468,10 @@ export class SubagentOrchestrator extends EventEmitter {
} catch (err) {
workerState.status = 'failed';
workerState.completedAt = Date.now();
workerState.error = err instanceof Error ? err.message : String(err);
workerState.error = guardSubAgentOutput(
err instanceof Error ? err.message : String(err),
'error',
);
this.emit('worker:status', { workerId: id, status: 'failed', workerState });
}
@@ -297,7 +497,8 @@ export class SubagentOrchestrator extends EventEmitter {
}
}
if (contextParts.length > 0) {
prompt += `\n## Previous Results\n${contextParts.join('\n\n')}\n`;
const context = guardSubAgentOutput(contextParts.join('\n\n'), 'result');
prompt += `\n## Previous Results\n${context}\n`;
}
}
@@ -310,6 +511,7 @@ export class SubagentOrchestrator extends EventEmitter {
workers: Map<string, WorkerState>,
mode: WorkflowTemplate['aggregation'],
contextResults: Map<string, string>,
synthesisPlan?: WorkerExecutionPlan,
): Promise<string> {
const workerList = Array.from(workers.values());
const doneWorkers = workerList.filter(w => w.status === 'done' && w.result);
@@ -318,33 +520,36 @@ export class SubagentOrchestrator extends EventEmitter {
switch (mode) {
case 'concatenate': {
return doneWorkers
const combined = doneWorkers
.map(w => `## ${w.name}\n${w.result}`)
.join('\n\n');
return guardSubAgentOutput(combined, 'result');
}
case 'last': {
return doneWorkers[doneWorkers.length - 1].result!;
return guardSubAgentOutput(doneWorkers[doneWorkers.length - 1].result!, 'result');
}
case 'synthesize': {
// Spawn a synthesizer worker to combine all results
const allResults = doneWorkers
const combined = doneWorkers
.map(w => `### ${w.name}\n${w.result}`)
.join('\n\n');
const allResults = guardSubAgentOutput(combined, 'result');
const synthesizeStep: WorkflowStep = {
name: 'Synthesizer',
role: 'synthesizer',
task: `Synthesize the following results from multiple workers into a cohesive response:\n\n${allResults}`,
tools: [],
};
const synthState = await this.runWorker(synthesizeStep, contextResults);
const synthState = await this.runWorker(synthesizeStep, contextResults, synthesisPlan!);
return synthState.result ?? '';
}
default:
return doneWorkers.map(w => w.result).join('\n\n');
return guardSubAgentOutput(doneWorkers.map(w => w.result).join('\n\n'), 'result');
}
}
}