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.mdnew file mode 100644index 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.mdindex 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.mdindex 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 nextdiff --git a/docs/guides/dynamic-workflows.md b/docs/guides/dynamic-workflows.mdindex 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 ofWorkflow 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.mdindex 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.mdxindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 = zconnections: 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 = zconnections: 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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): Streturn 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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): Normalif (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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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<ResolvedAgconnections: 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): Resolveif (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.tsindex 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.tsindex 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.tsindex 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',);}