From bb7b5a19ccd74ce7ef4fa6a57cd3ea797d6c9e1c Mon Sep 17 00:00:00 2001 From: Sujai Kumar Gupta <120925871+thesujai@users.noreply.github.com> Date: Thu, 12 Nov 2026 13:50:28 +0000 Subject: [PATCH 1/3] feat: configure parallel sub-agent limit via environment Default MAX_PARALLEL_SUB_AGENTS to 10 and validate positive integer overrides at startup. Pass the configured limit through turn resource resolution to orchestration. Co-authored-by: TrueForge Agent --- .changeset/configurable-parallel-subagents.md | 6 ++++++ .../src/agent-session/ITurnResourceResolver.ts | 2 ++ .../src/agent-session/SessionHandle.ts | 1 + .../src/agent-session/TurnResourceResolver.ts | 5 +++++ packages/trueforge-core/src/core/index.ts | 2 +- .../src/core/runtime/AgentThreadOrchestrator.ts | 12 +++++++++--- packages/trueforge/.env.example | 2 ++ packages/trueforge/src/apis/turns.ts | 1 + packages/trueforge/src/config.ts | 8 ++++++++ 9 files changed, 35 insertions(+), 4 deletions(-) create mode 100644 .changeset/configurable-parallel-subagents.md diff --git a/.changeset/configurable-parallel-subagents.md b/.changeset/configurable-parallel-subagents.md new file mode 100644 index 0000000000..f47c03930d --- /dev/null +++ b/.changeset/configurable-parallel-subagents.md @@ -0,0 +1,6 @@ +--- +'@truefoundry/trueforge-core': patch +'@truefoundry/trueforge': patch +--- + +Make the per-turn sub-agent concurrency limit configurable with `MAX_PARALLEL_SUB_AGENTS`, defaulting to 10. diff --git a/packages/trueforge-core/src/agent-session/ITurnResourceResolver.ts b/packages/trueforge-core/src/agent-session/ITurnResourceResolver.ts index fd633908af..e7b86e5fff 100644 --- a/packages/trueforge-core/src/agent-session/ITurnResourceResolver.ts +++ b/packages/trueforge-core/src/agent-session/ITurnResourceResolver.ts @@ -19,6 +19,8 @@ export interface ResolvedAgentDefinition { * per-request state (secrets, providers, caches) freely. */ export interface ITurnResourceResolver> { + /** Maximum sub-agent threads executed in parallel per turn. Defaults to 10. */ + readonly maxParallelSubAgents?: number | undefined; /** * Host web-search backend. When set and `config.web_search.enabled`, builtins * register search/fetch system tools. Omit when the host has no provider configured. diff --git a/packages/trueforge-core/src/agent-session/SessionHandle.ts b/packages/trueforge-core/src/agent-session/SessionHandle.ts index b872b40d26..faa7748ab5 100644 --- a/packages/trueforge-core/src/agent-session/SessionHandle.ts +++ b/packages/trueforge-core/src/agent-session/SessionHandle.ts @@ -481,6 +481,7 @@ export class SessionHandle< const previousMcpServers = input.previous?.snapshot.mcp_servers; const orchestrator = new AgentThreadOrchestrator({ agentThreads, + maxParallelSubAgents: input.resolver.maxParallelSubAgents, createDynamicSubAgentThread, tracing, logger: input.resolver.logger, diff --git a/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts b/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts index b68c35d8b1..95eed4c17b 100644 --- a/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts +++ b/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts @@ -97,6 +97,7 @@ export class TurnResourceResolver< mcpRequestTimeoutMs: number; mcpConnectTimeoutMs: number; mcpMaxResponseBytes?: number | undefined; + maxParallelSubAgents?: number | undefined; /** One sandbox type per runtime. Omit = no sandbox support. */ sandboxProvider?: TurnSandboxFactory | undefined; /** @@ -121,6 +122,10 @@ export class TurnResourceResolver< return this.deps.webSearchProvider; } + get maxParallelSubAgents(): number | undefined { + return this.deps.maxParallelSubAgents; + } + get logger(): Logger { return this.deps.logger; } diff --git a/packages/trueforge-core/src/core/index.ts b/packages/trueforge-core/src/core/index.ts index e5601afdf4..e26365612d 100644 --- a/packages/trueforge-core/src/core/index.ts +++ b/packages/trueforge-core/src/core/index.ts @@ -19,7 +19,7 @@ export type { AgentThreadExecutionResult, SubAgentCompletion, } from './runtime/AgentThread.types'; -export { AgentThreadOrchestrator } from './runtime/AgentThreadOrchestrator'; +export { AgentThreadOrchestrator, DEFAULT_MAX_PARALLEL_SUB_AGENTS } from './runtime/AgentThreadOrchestrator'; export type { CreateDynamicSubAgentThread } from './runtime/CreateDynamicSubAgentThread'; export { isAgentUserMessage, isEmptyMessageContent, isFileContentPart } from './runtime/UserInputMessage'; export type { UserMessage } from './runtime/UserInputMessage'; diff --git a/packages/trueforge-core/src/core/runtime/AgentThreadOrchestrator.ts b/packages/trueforge-core/src/core/runtime/AgentThreadOrchestrator.ts index f71b2469b7..601cbefb28 100644 --- a/packages/trueforge-core/src/core/runtime/AgentThreadOrchestrator.ts +++ b/packages/trueforge-core/src/core/runtime/AgentThreadOrchestrator.ts @@ -41,7 +41,7 @@ import { import type { CreateDynamicSubAgentThread } from './CreateDynamicSubAgentThread'; import { addAgentThreadMetrics, createEmptyAgentThreadMetrics, type AgentThreadMetrics } from './metrics'; -const MAX_PARALLEL_SUB_AGENTS = 5; +export const DEFAULT_MAX_PARALLEL_SUB_AGENTS = 10; const CANCELED_BECAUSE_USER_SENT_NEW_MESSAGE = 'Canceled because user sent a new message.'; function getActiveAgentThreads(agentThreads: Map): AgentThread[] { @@ -193,6 +193,7 @@ export async function* wrapWithSubAgentSpan( export interface AgentThreadOrchestratorInput { agentThreads: Map; + maxParallelSubAgents?: number | undefined; createDynamicSubAgentThread: CreateDynamicSubAgentThread; tracing: AgentTracing; logger: Logger; @@ -207,6 +208,7 @@ export interface AgentThreadOrchestratorInput { export class AgentThreadOrchestrator { private readonly agentThreads: Map; + private readonly maxParallelSubAgents: number; private readonly createDynamicSubAgentThread: CreateDynamicSubAgentThread; private readonly tracing: AgentTracing; private readonly logger: Logger; @@ -218,6 +220,10 @@ export class AgentThreadOrchestrator { private readonly mcpServerInitInfoById = new Map(); constructor(params: AgentThreadOrchestratorInput) { + this.maxParallelSubAgents = params.maxParallelSubAgents ?? DEFAULT_MAX_PARALLEL_SUB_AGENTS; + if (!Number.isInteger(this.maxParallelSubAgents) || this.maxParallelSubAgents < 1) { + throw new Error('maxParallelSubAgents must be a positive integer'); + } this.agentThreads = params.agentThreads; this.createDynamicSubAgentThread = params.createDynamicSubAgentThread; this.tracing = params.tracing; @@ -694,8 +700,8 @@ export class AgentThreadOrchestrator { turnPaused = false; } - for (let i = 0; i < runnable.length; i += MAX_PARALLEL_SUB_AGENTS) { - const batch = runnable.slice(i, i + MAX_PARALLEL_SUB_AGENTS); + for (let i = 0; i < runnable.length; i += this.maxParallelSubAgents) { + const batch = runnable.slice(i, i + this.maxParallelSubAgents); const generators = batch.map(thread => thread.parent ? wrapWithSubAgentSpan(rootSpan.trace, thread, signal) diff --git a/packages/trueforge/.env.example b/packages/trueforge/.env.example index 6ab5c3f284..87731cfdf3 100644 --- a/packages/trueforge/.env.example +++ b/packages/trueforge/.env.example @@ -108,6 +108,8 @@ REDIS_URL=redis://localhost:6379 # REDIS_REQUEST_REPLY_POLL_INTERVAL_MS=500 ## Turn execution and resumable stream settings. All optional. +## Max sub-agents running in parallel per turn. Must be a positive integer. Default 10. +# MAX_PARALLEL_SUB_AGENTS=10 ## Max seconds a single turn may run before cancellation. Default 600 (10 minutes). # SERVER_EXECUTION_TIMEOUT_SECONDS=600 ## Max seconds to wait for turn cancellation + connection drain on SIGTERM/SIGINT. Default 30. diff --git a/packages/trueforge/src/apis/turns.ts b/packages/trueforge/src/apis/turns.ts index 55af58ad43..3970356421 100644 --- a/packages/trueforge/src/apis/turns.ts +++ b/packages/trueforge/src/apis/turns.ts @@ -444,6 +444,7 @@ function createTurnResolver(deps: { mcpRequestTimeoutMs: configuration.MCP_REQUEST_TIMEOUT_MS, mcpConnectTimeoutMs: configuration.MCP_CONNECT_TIMEOUT_MS, mcpMaxResponseBytes: configuration.MCP_TOOL_CALL_MAX_RESPONSE_BYTES, + maxParallelSubAgents: configuration.MAX_PARALLEL_SUB_AGENTS, sandboxProvider: async ({ spec, existingSandboxId, tracing }) => { const provider = await resolveSandboxProvider({ tenant_id, diff --git a/packages/trueforge/src/config.ts b/packages/trueforge/src/config.ts index c87283e6fc..18d893a6b3 100644 --- a/packages/trueforge/src/config.ts +++ b/packages/trueforge/src/config.ts @@ -16,6 +16,7 @@ import os from 'node:os'; import path from 'node:path'; import { fileURLToPath } from 'node:url'; +import { DEFAULT_MAX_PARALLEL_SUB_AGENTS } from '@truefoundry/trueforge-core/core'; import envPaths from 'env-paths'; import { z } from 'zod'; @@ -788,6 +789,8 @@ export interface SharedServerConfiguration { * Default 3600 (60 minutes). */ SERVER_EXECUTION_TIMEOUT_SECONDS: number; + /** Max parallel sub-agents per turn. Env: `MAX_PARALLEL_SUB_AGENTS`. Default 10. */ + MAX_PARALLEL_SUB_AGENTS: number; /** * TTL for a running turn's resumable event stream. * Env: `TURN_STREAM_TTL_SECONDS`. Default execution timeout + 300. @@ -1227,6 +1230,11 @@ const shared: SharedServerConfiguration = { defaultValue: 30, }), SERVER_EXECUTION_TIMEOUT_SECONDS: serverExecutionTimeoutSeconds, + MAX_PARALLEL_SUB_AGENTS: parsePositiveInt({ + envKey: 'MAX_PARALLEL_SUB_AGENTS', + raw: getEnv('MAX_PARALLEL_SUB_AGENTS'), + defaultValue: DEFAULT_MAX_PARALLEL_SUB_AGENTS, + }), TURN_STREAM_TTL_SECONDS: parsePositiveInt({ envKey: 'TURN_STREAM_TTL_SECONDS', raw: getEnv('TURN_STREAM_TTL_SECONDS'), From 50024a6a5ddfc919e64e83c18d7b0c248d9b5e97 Mon Sep 17 00:00:00 2001 From: Sujai Kumar Gupta <120925871+thesujai@users.noreply.github.com> Date: Thu, 12 Nov 2026 13:57:05 +0000 Subject: [PATCH 2/3] refactor: keep sub-agent limit validation in server config Co-authored-by: TrueForge Agent --- .../trueforge-core/src/core/runtime/AgentThreadOrchestrator.ts | 3 --- 1 file changed, 3 deletions(-) diff --git a/packages/trueforge-core/src/core/runtime/AgentThreadOrchestrator.ts b/packages/trueforge-core/src/core/runtime/AgentThreadOrchestrator.ts index 601cbefb28..04c4f13b7c 100644 --- a/packages/trueforge-core/src/core/runtime/AgentThreadOrchestrator.ts +++ b/packages/trueforge-core/src/core/runtime/AgentThreadOrchestrator.ts @@ -221,9 +221,6 @@ export class AgentThreadOrchestrator { constructor(params: AgentThreadOrchestratorInput) { this.maxParallelSubAgents = params.maxParallelSubAgents ?? DEFAULT_MAX_PARALLEL_SUB_AGENTS; - if (!Number.isInteger(this.maxParallelSubAgents) || this.maxParallelSubAgents < 1) { - throw new Error('maxParallelSubAgents must be a positive integer'); - } this.agentThreads = params.agentThreads; this.createDynamicSubAgentThread = params.createDynamicSubAgentThread; this.tracing = params.tracing; From 896dfb5d568d81aeb5a5d32027366194021d53d5 Mon Sep 17 00:00:00 2001 From: Sujai Kumar Gupta <120925871+thesujai@users.noreply.github.com> Date: Fri, 13 Nov 2026 04:47:58 +0000 Subject: [PATCH 3/3] refactor: use optional-only sub-agent limit properties Omit unset limits when forwarding to preserve exact optional property semantics. Co-authored-by: TrueForge Agent --- .../src/agent-session/ITurnResourceResolver.ts | 2 +- .../src/agent-session/SessionHandle.ts | 3 ++- .../src/agent-session/TurnResourceResolver.ts | 13 +++++++------ .../src/core/runtime/AgentThreadOrchestrator.ts | 2 +- 4 files changed, 11 insertions(+), 9 deletions(-) diff --git a/packages/trueforge-core/src/agent-session/ITurnResourceResolver.ts b/packages/trueforge-core/src/agent-session/ITurnResourceResolver.ts index e7b86e5fff..63d5d56c27 100644 --- a/packages/trueforge-core/src/agent-session/ITurnResourceResolver.ts +++ b/packages/trueforge-core/src/agent-session/ITurnResourceResolver.ts @@ -20,7 +20,7 @@ export interface ResolvedAgentDefinition { */ export interface ITurnResourceResolver> { /** Maximum sub-agent threads executed in parallel per turn. Defaults to 10. */ - readonly maxParallelSubAgents?: number | undefined; + readonly maxParallelSubAgents?: number; /** * Host web-search backend. When set and `config.web_search.enabled`, builtins * register search/fetch system tools. Omit when the host has no provider configured. diff --git a/packages/trueforge-core/src/agent-session/SessionHandle.ts b/packages/trueforge-core/src/agent-session/SessionHandle.ts index faa7748ab5..e709a58460 100644 --- a/packages/trueforge-core/src/agent-session/SessionHandle.ts +++ b/packages/trueforge-core/src/agent-session/SessionHandle.ts @@ -479,9 +479,10 @@ export class SessionHandle< }); const previousMcpServers = input.previous?.snapshot.mcp_servers; + const maxParallelSubAgents = input.resolver.maxParallelSubAgents; const orchestrator = new AgentThreadOrchestrator({ agentThreads, - maxParallelSubAgents: input.resolver.maxParallelSubAgents, + ...(maxParallelSubAgents !== undefined ? { maxParallelSubAgents } : {}), createDynamicSubAgentThread, tracing, logger: input.resolver.logger, diff --git a/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts b/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts index 95eed4c17b..3e3a6d4696 100644 --- a/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts +++ b/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts @@ -83,6 +83,7 @@ export class TurnResourceResolver< readonly #sources = new Map>(); readonly #models = new Map>(); #sandbox?: HarnessSandbox | undefined; + readonly maxParallelSubAgents?: number; constructor( protected readonly deps: { @@ -97,7 +98,7 @@ export class TurnResourceResolver< mcpRequestTimeoutMs: number; mcpConnectTimeoutMs: number; mcpMaxResponseBytes?: number | undefined; - maxParallelSubAgents?: number | undefined; + maxParallelSubAgents?: number; /** One sandbox type per runtime. Omit = no sandbox support. */ sandboxProvider?: TurnSandboxFactory | undefined; /** @@ -116,16 +117,16 @@ export class TurnResourceResolver< /** Forwarded to RemoteMCP / AgentThread (required by their constructors). */ logger: Logger; }, - ) {} + ) { + if (deps.maxParallelSubAgents !== undefined) { + this.maxParallelSubAgents = deps.maxParallelSubAgents; + } + } get webSearchProvider(): IWebSearchProvider | undefined { return this.deps.webSearchProvider; } - get maxParallelSubAgents(): number | undefined { - return this.deps.maxParallelSubAgents; - } - get logger(): Logger { return this.deps.logger; } diff --git a/packages/trueforge-core/src/core/runtime/AgentThreadOrchestrator.ts b/packages/trueforge-core/src/core/runtime/AgentThreadOrchestrator.ts index 04c4f13b7c..af34001d24 100644 --- a/packages/trueforge-core/src/core/runtime/AgentThreadOrchestrator.ts +++ b/packages/trueforge-core/src/core/runtime/AgentThreadOrchestrator.ts @@ -193,7 +193,7 @@ export async function* wrapWithSubAgentSpan( export interface AgentThreadOrchestratorInput { agentThreads: Map; - maxParallelSubAgents?: number | undefined; + maxParallelSubAgents?: number; createDynamicSubAgentThread: CreateDynamicSubAgentThread; tracing: AgentTracing; logger: Logger;