Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

refactor(eve): remove workflow public opt-in (#395)

Rui02ed501d1d7f
diff --git a/.changeset/remove-experimental-workflow-export.md b/.changeset/remove-experimental-workflow-export.md
new file mode 100644
index 000000000..1d9c14679
--- /dev/null
+++ b/.changeset/remove-experimental-workflow-export.md
@@ -0,0 +1,5 @@
+---
+"eve": minor
+---
+
+Remove the experimental `ExperimentalWorkflow` opt-in marker from the public `eve/tools` API and remove the dynamic Workflow docs. The internal runtime path remains in place for existing compiled manifests, but authored apps can no longer enable the tool through the public API.
diff --git a/docs/concepts/default-harness.md b/docs/concepts/default-harness.md
index b021bf47c..6b11ce4c9 100644
--- a/docs/concepts/default-harness.md
+++ b/docs/concepts/default-harness.md
@@ -87,16 +87,6 @@ Three moves shape the harness. The right one depends on whether the model should
- **Disable** when the model should not have the capability at all. A `disableTool()` sentinel removes the built-in, and the model never sees it. Reach for this to lock down `bash` or `web_fetch` in an agent that should not run shell commands or fetch arbitrary URLs.
- **Author a new tool** when you want a capability the harness does not ship. Give it a fresh slug under `agent/tools/` and it joins the built-ins instead of replacing one. See [Tools](../tools) for the authoring model.
-## 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`:
-
-```ts
-export { ExperimentalWorkflow as default } from "eve/tools";
-```
-
-With it on, the model can orchestrate the agent's own subagents from model-authored JavaScript, all as one durable step. See [Dynamic workflows](../guides/dynamic-workflows).
-
## What to read next
- [Tools](../tools): define your own tools, gate them on approval, and shape their output with `toModelOutput`
diff --git a/docs/guides/dynamic-workflows.md b/docs/guides/dynamic-workflows.md
deleted file mode 100644
index e3881c3e6..000000000
--- a/docs/guides/dynamic-workflows.md
+++ /dev/null
@@ -1,70 +0,0 @@
----
-title: "Dynamic Workflows"
-description: "The experimental Workflow tool: let the model orchestrate its own subagents from model-authored JavaScript as one durable step."
----
-
-The experimental `Workflow` tool lets the model write JavaScript that coordinates the agent's own subagents as a single durable step. The program can run them in sequence, feed one result into the next, fan out over a list, and combine the results. You enable the capability and the model decides and runs the orchestration.
-
-A single turn can already call several subagents, and parallel tool calls dispatch concurrently. What a workflow adds is _programmatic_ coordination. The program decides how many subagents to run based on an earlier result, which output feeds which call, and how to combine everything. That is logic the model cannot express as a few one-off calls.
-
-## 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`.
-
-```ts title="agent/tools/workflow.ts"
-export { ExperimentalWorkflow as default } from "eve/tools";
-```
-
-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:
-
-```ts title="agent/subagents/analyst/agent.ts"
-import { defineAgent } from "eve";
-
-export default defineAgent({
- description: "Analyzes one metric: queries, computes, writes a short finding.",
- model: "anthropic/claude-opus-4.8",
-});
-```
-
-When asked for a weekly business review, the model picks the metrics, runs one `analyst` per metric in parallel, and combines the findings. The program below is the kind of JavaScript the model authors. It fans `analyst` out over a runtime-decided list of metrics and merges the results:
-
-```js
-const metrics = ["revenue", "signups", "churn"];
-const findings = await Promise.all(
- metrics.map((metric) => tools.analyst({ message: `Summarize last week's ${metric}.` })),
-);
-return findings.join("\n\n");
-```
-
-Each `tools.analyst(...)` call dispatches a child subagent, so the parent stream records one `subagent.called` per metric and one `subagent.completed` as each finishes:
-
-```json
-{ "type": "subagent.called", "data": { "name": "analyst", "toolName": "analyst", "callId": "call_1", "childSessionId": "ses_a1", "sequence": 0 } }
-{ "type": "subagent.called", "data": { "name": "analyst", "toolName": "analyst", "callId": "call_2", "childSessionId": "ses_a2", "sequence": 1 } }
-{ "type": "subagent.called", "data": { "name": "analyst", "toolName": "analyst", "callId": "call_3", "childSessionId": "ses_a3", "sequence": 2 } }
-{ "type": "subagent.completed", "data": { "subagentName": "analyst", "callId": "call_1", "output": "..." } }
-{ "type": "subagent.completed", "data": { "subagentName": "analyst", "callId": "call_2", "output": "..." } }
-{ "type": "subagent.completed", "data": { "subagentName": "analyst", "callId": "call_3", "output": "..." } }
-```
-
-## What a workflow can orchestrate
-
-A workflow reaches only this agent's own agents: the built-in `agent` (a copy of itself), declared [subagents](../subagents), and [remote agents](./remote-agents). That is the whole list. No files, network, shell, skills, or connections. A workflow is a coordination layer over subagents, not a place to do other work. Each call can still request structured output via `outputSchema`, exactly like a direct subagent delegation.
-
-## Where the JavaScript runs
-
-The orchestration code never touches the agent's process. The runtime hands the program text to a small isolated JavaScript engine (a QuickJS sandbox) and runs it there. Nothing from the host realm crosses in, so there is no `process`, no `globalThis` from the agent, and no `import`/`require`. The program can reach exactly two things, the agent functions bridged in as `tools.<name>` and the ordinary language built-ins.
-
-That is an allowlist, not a denylist. The sandbox cannot read files, open a socket, or see an environment variable because those are not present, not because each one is blocked in turn. When the program calls an agent function, that call bridges back out to the runtime, which dispatches it exactly like a direct delegation. The orchestration glue stays inside the sandbox.
-
-## Durability, approvals, and observability
-
-- **Durable.** The whole orchestration counts as one step. Subagents dispatched together run concurrently, and if a run parks (suspends durably without holding compute; see [Execution model & durability](../concepts/execution-model-and-durability)) on a long-running or human-gated child, it resumes where it left off after a restart.
-- **Approval-safe.** A subagent that needs human approval (HITL, human-in-the-loop) mid-run surfaces its request to the user, and the workflow picks back up once that is answered, same as direct delegation.
-- **Observable.** Every orchestrated subagent emits the usual `subagent.called` / `subagent.completed` events on the parent stream and gets its own child session and stream. The telemetry matches direct delegation, so existing dashboards and cost attribution keep working.
-
-## What to read next
-
-- Declare the subagents a workflow orchestrates → [Subagents](../subagents)
-- Call another deployment as one of those agents → [Remote agents](./remote-agents)
-- The `agent/tools/` opt-in mechanism → [Default harness](../concepts/default-harness)
diff --git a/docs/guides/meta.json b/docs/guides/meta.json
index f30738049..be12e6fd8 100644
--- a/docs/guides/meta.json
+++ b/docs/guides/meta.json
@@ -8,7 +8,6 @@
"session-context",
"state",
"dynamic-capabilities",
- "dynamic-workflows",
"remote-agents",
"dev-tui",
"frontend",
diff --git a/docs/guides/remote-agents.md b/docs/guides/remote-agents.md
index bc68da496..3dc70d288 100644
--- a/docs/guides/remote-agents.md
+++ b/docs/guides/remote-agents.md
@@ -60,5 +60,4 @@ Both failure paths surface to the parent as a failed tool result, so the caller
## What to read next
- Local delegation and the isolation boundary → [Subagents](../subagents)
-- Have the model orchestrate remote agents programmatically → [Dynamic workflows](./dynamic-workflows)
- Securing the receiving deployment → [Auth & route protection](./auth-and-route-protection)
diff --git a/docs/reference/typescript-api.md b/docs/reference/typescript-api.md
index ebcc49a1d..af9d3c9d9 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. `AgentWorkflowDefinition` and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape.
+A few non-`define*` helpers round out the set: `disableTool` 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. `AgentWorkflowDefinition` and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape.
## Runtime context (`ctx`)
@@ -68,31 +68,31 @@ 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/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` |
+| `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/evals` | `defineEval`, `defineEvalConfig`, `mockModel`, eval types |
+| `eve/evals/expect` | `includes`, `equals`, `matches`, `similarity` |
+| `eve/evals/reporters` | `Braintrust`, `JUnit`, `EvalReporter` |
+| `eve/evals/loaders` | `loadJson`, `loadYaml` |
+| `eve/react`, `eve/vue`, `eve/svelte` | `useEveAgent` |
+| `eve/next`, `eve/nuxt`, `eve/sveltekit` | framework bundler plugins |
+| [`eve/client`](../guides/client/overview) | `Client`, `ClientSession` |
Exported types ship from the same entrypoint as the helper they describe (for example `ToolDefinition` and `ToolContext` from `eve/tools`). For the exhaustive list, read `packages/eve/src/public/index.ts`.
diff --git a/docs/subagents.mdx b/docs/subagents.mdx
index cb5f1bb6c..dedc7c124 100644
--- a/docs/subagents.mdx
+++ b/docs/subagents.mdx
@@ -99,4 +99,3 @@ Split out a subagent when the task needs a different prompt or specialist role,
## What to read next
- [Remote agents](./guides/remote-agents): call another eve deployment as a subagent.
-- [Dynamic workflows](./guides/dynamic-workflows): have the model orchestrate its subagents programmatically (fan-out, map-reduce).
diff --git a/e2e/fixtures/agent-subagents/agent/tools/workflow.ts b/e2e/fixtures/agent-subagents/agent/tools/workflow.ts
index 783084219..4b31fcd00 100644
--- a/e2e/fixtures/agent-subagents/agent/tools/workflow.ts
+++ b/e2e/fixtures/agent-subagents/agent/tools/workflow.ts
@@ -1 +1 @@
-export { ExperimentalWorkflow as default } from "eve/tools";
+export default Object.freeze({ kind: "eve:enable-workflow-tool" });
diff --git a/packages/eve/src/harness/types.ts b/packages/eve/src/harness/types.ts
index f447588dd..4cc81f903 100644
--- a/packages/eve/src/harness/types.ts
+++ b/packages/eve/src/harness/types.ts
@@ -192,7 +192,7 @@ 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 `Workflow` marker).
+ * in the compiled manifest.
* Defaults to `false`.
*/
readonly workflow?: boolean;
diff --git a/packages/eve/src/internal/authored-definition/schema-backed.test.ts b/packages/eve/src/internal/authored-definition/schema-backed.test.ts
index eb0669184..8a426c1fe 100644
--- a/packages/eve/src/internal/authored-definition/schema-backed.test.ts
+++ b/packages/eve/src/internal/authored-definition/schema-backed.test.ts
@@ -1,12 +1,7 @@
import { describe, expect, it } from "vitest";
import { z } from "#compiled/zod/index.js";
-import {
- defineTool,
- defineDynamic,
- disableTool,
- ExperimentalWorkflow,
-} from "#public/definitions/tool.js";
+import { defineTool, defineDynamic, disableTool } from "#public/definitions/tool.js";
import { once } from "#public/tools/approval/approval-helpers.js";
import { normalizeToolDefinition } from "#internal/authored-definition/schema-backed.js";
@@ -40,8 +35,11 @@ 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 an enable-workflow entry for the internal workflow marker shape", () => {
+ const entry = normalizeToolDefinition(
+ Object.freeze({ kind: "eve:enable-workflow-tool" }),
+ FAILURE_MESSAGE,
+ );
expect(entry).toEqual({ kind: "enable-workflow" });
});
diff --git a/packages/eve/src/internal/authored-definition/schema-backed.ts b/packages/eve/src/internal/authored-definition/schema-backed.ts
index 869f5b0de..5989b89e7 100644
--- a/packages/eve/src/internal/authored-definition/schema-backed.ts
+++ b/packages/eve/src/internal/authored-definition/schema-backed.ts
@@ -1,4 +1,4 @@
-import { isDisabledToolSentinel, isEnableWorkflowToolSentinel } from "#public/definitions/tool.js";
+import { isDisabledToolSentinel } from "#public/definitions/tool.js";
import {
expectFunction,
expectObjectRecord,
@@ -19,6 +19,19 @@ type NormalizedAuthoredTool = Readonly<Omit<InternalToolDefinitionWithExecuteFn,
type MutableNormalizedAuthoredTool = {
-readonly [K in keyof NormalizedAuthoredTool]: NormalizedAuthoredTool[K];
};
+const ENABLE_WORKFLOW_TOOL_SENTINEL_KIND = "eve:enable-workflow-tool";
+
+interface EnableWorkflowToolSentinel {
+ readonly kind: typeof ENABLE_WORKFLOW_TOOL_SENTINEL_KIND;
+}
+
+function isEnableWorkflowToolSentinel(value: unknown): value is EnableWorkflowToolSentinel {
+ return (
+ typeof value === "object" &&
+ value !== null &&
+ (value as { kind?: unknown }).kind === ENABLE_WORKFLOW_TOOL_SENTINEL_KIND
+ );
+}
/**
* Result of normalizing one authored tool default export. Either a real tool
diff --git a/packages/eve/src/public/definitions/tool.ts b/packages/eve/src/public/definitions/tool.ts
index 277899989..30462fcf2 100644
--- a/packages/eve/src/public/definitions/tool.ts
+++ b/packages/eve/src/public/definitions/tool.ts
@@ -299,48 +299,3 @@ export function isDisabledToolSentinel(value: unknown): value is DisabledToolSen
(value as { kind?: unknown }).kind === DISABLED_TOOL_SENTINEL_KIND
);
}
-
-/**
- * Marker discriminator written into the {@link ExperimentalWorkflow} opt-in
- * sentinel.
- */
-const ENABLE_WORKFLOW_TOOL_SENTINEL_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.
- */
-export interface EnableWorkflowToolSentinel {
- readonly kind: typeof ENABLE_WORKFLOW_TOOL_SENTINEL_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`:
- *
- * ```ts
- * export { ExperimentalWorkflow as default } from "eve/tools";
- * ```
- *
- * The capability is experimental. The resulting model-facing tool is still
- * called `Workflow`.
- */
-export const ExperimentalWorkflow: EnableWorkflowToolSentinel = Object.freeze({
- kind: ENABLE_WORKFLOW_TOOL_SENTINEL_KIND,
-});
-
-/**
- * Type guard: returns whether `value` is the {@link ExperimentalWorkflow}
- * opt-in sentinel.
- */
-export function isEnableWorkflowToolSentinel(value: unknown): value is EnableWorkflowToolSentinel {
- return (
- typeof value === "object" &&
- value !== null &&
- (value as { kind?: unknown }).kind === ENABLE_WORKFLOW_TOOL_SENTINEL_KIND
- );
-}
diff --git a/packages/eve/src/public/tools/index.ts b/packages/eve/src/public/tools/index.ts
index 9dff3822c..3e7a57478 100644
--- a/packages/eve/src/public/tools/index.ts
+++ b/packages/eve/src/public/tools/index.ts
@@ -4,18 +4,15 @@
export {
type DisabledToolSentinel,
- type EnableWorkflowToolSentinel,
defineDynamic,
defineTool,
disableTool,
isDisabledToolSentinel,
- isEnableWorkflowToolSentinel,
type ToolAuthOptions,
type ToolAuthProvider,
type ToolDefinition,
type ToolContext,
type ToolModelOutput,
- ExperimentalWorkflow,
} from "#public/definitions/tool.js";
export type { Approval, ApprovalContext, ApprovalStatus } from "#public/definitions/approval.js";
export type {