Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

Add config surface for workflow world (#139)

JJ Kasper4bfbaa077dff
diff --git a/.changeset/workflow-world-config.md b/.changeset/workflow-world-config.md
new file mode 100644
index 000000000..045b900e7
--- /dev/null
+++ b/.changeset/workflow-world-config.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Add root agent `experimental.workflow.world` configuration for selecting an installed Workflow world package. Eve now loads and registers the configured world at runtime and documents how self-hosted deployments can provide a custom Workflow world.
diff --git a/docs/agent-config.md b/docs/agent-config.md
index 091af4797..182d98072 100644
--- a/docs/agent-config.md
+++ b/docs/agent-config.md
@@ -54,16 +54,43 @@ export default defineAgent({
See [Default harness](./concepts/default-harness#compaction) for how the loop applies it.
+## Workflow world
+
+By default, eve selects the Workflow SDK world for the host: Vercel Workflow on
+Vercel, and the SDK's local world in local development or `eve start`. Advanced
+self-hosted deployments can select the Workflow world package to use from the
+root `agent.ts`:
+
+```ts title="agent/agent.ts"
+import { defineAgent } from "eve";
+
+export default defineAgent({
+ model: "anthropic/claude-opus-4.8",
+ experimental: {
+ workflow: {
+ world: "@workflow/world-postgres",
+ },
+ },
+});
+```
+
+Install that package in your app. It should export a default factory or
+`createWorld()` function.
+
+Put credentials and host-specific options in runtime environment variables read
+by the world package, not in `agent.ts`. If the installed package must stay
+external in hosted output, list it in `build.externalDependencies`.
+
## Other defineAgent fields
`defineAgent` takes a few more fields, all optional. For the exported types, see the [TypeScript API](./reference/typescript-api).
-| Field | Type | Default | Description |
-| -------------- | --------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `modelOptions` | `AgentModelOptionsDefinition` | none | Provider option overrides forwarded to the model call. |
-| `experimental` | `{ codeMode?: boolean }` | flags unset | Opt-in flags that can change or disappear in any release. Treat them as unstable. `codeMode` routes executable tools through a sandboxed code-execution wrapper, where the model writes JavaScript that calls the tools inside the [sandbox](./sandbox). |
-| `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 |
+| -------------- | ------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `modelOptions` | `AgentModelOptionsDefinition` | none | Provider option overrides forwarded to the model call. |
+| `experimental` | `{ codeMode?: boolean; workflow?: { world?: string } }` | flags unset | Opt-in flags that can change or disappear in any release. Treat them as unstable. `codeMode` routes executable tools through a sandboxed code-execution wrapper, where the model writes JavaScript that calls the tools inside the [sandbox](./sandbox). `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. |
`codeMode` is experimental and may change or be removed.
diff --git a/docs/concepts/execution-model-and-durability.md b/docs/concepts/execution-model-and-durability.md
index 389092696..8c4b6e53f 100644
--- a/docs/concepts/execution-model-and-durability.md
+++ b/docs/concepts/execution-model-and-durability.md
@@ -19,7 +19,22 @@ The Workflow SDK is not inherently tied to Vercel. In local development and in a
Nitro hosts the HTTP routes and workflow entrypoints. It does not supply the workflow state store or the sandbox runtime. Those are separate adapters: Workflow uses the active world implementation, and Sandbox uses the backend from `agent/sandbox` or `defaultBackend()`.
-Today, eve owns Workflow world selection. In the future, eve will expose a supported way to provide a different Workflow world, so advanced self-hosted deployments can swap the state, queue, auth, and streaming backend behind the same agent runtime. The underlying [Workflow Worlds](https://workflow-sdk.dev/worlds) abstraction is what makes that possible, but it is not an eve application API yet.
+For advanced self-hosted deployments, the root `agent.ts` can select the installed Workflow world package to use with `experimental.workflow.world`:
+
+```ts title="agent/agent.ts"
+import { defineAgent } from "eve";
+
+export default defineAgent({
+ model: "anthropic/claude-opus-4.8",
+ experimental: {
+ workflow: {
+ world: "@workflow/world-postgres",
+ },
+ },
+});
+```
+
+The world package backs workflow state, queues, hooks, and streams. Keep secrets and deployment-specific options in runtime environment variables read by that package, not in `agent.ts`. See [agent.ts](../agent-config#workflow-world) and [Workflow Worlds](https://workflow-sdk.dev/worlds).
## Resuming after a crash
diff --git a/docs/guides/deployment.md b/docs/guides/deployment.md
index 61420c8b0..c4ff4684f 100644
--- a/docs/guides/deployment.md
+++ b/docs/guides/deployment.md
@@ -21,7 +21,22 @@ Nitro is the HTTP host layer. It gives eve a build artifact that can serve the h
On Vercel, eve emits Vercel Build Output, the Workflow SDK runs on Vercel Workflow, and `defaultBackend()` selects Vercel Sandbox. Outside Vercel, `eve start` serves the standard Nitro Node output, the Workflow SDK uses its local world by default, and `defaultBackend()` selects a local sandbox backend in availability order. That local workflow world persists run state on disk and has no direct coupling to Vercel; Vercel-only behavior such as latest-deployment routing and dashboard run attributes is additive.
-Eve does not expose Workflow world selection as a public app API today. Future releases will let advanced deployments provide a different Workflow world, the SDK abstraction for workflow state, queues, auth, and streaming; see [Workflow Worlds](https://workflow-sdk.dev/worlds) for the underlying concept.
+Advanced self-hosted deployments can select a different installed Workflow world package in the root `agent.ts`:
+
+```ts title="agent/agent.ts"
+import { defineAgent } from "eve";
+
+export default defineAgent({
+ model: "anthropic/claude-opus-4.8",
+ experimental: {
+ workflow: {
+ world: "@acme/eve-workflow-world",
+ },
+ },
+});
+```
+
+The world package should read credentials and host-specific options from runtime environment variables. It should export a default factory or `createWorld()` function. See [Workflow Worlds](https://workflow-sdk.dev/worlds) for the underlying SDK abstraction.
## 2. Environment variables and secrets
@@ -125,7 +140,7 @@ Eve writes the standard Nitro output under `.output/` instead of Vercel Build Ou
Self-deployed agents should make the Vercel-specific choices explicit:
-- Let the Workflow SDK use its default local world, which stores workflow state under `.workflow-data`, or configure your host so that directory is on persistent storage.
+- Let the Workflow SDK use its default local world, which stores workflow state under `.workflow-data`, configure your host so that directory is on persistent storage, or select another world with `experimental.workflow.world` in the root `agent.ts`.
- Install the AI SDK package for your provider, then use a direct provider model object and `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` when you want no Gateway dependency.
- Use `AI_GATEWAY_API_KEY` if you still want Gateway routing from a non-Vercel host.
- Replace `vercelOidc()` with auth that your host can verify.
diff --git a/docs/reference/typescript-api.md b/docs/reference/typescript-api.md
index e1ca0a4c0..6e9b6a66f 100644
--- a/docs/reference/typescript-api.md
+++ b/docs/reference/typescript-api.md
@@ -50,7 +50,7 @@ export default defineTool({
| `defineEvalConfig` | `eve/evals` | `evals/evals.config.ts` | [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 predicates `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`).
+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 predicates `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`). `AgentWorkflowDefinition` and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape.
## Runtime context (`ctx`)
@@ -68,7 +68,7 @@ A few non-`define*` helpers round out the set: `disableTool` and `ExperimentalWo
| Import | Holds |
| ----------------------------------------------------------- | -------------------------------------------------------------------- |
-| `eve` | `defineAgent`, `defineRemoteAgent` |
+| `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` |
diff --git a/packages/eve/src/compiler/manifest.test.ts b/packages/eve/src/compiler/manifest.test.ts
new file mode 100644
index 000000000..0874d815f
--- /dev/null
+++ b/packages/eve/src/compiler/manifest.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+
+import { compiledAgentManifestSchema, createCompiledAgentManifest } from "#compiler/manifest.js";
+import { classifyModelRouting } from "#internal/classify-model-routing.js";
+
+describe("compiledAgentManifestSchema", () => {
+ it("accepts compiled workflow world configuration", () => {
+ const manifest = createCompiledAgentManifest({
+ agentRoot: "/app/agent",
+ appRoot: "/app",
+ config: {
+ model: { id: "openai/gpt-5.5", routing: classifyModelRouting("openai/gpt-5.5") },
+ name: "app",
+ experimental: {
+ workflow: {
+ world: "@acme/eve-world",
+ },
+ },
+ },
+ });
+
+ const parsed = compiledAgentManifestSchema.safeParse(manifest);
+
+ expect(parsed.success).toBe(true);
+ expect(manifest.config.experimental?.workflow).toEqual({ world: "@acme/eve-world" });
+ });
+});
diff --git a/packages/eve/src/compiler/manifest.ts b/packages/eve/src/compiler/manifest.ts
index d6f235e56..134198f6e 100644
--- a/packages/eve/src/compiler/manifest.ts
+++ b/packages/eve/src/compiler/manifest.ts
@@ -39,7 +39,7 @@ export const ROOT_COMPILED_AGENT_NODE_ID = "__root__";
/**
* Current compiled manifest schema version.
*/
-export const COMPILED_AGENT_MANIFEST_VERSION = 29;
+export const COMPILED_AGENT_MANIFEST_VERSION = 30;
/**
* Compiled channel entry preserved in the compiled manifest.
@@ -318,6 +318,14 @@ const compiledAgentBuildDefinitionSchema: z.ZodType<CompiledAgentBuildDefinition
})
.strict();
+const compiledAgentWorkflowWorldDefinitionSchema = z.string();
+
+const compiledAgentWorkflowDefinitionSchema = z
+ .object({
+ world: compiledAgentWorkflowWorldDefinitionSchema.optional(),
+ })
+ .strict();
+
const compiledAgentCompactionDefinitionSchema: z.ZodType<CompiledAgentCompactionDefinition> = z
.object({
model: compiledRuntimeModelReferenceSchema.optional(),
@@ -330,7 +338,13 @@ const compiledAgentConfigSchema: z.ZodType<CompiledAgentDefinition> = z
build: compiledAgentBuildDefinitionSchema.optional(),
compaction: compiledAgentCompactionDefinitionSchema.optional(),
description: z.string().optional(),
- experimental: z.object({ codeMode: z.boolean().optional() }).strict().optional(),
+ experimental: z
+ .object({
+ codeMode: z.boolean().optional(),
+ workflow: compiledAgentWorkflowDefinitionSchema.optional(),
+ })
+ .strict()
+ .optional(),
model: compiledRuntimeModelReferenceSchema,
name: z.string(),
outputSchema: jsonObjectSchema.optional(),
@@ -665,7 +679,15 @@ export function createCompiledAgentNodeManifest(input: {
experimental:
input.config.experimental === undefined
? undefined
- : { codeMode: input.config.experimental.codeMode },
+ : {
+ codeMode: input.config.experimental.codeMode,
+ workflow:
+ input.config.experimental.workflow === undefined
+ ? undefined
+ : {
+ world: input.config.experimental.workflow.world,
+ },
+ },
model: cloneCompiledRuntimeModelReference(input.config.model),
name: input.config.name,
outputSchema: input.config.outputSchema,
diff --git a/packages/eve/src/compiler/normalize-agent-config.ts b/packages/eve/src/compiler/normalize-agent-config.ts
index af3726b4c..f3b1c1656 100644
--- a/packages/eve/src/compiler/normalize-agent-config.ts
+++ b/packages/eve/src/compiler/normalize-agent-config.ts
@@ -18,6 +18,8 @@ import {
type ManifestCompileContext,
} from "#compiler/normalize-helpers.js";
+type Mutable<T> = { -readonly [K in keyof T]: T[K] };
+
/**
* Compiles the agent-level configuration (model, compaction, build,
* workspace) for one authored agent node.
@@ -78,8 +80,9 @@ export async function compileAgentConfig(
compiledConfig.description = definition.description;
}
- if (definition.experimental?.codeMode !== undefined) {
- compiledConfig.experimental = { codeMode: definition.experimental.codeMode };
+ const experimental = normalizeExperimentalDefinition(definition.experimental);
+ if (experimental !== undefined) {
+ compiledConfig.experimental = experimental;
}
if (definition.build !== undefined) {
@@ -123,6 +126,28 @@ export async function compileAgentConfig(
return compiledConfig;
}
+function normalizeExperimentalDefinition(
+ experimental: CompiledAgentDefinition["experimental"] | undefined,
+): CompiledAgentDefinition["experimental"] | undefined {
+ if (experimental === undefined) {
+ return undefined;
+ }
+
+ const compiledExperimental: Mutable<NonNullable<CompiledAgentDefinition["experimental"]>> = {};
+
+ if (experimental.codeMode !== undefined) {
+ compiledExperimental.codeMode = experimental.codeMode;
+ }
+
+ if (experimental.workflow !== undefined) {
+ compiledExperimental.workflow = {
+ world: experimental.workflow.world,
+ };
+ }
+
+ return compiledExperimental;
+}
+
async function normalizeAuthoredModelReference(input: {
readonly modelCatalog: ManifestCompileContext["modelCatalog"];
readonly purpose: string;
diff --git a/packages/eve/src/compiler/normalize-manifest.test.ts b/packages/eve/src/compiler/normalize-manifest.test.ts
new file mode 100644
index 000000000..38cc0b3a9
--- /dev/null
+++ b/packages/eve/src/compiler/normalize-manifest.test.ts
@@ -0,0 +1,102 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { AgentSourceManifest } from "#discover/manifest.js";
+import {
+ createAgentSourceManifest,
+ createLocalSubagentSourceRef,
+ createModuleSourceRef,
+} from "#discover/manifest.js";
+import { classifyModelRouting } from "#internal/classify-model-routing.js";
+import type { CompiledAgentDefinition } from "#compiler/manifest.js";
+import { compileAgentManifest } from "#compiler/normalize-manifest.js";
+
+const mocks = vi.hoisted(() => ({
+ compileAgentConfig: vi.fn(),
+ loadModuleBackedDefinition: vi.fn(),
+}));
+
+vi.mock("#compiler/normalize-agent-config.js", () => ({
+ compileAgentConfig: mocks.compileAgentConfig,
+}));
+
+vi.mock("#compiler/normalize-helpers.js", () => ({
+ loadModuleBackedDefinition: mocks.loadModuleBackedDefinition,
+}));
+
+describe("compileAgentManifest", () => {
+ beforeEach(() => {
+ mocks.compileAgentConfig.mockReset();
+ mocks.loadModuleBackedDefinition.mockReset();
+ });
+
+ it("rejects Workflow runtime configuration on subagents", async () => {
+ const subagentManifest = createAgentSourceManifest({
+ agentId: "research",
+ agentRoot: "/app/agent/subagents/research",
+ appRoot: "/app",
+ configModule: createModuleSourceRef({
+ logicalPath: "agent.ts",
+ }),
+ });
+ const manifest = createAgentSourceManifest({
+ agentId: "root",
+ agentRoot: "/app/agent",
+ appRoot: "/app",
+ subagents: [
+ createLocalSubagentSourceRef({
+ entryPath: "subagents/research/agent.ts",
+ logicalPath: "subagents/research",
+ manifest: subagentManifest,
+ rootPath: "/app/agent/subagents/research",
+ subagentId: "research",
+ }),
+ ],
+ });
+
+ mocks.compileAgentConfig.mockImplementation(async (input: AgentSourceManifest) => {
+ if (input.agentId === "research") {
+ return createConfig({
+ description: "Research subagent",
+ name: "research",
+ experimental: {
+ workflow: {
+ world: "@workflow/world-postgres",
+ },
+ },
+ });
+ }
+
+ return createConfig({ name: "root" });
+ });
+ mocks.loadModuleBackedDefinition.mockResolvedValue({
+ description: "Research subagent",
+ model: "openai/gpt-5.5",
+ });
+
+ await expect(compileAgentManifest(manifest)).rejects.toThrow(
+ 'Remove "experimental.workflow" from "research"',
+ );
+ });
+});
+
+function createConfig(
+ input: Pick<CompiledAgentDefinition, "name"> &
+ Partial<Pick<CompiledAgentDefinition, "description" | "experimental">>,
+): CompiledAgentDefinition {
+ const config: CompiledAgentDefinition = {
+ model: {
+ id: "openai/gpt-5.5",
+ routing: classifyModelRouting("openai/gpt-5.5"),
+ },
+ name: input.name,
+ };
+
+ if (input.description !== undefined) {
+ config.description = input.description;
+ }
+ if (input.experimental !== undefined) {
+ config.experimental = input.experimental;
+ }
+
+ return config;
+}
diff --git a/packages/eve/src/compiler/normalize-manifest.ts b/packages/eve/src/compiler/normalize-manifest.ts
index 625e57d37..6656fddee 100644
--- a/packages/eve/src/compiler/normalize-manifest.ts
+++ b/packages/eve/src/compiler/normalize-manifest.ts
@@ -55,9 +55,17 @@ export async function compileAgentManifest(
async function compileAgentNodeManifest(
manifest: AgentSourceManifest,
context: ManifestCompileContext,
- options: { readonly externalDependencies?: readonly string[] } = {},
+ options: {
+ readonly externalDependencies?: readonly string[];
+ readonly allowWorkflowConfig?: boolean;
+ } = {},
): Promise<CompiledAgentNodeManifest> {
const rawConfig = await compileAgentConfig(manifest, context);
+ if (options.allowWorkflowConfig === false && rawConfig.experimental?.workflow !== undefined) {
+ throw new Error(
+ `Workflow runtime configuration is only supported on the root agent config. Remove "experimental.workflow" from "${manifest.agentId}".`,
+ );
+ }
const externalDependencies = mergeExternalDependencies(
options.externalDependencies,
rawConfig.build?.externalDependencies,
diff --git a/packages/eve/src/compiler/normalize-subagent.ts b/packages/eve/src/compiler/normalize-subagent.ts
index 8b6c82d41..85c477a50 100644
--- a/packages/eve/src/compiler/normalize-subagent.ts
+++ b/packages/eve/src/compiler/normalize-subagent.ts
@@ -32,7 +32,10 @@ import type { JsonObject } from "#shared/json.js";
export type CompileAgentNodeManifestFn = (
manifest: AgentSourceManifest,
context: ManifestCompileContext,
- options?: { readonly externalDependencies?: readonly string[] },
+ options?: {
+ readonly externalDependencies?: readonly string[];
+ readonly allowWorkflowConfig?: boolean;
+ },
) => Promise<CompiledAgentNodeManifest>;
/**
@@ -167,7 +170,7 @@ async function compileSubagent(input: {
appRoot: input.appRoot,
},
input.context,
- { externalDependencies: input.externalDependencies },
+ { allowWorkflowConfig: false, externalDependencies: input.externalDependencies },
);
const description = agent.config.description;
diff --git a/packages/eve/src/internal/application/compiled-artifacts.test.ts b/packages/eve/src/internal/application/compiled-artifacts.test.ts
new file mode 100644
index 000000000..3c0ecf0d9
--- /dev/null
+++ b/packages/eve/src/internal/application/compiled-artifacts.test.ts
@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+
+import { COMPILE_METADATA_KIND, COMPILE_METADATA_VERSION } from "#compiler/artifacts.js";
+import type { CompileAgentResult } from "#compiler/compile-agent.js";
+import { createCompiledAgentManifest } from "#compiler/manifest.js";
+import { createCompiledArtifactsBootstrapSource } from "#internal/application/compiled-artifacts.js";
+import { classifyModelRouting } from "#internal/classify-model-routing.js";
+
+describe("createCompiledArtifactsBootstrapSource", () => {
+ it("generates static Workflow world bootstrap imports from compiled config", async () => {
+ const source = await createCompiledArtifactsBootstrapSource({
+ compileResult: {
+ manifest: createCompiledAgentManifest({
+ agentRoot: "/app/agent",
+ appRoot: "/app",
+ config: {
+ model: {
+ id: "openai/gpt-5.5",
+ routing: classifyModelRouting("openai/gpt-5.5"),
+ },
+ name: "app",
+ experimental: {
+ workflow: {
+ world: "@acme/eve-world",
+ },
+ },
+ },
+ }),
+ metadata: {
+ compile: { moduleMap: { path: "module-map.mjs", sha256: "0" } },
+ discovery: {
+ diagnostics: { path: "diagnostics.json", sha256: "0" },
+ manifest: { path: "manifest.json", sha256: "0" },
+ sourceGraphHash: "0",
+ summary: { errors: 0, warnings: 0 },
+ },
+ generator: { name: "eve", version: "0.0.0-test" },
+ kind: COMPILE_METADATA_KIND,
+ status: "ready",
+ version: COMPILE_METADATA_VERSION,
+ },
+ } as CompileAgentResult,
+ installModulePath: "/eve/src/runtime/loaders/bundled-artifacts.ts",
+ metadata: {
+ compile: { moduleMap: { path: "module-map.mjs", sha256: "0" } },
+ discovery: {
+ diagnostics: { path: "diagnostics.json", sha256: "0" },
+ manifest: { path: "manifest.json", sha256: "0" },
+ sourceGraphHash: "0",
+ summary: { errors: 0, warnings: 0 },
+ },
+ generator: { name: "eve", version: "0.0.0-test" },
+ kind: COMPILE_METADATA_KIND,
+ status: "ready",
+ version: COMPILE_METADATA_VERSION,
+ },
+ moduleMapPath: "/app/.eve/compile/compiled-artifacts-bootstrap.mjs",
+ });
+
+ expect(source).toContain('import * as workflowWorldModule from "@acme/eve-world";');
+ expect(source).toContain(
+ "await installConfiguredWorkflowWorld({ module: workflowWorldModule });",
+ );
+ });
+});
diff --git a/packages/eve/src/internal/application/compiled-artifacts.ts b/packages/eve/src/internal/application/compiled-artifacts.ts
index 5a8cba6dd..3883433db 100644
--- a/packages/eve/src/internal/application/compiled-artifacts.ts
+++ b/packages/eve/src/internal/application/compiled-artifacts.ts
@@ -7,6 +7,7 @@ import type { CompileAgentResult } from "#compiler/compile-agent.js";
import { createCompiledModuleMapSource } from "#compiler/module-map.js";
import { stringifyEsmImportSpecifier } from "#internal/application/import-specifier.js";
import { resolvePackageSourceFilePath } from "#internal/application/package.js";
+import type { AgentWorkflowWorldDefinition } from "#shared/agent-definition.js";
/**
* Paths to the generated compiled-artifacts files shared by Nitro and the
@@ -102,12 +103,13 @@ function stripCompiledModuleMapExports(source: string): string {
.replace(/\nexport default moduleMap;\n?$/, "\n");
}
-async function createCompiledArtifactsBootstrapSource(input: {
+export async function createCompiledArtifactsBootstrapSource(input: {
compileResult: CompileAgentResult;
installModulePath: string;
metadata: CompileMetadata;
moduleMapPath: string;
}): Promise<string> {
+ const workflowWorld = input.compileResult.manifest.config.experimental?.workflow?.world;
const moduleMapSource = stripCompiledModuleMapExports(
createCompiledModuleMapSource({
importSpecifierStyle: "absolute",
@@ -119,6 +121,7 @@ async function createCompiledArtifactsBootstrapSource(input: {
return [
"// Generated by eve. Do not edit by hand.",
`import { installBundledCompiledArtifacts } from ${stringifyEsmImportSpecifier(input.installModulePath)};`,
+ ...createWorkflowWorldBootstrapImports(workflowWorld),
"",
moduleMapSource,
"",
@@ -135,6 +138,7 @@ async function createCompiledArtifactsBootstrapSource(input: {
"}",
"",
"installCompiledArtifactsBootstrap();",
+ ...createWorkflowWorldBootstrapBody(workflowWorld),
"",
"// Default export satisfies the Nitro plugin contract so this file",
"// can be used directly as a Nitro plugin without a separate wrapper.",
@@ -150,6 +154,29 @@ async function createCompiledArtifactsBootstrapSource(input: {
].join("\n");
}
+function createWorkflowWorldBootstrapImports(
+ world: AgentWorkflowWorldDefinition | undefined,
+): string[] {
+ if (world === undefined) {
+ return [];
+ }
+
+ return [
+ `import * as workflowWorldModule from ${stringifyEsmImportSpecifier(world)};`,
+ `import { installConfiguredWorkflowWorld } from ${stringifyEsmImportSpecifier(resolvePackageSourceFilePath("src/internal/workflow/configure-world.ts"))};`,
+ ];
+}
+
+function createWorkflowWorldBootstrapBody(
+ world: AgentWorkflowWorldDefinition | undefined,
+): string[] {
+ if (world === undefined) {
+ return [];
+ }
+
+ return ["", "await installConfiguredWorkflowWorld({ module: workflowWorldModule });"];
+}
+
function createInstrumentationPluginSource(input: {
agentName: string;
instrumentationPath: string;
diff --git a/packages/eve/src/internal/authored-definition/core.test.ts b/packages/eve/src/internal/authored-definition/core.test.ts
new file mode 100644
index 000000000..c5ea611ad
--- /dev/null
+++ b/packages/eve/src/internal/authored-definition/core.test.ts
@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+
+import { normalizeAgentDefinition } from "#internal/authored-definition/core.js";
+
+const FAILURE_MESSAGE = "Expected the agent config to match the public eve shape.";
+
+describe("normalizeAgentDefinition", () => {
+ it("accepts a workflow world package name", () => {
+ const definition = normalizeAgentDefinition(
+ {
+ model: "openai/gpt-5.5",
+ experimental: {
+ workflow: {
+ world: "@workflow/world-postgres",
+ },
+ },
+ },
+ FAILURE_MESSAGE,
+ );
+
+ expect(definition.experimental?.workflow).toEqual({ world: "@workflow/world-postgres" });
+ });
+
+ it("rejects non-string workflow world values", () => {
+ expect(() =>
+ normalizeAgentDefinition(
+ {
+ model: "openai/gpt-5.5",
+ experimental: {
+ workflow: {
+ world: {
+ module: "@acme/eve-world",
+ },
+ },
+ },
+ },
+ FAILURE_MESSAGE,
+ ),
+ ).toThrow(FAILURE_MESSAGE);
+ });
+
+ it("rejects empty workflow world package names", () => {
+ expect(() =>
+ normalizeAgentDefinition(
+ {
+ model: "openai/gpt-5.5",
+ experimental: {
+ workflow: {
+ world: " ",
+ },
+ },
+ },
+ FAILURE_MESSAGE,
+ ),
+ ).toThrow('"experimental.workflow.world" must be a non-empty package name');
+ });
+});
diff --git a/packages/eve/src/internal/authored-definition/core.ts b/packages/eve/src/internal/authored-definition/core.ts
index 6d031988b..062d25526 100644
--- a/packages/eve/src/internal/authored-definition/core.ts
+++ b/packages/eve/src/internal/authored-definition/core.ts
@@ -1,4 +1,8 @@
-import type { AgentDefinition, AgentBuildDefinition } from "#public/definitions/agent.js";
+import type {
+ AgentDefinition,
+ AgentBuildDefinition,
+ AgentWorkflowDefinition,
+} from "#public/definitions/agent.js";
import type { ScheduleDefinition, ScheduleRunHandler } from "#public/definitions/schedule.js";
import type { SkillDefinition, SkillFileContent } from "#public/definitions/skill.js";
import type { InstructionsDefinition } from "#public/definitions/instructions.js";
@@ -116,18 +120,49 @@ function normalizeAgentBuildDefinition(
return normalizedDefinition;
}
+function normalizeAgentWorkflowDefinition(
+ value: unknown,
+ message: string,
+): AgentWorkflowDefinition {
+ const record = expectObjectRecord(value, message);
+ expectOnlyKnownKeys(record, ["world"], message);
+ const normalizedDefinition: Mutable<AgentWorkflowDefinition> = {};
+
+ if (record.world !== undefined) {
+ normalizedDefinition.world = normalizeAgentWorkflowWorldDefinition(record.world, message);
+ }
+
+ return normalizedDefinition;
+}
+
+function normalizeAgentWorkflowWorldDefinition(
+ value: unknown,
+ message: string,
+): NonNullable<AgentWorkflowDefinition["world"]> {
+ const packageName = expectString(value, message);
+ if (packageName.trim() === "") {
+ throw new Error(`${message} "experimental.workflow.world" must be a non-empty package name.`);
+ }
+
+ return packageName;
+}
+
function normalizeAgentExperimentalDefinition(
value: unknown,
message: string,
): NonNullable<NormalizedAgentDefinition["experimental"]> {
const record = expectObjectRecord(value, message);
- expectOnlyKnownKeys(record, ["codeMode"], message);
+ expectOnlyKnownKeys(record, ["codeMode", "workflow"], message);
const normalizedDefinition: Mutable<NonNullable<NormalizedAgentDefinition["experimental"]>> = {};
if (record.codeMode !== undefined) {
normalizedDefinition.codeMode = expectBoolean(record.codeMode, message);
}
+ if (record.workflow !== undefined) {
+ normalizedDefinition.workflow = normalizeAgentWorkflowDefinition(record.workflow, message);
+ }
+
return normalizedDefinition;
}
diff --git a/packages/eve/src/internal/workflow/configure-world.test.ts b/packages/eve/src/internal/workflow/configure-world.test.ts
new file mode 100644
index 000000000..4c2c4fcfc
--- /dev/null
+++ b/packages/eve/src/internal/workflow/configure-world.test.ts
@@ -0,0 +1,72 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { installConfiguredWorkflowWorld } from "#internal/workflow/configure-world.js";
+
+const mocks = vi.hoisted(() => ({
+ setWorld: vi.fn(),
+}));
+
+vi.mock("#compiled/@workflow/core/runtime.js", () => ({
+ setWorld: mocks.setWorld,
+}));
+
+describe("installConfiguredWorkflowWorld", () => {
+ beforeEach(() => {
+ mocks.setWorld.mockClear();
+ });
+
+ it("installs and starts a world from the module default export", async () => {
+ const world = createMockWorld();
+ const createWorld = vi.fn(() => world);
+
+ await expect(
+ installConfiguredWorkflowWorld({
+ module: { default: createWorld },
+ }),
+ ).resolves.toBe(world);
+
+ expect(createWorld).toHaveBeenCalledOnce();
+ expect(mocks.setWorld).toHaveBeenCalledWith(world);
+ expect(world.start).toHaveBeenCalledOnce();
+ });
+
+ it("falls back to a createWorld export when no export name is configured", async () => {
+ const world = createMockWorld();
+
+ await installConfiguredWorkflowWorld({
+ module: { createWorld: () => world },
+ });
+
+ expect(mocks.setWorld).toHaveBeenCalledWith(world);
+ });
+
+ it("rejects modules without a default or createWorld factory", async () => {
+ await expect(
+ installConfiguredWorkflowWorld({
+ module: {},
+ }),
+ ).rejects.toThrow(
+ 'Configured Workflow world module must export a default function or "createWorld" function.',
+ );
+
+ expect(mocks.setWorld).not.toHaveBeenCalled();
+ });
+
+ it("rejects factories that do not return a Workflow World", async () => {
+ await expect(
+ installConfiguredWorkflowWorld({
+ module: { default: () => ({}) },
+ }),
+ ).rejects.toThrow("Configured Workflow world factory did not return a valid World.");
+
+ expect(mocks.setWorld).not.toHaveBeenCalled();
+ });
+});
+
+function createMockWorld() {
+ return {
+ createQueueHandler: vi.fn(),
+ events: {},
+ start: vi.fn(),
+ };
+}
diff --git a/packages/eve/src/internal/workflow/configure-world.ts b/packages/eve/src/internal/workflow/configure-world.ts
new file mode 100644
index 000000000..547bb7283
--- /dev/null
+++ b/packages/eve/src/internal/workflow/configure-world.ts
@@ -0,0 +1,64 @@
+import { setWorld } from "#compiled/@workflow/core/runtime.js";
+import type { World } from "#compiled/@workflow/world/index.js";
+
+export interface ConfiguredWorkflowWorldModule {
+ readonly [name: string]: unknown;
+ readonly default?: unknown;
+}
+
+export interface InstallConfiguredWorkflowWorldInput {
+ readonly module: ConfiguredWorkflowWorldModule | (() => unknown);
+}
+
+/**
+ * Installs a Workflow world selected by the compiled agent config.
+ */
+export async function installConfiguredWorkflowWorld(
+ input: InstallConfiguredWorkflowWorldInput,
+): Promise<World> {
+ const world = await createWorkflowWorld(input);
+ setWorld(world);
+ await world.start?.();
+ return world;
+}
+
+async function createWorkflowWorld(input: InstallConfiguredWorkflowWorldInput): Promise<World> {
+ const factory = resolveWorkflowWorldFactory(input);
+ const world = await factory();
+
+ if (!isWorkflowWorld(world)) {
+ throw new Error("Configured Workflow world factory did not return a valid World.");
+ }
+
+ return world;
+}
+
+function resolveWorkflowWorldFactory(input: InstallConfiguredWorkflowWorldInput): () => unknown {
+ if (typeof input.module === "function") {
+ return input.module;
+ }
+
+ if (typeof input.module.default === "function") {
+ return input.module.default as () => unknown;
+ }
+
+ if (typeof input.module.createWorld === "function") {
+ return input.module.createWorld as () => unknown;
+ }
+
+ throw new Error(
+ 'Configured Workflow world module must export a default function or "createWorld" function.',
+ );
+}
+
+function isWorkflowWorld(value: unknown): value is World {
+ return (
+ typeof value === "object" &&
+ value !== null &&
+ "createQueueHandler" in value &&
+ typeof value.createQueueHandler === "function" &&
+ "events" in value &&
+ typeof value.events === "object" &&
+ value.events !== null
+ );
+}
diff --git a/packages/eve/src/public/definitions/agent.ts b/packages/eve/src/public/definitions/agent.ts
index 6025bea2d..525bb7ab8 100644
--- a/packages/eve/src/public/definitions/agent.ts
+++ b/packages/eve/src/public/definitions/agent.ts
@@ -5,6 +5,8 @@ export type {
AgentModelOptionsDefinition,
AgentBuildDefinition,
AgentExperimentalDefinition,
+ AgentWorkflowDefinition,
+ AgentWorkflowWorldDefinition,
PublicAgentModelDefinition as AgentModelDefinition,
PublicAgentCompactionDefinition as AgentCompactionDefinition,
} from "#shared/agent-definition.js";
diff --git a/packages/eve/src/public/index.ts b/packages/eve/src/public/index.ts
index e967b874b..30557a12c 100644
--- a/packages/eve/src/public/index.ts
+++ b/packages/eve/src/public/index.ts
@@ -8,6 +8,8 @@ export {
type AgentExperimentalDefinition,
type AgentModelDefinition,
type AgentModelOptionsDefinition,
+ type AgentWorkflowDefinition,
+ type AgentWorkflowWorldDefinition,
defineAgent,
} from "#public/definitions/agent.js";
export {
diff --git a/packages/eve/src/shared/agent-definition.ts b/packages/eve/src/shared/agent-definition.ts
index 805f7b766..d98891e23 100644
--- a/packages/eve/src/shared/agent-definition.ts
+++ b/packages/eve/src/shared/agent-definition.ts
@@ -109,6 +109,11 @@ export interface AgentExperimentalDefinition {
* environment variable (`"1"` enables it) for backwards compatibility.
*/
readonly codeMode?: boolean;
+ /**
+ * Durable Workflow runtime configuration. Root agents may use this to select
+ * the Workflow world backing sessions and runs.
+ */
+ readonly workflow?: AgentWorkflowDefinition;
}
/**
@@ -130,6 +135,26 @@ export interface AgentBuildDefinition {
readonly externalDependencies?: string[];
}
+/**
+ * Package name for a Workflow world module.
+ *
+ * The package must export either a default factory or a `createWorld` factory.
+ * The factory is called at runtime so credentials and deployment-specific
+ * options can come from environment variables instead of the compiled manifest.
+ */
+export type AgentWorkflowWorldDefinition = string;
+
+/**
+ * Advanced durable-runtime configuration for eve's Workflow SDK integration.
+ */
+export interface AgentWorkflowDefinition {
+ /**
+ * Workflow world module used for durable workflow storage, queueing, hooks,
+ * and streaming.
+ */
+ readonly world?: AgentWorkflowWorldDefinition;
+}
+
/**
* Compiled-side agent definition. Carries a `name` because the compiler
* stamps the path-derived `agentId` onto every compiled agent node.