Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): workflow - move maxSubagents into tool config (#751)

Andrew Barba1f85922d4717
diff --git a/.changeset/tidy-workflow-config.md b/.changeset/tidy-workflow-config.md
new file mode 100644
index 000000000..6cc02679e
--- /dev/null
+++ b/.changeset/tidy-workflow-config.md
@@ -0,0 +1,5 @@
+---
+"eve": minor
+---
+
+Replace the `ExperimentalWorkflow` marker with `experimental_workflow(options)` and move the per-program `maxSubagents` setting from `defineAgent({ limits })` to that Workflow tool definition.
diff --git a/docs/agent-config.md b/docs/agent-config.md
index 604e20473..8fcb33e47 100644
--- a/docs/agent-config.md
+++ b/docs/agent-config.md
@@ -203,14 +203,14 @@ installed package must stay external in hosted output, list it in
`defineAgent` takes a few more fields, all optional. For the exported types, see the [TypeScript API](./reference/typescript-api).
-| Field | Type | Default | Description |
-| -------------- | --------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `reasoning` | `AgentReasoningDefinition` | provider default | Provider-agnostic reasoning effort forwarded to the agent's turn model calls. |
-| `modelOptions` | `AgentModelOptionsDefinition` | none | Provider option overrides forwarded to the model call. |
-| `limits` | `AgentLimitsDefinition` | field-specific | Framework-owned runtime limits. `maxInputTokensPerSession` defaults to `40_000_000` for root sessions, and delegated subagent sessions inherit the parent's remaining quota; `maxOutputTokensPerSession` is unset unless configured; `false` uncaps a session token limit. `maxSubagents` limits calls made by one `Workflow` invocation. |
-| `experimental` | `{ workflow?: { world?: string } }` | unset | Opt-in settings that can change or disappear in any release. Treat them as unstable. `workflow.world` selects the Workflow world package backing session state, queues, hooks, and streams on the root agent. |
-| `outputSchema` | Standard Schema or a JSON Schema object | none | Structured return type for task-mode runs (a subagent, schedule, or remote job). Interactive conversation turns ignore it unless the client supplies a per-message schema. |
-| `build` | `{ externalDependencies?: string[] }` | none | Hosted-build packaging controls. `externalDependencies` keeps listed packages external while eve compiles authored modules such as tools and channels, and traces those packages into the hosted output. |
+| Field | Type | Default | Description |
+| -------------- | --------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `reasoning` | `AgentReasoningDefinition` | provider default | Provider-agnostic reasoning effort forwarded to the agent's turn model calls. |
+| `modelOptions` | `AgentModelOptionsDefinition` | none | Provider option overrides forwarded to the model call. |
+| `limits` | `AgentLimitsDefinition` | field-specific | Framework-owned runtime limits. `maxInputTokensPerSession` defaults to `40_000_000` for root sessions, and delegated subagent sessions inherit the parent's remaining quota; `maxOutputTokensPerSession` is unset unless configured; `false` uncaps a session token limit. |
+| `experimental` | `{ workflow?: { world?: string } }` | unset | Opt-in settings that can change or disappear in any release. Treat them as unstable. `workflow.world` selects the Workflow world package backing session state, queues, hooks, and streams on the root agent. |
+| `outputSchema` | Standard Schema or a JSON Schema object | none | Structured return type for task-mode runs (a subagent, schedule, or remote job). Interactive conversation turns ignore it unless the client supplies a per-message schema. |
+| `build` | `{ externalDependencies?: string[] }` | none | Hosted-build packaging controls. `externalDependencies` keeps listed packages external while eve compiles authored modules such as tools and channels, and traces those packages into the hosted output. |
`externalDependencies` is a packaging control only. It keeps selected packages as runtime dependencies in the hosted output; it does not authorize, configure, or review any third-party service those packages may call.
diff --git a/docs/concepts/default-harness.md b/docs/concepts/default-harness.md
index 8963e3145..8d519fac7 100644
--- a/docs/concepts/default-harness.md
+++ b/docs/concepts/default-harness.md
@@ -91,13 +91,15 @@ Three moves shape the harness. The right one depends on whether the model should
## The opt-in `Workflow` tool
-An experimental `Workflow` tool ships but stays off by default. To turn it on, re-export the opt-in marker from `agent/tools/workflow.ts`:
+An experimental `Workflow` tool ships but stays off by default. To turn it on, export its definition from `agent/tools/workflow.ts`:
```ts
-export { ExperimentalWorkflow as default } from "eve/tools";
+import { experimental_workflow } from "eve/tools";
+
+export default experimental_workflow({ maxSubagents: 100 });
```
-With it on, the model can orchestrate the agent's own subagents from model-authored JavaScript, all as one durable step. The tool is root-only — delegated subagent sessions never see it — and one program may dispatch at most `limits.maxSubagents` subagent calls (default 100). See [Dynamic workflows](../guides/dynamic-workflows).
+With it on, the model can orchestrate the agent's own subagents from model-authored JavaScript, all as one durable step. The tool is root-only — delegated subagent sessions never see it — and one program may dispatch at most the configured `maxSubagents` calls (default 100). See [Dynamic workflows](../guides/dynamic-workflows).
## What to read next
diff --git a/docs/guides/dynamic-workflows.md b/docs/guides/dynamic-workflows.md
index 19b340577..5207c9134 100644
--- a/docs/guides/dynamic-workflows.md
+++ b/docs/guides/dynamic-workflows.md
@@ -9,10 +9,12 @@ A single turn can already call several subagents, and parallel tool calls dispat
## Enable the Workflow tool
-Re-export the opt-in marker as the default export of `agent/tools/workflow.ts`. The marker name carries the "experimental" warning, but the tool the model actually sees is named `Workflow`.
+Export the experimental Workflow definition from `agent/tools/workflow.ts`. The helper name carries the "experimental" warning, but the tool the model actually sees is named `Workflow`.
```ts title="agent/tools/workflow.ts"
-export { ExperimentalWorkflow as default } from "eve/tools";
+import { experimental_workflow } from "eve/tools";
+
+export default experimental_workflow();
```
Without that file, the `Workflow` tool stays off. It earns its keep only when the agent has subagents (or the built-in `agent`) worth coordinating:
@@ -55,15 +57,12 @@ A workflow reaches only this agent's own agents: the built-in `agent` (a copy of
Workflow orchestration is capped in two independent ways.
-**Per-program call budget.** One Workflow program may dispatch at most `limits.maxSubagents` subagent calls in total, counted across the whole program — sequential and parallel calls alike. The default is 100. Calls beyond the budget do not start a child session; they resolve inside the program with a `WORKFLOW_SUBAGENT_LIMIT_REACHED` error result, and the budget is stated in the tool's description so the model sizes its fan-out to fit.
+**Per-program call budget.** One Workflow program may dispatch at most `maxSubagents` subagent calls in total, counted across the whole program — sequential and parallel calls alike. Configure it on `experimental_workflow`; the default is 100. Calls beyond the budget do not start a child session; they resolve inside the program with a `WORKFLOW_SUBAGENT_LIMIT_REACHED` error result, and the budget is stated in the tool's description so the model sizes its fan-out to fit.
-```ts title="agent/agent.ts"
-export default defineAgent({
- model: "anthropic/claude-sonnet-5",
- limits: {
- maxSubagents: 4,
- },
-});
+```ts title="agent/tools/workflow.ts"
+import { experimental_workflow } from "eve/tools";
+
+export default experimental_workflow({ maxSubagents: 4 });
```
**Root-only orchestration.** Only the root session receives `Workflow`. Children started by a workflow receive neither `Workflow` nor the built-in `agent`, so Workflow programs cannot recurse. A declared child can still call subagents defined in its own directory (see [Subagents](../subagents)).
diff --git a/docs/reference/typescript-api.md b/docs/reference/typescript-api.md
index 665482501..95b3c40e6 100644
--- a/docs/reference/typescript-api.md
+++ b/docs/reference/typescript-api.md
@@ -52,7 +52,7 @@ export default defineTool({
| `mockModel` | `eve/evals` | Deterministic fixture agent models | [Evals](../evals/overview) |
| `useEveAgent` | `eve/react`, `eve/vue`, `eve/svelte` | frontend | [Frontend](../guides/frontend/overview) |
-A few non-`define*` helpers round out the set: `disableTool` and `ExperimentalWorkflow` from `eve/tools` (see [Default harness](../concepts/default-harness)), the route verbs `GET`/`POST`/`PUT`/`PATCH`/`DELETE`/`WS` from `eve/channels`, the approval policies `always`/`once`/`never` from `eve/tools/approval`, and the channel auth helpers `localDev`/`vercelOidc`/`placeholderAuth` from `eve/channels/auth`. To wrap a built-in tool, import its default value from `eve/tools/defaults` (`bash`, `readFile`, `writeFile`, `glob`, `grep`, `webFetch`, `webSearch`, `todo`, `loadSkill`). `AgentReasoningDefinition` is exported from `eve` for the top-level `defineAgent({ reasoning })` setting. `AgentLimitsDefinition` is exported for `defineAgent({ limits })`. `AgentWorkflowDefinition` and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape.
+A few non-`define*` helpers round out the set: `disableTool` and `experimental_workflow` from `eve/tools` (see [Default harness](../concepts/default-harness)), the route verbs `GET`/`POST`/`PUT`/`PATCH`/`DELETE`/`WS` from `eve/channels`, the approval policies `always`/`once`/`never` from `eve/tools/approval`, and the channel auth helpers `localDev`/`vercelOidc`/`placeholderAuth` from `eve/channels/auth`. To wrap a built-in tool, import its default value from `eve/tools/defaults` (`bash`, `readFile`, `writeFile`, `glob`, `grep`, `webFetch`, `webSearch`, `todo`, `loadSkill`). `AgentReasoningDefinition` is exported from `eve` for the top-level `defineAgent({ reasoning })` setting. `AgentLimitsDefinition` is exported for `defineAgent({ limits })`. `AgentWorkflowDefinition` and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape. `ExperimentalWorkflowToolInput` is exported from `eve/tools` for the `experimental_workflow(...)` config shape.
## Runtime context (`ctx`)
@@ -68,32 +68,32 @@ A few non-`define*` helpers round out the set: `disableTool` and `ExperimentalWo
## Imports at a glance
-| Import | Holds |
-| ----------------------------------------------------------- | -------------------------------------------------------------------- |
-| `eve` | `defineAgent`, `defineRemoteAgent`, agent config types |
-| `eve/tools` | `defineTool`, `defineDynamic`, `disableTool`, `ExperimentalWorkflow` |
-| `eve/tools/defaults` | the built-in tools as plain values |
-| `eve/tools/approval` | `always`, `once`, `never` |
-| `eve/connections` | `defineMcpClientConnection`, `defineOpenAPIConnection` |
-| `eve/channels` | `defineChannel`, route verbs |
-| `eve/channels/eve` | `eveChannel` |
-| `eve/channels/auth` | `localDev`, `vercelOidc`, `placeholderAuth` |
-| `eve/channels/{slack,discord,teams,telegram,twilio,github}` | platform channel factories |
-| `eve/hooks` | `defineHook` |
-| `eve/schedules` | `defineSchedule` |
-| `eve/skills` | `defineSkill`, `defineDynamic` |
-| `eve/instructions` | `defineInstructions`, `defineDynamic` |
-| `eve/context` | `defineState`, session and state types |
-| `eve/sandbox` | `defineSandbox`, backends |
-| `eve/instrumentation` | `defineInstrumentation`, `isChannel` |
-| `eve/models/openai` | `experimental_chatgpt` |
-| `eve/evals` | `defineEval`, `defineEvalConfig`, `mockModel`, eval types |
-| `eve/evals/expect` | `includes`, `equals`, `matches`, `similarity` |
-| `eve/evals/reporters` | `Braintrust`, `JUnit`, `EvalReporter` |
-| `eve/evals/loaders` | `loadJson`, `loadYaml` |
-| `eve/react`, `eve/vue`, `eve/svelte` | `useEveAgent` |
-| `eve/next`, `eve/nuxt`, `eve/sveltekit` | framework bundler plugins |
-| [`eve/client`](../guides/client/overview) | `Client`, `ClientSession` |
+| Import | Holds |
+| ----------------------------------------------------------- | --------------------------------------------------------------------- |
+| `eve` | `defineAgent`, `defineRemoteAgent`, agent config types |
+| `eve/tools` | `defineTool`, `defineDynamic`, `disableTool`, `experimental_workflow` |
+| `eve/tools/defaults` | the built-in tools as plain values |
+| `eve/tools/approval` | `always`, `once`, `never` |
+| `eve/connections` | `defineMcpClientConnection`, `defineOpenAPIConnection` |
+| `eve/channels` | `defineChannel`, route verbs |
+| `eve/channels/eve` | `eveChannel` |
+| `eve/channels/auth` | `localDev`, `vercelOidc`, `placeholderAuth` |
+| `eve/channels/{slack,discord,teams,telegram,twilio,github}` | platform channel factories |
+| `eve/hooks` | `defineHook` |
+| `eve/schedules` | `defineSchedule` |
+| `eve/skills` | `defineSkill`, `defineDynamic` |
+| `eve/instructions` | `defineInstructions`, `defineDynamic` |
+| `eve/context` | `defineState`, session and state types |
+| `eve/sandbox` | `defineSandbox`, backends |
+| `eve/instrumentation` | `defineInstrumentation`, `isChannel` |
+| `eve/models/openai` | `experimental_chatgpt` |
+| `eve/evals` | `defineEval`, `defineEvalConfig`, `mockModel`, eval types |
+| `eve/evals/expect` | `includes`, `equals`, `matches`, `similarity` |
+| `eve/evals/reporters` | `Braintrust`, `JUnit`, `EvalReporter` |
+| `eve/evals/loaders` | `loadJson`, `loadYaml` |
+| `eve/react`, `eve/vue`, `eve/svelte` | `useEveAgent` |
+| `eve/next`, `eve/nuxt`, `eve/sveltekit` | framework bundler plugins |
+| [`eve/client`](../guides/client/overview) | `Client`, `ClientSession` |
Exported types ship from the same entrypoint as the helper they describe (for example `ToolDefinition` and `ToolContext` from `eve/tools`). For the exhaustive list, read `packages/eve/src/public/index.ts`.
diff --git a/docs/subagents.mdx b/docs/subagents.mdx
index d10846d47..0c1b8b7f3 100644
--- a/docs/subagents.mdx
+++ b/docs/subagents.mdx
@@ -81,7 +81,7 @@ eve lowers every subagent visible to the current agent (the root built-in copy,
Declared subagents can call nested subagents defined under their own directories. eve does not apply a separate depth limit; nesting ends where the authored directory tree ends. The built-in `agent` follows the stricter root-only rule above, so `limits.maxSubagentDepth` no longer exists.
-`Workflow` is also root-only. Child sessions can still call their own declared or remote subagents, but they receive neither `Workflow` nor the built-in `agent`. `limits.maxSubagents` separately caps the number of calls made by one Workflow program (default 100); see [Dynamic workflows](./guides/dynamic-workflows).
+`Workflow` is also root-only. Child sessions can still call their own declared or remote subagents, but they receive neither `Workflow` nor the built-in `agent`. The Workflow tool's `maxSubagents` option caps the number of calls made by one program (default 100); see [Dynamic workflows](./guides/dynamic-workflows).
A declared subagent's tool name is the bare path-derived name, with no prefix. `agent/subagents/researcher/` registers as the tool `researcher`. Unlike connection tools (`<connection>__<tool>`), it carries no namespace, so the model, approvals, logs, and evals all reference it by that name. Its input schema is:
diff --git a/e2e/fixtures/agent-subagents/agent/agent.ts b/e2e/fixtures/agent-subagents/agent/agent.ts
index 818ff546f..dc6d957f5 100644
--- a/e2e/fixtures/agent-subagents/agent/agent.ts
+++ b/e2e/fixtures/agent-subagents/agent/agent.ts
@@ -1,9 +1,6 @@
import { defineAgent } from "eve";
export default defineAgent({
- limits: {
- maxSubagents: 2,
- },
model: "anthropic/claude-sonnet-5",
reasoning: "high",
});
diff --git a/e2e/fixtures/agent-subagents/agent/tools/workflow.ts b/e2e/fixtures/agent-subagents/agent/tools/workflow.ts
index 783084219..d6af27e60 100644
--- a/e2e/fixtures/agent-subagents/agent/tools/workflow.ts
+++ b/e2e/fixtures/agent-subagents/agent/tools/workflow.ts
@@ -1 +1,3 @@
-export { ExperimentalWorkflow as default } from "eve/tools";
+import { experimental_workflow } from "eve/tools";
+
+export default experimental_workflow({ maxSubagents: 2 });
diff --git a/e2e/fixtures/agent-subagents/evals/workflow-subagent-limit.eval.ts b/e2e/fixtures/agent-subagents/evals/workflow-subagent-limit.eval.ts
index 3dee5f5d8..1689f1332 100644
--- a/e2e/fixtures/agent-subagents/evals/workflow-subagent-limit.eval.ts
+++ b/e2e/fixtures/agent-subagents/evals/workflow-subagent-limit.eval.ts
@@ -1,13 +1,13 @@
import { defineEval } from "eve/evals";
/**
- * Workflow subagent budget: the fixture caps `limits.maxSubagents` at 2, so a
- * three-call fan-out spawns two children and the third call resolves inside
- * the program with a `WORKFLOW_SUBAGENT_LIMIT_REACHED` error result.
+ * Workflow subagent budget: the fixture configures `maxSubagents` as 2 on the
+ * Workflow tool, so a three-call fan-out spawns two children and the third call
+ * resolves inside the program with a `WORKFLOW_SUBAGENT_LIMIT_REACHED` error.
*/
export default defineEval({
description:
- "Workflow calls beyond limits.maxSubagents resolve with WORKFLOW_SUBAGENT_LIMIT_REACHED instead of spawning children.",
+ "Workflow calls beyond the tool's maxSubagents config resolve with WORKFLOW_SUBAGENT_LIMIT_REACHED instead of spawning children.",
async test(t) {
await t.send(
[
diff --git a/packages/eve/src/channel/types.ts b/packages/eve/src/channel/types.ts
index 0bc76620a..ca1edb54a 100644
--- a/packages/eve/src/channel/types.ts
+++ b/packages/eve/src/channel/types.ts
@@ -15,7 +15,7 @@ import type { ChannelInstrumentationProjection } from "#channel/instrumentation.
export type RunSessionLimits = Pick<
AgentLimitsDefinition,
- "maxInputTokensPerSession" | "maxOutputTokensPerSession" | "maxSubagents"
+ "maxInputTokensPerSession" | "maxOutputTokensPerSession"
>;
// ---------------------------------------------------------------------------
diff --git a/packages/eve/src/compiler/manifest.test.ts b/packages/eve/src/compiler/manifest.test.ts
index 8dae3d23a..ae84c877e 100644
--- a/packages/eve/src/compiler/manifest.test.ts
+++ b/packages/eve/src/compiler/manifest.test.ts
@@ -60,6 +60,40 @@ describe("compiledAgentManifestSchema", () => {
).toThrow();
});
+ it("rejects the removed agent-level maxSubagents limit", () => {
+ const manifest = createCompiledAgentManifest({
+ agentRoot: "/app/agent",
+ appRoot: "/app",
+ config: {
+ model: { id: "openai/gpt-5.5", routing: classifyModelRouting("openai/gpt-5.5") },
+ name: "app",
+ },
+ });
+
+ expect(() =>
+ compiledAgentManifestSchema.parse({
+ ...manifest,
+ config: { ...manifest.config, limits: { maxSubagents: 4 } },
+ }),
+ ).toThrow();
+ });
+
+ it("preserves experimental Workflow tool configuration", () => {
+ const manifest = createCompiledAgentManifest({
+ agentRoot: "/app/agent",
+ appRoot: "/app",
+ config: {
+ model: { id: "openai/gpt-5.5", routing: classifyModelRouting("openai/gpt-5.5") },
+ name: "app",
+ },
+ workflowTool: { maxSubagents: 6 },
+ });
+
+ const parsed = compiledAgentManifestSchema.parse(manifest);
+
+ expect(parsed.workflowTool).toEqual({ maxSubagents: 6 });
+ });
+
it("preserves dynamic model resolver source", () => {
const manifest = createCompiledAgentManifest({
agentRoot: "/app/agent",
diff --git a/packages/eve/src/compiler/manifest.ts b/packages/eve/src/compiler/manifest.ts
index 252a1ac2a..461f3ac76 100644
--- a/packages/eve/src/compiler/manifest.ts
+++ b/packages/eve/src/compiler/manifest.ts
@@ -41,7 +41,7 @@ export const ROOT_COMPILED_AGENT_NODE_ID = "__root__";
/**
* Current compiled manifest schema version.
*/
-export const COMPILED_AGENT_MANIFEST_VERSION = 35;
+export const COMPILED_AGENT_MANIFEST_VERSION = 36;
/**
* Compiled channel entry preserved in the compiled manifest.
@@ -177,6 +177,13 @@ export type CompiledConnectionDefinition = z.infer<typeof compiledConnectionDefi
*/
export type CompiledToolDefinition = InternalToolDefinition & ModuleSourceRef;
+/**
+ * Serializable configuration for the experimental framework `Workflow` tool.
+ */
+export interface CompiledWorkflowToolDefinition {
+ readonly maxSubagents?: number;
+}
+
/**
* Compiled dynamic tool resolver entry. The resolver function lives in the
* compiled module map; the manifest entry carries only the metadata needed
@@ -394,12 +401,17 @@ const sessionTokenLimitSchema = z.union([z.number().int().positive(), z.literal(
const compiledAgentLimitsDefinitionSchema = z
.object({
- maxSubagents: z.number().int().positive().optional(),
maxInputTokensPerSession: sessionTokenLimitSchema.optional(),
maxOutputTokensPerSession: sessionTokenLimitSchema.optional(),
})
.strict();
+const compiledWorkflowToolDefinitionSchema: z.ZodType<CompiledWorkflowToolDefinition> = z
+ .object({
+ maxSubagents: z.number().int().positive().optional(),
+ })
+ .strict();
+
const compiledAgentConfigSchema: z.ZodType<CompiledAgentDefinition> = z
.object({
build: compiledAgentBuildDefinitionSchema.optional(),
@@ -631,7 +643,7 @@ const compiledAgentNodeManifestSchema = z
connections: z.array(compiledConnectionDefinitionSchema),
diagnosticsSummary: discoverDiagnosticsSummarySchema,
disabledFrameworkTools: z.array(z.string()).readonly(),
- workflowEnabled: z.boolean().default(false),
+ workflowTool: compiledWorkflowToolDefinitionSchema.optional(),
dynamicInstructions: z.array(compiledDynamicInstructionsDefinitionSchema).default([]),
dynamicSkills: z.array(compiledDynamicSkillDefinitionSchema).default([]),
dynamicTools: z.array(compiledDynamicToolDefinitionSchema).default([]),
@@ -718,7 +730,7 @@ export const compiledAgentManifestSchema = z
connections: z.array(compiledConnectionDefinitionSchema),
diagnosticsSummary: discoverDiagnosticsSummarySchema,
disabledFrameworkTools: z.array(z.string()).readonly(),
- workflowEnabled: z.boolean().default(false),
+ workflowTool: compiledWorkflowToolDefinitionSchema.optional(),
dynamicInstructions: z.array(compiledDynamicInstructionsDefinitionSchema).default([]),
dynamicSkills: z.array(compiledDynamicSkillDefinitionSchema).default([]),
dynamicTools: z.array(compiledDynamicToolDefinitionSchema).default([]),
@@ -749,7 +761,7 @@ export function createCompiledAgentNodeManifest(input: {
readonly connections?: readonly CompiledConnectionDefinition[];
readonly diagnosticsSummary?: DiscoverDiagnosticsSummary;
readonly disabledFrameworkTools?: readonly string[];
- readonly workflowEnabled?: boolean;
+ readonly workflowTool?: CompiledWorkflowToolDefinition;
readonly dynamicInstructions?: readonly CompiledDynamicInstructionsDefinition[];
readonly dynamicSkills?: readonly CompiledDynamicSkillDefinition[];
readonly dynamicTools?: readonly CompiledDynamicToolDefinition[];
@@ -813,7 +825,6 @@ export function createCompiledAgentNodeManifest(input: {
: {
maxInputTokensPerSession: input.config.limits.maxInputTokensPerSession,
maxOutputTokensPerSession: input.config.limits.maxOutputTokensPerSession,
- maxSubagents: input.config.limits.maxSubagents,
},
source:
input.config.source === undefined
@@ -827,7 +838,10 @@ export function createCompiledAgentNodeManifest(input: {
warnings: 0,
},
disabledFrameworkTools: [...(input.disabledFrameworkTools ?? [])],
- workflowEnabled: input.workflowEnabled ?? false,
+ workflowTool:
+ input.workflowTool === undefined
+ ? undefined
+ : { maxSubagents: input.workflowTool.maxSubagents },
dynamicInstructions: [...(input.dynamicInstructions ?? [])],
dynamicSkills: [...(input.dynamicSkills ?? [])],
dynamicTools: [...(input.dynamicTools ?? [])],
@@ -900,7 +914,7 @@ export function createCompiledAgentManifest(input: {
readonly connections?: readonly CompiledConnectionDefinition[];
readonly diagnosticsSummary?: DiscoverDiagnosticsSummary;
readonly disabledFrameworkTools?: readonly string[];
- readonly workflowEnabled?: boolean;
+ readonly workflowTool?: CompiledWorkflowToolDefinition;
readonly dynamicSkills?: readonly CompiledDynamicSkillDefinition[];
readonly dynamicTools?: readonly CompiledDynamicToolDefinition[];
readonly hooks?: readonly CompiledHookDefinition[];
diff --git a/packages/eve/src/compiler/module-map.test.ts b/packages/eve/src/compiler/module-map.test.ts
index f14273aae..82d8b6b56 100644
--- a/packages/eve/src/compiler/module-map.test.ts
+++ b/packages/eve/src/compiler/module-map.test.ts
@@ -24,7 +24,6 @@ function createManifestWithTool(agentRoot: string): CompiledAgentManifest {
},
extensionMounts: [],
disabledFrameworkTools: [],
- workflowEnabled: false,
dynamicInstructions: [],
dynamicSkills: [],
dynamicTools: [],
diff --git a/packages/eve/src/compiler/normalize-agent-config.ts b/packages/eve/src/compiler/normalize-agent-config.ts
index e7e092179..757cb48ae 100644
--- a/packages/eve/src/compiler/normalize-agent-config.ts
+++ b/packages/eve/src/compiler/normalize-agent-config.ts
@@ -127,7 +127,6 @@ export async function compileAgentConfig(
if (definition.limits !== undefined) {
compiledConfig.limits = {
- maxSubagents: definition.limits.maxSubagents,
maxInputTokensPerSession: definition.limits.maxInputTokensPerSession,
maxOutputTokensPerSession: definition.limits.maxOutputTokensPerSession,
};
diff --git a/packages/eve/src/compiler/normalize-extension.ts b/packages/eve/src/compiler/normalize-extension.ts
index fe0124855..d42a981cf 100644
--- a/packages/eve/src/compiler/normalize-extension.ts
+++ b/packages/eve/src/compiler/normalize-extension.ts
@@ -191,7 +191,7 @@ async function composeManifestContributions(input: {
sourceId: scopeSourceId(entry.definition.sourceId),
logicalPath: rebase(entry.definition.logicalPath),
});
- } else if (entry.kind === "enable-workflow") {
+ } else if (entry.kind === "workflow-tool") {
throw new Error(
`${describeExtensionSource(role, namespace, source.logicalPath)} enables the Workflow tool, ` +
`but the Workflow tool is the consuming agent's to enable, not an extension's. Remove it.`,
diff --git a/packages/eve/src/compiler/normalize-manifest.test.ts b/packages/eve/src/compiler/normalize-manifest.test.ts
index 38cc0b3a9..aa2586e92 100644
--- a/packages/eve/src/compiler/normalize-manifest.test.ts
+++ b/packages/eve/src/compiler/normalize-manifest.test.ts
@@ -9,6 +9,7 @@ import {
import { classifyModelRouting } from "#internal/classify-model-routing.js";
import type { CompiledAgentDefinition } from "#compiler/manifest.js";
import { compileAgentManifest } from "#compiler/normalize-manifest.js";
+import { experimental_workflow } from "#public/definitions/tool.js";
const mocks = vi.hoisted(() => ({
compileAgentConfig: vi.fn(),
@@ -77,6 +78,21 @@ describe("compileAgentManifest", () => {
'Remove "experimental.workflow" from "research"',
);
});
+
+ it("compiles experimental Workflow tool configuration", async () => {
+ const manifest = createAgentSourceManifest({
+ agentId: "root",
+ agentRoot: "/app/agent",
+ appRoot: "/app",
+ tools: [createModuleSourceRef({ logicalPath: "tools/workflow.ts" })],
+ });
+ mocks.compileAgentConfig.mockResolvedValue(createConfig({ name: "root" }));
+ mocks.loadModuleBackedDefinition.mockResolvedValue(experimental_workflow({ maxSubagents: 6 }));
+
+ const compiled = await compileAgentManifest(manifest);
+
+ expect(compiled.workflowTool).toEqual({ maxSubagents: 6 });
+ });
});
function createConfig(
diff --git a/packages/eve/src/compiler/normalize-manifest.ts b/packages/eve/src/compiler/normalize-manifest.ts
index f1268f418..80adefce7 100644
--- a/packages/eve/src/compiler/normalize-manifest.ts
+++ b/packages/eve/src/compiler/normalize-manifest.ts
@@ -10,6 +10,7 @@ import {
type CompiledInstructionsDefinition,
type CompiledSkillDefinition,
type CompiledToolDefinition,
+ type CompiledWorkflowToolDefinition,
createCompiledAgentManifest,
createCompiledAgentNodeManifest,
ROOT_COMPILED_AGENT_NODE_ID,
@@ -106,15 +107,15 @@ async function compileAgentNodeManifest(
const tools: CompiledToolDefinition[] = [];
const dynamicTools: CompiledDynamicToolDefinition[] = [];
const disabledFrameworkTools: string[] = [];
- let workflowEnabled = false;
+ let workflowTool: CompiledWorkflowToolDefinition | undefined;
for (const entry of compiledToolEntries) {
if (entry.kind === "tool") {
tools.push(entry.definition);
} else if (entry.kind === "dynamic-tool") {
dynamicTools.push(entry.definition);
- } else if (entry.kind === "enable-workflow") {
- workflowEnabled = true;
+ } else if (entry.kind === "workflow-tool") {
+ workflowTool = { maxSubagents: entry.maxSubagents };
} else {
disabledFrameworkTools.push(entry.name);
}
@@ -246,7 +247,7 @@ async function compileAgentNodeManifest(
connections,
diagnosticsSummary: manifest.diagnosticsSummary,
disabledFrameworkTools,
- workflowEnabled,
+ workflowTool,
dynamicSkills,
dynamicTools,
hooks,
diff --git a/packages/eve/src/compiler/normalize-tool.ts b/packages/eve/src/compiler/normalize-tool.ts
index bdc09dc6f..82490366e 100644
--- a/packages/eve/src/compiler/normalize-tool.ts
+++ b/packages/eve/src/compiler/normalize-tool.ts
@@ -17,7 +17,7 @@ import {
export type CompiledToolEntry =
| { readonly kind: "tool"; readonly definition: CompiledToolDefinition }
| { readonly kind: "disabled"; readonly name: string }
- | { readonly kind: "enable-workflow" }
+ | { readonly kind: "workflow-tool"; readonly maxSubagents?: number }
| { readonly kind: "dynamic-tool"; readonly definition: CompiledDynamicToolDefinition };
/**
@@ -54,8 +54,8 @@ export async function compileToolEntry(
return { kind: "disabled", name: toolName };
}
- if (entry.kind === "enable-workflow") {
- return { kind: "enable-workflow" };
+ if (entry.kind === "workflow-tool") {
+ return { kind: "workflow-tool", maxSubagents: entry.maxSubagents };
}
if (entry.kind === "dynamic-tool") {
diff --git a/packages/eve/src/execution/create-session-step.test.ts b/packages/eve/src/execution/create-session-step.test.ts
index eb785803a..3a5f4eac5 100644
--- a/packages/eve/src/execution/create-session-step.test.ts
+++ b/packages/eve/src/execution/create-session-step.test.ts
@@ -165,32 +165,11 @@ describe("createSessionStep", () => {
});
});
- it("keeps a tighter configured workflow max subagents under the inherited cap", async () => {
+ it("seeds workflow max subagents from the authored Workflow tool", async () => {
vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue({
resolvedAgent: {
- config: {
- limits: { maxSubagents: 5 },
- },
- },
- turnAgent: TestTurnAgent,
- } as never);
-
- const { state } = await createSessionStep({
- compiledArtifactsSource: { kind: "bundled" },
- continuationToken: "subagent:test",
- inheritedLimits: { maxSubagents: 12 },
- sessionId: "sess-child",
- });
-
- expect(state.snapshot?.session.workflowMaxSubagents).toBe(5);
- });
-
- it("seeds workflow max subagents from resolved agent config", async () => {
- vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue({
- resolvedAgent: {
- config: {
- limits: { maxSubagents: 12 },
- },
+ config: {},
+ workflowTool: { maxSubagents: 5 },
},
turnAgent: TestTurnAgent,
} as never);
@@ -201,26 +180,6 @@ describe("createSessionStep", () => {
sessionId: "sess-root",
});
- expect(state.snapshot?.session.workflowMaxSubagents).toBe(12);
- });
-
- it("caps configured workflow max subagents at the inherited cap", async () => {
- vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue({
- resolvedAgent: {
- config: {
- limits: { maxSubagents: 12 },
- },
- },
- turnAgent: TestTurnAgent,
- } as never);
-
- const { state } = await createSessionStep({
- compiledArtifactsSource: { kind: "bundled" },
- continuationToken: "subagent:test",
- inheritedLimits: { maxSubagents: 5 },
- sessionId: "sess-child",
- });
-
expect(state.snapshot?.session.workflowMaxSubagents).toBe(5);
});
});
diff --git a/packages/eve/src/execution/create-session-step.ts b/packages/eve/src/execution/create-session-step.ts
index 933faee1f..df10de45d 100644
--- a/packages/eve/src/execution/create-session-step.ts
+++ b/packages/eve/src/execution/create-session-step.ts
@@ -5,10 +5,7 @@ import {
type DurableSessionState,
} from "#execution/durable-session-store.js";
import { createSession } from "#execution/session.js";
-import {
- resolveInheritedCountLimit,
- resolveInheritedTokenLimit,
-} from "#execution/run-session-limits.js";
+import { resolveInheritedTokenLimit } from "#execution/run-session-limits.js";
import type { RunSessionLimits } from "#channel/types.js";
import type { JsonObject } from "#shared/json.js";
@@ -45,7 +42,7 @@ export async function createSessionStep(input: {
nodeId: input.nodeId,
});
- // Every axis below resolves tighter-wins against the cap inherited from the
+ // Both token axes resolve tighter-wins against the cap inherited from the
// delegating parent: a child may narrow what its parent granted, never widen
// it. Root runs have no inherited limits, so their configured values apply.
const session = createSession({
@@ -71,11 +68,7 @@ export async function createSessionStep(input: {
sessionId: input.sessionId,
subagentDepth: input.subagentDepth,
turnAgent: bundle.turnAgent,
- // Caps one Workflow invocation's fan-out anywhere in this session.
- workflowMaxSubagents: resolveInheritedCountLimit({
- configured: bundle.resolvedAgent.config.limits?.maxSubagents,
- inherited: input.inheritedLimits?.maxSubagents,
- }),
+ workflowMaxSubagents: bundle.resolvedAgent.workflowTool?.maxSubagents,
});
return { state: createDurableSessionState({ session }) };
diff --git a/packages/eve/src/execution/node-step.ts b/packages/eve/src/execution/node-step.ts
index 2e3c8dfdf..2781cc8f1 100644
--- a/packages/eve/src/execution/node-step.ts
+++ b/packages/eve/src/execution/node-step.ts
@@ -66,9 +66,8 @@ export interface CreateExecutionNodeStepInput {
readonly modelResolutionScope: RuntimeModelResolutionScope;
readonly node: ResolvedRuntimeAgentNode;
/**
- * Effective `limits.maxSubagents` cap for Workflow invocations in this run,
- * materialized on the session at creation (config resolved against any
- * inherited parent cap).
+ * Effective `maxSubagents` cap configured by the experimental Workflow tool
+ * definition and materialized on the session at creation.
*/
readonly workflowMaxSubagents?: number;
}
@@ -90,7 +89,7 @@ export function createExecutionNodeStep(input: CreateExecutionNodeStepInput): St
return createToolLoopHarness({
abortSignal: input.abortSignal,
capabilities: input.capabilities,
- workflow: input.node.agent.workflowEnabled === true,
+ workflow: input.node.agent.workflowTool !== undefined,
workflowMaxSubagents: input.workflowMaxSubagents,
handleEvent: input.handleEvent,
mode: input.mode,
diff --git a/packages/eve/src/execution/run-session-limits.ts b/packages/eve/src/execution/run-session-limits.ts
index 2662dce0e..bf012e4da 100644
--- a/packages/eve/src/execution/run-session-limits.ts
+++ b/packages/eve/src/execution/run-session-limits.ts
@@ -21,21 +21,3 @@ export function resolveInheritedTokenLimit(input: {
}
return Math.min(input.configured, input.inherited);
}
-
-/**
- * Resolves a positive integer limit against an inherited parent cap: the
- * tighter value wins; absence means the other side applies. Used for the
- * the Workflow delegation-count axis (`maxSubagents`).
- */
-export function resolveInheritedCountLimit(input: {
- readonly configured?: number;
- readonly inherited?: number;
-}): number | undefined {
- if (input.inherited === undefined) {
- return input.configured;
- }
- if (input.configured === undefined) {
- return input.inherited;
- }
- return Math.min(input.configured, input.inherited);
-}
diff --git a/packages/eve/src/execution/subagent-tool.test.ts b/packages/eve/src/execution/subagent-tool.test.ts
index a84cd6912..83cdad7b8 100644
--- a/packages/eve/src/execution/subagent-tool.test.ts
+++ b/packages/eve/src/execution/subagent-tool.test.ts
@@ -182,14 +182,12 @@ describe("buildSubagentRunInput", () => {
initiatorAuth: null,
session: {
...makeSession(),
- workflowMaxSubagents: 7,
},
});
expect(runInput.limits).toEqual({
maxInputTokensPerSession: false,
maxOutputTokensPerSession: false,
- maxSubagents: 7,
});
});
diff --git a/packages/eve/src/execution/subagent-tool.ts b/packages/eve/src/execution/subagent-tool.ts
index 96b6f18a5..b02974a08 100644
--- a/packages/eve/src/execution/subagent-tool.ts
+++ b/packages/eve/src/execution/subagent-tool.ts
@@ -97,9 +97,6 @@ export function buildSubagentRunInput(input: {
const inheritedLimits: {
-readonly [K in keyof RunSessionLimits]: RunSessionLimits[K];
} = resolveRemainingSessionTokenLimits(session, input.fanoutSize);
- if (session.workflowMaxSubagents !== undefined) {
- inheritedLimits.maxSubagents = session.workflowMaxSubagents;
- }
const runInput: {
-readonly [K in keyof RunInput]: RunInput[K];
diff --git a/packages/eve/src/execution/workflow-entry.test.ts b/packages/eve/src/execution/workflow-entry.test.ts
index 2bccfff64..12baa441d 100644
--- a/packages/eve/src/execution/workflow-entry.test.ts
+++ b/packages/eve/src/execution/workflow-entry.test.ts
@@ -244,7 +244,7 @@ describe("workflowEntry", () => {
await workflowEntry({
input: { message: "hello there" },
- limits: { maxSubagents: 4 },
+ limits: { maxInputTokensPerSession: 4 },
serializedContext: createSerializedContext({
[SubagentDepthKey.name]: 3,
}),
@@ -252,7 +252,7 @@ describe("workflowEntry", () => {
expect(createSessionStep).toHaveBeenCalledWith(
expect.objectContaining({
- inheritedLimits: { maxSubagents: 4 },
+ inheritedLimits: { maxInputTokensPerSession: 4 },
subagentDepth: 3,
}),
);
diff --git a/packages/eve/src/harness/types.ts b/packages/eve/src/harness/types.ts
index 7dcabe709..74adc8423 100644
--- a/packages/eve/src/harness/types.ts
+++ b/packages/eve/src/harness/types.ts
@@ -84,8 +84,7 @@ export interface HarnessSession {
readonly subagentDepth?: number;
/**
* Effective maximum subagent calls one `Workflow` invocation may dispatch
- * for this session. Resolved at session creation as the tighter of the
- * agent's `limits.maxSubagents` and any cap inherited from the parent run.
+ * for this session, configured by `experimental_workflow({ maxSubagents })`.
* When omitted, the dispatch step applies the framework default.
*/
readonly workflowMaxSubagents?: number;
@@ -228,16 +227,15 @@ export interface ToolLoopHarnessConfig {
/**
* Exposes the `Workflow` orchestration tool — an isolated JavaScript sandbox
* whose only callable operations are this agent's subagents and remote
- * agents. Resolved by the runtime from the agent's `workflowEnabled` flag
- * (set when `agent/tools/workflow.ts` re-exports the `ExperimentalWorkflow`
- * marker). Only root sessions ever see the tool.
+ * agents. Resolved from the `experimental_workflow(...)` definition exported
+ * by `agent/tools/workflow.ts`. Only root sessions ever see the tool.
* Defaults to `false`.
*/
readonly workflow?: boolean;
/**
* Maximum subagent calls one `Workflow` invocation may dispatch, from the
- * agent's `limits.maxSubagents`. Advertised in the tool description; the
- * dispatch step enforces it. Defaults to
+ * authored Workflow tool definition. Advertised in the tool description;
+ * the dispatch step enforces it. Defaults to
* {@link import("#harness/workflow-subagent-limit.js").DEFAULT_WORKFLOW_MAX_SUBAGENTS}.
*/
readonly workflowMaxSubagents?: number;
diff --git a/packages/eve/src/harness/workflow-subagent-limit.ts b/packages/eve/src/harness/workflow-subagent-limit.ts
index ca3470cf2..405cb8fbd 100644
--- a/packages/eve/src/harness/workflow-subagent-limit.ts
+++ b/packages/eve/src/harness/workflow-subagent-limit.ts
@@ -2,8 +2,8 @@ import type { RuntimeActionRequest } from "#runtime/actions/types.js";
import type { WorkflowSandboxInterrupt } from "#shared/workflow-sandbox.js";
/**
- * Default for `limits.maxSubagents`: the maximum number of subagent (and
- * remote-agent) calls one `Workflow` tool invocation may dispatch.
+ * Default maximum number of subagent (and remote-agent) calls one `Workflow`
+ * tool invocation may dispatch.
*/
export const DEFAULT_WORKFLOW_MAX_SUBAGENTS = 100;
diff --git a/packages/eve/src/internal/authored-definition/core.test.ts b/packages/eve/src/internal/authored-definition/core.test.ts
index 8e5117847..46043724a 100644
--- a/packages/eve/src/internal/authored-definition/core.test.ts
+++ b/packages/eve/src/internal/authored-definition/core.test.ts
@@ -95,7 +95,6 @@ describe("normalizeAgentDefinition", () => {
limits: {
maxInputTokensPerSession: 200_000,
maxOutputTokensPerSession: 20_000,
- maxSubagents: 6,
},
},
FAILURE_MESSAGE,
@@ -104,7 +103,6 @@ describe("normalizeAgentDefinition", () => {
expect(definition.limits).toEqual({
maxInputTokensPerSession: 200_000,
maxOutputTokensPerSession: 20_000,
- maxSubagents: 6,
});
});
@@ -138,12 +136,12 @@ describe("normalizeAgentDefinition", () => {
).toThrow(FAILURE_MESSAGE);
});
- it.each([0, 1.5, -1, "6"])("rejects invalid workflow max subagents %j", (maxSubagents) => {
+ it("rejects the removed agent-level workflow max subagents limit", () => {
expect(() =>
normalizeAgentDefinition(
{
model: "openai/gpt-5.5",
- limits: { maxSubagents },
+ limits: { maxSubagents: 6 },
},
FAILURE_MESSAGE,
),
diff --git a/packages/eve/src/internal/authored-definition/core.ts b/packages/eve/src/internal/authored-definition/core.ts
index 407f42862..688a2016a 100644
--- a/packages/eve/src/internal/authored-definition/core.ts
+++ b/packages/eve/src/internal/authored-definition/core.ts
@@ -10,6 +10,7 @@ import {
expectFunction,
expectObjectRecord,
expectOnlyKnownKeys,
+ expectPositiveInteger,
expectProviderOptions,
expectString,
getOptionalStringRecordProperty,
@@ -129,14 +130,6 @@ function normalizeAgentReasoningDefinition(
}
}
-function expectPositiveInteger(value: unknown, message: string): number {
- if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
- throw new Error(message);
- }
-
- return value;
-}
-
function normalizeAgentModelDefinition(
value: unknown,
message: string,
@@ -183,11 +176,7 @@ function normalizeAgentLimitsDefinition(
message: string,
): NonNullable<NormalizedAgentDefinition["limits"]> {
const record = expectObjectRecord(value, message);
- expectOnlyKnownKeys(
- record,
- ["maxInputTokensPerSession", "maxOutputTokensPerSession", "maxSubagents"],
- message,
- );
+ expectOnlyKnownKeys(record, ["maxInputTokensPerSession", "maxOutputTokensPerSession"], message);
const normalizedDefinition: Mutable<NonNullable<NormalizedAgentDefinition["limits"]>> = {};
if (record.maxInputTokensPerSession !== undefined) {
@@ -202,10 +191,6 @@ function normalizeAgentLimitsDefinition(
message,
);
}
- if (record.maxSubagents !== undefined) {
- normalizedDefinition.maxSubagents = expectPositiveInteger(record.maxSubagents, message);
- }
-
return normalizedDefinition;
}
diff --git a/packages/eve/src/internal/authored-definition/schema-backed.test.ts b/packages/eve/src/internal/authored-definition/schema-backed.test.ts
index cbb463454..9e55a2948 100644
--- a/packages/eve/src/internal/authored-definition/schema-backed.test.ts
+++ b/packages/eve/src/internal/authored-definition/schema-backed.test.ts
@@ -5,7 +5,7 @@ import {
defineTool,
defineDynamic,
disableTool,
- ExperimentalWorkflow,
+ experimental_workflow,
} from "#public/definitions/tool.js";
import { once } from "#public/tools/approval/approval-helpers.js";
import { normalizeToolDefinition } from "#internal/authored-definition/schema-backed.js";
@@ -40,10 +40,22 @@ describe("normalizeToolDefinition", () => {
expect(entry).toEqual({ kind: "disabled" });
});
- it("returns an enable-workflow entry for the ExperimentalWorkflow marker", () => {
- const entry = normalizeToolDefinition(ExperimentalWorkflow, FAILURE_MESSAGE);
+ it("returns a configured entry for the experimental Workflow tool", () => {
+ const entry = normalizeToolDefinition(
+ experimental_workflow({ maxSubagents: 6 }),
+ FAILURE_MESSAGE,
+ );
- expect(entry).toEqual({ kind: "enable-workflow" });
+ expect(entry).toEqual({ kind: "workflow-tool", maxSubagents: 6 });
+ });
+
+ it.each([0, 1.5, -1, "6"])("rejects invalid workflow max subagents %j", (maxSubagents) => {
+ expect(() =>
+ normalizeToolDefinition(
+ experimental_workflow({ maxSubagents: maxSubagents as number }),
+ FAILURE_MESSAGE,
+ ),
+ ).toThrow(FAILURE_MESSAGE);
});
it("rejects authored tool exports that carry an authored `name` field", () => {
diff --git a/packages/eve/src/internal/authored-definition/schema-backed.ts b/packages/eve/src/internal/authored-definition/schema-backed.ts
index 15e2a8626..5a3545fb1 100644
--- a/packages/eve/src/internal/authored-definition/schema-backed.ts
+++ b/packages/eve/src/internal/authored-definition/schema-backed.ts
@@ -1,8 +1,12 @@
-import { isDisabledToolSentinel, isEnableWorkflowToolSentinel } from "#public/definitions/tool.js";
+import {
+ isDisabledToolSentinel,
+ isExperimentalWorkflowToolDefinition,
+} from "#public/definitions/tool.js";
import {
expectFunction,
expectObjectRecord,
expectOnlyKnownKeys,
+ expectPositiveInteger,
expectString,
} from "#internal/authored-module.js";
import type { InternalToolDefinitionWithExecuteFn } from "#shared/tool-definition.js";
@@ -34,7 +38,7 @@ type MutableNormalizedAuthoredTool = {
type NormalizedToolEntry =
| { readonly kind: "tool"; readonly definition: NormalizedAuthoredTool }
| { readonly kind: "disabled" }
- | { readonly kind: "enable-workflow" }
+ | { readonly kind: "workflow-tool"; readonly maxSubagents?: number }
| {
readonly kind: "dynamic-tool";
readonly eventNames: readonly DynamicToolEventName[];
@@ -43,7 +47,7 @@ type NormalizedToolEntry =
/**
* Normalizes one authored tool default export. Recognizes real tool
* definitions (`defineTool(...)`), disable sentinels (`disableTool()`), and the
- * `Workflow` opt-in sentinel.
+ * experimental `Workflow` tool definition.
*
* Authored `name` fields are rejected — tool identity is path-derived.
*/
@@ -58,8 +62,16 @@ export function normalizeToolDefinition(value: unknown, message: string): Normal
if (isDisabledToolSentinel(value)) {
return { kind: "disabled" };
}
- if (isEnableWorkflowToolSentinel(value)) {
- return { kind: "enable-workflow" };
+ if (isExperimentalWorkflowToolDefinition(value)) {
+ const record = expectObjectRecord(value, message);
+ expectOnlyKnownKeys(record, ["kind", "maxSubagents"], message);
+ return {
+ kind: "workflow-tool",
+ maxSubagents:
+ record.maxSubagents === undefined
+ ? undefined
+ : expectPositiveInteger(record.maxSubagents, message),
+ };
}
const record = expectObjectRecord(value, message);
diff --git a/packages/eve/src/internal/authored-module.ts b/packages/eve/src/internal/authored-module.ts
index 36ca674d5..89099e895 100644
--- a/packages/eve/src/internal/authored-module.ts
+++ b/packages/eve/src/internal/authored-module.ts
@@ -60,6 +60,17 @@ export function expectBoolean(value: unknown, message: string): boolean {
return value;
}
+/**
+ * Returns one positive integer or throws.
+ */
+export function expectPositiveInteger(value: unknown, message: string): number {
+ if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+ throw new Error(message);
+ }
+
+ return value;
+}
+
/**
* Returns the value as a function or throws.
*/
diff --git a/packages/eve/src/internal/nitro/host/create-application-nitro.scenario.test.ts b/packages/eve/src/internal/nitro/host/create-application-nitro.scenario.test.ts
index a0ad56dc7..2ff36a906 100644
--- a/packages/eve/src/internal/nitro/host/create-application-nitro.scenario.test.ts
+++ b/packages/eve/src/internal/nitro/host/create-application-nitro.scenario.test.ts
@@ -582,7 +582,7 @@ describe("createApplicationNitro", () => {
const directHost = createPreparedHost();
const workflowHost = createPreparedHost();
- workflowHost.compileResult.manifest.workflowEnabled = true;
+ workflowHost.compileResult.manifest.workflowTool = {};
await createApplicationNitro(directHost, false);
await createApplicationNitro(workflowHost, false);
diff --git a/packages/eve/src/internal/nitro/host/create-application-nitro.ts b/packages/eve/src/internal/nitro/host/create-application-nitro.ts
index 5a1cc2c52..22bcbbb24 100644
--- a/packages/eve/src/internal/nitro/host/create-application-nitro.ts
+++ b/packages/eve/src/internal/nitro/host/create-application-nitro.ts
@@ -103,7 +103,7 @@ function includesWorkflowStepRegistrations(surface: NitroBuildSurface): boolean
/** Whether any agent needs the dynamic Workflow sandbox runtime. */
function manifestEnablesWorkflow(manifest: CompiledAgentManifest): boolean {
const nodes = [manifest, ...manifest.subagents.map((subagent) => subagent.agent)];
- return nodes.some((node) => node.workflowEnabled === true);
+ return nodes.some((node) => node.workflowTool !== undefined);
}
function manifestHasWebSocketChannel(manifest: CompiledAgentManifest): boolean {
diff --git a/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response-from-manifest.ts b/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response-from-manifest.ts
index 3d4fb9cc9..749c1126b 100644
--- a/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response-from-manifest.ts
+++ b/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response-from-manifest.ts
@@ -243,7 +243,7 @@ export function buildAgentInfoResponseFromManifest(
},
version: 1,
workflow: {
- enabled: manifest.workflowEnabled,
+ enabled: manifest.workflowTool !== undefined,
toolName: WORKFLOW_TOOL_NAME,
},
workspace: {
diff --git a/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response.ts b/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response.ts
index f0fcf6d39..1aaf75d09 100644
--- a/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response.ts
+++ b/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response.ts
@@ -285,7 +285,7 @@ export function buildAgentInfoResponse(
tools,
version: 1,
workflow: {
- enabled: agent.workflowEnabled,
+ enabled: agent.workflowTool !== undefined,
toolName: WORKFLOW_TOOL_NAME,
},
workspace: {
diff --git a/packages/eve/src/public/definitions/exact.test.ts b/packages/eve/src/public/definitions/exact.test.ts
index 3bb30c612..c9e5de71f 100644
--- a/packages/eve/src/public/definitions/exact.test.ts
+++ b/packages/eve/src/public/definitions/exact.test.ts
@@ -10,7 +10,7 @@ import { defineInstrumentation } from "#public/definitions/instrumentation.js";
import { defineSandbox } from "#public/definitions/sandbox.js";
import { defineSchedule } from "#public/definitions/schedule.js";
import { defineSkill } from "#public/definitions/skill.js";
-import { defineTool } from "#public/definitions/tool.js";
+import { defineTool, experimental_workflow } from "#public/definitions/tool.js";
describe("definition helper exact inputs", () => {
it("preserves literal inference for valid definitions", () => {
@@ -19,7 +19,6 @@ describe("definition helper exact inputs", () => {
limits: {
maxInputTokensPerSession: 200_000,
maxOutputTokensPerSession: 20_000,
- maxSubagents: 6,
},
model: "anthropic/claude-sonnet-5",
});
@@ -32,7 +31,7 @@ describe("definition helper exact inputs", () => {
expect(agent.description).toBe("type-test");
expect(agent.limits.maxInputTokensPerSession).toBe(200_000);
expect(agent.limits.maxOutputTokensPerSession).toBe(20_000);
- expect(agent.limits.maxSubagents).toBe(6);
+ expect(experimental_workflow({ maxSubagents: 6 }).maxSubagents).toBe(6);
expect(schedule.cron).toBe("0 9 * * *");
});
});
@@ -46,6 +45,19 @@ function typeOnlyFixtures(): void {
model: "anthropic/claude-sonnet-5",
});
+ defineAgent({
+ limits: {
+ // @ts-expect-error Workflow fan-out is configured by experimental_workflow.
+ maxSubagents: 6,
+ },
+ model: "anthropic/claude-sonnet-5",
+ });
+
+ experimental_workflow({
+ // @ts-expect-error Workflow maxSubagents must be a number.
+ maxSubagents: "6",
+ });
+
const agentWithName = {
model: "anthropic/claude-sonnet-5",
name: "agent-name",
diff --git a/packages/eve/src/public/definitions/tool.ts b/packages/eve/src/public/definitions/tool.ts
index 5be6d58b7..e693e70db 100644
--- a/packages/eve/src/public/definitions/tool.ts
+++ b/packages/eve/src/public/definitions/tool.ts
@@ -336,50 +336,74 @@ export function isDisabledToolSentinel(value: unknown): value is DisabledToolSen
}
/**
- * Marker discriminator written into the {@link ExperimentalWorkflow} opt-in
- * sentinel.
+ * Discriminator written into definitions returned by
+ * {@link experimental_workflow}.
*/
-const ENABLE_WORKFLOW_TOOL_SENTINEL_KIND = "eve:enable-workflow-tool";
+const EXPERIMENTAL_WORKFLOW_TOOL_KIND = "eve:enable-workflow-tool";
/**
- * Marker value re-exported as the default export of a file in `agent/tools/`
- * (conventionally `agent/tools/workflow.ts`) to enable the framework `Workflow`
- * orchestration tool. The tool is off unless this marker is present,
- * mirroring the {@link disableTool} opt-out in reverse.
+ * Configuration accepted by {@link experimental_workflow}.
*/
-export interface EnableWorkflowToolSentinel {
- readonly kind: typeof ENABLE_WORKFLOW_TOOL_SENTINEL_KIND;
+export interface ExperimentalWorkflowToolInput {
+ /**
+ * Maximum number of subagent or remote-agent calls one `Workflow` program
+ * may dispatch, counted across sequential and parallel calls alike.
+ *
+ * Calls beyond the limit fail with a `WORKFLOW_SUBAGENT_LIMIT_REACHED`
+ * result instead of starting a child session.
+ *
+ * @default 100
+ */
+ readonly maxSubagents?: number;
+}
+
+/**
+ * Framework `Workflow` tool definition returned by
+ * {@link experimental_workflow}.
+ */
+export interface ExperimentalWorkflowToolDefinition extends ExperimentalWorkflowToolInput {
+ readonly kind: typeof EXPERIMENTAL_WORKFLOW_TOOL_KIND;
}
/**
- * Opt-in marker for the framework `Workflow` tool, an isolated JavaScript sandbox whose
- * only callable operations are this agent's subagents and remote agents, for
- * orchestrating them from model-authored JavaScript. Re-export it as the
- * default export of `agent/tools/workflow.ts`:
+ * Enables and configures the experimental framework `Workflow` tool, an
+ * isolated JavaScript sandbox whose only callable operations are this agent's
+ * subagents and remote agents. Export the result from
+ * `agent/tools/workflow.ts`:
*
* ```ts
- * export { ExperimentalWorkflow as default } from "eve/tools";
- * ```
+ * import { experimental_workflow } from "eve/tools";
*
- * Only the root session sees the `Workflow` tool — delegated subagent sessions
- * never get it — and one Workflow program may dispatch at most
- * `limits.maxSubagents` subagent calls (default 100).
+ * export default experimental_workflow({ maxSubagents: 25 });
+ * ```
*
- * The capability is experimental. The resulting model-facing tool is still
- * called `Workflow`.
+ * Only the root session sees the tool. The resulting model-facing tool is
+ * still called `Workflow`.
*/
-export const ExperimentalWorkflow: EnableWorkflowToolSentinel = Object.freeze({
- kind: ENABLE_WORKFLOW_TOOL_SENTINEL_KIND,
-});
+export function experimental_workflow(
+ input: ExperimentalWorkflowToolInput = {},
+): ExperimentalWorkflowToolDefinition {
+ const definition: {
+ kind: typeof EXPERIMENTAL_WORKFLOW_TOOL_KIND;
+ maxSubagents?: number;
+ } = {
+ kind: EXPERIMENTAL_WORKFLOW_TOOL_KIND,
+ };
+ if (input.maxSubagents !== undefined) {
+ definition.maxSubagents = input.maxSubagents;
+ }
+ return definition;
+}
/**
- * Type guard: returns whether `value` is the {@link ExperimentalWorkflow}
- * opt-in sentinel.
+ * Type guard for a definition returned by {@link experimental_workflow}.
*/
-export function isEnableWorkflowToolSentinel(value: unknown): value is EnableWorkflowToolSentinel {
+export function isExperimentalWorkflowToolDefinition(
+ value: unknown,
+): value is ExperimentalWorkflowToolDefinition {
return (
typeof value === "object" &&
value !== null &&
- (value as { kind?: unknown }).kind === ENABLE_WORKFLOW_TOOL_SENTINEL_KIND
+ (value as { kind?: unknown }).kind === EXPERIMENTAL_WORKFLOW_TOOL_KIND
);
}
diff --git a/packages/eve/src/public/tools/index.ts b/packages/eve/src/public/tools/index.ts
index c738bcbed..efc0ee235 100644
--- a/packages/eve/src/public/tools/index.ts
+++ b/packages/eve/src/public/tools/index.ts
@@ -4,13 +4,14 @@
export {
type DisabledToolSentinel,
- type EnableWorkflowToolSentinel,
+ type ExperimentalWorkflowToolDefinition,
+ type ExperimentalWorkflowToolInput,
defineDynamic,
defineTool,
disableTool,
+ experimental_workflow,
isDisabledToolSentinel,
- isEnableWorkflowToolSentinel,
- ExperimentalWorkflow,
+ isExperimentalWorkflowToolDefinition,
type ToolAuthOptions,
type ToolAuthProvider,
type ToolDefinition,
diff --git a/packages/eve/src/runtime/resolve-agent.ts b/packages/eve/src/runtime/resolve-agent.ts
index c4735be68..48418b865 100644
--- a/packages/eve/src/runtime/resolve-agent.ts
+++ b/packages/eve/src/runtime/resolve-agent.ts
@@ -107,7 +107,10 @@ export async function resolveAgent(input: ResolveAgentInput): Promise<ResolvedAg
connections: resolvedConnections,
disabledFrameworkChannels,
disabledFrameworkTools: [...input.manifest.disabledFrameworkTools],
- workflowEnabled: input.manifest.workflowEnabled,
+ workflowTool:
+ input.manifest.workflowTool === undefined
+ ? undefined
+ : { maxSubagents: input.manifest.workflowTool.maxSubagents },
dynamicInstructionsResolvers: resolvedDynamicInstructionsResolvers,
dynamicSkillResolvers: resolvedDynamicSkillResolvers,
dynamicToolResolvers: resolvedDynamicToolResolvers,
@@ -244,7 +247,6 @@ function createResolvedAgentConfig(manifest: CompiledAgentNodeManifest): Resolve
if (manifest.config.limits !== undefined) {
config.limits = {
- maxSubagents: manifest.config.limits.maxSubagents,
maxInputTokensPerSession: manifest.config.limits.maxInputTokensPerSession,
maxOutputTokensPerSession: manifest.config.limits.maxOutputTokensPerSession,
};
diff --git a/packages/eve/src/runtime/types.ts b/packages/eve/src/runtime/types.ts
index 12986ed1c..10785bcf6 100644
--- a/packages/eve/src/runtime/types.ts
+++ b/packages/eve/src/runtime/types.ts
@@ -387,13 +387,13 @@ export interface ResolvedAgent {
*/
readonly disabledFrameworkTools: readonly string[];
/**
- * Whether the author opted into the framework `Workflow` orchestration tool
- * by re-exporting the `Workflow` marker as the default export of a file in
- * `agent/tools/`. When true, the harness exposes an isolated JavaScript sandbox
- * whose only callable operations are this agent's subagents and remote
- * agents.
+ * Configuration for the experimental framework `Workflow` orchestration
+ * tool. Present when an authored tool module exports
+ * `experimental_workflow(...)`.
*/
- readonly workflowEnabled: boolean;
+ readonly workflowTool?: {
+ readonly maxSubagents?: number;
+ };
readonly dynamicInstructionsResolvers: readonly ResolvedDynamicInstructionsResolver[];
readonly dynamicSkillResolvers: readonly ResolvedDynamicSkillResolver[];
readonly dynamicToolResolvers: readonly ResolvedDynamicToolResolver[];
diff --git a/packages/eve/src/shared/agent-definition.ts b/packages/eve/src/shared/agent-definition.ts
index 62f43dca6..2d8cee7bb 100644
--- a/packages/eve/src/shared/agent-definition.ts
+++ b/packages/eve/src/shared/agent-definition.ts
@@ -149,22 +149,6 @@ export interface PublicAgentCompactionDefinition {
* Configures framework-owned runtime limits for this agent's runs.
*/
export interface AgentLimitsDefinition {
- /**
- * Maximum number of subagent calls one `Workflow` tool invocation may
- * dispatch.
- *
- * Applies to the opt-in `Workflow` orchestration tool: a single
- * model-authored workflow program may spawn at most this many subagent or
- * remote-agent calls, counted across the whole program (sequential and
- * parallel calls alike). Calls beyond the limit fail with an error result
- * instead of starting a child session.
- *
- * Delegated subagent sessions resolve this against the cap inherited from
- * the delegating parent; the tighter value wins.
- *
- * @default 100
- */
- readonly maxSubagents?: number;
/**
* Maximum provider-reported input tokens accumulated by one durable session.
*
diff --git a/packages/eve/test/scenarios/app-runtime-dependencies.scenario.test.ts b/packages/eve/test/scenarios/app-runtime-dependencies.scenario.test.ts
index 454181496..322dbb654 100644
--- a/packages/eve/test/scenarios/app-runtime-dependencies.scenario.test.ts
+++ b/packages/eve/test/scenarios/app-runtime-dependencies.scenario.test.ts
@@ -334,7 +334,7 @@ describe("app runtime dependency tracing", () => {
await mkdir(join(appRoot, "agent", "tools"), { recursive: true });
await writeFile(
join(appRoot, "agent", "tools", "workflow.ts"),
- 'export default { kind: "eve:enable-workflow-tool" };\n',
+ 'export default { kind: "eve:enable-workflow-tool", maxSubagents: 6 };\n',
);
}