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.mdnew file mode 100644index 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.mdindex 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.mdindex 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 aNitro 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 crashdiff --git a/docs/guides/deployment.md b/docs/guides/deployment.mdindex 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 hOn 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 OuSelf-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.mdindex 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.tsnew file mode 100644index 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.tsindex 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> = zbuild: 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.