eve 0.29.4 → 0.30.0

package/docs/guides/dynamic-capabilities.md

@@ -1,9 +1,9 @@
 ---
 title: "Dynamic Capabilities"
-description: "Resolve models, tools, skills, and instructions at runtime: dynamic model selection, defineDynamic resolver events, execution order, and durable dynamic tools."
+description: "Resolve models, subagents, tools, skills, and instructions at runtime with defineDynamic resolver events."
 ---
 
-`defineDynamic` resolves the model, tools, skills, and instructions at runtime from a session event instead of declaring them up front. Reach for it when the right capability isn't known until the session starts, because it hinges on who the caller is, what tenant they belong to, feature flags, or external data. The [tools](../tools), [skills](../skills), and [instructions](../instructions) guides each point here for their dynamic form.
+`defineDynamic` resolves the model, subagents, tools, skills, and instructions at runtime from a session event instead of declaring them up front. Reach for it when the right capability isn't known until the session starts, because it hinges on who the caller is, what tenant they belong to, feature flags, or external data. The [subagents](../subagents), [tools](../tools), [skills](../skills), and [instructions](../instructions) guides each point here for their dynamic form.
 
 ## Dynamic models
 
@@ -16,10 +16,77 @@ uncached prices. See
 [agent configuration](../agent-config#choose-the-model-dynamically) for the
 full contract.
 
-`fallback` is model-only: the agent always needs exactly one model, and the
-compiled fallback anchors build-time metadata. Tools, skills, and instructions
-default by authoring a static entry (or returning `null`), so `fallback` on
-their `defineDynamic` export is a build error.
+The agent always needs exactly one model, so the compiled fallback anchors
+build-time metadata. Tools, skills, instructions, and subagents default by
+authoring a static entry (or returning `null`), so `fallback` on their
+`defineDynamic` export is a build error.
+
+## Dynamic subagents
+
+Wrap a declared subagent's own `agent.ts` in `defineDynamic` when its
+availability depends on the caller, tenant, environment, or a feature flag.
+Return the child definition to configure and expose it. Return `null` or
+`undefined` to omit it from the parent's model-visible tools.
+
+```ts title="agent/subagents/finance/agent.ts"
+import { defineAgent, defineDynamic } from "eve";
+
+export default defineDynamic({
+  events: {
+    "session.started": (_event, ctx) =>
+      ctx.session.auth.current?.attributes.plan === "enterprise"
+        ? defineAgent({
+            description: "Analyze financial and accounting data.",
+            model: "openai/gpt-5.5",
+          })
+        : null,
+  },
+});
+```
+
+eve always compiles the subagent's filesystem manifest, including its
+instructions, tools, skills, connections, sandbox, and nested subagents. When
+the resolver selects it, eve injects the returned agent configuration into that
+compiled manifest. Each resolution can return a different model or other
+runtime agent settings. Runtime-selected models must use string model IDs;
+build and Workflow-world configuration cannot be selected at runtime.
+
+A single-file remote subagent uses the same lifecycle. Return
+`defineRemoteAgent(...)` to expose the selected deployment, or nil to omit it:
+
+```ts title="agent/subagents/finance.ts"
+import { defineDynamic, defineRemoteAgent } from "eve";
+
+export default defineDynamic({
+  events: {
+    "session.started": (_event, ctx) =>
+      ctx.session.auth.current?.attributes.plan === "enterprise"
+        ? defineRemoteAgent({
+            description: "Analyze financial and accounting data.",
+            url: "https://finance-agent.example.com",
+          })
+        : null,
+  },
+});
+```
+
+The returned remote definition can change its URL, path, headers, auth,
+principal forwarding, and output schema. Function-valued URLs resolve when the
+dynamic event runs. Auth and headers remain lazy and resolve before each
+outbound request without entering durable workflow state.
+
+Dynamic subagents support `session.started` and `turn.started`. A turn selection
+shadows the session selection for that turn, including when the turn handler
+returns nil. If a resolver throws or returns an invalid definition, eve logs the
+failure and omits the subagent.
+
+The resolved set applies to local and remote direct delegation and the
+`Workflow` tool. eve
+also checks availability again before starting the child, so a stale or
+manually constructed call fails with `SUBAGENT_UNAVAILABLE`. Treat conditional
+availability as capability composition, not as the only authorization
+boundary: sensitive child tools still need their own authorization and
+approval checks.
 
 ## Dynamic tools
 
@@ -162,6 +229,7 @@ Both resolve before the prompt is assembled, so the model sees the right instruc
 
 ## What to read next
 
+- Conditionally expose a specialist → [Subagents](../subagents)
 - The static tool basics this builds on → [Tools](../tools)
 - The built-in tools and how to override them → [Default harness](../concepts/default-harness)
 - Authenticate a tool or connection to an external service → [Auth & route protection](./auth-and-route-protection)

package/docs/guides/frontend/nextjs.mdx

@@ -88,7 +88,7 @@ const agent = useEveAgent({
 });
 ```
 
-The default eve channel is fail-closed. With no `agent/channels/eve.ts` authored, eve registers `eveChannel({ auth: [vercelOidc(), localDev()] })`: `vercelOidc()` gets the first chance to resolve a Vercel caller, `localDev()` opens the remaining localhost requests, and everything else gets a `401`. To run your app's own auth policy, add `agent/channels/eve.ts`:
+The default eve channel is fail-closed. With no `agent/channels/eve.ts` authored, eve registers `eveChannel({ auth: [vercelOidc(), localDev(), placeholderAuth()] })`: `vercelOidc()` gets the first chance to resolve a Vercel caller, `localDev()` authenticates while the process is an `eve dev` or `vercel dev` server, and everything else gets a `401`. To run your app's own auth policy, add `agent/channels/eve.ts`:
 
 ```ts title="agent/channels/eve.ts"
 import { eveChannel } from "eve/channels/eve";

package/docs/guides/frontend/nuxt.mdx

@@ -60,7 +60,7 @@ async function handleSubmit() {
 </template>
 ```
 
-The default eve channel is fail-closed. With no `agent/channels/eve.ts` authored, eve registers `eveChannel({ auth: [vercelOidc(), localDev()] })`: `vercelOidc()` gets the first chance to resolve a Vercel caller, `localDev()` opens the remaining localhost requests, and everything else gets a `401`. To run your own auth policy, add `agent/channels/eve.ts`:
+The default eve channel is fail-closed. With no `agent/channels/eve.ts` authored, eve registers `eveChannel({ auth: [vercelOidc(), localDev(), placeholderAuth()] })`: `vercelOidc()` gets the first chance to resolve a Vercel caller, `localDev()` authenticates while the process is an `eve dev` or `vercel dev` server, and everything else gets a `401`. To run your own auth policy, add `agent/channels/eve.ts`:
 
 ```ts title="agent/channels/eve.ts"
 import { eveChannel } from "eve/channels/eve";

package/docs/guides/frontend/sveltekit.mdx

@@ -69,7 +69,7 @@ With the plugin in `vite.config.ts`, components call [`useEveAgent`](./use-eve-a
 </form>
 ```
 
-The default eve channel is fail-closed. With no `agent/channels/eve.ts` authored, eve registers `eveChannel({ auth: [vercelOidc(), localDev()] })`: `vercelOidc()` gets the first chance to resolve a Vercel caller, `localDev()` opens the remaining localhost requests, and everything else gets a `401`. To set your own auth policy, add `agent/channels/eve.ts`:
+The default eve channel is fail-closed. With no `agent/channels/eve.ts` authored, eve registers `eveChannel({ auth: [vercelOidc(), localDev(), placeholderAuth()] })`: `vercelOidc()` gets the first chance to resolve a Vercel caller, `localDev()` authenticates while the process is an `eve dev` or `vercel dev` server, and everything else gets a `401`. To set your own auth policy, add `agent/channels/eve.ts`:
 
 ```ts title="agent/channels/eve.ts"
 import { eveChannel } from "eve/channels/eve";

package/docs/guides/remote-agents.md

@@ -30,6 +30,39 @@ export default defineRemoteAgent({
 | `path`             | `string`                                      | No       | `/eve/v1/session` | Route appended to `url` for the create-session request.                                                                                                  |
 | `outputSchema`     | `StandardSchema \| JSON Schema`               | No       | none              | Structured return type the caller requires. Lowered to JSON Schema at compile time and enforced by the remote like any task-mode output schema.          |
 
+## Dynamic remote agents
+
+Wrap the file in `defineDynamic` when the target or its availability depends on
+the current session. Return `defineRemoteAgent(...)` to expose it and nil to
+omit it:
+
+```ts title="agent/subagents/weather.ts"
+import { defineDynamic, defineRemoteAgent } from "eve";
+
+export default defineDynamic({
+  events: {
+    "session.started": (_event, ctx) =>
+      ctx.session.auth.current?.attributes.region === "us"
+        ? defineRemoteAgent({
+            description: "Answers weather questions for US customers.",
+            url: "https://us-weather-agent.example.com",
+          })
+        : null,
+  },
+});
+```
+
+Dynamic remote subagents support `session.started` and `turn.started`. The
+returned definition may select different remote settings at either scope. eve
+resolves function-valued URLs when the event handler runs. Auth and headers
+remain lazy and resolve before each outbound request without entering durable
+workflow state.
+
+Author `auth` and `headers` directly in the `defineRemoteAgent({ ... })` object
+and keep their functions self-contained with module imports or environment
+variables. They are rehydrated outside the event handler, so they cannot close
+over `_event`, `ctx`, or handler-local values.
+
 ## Runtime URLs
 
 A string `url` is read at compile time and frozen into the build. When the target comes from a runtime env var — known only once the deployment runs — pass a function instead. eve calls it when it resolves the agent graph at runtime, so it can read `process.env`:

package/docs/reference/project-layout.md

@@ -91,7 +91,7 @@ agent/subagents/researcher/
 
 Rules:
 
-- `agent.ts` is required, and must declare a `description`. The parent reads it on the lowered subagent tool to decide when to delegate.
+- `agent.ts` is required. A static subagent's definition must declare a `description`; a dynamic subagent's resolver must return a definition with one. The parent reads it on the lowered subagent tool to decide when to delegate.
 - `instructions.md` / `instructions.ts` is optional (unlike the root agent, where it is required).
 - `connections/`, `hooks/`, `skills/`, `lib/`, `sandbox/`, and `tools/` are all supported, discovered from the subagent's own directory.
 - `channels/` and `schedules/` are not supported inside local subagents.

package/docs/reference/typescript-api.md

@@ -30,27 +30,27 @@ export default defineTool({
 
 ## The define\* helpers
 
-| Helper                                                | Import from                                   | Authored at                          | Guide                                                  |
-| ----------------------------------------------------- | --------------------------------------------- | ------------------------------------ | ------------------------------------------------------ |
-| `defineAgent`                                         | `eve`                                         | `agent/agent.ts`                     | [agent.ts](../agent-config)                            |
-| `defineTool`                                          | `eve/tools`                                   | `agent/tools/<name>.ts`              | [Tools](../tools)                                      |
-| `defineDynamic`                                       | `eve/tools`, `eve/skills`, `eve/instructions` | `agent/{tools,skills,instructions}/` | [Dynamic capabilities](../guides/dynamic-capabilities) |
-| `defineMcpClientConnection`                           | `eve/connections`                             | `agent/connections/<name>.ts`        | [MCP connections](../connections/mcp)                  |
-| `defineOpenAPIConnection`                             | `eve/connections`                             | `agent/connections/<name>.ts`        | [OpenAPI connections](../connections/openapi)          |
-| `defineChannel`                                       | `eve/channels`                                | `agent/channels/<name>.ts`           | [Custom channels](../channels/custom)                  |
-| `eveChannel`, `slackChannel`, and the other platforms | `eve/channels/<platform>`                     | `agent/channels/<platform>.ts`       | [Channels](../channels/overview)                       |
-| `defineSkill`                                         | `eve/skills`                                  | `agent/skills/<name>.ts`             | [Skills](../skills)                                    |
-| `defineInstructions`                                  | `eve/instructions`                            | `agent/instructions.ts`              | [Instructions](../instructions)                        |
-| `defineHook`                                          | `eve/hooks`                                   | `agent/hooks/<slug>.ts`              | [Hooks](../guides/hooks)                               |
-| `defineSchedule`                                      | `eve/schedules`                               | `agent/schedules/<name>.ts`          | [Schedules](../schedules)                              |
-| `defineState`                                         | `eve/context`                                 | tools, hooks, lifecycle              | [Session context](../guides/session-context)           |
-| `defineSandbox`                                       | `eve/sandbox`                                 | `agent/sandbox.ts`                   | [Sandbox](../sandbox)                                  |
-| `defineInstrumentation`                               | `eve/instrumentation`                         | `agent/instrumentation.ts`           | [instrumentation.ts](../guides/instrumentation)        |
-| `defineRemoteAgent`                                   | `eve`                                         | `agent/subagents/<id>/agent.ts`      | [Remote agents](../guides/remote-agents)               |
-| `defineEval`                                          | `eve/evals`                                   | `evals/*.eval.ts`                    | [Evals](../evals/overview)                             |
-| `defineEvalConfig`                                    | `eve/evals`                                   | `evals/evals.config.ts`              | [Evals](../evals/overview)                             |
-| `mockModel`                                           | `eve/evals`                                   | Deterministic fixture agent models   | [Evals](../evals/overview)                             |
-| `useEveAgent`                                         | `eve/react`, `eve/vue`, `eve/svelte`          | frontend                             | [Frontend](../guides/frontend/overview)                |
+| Helper                                                | Import from                                          | Authored at                                                                | Guide                                                  |
+| ----------------------------------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------ |
+| `defineAgent`                                         | `eve`                                                | `agent/agent.ts`                                                           | [agent.ts](../agent-config)                            |
+| `defineTool`                                          | `eve/tools`                                          | `agent/tools/<name>.ts`                                                    | [Tools](../tools)                                      |
+| `defineDynamic`                                       | `eve`, `eve/tools`, `eve/skills`, `eve/instructions` | dynamic model or subagent `agent.ts`; `agent/{tools,skills,instructions}/` | [Dynamic capabilities](../guides/dynamic-capabilities) |
+| `defineMcpClientConnection`                           | `eve/connections`                                    | `agent/connections/<name>.ts`                                              | [MCP connections](../connections/mcp)                  |
+| `defineOpenAPIConnection`                             | `eve/connections`                                    | `agent/connections/<name>.ts`                                              | [OpenAPI connections](../connections/openapi)          |
+| `defineChannel`                                       | `eve/channels`                                       | `agent/channels/<name>.ts`                                                 | [Custom channels](../channels/custom)                  |
+| `eveChannel`, `slackChannel`, and the other platforms | `eve/channels/<platform>`                            | `agent/channels/<platform>.ts`                                             | [Channels](../channels/overview)                       |
+| `defineSkill`                                         | `eve/skills`                                         | `agent/skills/<name>.ts`                                                   | [Skills](../skills)                                    |
+| `defineInstructions`                                  | `eve/instructions`                                   | `agent/instructions.ts`                                                    | [Instructions](../instructions)                        |
+| `defineHook`                                          | `eve/hooks`                                          | `agent/hooks/<slug>.ts`                                                    | [Hooks](../guides/hooks)                               |
+| `defineSchedule`                                      | `eve/schedules`                                      | `agent/schedules/<name>.ts`                                                | [Schedules](../schedules)                              |
+| `defineState`                                         | `eve/context`                                        | tools, hooks, lifecycle                                                    | [Session context](../guides/session-context)           |
+| `defineSandbox`                                       | `eve/sandbox`                                        | `agent/sandbox.ts`                                                         | [Sandbox](../sandbox)                                  |
+| `defineInstrumentation`                               | `eve/instrumentation`                                | `agent/instrumentation.ts`                                                 | [instrumentation.ts](../guides/instrumentation)        |
+| `defineRemoteAgent`                                   | `eve`                                                | `agent/subagents/<id>/agent.ts`                                            | [Remote agents](../guides/remote-agents)               |
+| `defineEval`                                          | `eve/evals`                                          | `evals/*.eval.ts`                                                          | [Evals](../evals/overview)                             |
+| `defineEvalConfig`                                    | `eve/evals`                                          | `evals/evals.config.ts`                                                    | [Evals](../evals/overview)                             |
+| `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 `experimental_workflow` from `eve/tools` (see [Default harness](../concepts/default-harness)), `sleep` from `eve/tools/sleep`, the route verbs `GET`/`POST`/`PUT`/`PATCH`/`DELETE`/`WS` from `eve/channels`, the approval policies `always`/`once`/`never` from `eve/tools/approval`, and the channel auth helpers `localDev`/`vercelOidc`/`placeholderAuth` from `eve/channels/auth`. To wrap a built-in tool, import its default value from `eve/tools/defaults` (`bash`, `readFile`, `writeFile`, `glob`, `grep`, `webFetch`, `webSearch`, `todo`, `loadSkill`). `AgentReasoningDefinition` is exported from `eve` for the top-level `defineAgent({ reasoning })` setting. `AgentLimitsDefinition` is exported for `defineAgent({ limits })`. `AgentWorkflowDefinition` and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape. `ExperimentalWorkflowToolInput` is exported from `eve/tools` for the `experimental_workflow(...)` config shape.
 
@@ -68,33 +68,33 @@ A few non-`define*` helpers round out the set: `disableTool` and `experimental_w
 
 ## Imports at a glance
 
-| Import                                                      | Holds                                                                 |
-| ----------------------------------------------------------- | --------------------------------------------------------------------- |
-| `eve`                                                       | `defineAgent`, `defineRemoteAgent`, agent config types                |
-| `eve/tools`                                                 | `defineTool`, `defineDynamic`, `disableTool`, `experimental_workflow` |
-| `eve/tools/defaults`                                        | the built-in tools as plain values                                    |
-| `eve/tools/approval`                                        | `always`, `once`, `never`                                             |
-| `eve/tools/sleep`                                           | opt-in durable `sleep` tool                                           |
-| `eve/connections`                                           | `defineMcpClientConnection`, `defineOpenAPIConnection`                |
-| `eve/channels`                                              | `defineChannel`, route verbs                                          |
-| `eve/channels/eve`                                          | `eveChannel`                                                          |
-| `eve/channels/auth`                                         | `localDev`, `vercelOidc`, `placeholderAuth`                           |
-| `eve/channels/{slack,discord,teams,telegram,twilio,github}` | platform channel factories                                            |
-| `eve/hooks`                                                 | `defineHook`                                                          |
-| `eve/schedules`                                             | `defineSchedule`                                                      |
-| `eve/skills`                                                | `defineSkill`, `defineDynamic`                                        |
-| `eve/instructions`                                          | `defineInstructions`, `defineDynamic`                                 |
-| `eve/context`                                               | `defineState`, session and state types                                |
-| `eve/sandbox`                                               | `defineSandbox`, backends                                             |
-| `eve/instrumentation`                                       | `defineInstrumentation`, `isChannel`                                  |
-| `eve/models/openai`                                         | `experimental_chatgpt`                                                |
-| `eve/evals`                                                 | `defineEval`, `defineEvalConfig`, `mockModel`, eval types             |
-| `eve/evals/expect`                                          | `includes`, `equals`, `matches`, `similarity`                         |
-| `eve/evals/reporters`                                       | `Braintrust`, `JUnit`, `EvalReporter`                                 |
-| `eve/evals/loaders`                                         | `loadJson`, `loadYaml`                                                |
-| `eve/react`, `eve/vue`, `eve/svelte`                        | `useEveAgent`                                                         |
-| `eve/next`, `eve/nuxt`, `eve/sveltekit`                     | framework bundler plugins                                             |
-| [`eve/client`](../guides/client/overview)                   | `Client`, `ClientSession`                                             |
+| Import                                                      | Holds                                                                   |
+| ----------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `eve`                                                       | `defineAgent`, `defineRemoteAgent`, `defineDynamic`, agent config types |
+| `eve/tools`                                                 | `defineTool`, `defineDynamic`, `disableTool`, `experimental_workflow`   |
+| `eve/tools/defaults`                                        | the built-in tools as plain values                                      |
+| `eve/tools/approval`                                        | `always`, `once`, `never`                                               |
+| `eve/tools/sleep`                                           | opt-in durable `sleep` tool                                             |
+| `eve/connections`                                           | `defineMcpClientConnection`, `defineOpenAPIConnection`                  |
+| `eve/channels`                                              | `defineChannel`, route verbs                                            |
+| `eve/channels/eve`                                          | `eveChannel`                                                            |
+| `eve/channels/auth`                                         | `localDev`, `vercelOidc`, `placeholderAuth`                             |
+| `eve/channels/{slack,discord,teams,telegram,twilio,github}` | platform channel factories                                              |
+| `eve/hooks`                                                 | `defineHook`                                                            |
+| `eve/schedules`                                             | `defineSchedule`                                                        |
+| `eve/skills`                                                | `defineSkill`, `defineDynamic`                                          |
+| `eve/instructions`                                          | `defineInstructions`, `defineDynamic`                                   |
+| `eve/context`                                               | `defineState`, session and state types                                  |
+| `eve/sandbox`                                               | `defineSandbox`, backends                                               |
+| `eve/instrumentation`                                       | `defineInstrumentation`, `isChannel`                                    |
+| `eve/models/openai`                                         | `experimental_chatgpt`                                                  |
+| `eve/evals`                                                 | `defineEval`, `defineEvalConfig`, `mockModel`, eval types               |
+| `eve/evals/expect`                                          | `includes`, `equals`, `matches`, `similarity`                           |
+| `eve/evals/reporters`                                       | `Braintrust`, `JUnit`, `EvalReporter`                                   |
+| `eve/evals/loaders`                                         | `loadJson`, `loadYaml`                                                  |
+| `eve/react`, `eve/vue`, `eve/svelte`                        | `useEveAgent`                                                           |
+| `eve/next`, `eve/nuxt`, `eve/sveltekit`                     | framework bundler plugins                                               |
+| [`eve/client`](../guides/client/overview)                   | `Client`, `ClientSession`                                               |
 
 Exported types ship from the same entrypoint as the helper they describe (for example `ToolDefinition` and `ToolContext` from `eve/tools`). For the exhaustive list, read `packages/eve/src/public/index.ts`.
 

package/docs/subagents.mdx

@@ -47,11 +47,41 @@ export default defineAgent({
 
 `description` is required. The parent reads it to decide whether to delegate, so the compiler rejects any subagent whose `agent.ts` leaves it out.
 
+### Conditional availability
+
+To expose a declared subagent only for certain sessions or turns, export
+`defineDynamic` from that subagent's `agent.ts`. Return a `defineAgent`
+configuration to expose the subagent, or nil to omit it from the parent's tools.
+
+```ts title="agent/subagents/researcher/agent.ts"
+import { defineAgent, defineDynamic } from "eve";
+
+export default defineDynamic({
+  events: {
+    "session.started": (_event, ctx) =>
+      ctx.session.auth.current?.attributes.research === true
+        ? defineAgent({
+            description: "Investigate ambiguous questions before the parent responds.",
+            model: "anthropic/claude-opus-4.8",
+          })
+        : null,
+  },
+});
+```
+
+Resolvers run at `session.started` or `turn.started`; `step.started` is not
+supported for subagents. A nil result (`null` or `undefined`) removes the
+subagent's description and tool definition from the model-visible surface.
+The subagent's filesystem manifest is always compiled; a non-nil result injects
+the returned agent configuration when the child runs.
+See [Dynamic capabilities](./guides/dynamic-capabilities#dynamic-subagents) for
+scope precedence, failure behavior, and the dispatch-time guard.
+
 Minimum files:
 
 ```text
 agent/subagents/researcher/
-├── agent.ts            # required (must export a description)
+├── agent.ts            # required
 ├── instructions.md     # or instructions.ts, optional
 ├── tools/              # optional, its own tools
 ├── skills/             # optional, its own skills
@@ -100,7 +130,7 @@ A declared subagent's tool name is the bare path-derived name, with no prefix. `
 }
 ```
 
-Because the name lives in the same runtime tool namespace as authored tools, a subagent named `researcher` collides with a tool named `researcher`. eve rejects the build rather than picking a winner, so keep subagent directory names distinct from tool names.
+Because the name lives in the same runtime tool namespace as authored tools, a subagent named `researcher` collides with a tool named `researcher`. eve rejects static collisions at build time and active dynamic collisions at runtime rather than picking a winner, so keep subagent directory names distinct from tool names.
 
 Do not rely on subagent delegation by itself as an approval boundary. Put sensitive tools behind `approval`, connection approval, route/session authorization, or other controls wherever those tools can be called.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve",
-  "version": "0.29.4",
+  "version": "0.30.0",
   "private": false,
   "description": "Filesystem-first framework for durable backend AI agents that run anywhere.",
   "keywords": [
@@ -320,13 +320,13 @@
     "@vercel/otel": "2.1.3",
     "@vercel/sandbox": "2.8.0",
     "@vercel/sdk": "1.28.8",
-    "@workflow/core": "5.0.0-beta.38",
-    "@workflow/errors": "5.0.0-beta.14",
+    "@workflow/core": "5.0.0-beta.39",
+    "@workflow/errors": "5.0.0-beta.15",
     "@workflow/serde": "5.0.0-beta.2",
     "@workflow/utils": "5.0.0-beta.8",
-    "@workflow/world": "5.0.0-beta.23",
-    "@workflow/world-local": "5.0.0-beta.32",
-    "@workflow/world-vercel": "5.0.0-beta.34",
+    "@workflow/world": "5.0.0-beta.24",
+    "@workflow/world-local": "5.0.0-beta.33",
+    "@workflow/world-vercel": "5.0.0-beta.35",
     "ai": "^7.0.38",
     "autoevals": "0.0.132",
     "chat": "4.34.0",
@@ -355,7 +355,7 @@
     "vue": "^3.5.0",
     "zod": "4.4.3",
     "zod-validation-error": "5.0.0",
-    "@vercel/eve-catalog": "0.0.1"
+    "@eve/catalog": "0.0.1"
   },
   "peerDependencies": {
     "@opentelemetry/api": "^1.0.0",
@@ -385,7 +385,7 @@
     "clean": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\"",
     "build": "pnpm run check:bin-runtime-dependencies && pnpm run build:js && node ./scripts/copy-docs.mjs && node ./scripts/stamp-version-tokens.mjs",
     "build:compiled": "node ./scripts/vendor-compiled.mjs",
-    "build:js": "pnpm run build:compiled && pnpm run clean && pnpm run build:types && node ./scripts/copy-compiled-assets.mjs && node ./scripts/build-rolldown.mjs && node ./scripts/copy-runtime-assets.mjs",
+    "build:js": "pnpm run build:compiled && pnpm run clean && pnpm run build:types && node ./scripts/copy-compiled-assets.mjs && node --conditions=eve-source ./scripts/build-rolldown.mjs && node ./scripts/copy-runtime-assets.mjs",
     "build:types": "pnpm run build:compiled && tsc -p tsconfig.build.json",
     "check:bin-runtime-dependencies": "node ./scripts/check-bin-runtime-dependencies.mjs",
     "dev": "pnpm run build:compiled && node ./scripts/copy-runtime-assets.mjs && tsc -p tsconfig.dev.json --watch --preserveWatchOutput",

package/dist/src/compiled/_chunks/workflow/resume-hook-D1_5NCZ6.js

@@ -1 +0,0 @@
-import{r as e}from"./rolldown-runtime-DaDcL9Zw.js";import{A as t,C as n,Mn as r,Q as i,Vn as a,W as o,_ as s,a as c,ct as l,et as u,fn as d,hn as f,lt as p,mn as m,n as h,nn as g,qt as _,st as v,t as y,xn as b,zn as x}from"./wait-until-z48sPUjU.js";import{E as S,d as C,n as w,o as T,r as E}from"./dist-BeQ_csYA.js";import{A as D}from"./dist-WjtNsOyf.js";import{t as O}from"./spec-version-C0hBsfu-.js";var k=e({getHookByToken:()=>P,resumeHook:()=>F,resumeWebhook:()=>I});function A(e){let t=e.executionContext?.workflowCoreVersion,n=e.executionContext?.traceCarrier;return{deploymentId:e.deploymentId,workflowName:e.workflowName,runSpecVersion:e.specVersion,workflowCoreVersion:typeof t==`string`?t:void 0,traceCarrier:n&&typeof n==`object`?n:void 0,encryptionPublicKey:e.encryptionPublicKey}}async function j(e){if(e.resumeContext)return{resumeContext:e.resumeContext,source:`hook`};let t=await(await b()).runs.get(e.runId);return{resumeContext:A(t),source:`run_fallback`,run:t}}async function M(e,t){let n=await b(),r=t.run?await n.getEncryptionKeyForRun?.(t.run):await n.getEncryptionKeyForRun?.(e.runId,{deploymentId:t.resumeContext.deploymentId});return r?await a(r):void 0}async function N(e){let n=await b(),r=await n.hooks.getByToken(e),i;if(r.metadata!==void 0){let e=await j(r),a=e.run?await n.getEncryptionKeyForRun?.(e.run):await n.getEncryptionKeyForRun?.(r.runId,{deploymentId:e.resumeContext.deploymentId});i=a?await d(a):void 0,r.metadata=await t(r.metadata,r.runId,i)}return{hook:r,encryptionKey:i}}async function P(e){let{hook:t}=await N(e);return t}async function F(e,t,r){return await h(()=>u(`hook.resume`,async a=>{let u=await b();try{let d=typeof e==`string`?await u.hooks.getByToken(e):e,h=await j(d),{resumeContext:v}=h;if(a?.setAttributes({...p(d.token),...l(d.hookId),...g(d.runId),"workflow.hook.resume_context_source":h.source}),h.run&&D(h.run.status))throw new T(d.token);let b=s(v.workflowCoreVersion),S,w=r?void 0:x(v.encryptionPublicKey);if(w)S=m(w);else{let e=r??await M(d,h);b.supportedFormats.has(f.ENCRYPTED)||(e=void 0),S=e}let k=(v.runSpecVersion??0)>=5&&b.supportedFormats.has(f.GZIP),A=[],N=O(d.specVersion),P=await n(t,d.runId,S,A,globalThis,N,b.framedByteStreams,k);y(Promise.all(A),e=>{e!==void 0&&o.warn(`Background flush of hook payload ops failed`,{workflowRunId:d.runId,hookId:d.hookId,error:e instanceof Error?e.message:String(e)})});try{await u.events.create(d.runId,{eventType:`hook_received`,specVersion:5,correlationId:d.hookId,eventData:{...N?{}:{token:d.token},payload:P}},{v1Compat:N})}catch(e){throw T.is(e)||E.is(e)||C.is(e)?new T(d.token):e}a?.setAttributes({..._(v.workflowName)});let F=await i(v.traceCarrier);return F&&a?.addLink?.(F),await u.queue(c(v.workflowName),{runId:d.runId,traceCarrier:v.traceCarrier??void 0},{deploymentId:v.deploymentId,specVersion:v.runSpecVersion??1}),d}catch(t){throw a?.setAttributes({...p(typeof e==`string`?e:e.token),...v(!1)}),t}}))}async function I(e,t){let{hook:n,encryptionKey:i}=await N(e);if(n.isWebhook===!1)throw new T(e);let a,o;if(n.metadata&&typeof n.metadata==`object`&&`respondWith`in n.metadata)if(n.metadata.respondWith===`manual`){let{readable:e,writable:n}=new TransformStream;o=e,t[r]=n}else if(n.metadata.respondWith instanceof Response)a=n.metadata.respondWith;else throw new S(`Invalid \`respondWith\` value: ${n.metadata.respondWith}`,{slug:w.WEBHOOK_INVALID_RESPOND_WITH_VALUE});else a=new Response(null,{status:202});if(await F(n,t,i),o){let e=o.getReader(),t=await e.read();t.value&&(a=t.value),e.cancel()}if(!a)throw new S(`Workflow run did not send a response`,{slug:w.WEBHOOK_RESPONSE_NOT_SENT});return a}export{k as i,F as n,I as r,P as t};

package/dist/src/compiled/_chunks/workflow/run-C240Ctf4.js

@@ -1 +0,0 @@
-import{$ as e,Bn as t,Bt as n,D as r,H as i,Jt as a,N as o,P as s,Rn as c,Sn as l,U as u,Vn as d,W as f,Yn as p,_ as ee,a as m,bn as h,et as g,fn as _,g as te,hn as v,k as y,mn as ne,n as b,nn as re,qt as ie,rn as ae,rt as oe,s as x,t as S,w as se,xn as C,yn as w,zn as T}from"./wait-until-z48sPUjU.js";import{C as E,D,E as O,O as k,S as A,T as j,g as M,h as N,l as P,p as F,r as I,s as L,t as R,w as z,x as B}from"./dist-BeQ_csYA.js";import{t as V}from"./attribute-changes-1LmTKuTT.js";import{G as H,W as U,i as ce,o as W}from"./dist-WjtNsOyf.js";import{t as G}from"./spec-version-C0hBsfu-.js";const K=new Set([`PARSE_ERROR`,`SCHEMA_VALIDATION`,k.WORLD_CONTRACT_ERROR]),q=new Set([`TRANSPORT`,`TIMEOUT`]),le=[O.is,N.is,B.is,F.is];function J(e){if(!D.is(e)||e.status!==void 0)return!1;let t=`cause`in e?e.cause:void 0;return e.code!==void 0&&K.has(e.code)||e.message.startsWith(`Failed to parse response body for `)||e.message.startsWith(`Schema validation failed for `)||typeof t==`object`&&!!t&&`name`in t&&t.name===`ZodError`}function Y(e){return M.is(e)?!0:D.is(e)?e.status!==void 0&&e.status>=500||e.code!==void 0&&q.has(e.code):!1}function ue(e){if(P.is(e))return k.REPLAY_DIVERGENCE;if(R.is(e))return k.CORRUPTED_EVENT_LOG;if(L.is(e))return k.MAX_EVENTS_EXCEEDED;if(J(e)||Y(e))return k.WORLD_CONTRACT_ERROR;for(let t of le)if(t(e))return k.RUNTIME_ERROR;return k.USER_ERROR}const de=W();function fe(){let e=u.getStore(),t=e?.workflowMetadata?.workflowRunId;if(t)return{[H]:e.rootRunId??t,[U]:t}}let X=!1;async function Z(r,i,o){"use step";return await b(()=>{let s=r?.workflowId;if(!s)throw new O(`'start' received an invalid workflow function. Ensure the Workflow SDK is configured correctly and the function includes a 'use workflow' directive.`,{slug:`start-invalid-workflow-function`});return g(`workflow.start ${p(s)}`,async r=>{r?.setAttributes({...ie(s),...a(`start`)});let u=[],p=o??{};Array.isArray(i)?u=i:typeof i==`object`&&(p=i),r?.setAttributes({...n(u.length)});let h=p.world??await C();l(h);let g=await h.getDeploymentId(),_=p.deploymentId??g;_===`latest`&&(h.resolveLatestDeploymentId?_=await h.resolveLatestDeploymentId():(X||(X=!0,f.warn(`deploymentId: 'latest' has no effect in this world and was ignored. It is only supported by worlds with atomic deployments, such as Vercel. The run will target the current deployment.`,{currentDeploymentId:g})),_=g));let y=`wrun_${h.createRunId?h.createRunId(p):de()}`,b,w,E;if(_===g)b=!0,w=!0;else if(typeof h.streams?.get!=`function`)b=!1,w=!1;else{let e=await x(h,{deploymentId:_,runId:y,timeout:2e3,namespace:p.namespace}).catch(()=>void 0);E=e?.encryptionPublicKey;let t=ee(e?.workflowCoreVersion);b=t.framedByteStreams,w=t.supportedFormats.has(v.GZIP)}let D=[],k=await e(),A=p.specVersion??h.specVersion,j=G(A),M=p.allowReservedAttributes===!0,N;if(p.attributes&&Object.keys(p.attributes).length>0){if(A<4)throw new O(`Initial workflow attributes require a World that supports spec version 4 or later.`);for(let[e,t]of Object.entries(p.attributes))if(typeof t!=`string`)throw new O(`Initial workflow attribute ${JSON.stringify(e)} must be a string value.`);let e=V(p.attributes,{allowReservedAttributes:M});N=Object.fromEntries(e.map(({key:e,value:t})=>[e,t]))}let P=A>=4?fe():void 0,F=P?{...P,...N}:N,L=F?{attributes:F,...M||P!=null?{allowReservedAttributes:!0}:{}}:{};if(p.replayedFromRunId!==void 0&&!ce.safeParse(p.replayedFromRunId).success)throw new O(`replayedFromRunId must be a run ID (wrun_<ulid>); received ${JSON.stringify(String(p.replayedFromRunId).slice(0,64))}.`);let R=T(E),z,B;if(R)z=ne(R),B=E;else{let e=await h.getEncryptionKeyForRun?.(y,{...p,deploymentId:_});z=e?await d(e):void 0,B=e?c((await t(e)).publicKey):void 0}let H=await se(u,y,z,D,globalThis,j,b,w&&A>=5),U={traceCarrier:k,workflowCoreVersion:te,features:{encryption:!!z},...p.replayedFromRunId?{replayedFromRunId:p.replayedFromRunId}:{}},[W,K]=await Promise.allSettled([h.events.create(y,{eventType:`run_created`,specVersion:A,eventData:{deploymentId:_,workflowName:s,input:H,executionContext:U,...B?{encryptionPublicKey:B}:{},...L}},{v1Compat:j}),h.queue(m(s,p.namespace),{runId:y,traceCarrier:k,...A>=3?{runInput:{input:H,deploymentId:_,workflowName:s,specVersion:A,executionContext:U,...B?{encryptionPublicKey:B}:{},...L}}:{}},{deploymentId:_,specVersion:A,...p.region===void 0?{}:{region:p.region}})]);if(K.status===`rejected`)throw K.reason;let q=!1;if(W.status===`rejected`){let e=W.reason;if(!I.is(e))if(Y(e))q=!0,f.warn(`Run creation event failed, but the run was accepted via the queue. The run_created event will be re-tried async by the runtime.`,{workflowRunId:y,error:e.message});else throw e}else{let e=W.value;if(!e.run)throw new O(`Missing 'run' in server response for 'run_created' event`);if(!j&&e.run.runId!==y)throw new O(`Server returned different runId than requested: expected ${y}, got ${e.run.runId}`)}return S(Promise.all(D),e=>{f.warn(`Background flush of workflow argument streams failed`,{workflowRunId:y,error:e instanceof Error?e.message:String(e)})}),r?.setAttributes({...re(y),...oe(_),...W.status===`fulfilled`&&W.value.run?ae(W.value.run.status):{}}),new $(y,{resilientStart:q})})})}const pe=e=>Array.isArray(e)?e:[e];async function me(e,t,n={}){try{let r=await e.runs.get(t,{resolveData:`all`}),i=await e.getEncryptionKeyForRun?.(r),a=i?await _(i):void 0,s=pe(await o(r.input,t,a,globalThis)),c=n.specVersion??r.specVersion??1,l=n.deploymentId??r.deploymentId;return(await Z({workflowId:r.workflowName},s,{deploymentId:l,world:e,specVersion:c,replayedFromRunId:t,namespace:n.namespace})).runId}catch(e){throw Error(`Failed to recreate run from ${t}: ${e instanceof Error?e.message:String(e)}`,{cause:e})}}async function he(e,t,n){try{let r=(await e.runs.get(t,{resolveData:`none`})).specVersion??1,i=G(r),a={eventType:`run_cancelled`,specVersion:r,...n?.cancelReason===void 0?{}:{eventData:{cancelReason:n.cancelReason}}};await e.events.create(t,a,{v1Compat:i})}catch(e){throw Error(`Failed to cancel run ${t}: ${e instanceof Error?e.message:String(e)}`,{cause:e})}}async function ge(e,t,n){try{let r=await e.runs.get(t,{resolveData:`none`});await e.queue(m(r.workflowName,n?.namespace),{runId:t},{deploymentId:r.deploymentId,specVersion:r.specVersion??1})}catch(e){throw Error(`Failed to re-enqueue run ${t}: ${e instanceof Error?e.message:String(e)}`,{cause:e})}}async function Q(e,t,n){try{let r=await e.runs.get(t,{resolveData:`none`}),i=G(r.specVersion),a=[],o=null;do{let n=await e.events.list({runId:t,pagination:{limit:1e3,...o?{cursor:o}:{}},resolveData:`none`});a.push(...n.data),o=n.hasMore?n.cursor:null}while(o);let s=a.filter(e=>e.eventType===`wait_created`),c=new Set(a.filter(e=>e.eventType===`wait_completed`).map(e=>e.correlationId)),l=s.filter(e=>!c.has(e.correlationId));if(n?.correlationIds&&n.correlationIds.length>0){let e=new Set(n.correlationIds);l=l.filter(t=>t.correlationId&&e.has(t.correlationId))}let u=[],d=0;for(let n of l){if(!n.correlationId)continue;let a=i?{eventType:`wait_completed`,correlationId:n.correlationId}:{eventType:`wait_completed`,correlationId:n.correlationId,specVersion:r.specVersion,eventData:{resumeAt:n.eventData.resumeAt}};try{await e.events.create(t,a,{v1Compat:i}),d++}catch(e){I.is(e)?d++:u.push(e instanceof Error?e:Error(String(e)))}}if(d>0&&await e.queue(m(r.workflowName,n?.namespace),{runId:t},{deploymentId:r.deploymentId,specVersion:r.specVersion??1}),u.length>0)throw AggregateError(u,`Failed to complete ${u.length}/${l.length} pending wait(s) for run ${t}`);return{stoppedCount:d}}catch(e){throw e instanceof AggregateError?e:Error(`Failed to wake up run ${t}: ${e instanceof Error?e.message:String(e)}`,{cause:e})}}async function _e(e,t,n,r){try{return await e.streams.get(t,n,r?.startIndex)}catch(e){throw Error(`Failed to read stream ${n}: ${e instanceof Error?e.message:String(e)}`,{cause:e})}}async function ve(e,t){try{return await e.streams.list(t)}catch(e){throw Error(`Failed to list streams for run ${t}: ${e instanceof Error?e.message:String(e)}`,{cause:e})}}var $=class e{static[h](e){return{runId:e.runId,resilientStart:e.#r}}static[w](t){return new e(t.runId,{resilientStart:t.resilientStart})}runId;#e;get#t(){return this.#e||=C(),this.#e}#n=null;#r=!1;constructor(e,t){this.runId=e,this.#r=t?.resilientStart??!1}#i(){return this.#n||=(async()=>{let e=await this.#t,t=await e.runs.get(this.runId),n=await e.getEncryptionKeyForRun?.(t);return n?await _(n):void 0})(),this.#n}#a(){return()=>this.#i()}async wakeUp(e){"use step";return Q(await this.#t,this.runId,e)}async cancel(e){"use step";await(await this.#t).events.create(this.runId,{eventType:`run_cancelled`,specVersion:5,...e?.cancelReason===void 0?{}:{eventData:{cancelReason:e.cancelReason}}})}get exists(){"use step";return this.#t.then(e=>e.runs.get(this.runId,{resolveData:`none`}).then(()=>!0).catch(e=>{if(j.is(e))return!1;throw e}))}get status(){"use step";return this.#t.then(e=>e.runs.get(this.runId).then(e=>e.status))}get returnValue(){"use step";return this.#o()}get workflowName(){"use step";return this.#t.then(e=>e.runs.get(this.runId).then(e=>e.workflowName))}get createdAt(){"use step";return this.#t.then(e=>e.runs.get(this.runId).then(e=>e.createdAt))}get startedAt(){"use step";return this.#t.then(e=>e.runs.get(this.runId).then(e=>e.startedAt))}get completedAt(){"use step";return this.#t.then(e=>e.runs.get(this.runId).then(e=>e.completedAt))}get readable(){return this.getReadable()}getReadable(e={}){"use step";let{ops:t=[],global:n=globalThis,startIndex:a,namespace:o}=e,s=i(this.runId,o),c=this.#a(),l=r(n,t,this.runId,c).ReadableStream({name:s,startIndex:a}),u=this.#t,d=this.runId;return Object.assign(l,{getTailIndex:async()=>(await(await u).streams.getInfo(d,s)).tailIndex})}async#o(){let e=await this.#t,t=0,n=this.#r?3:0,r=[1e3,3e3,6e3];for(;;)try{let t=await e.runs.get(this.runId);if(t.status===`completed`){let e=await this.#i();return await s(t.output,this.runId,e)}if(t.status===`cancelled`)throw new A(this.runId);if(t.status===`failed`){let e=await this.#i(),n;try{n=await y(t.error,this.runId,e)}catch{n=Error(`Failed to hydrate workflow run error`)}throw new E(this.runId,n,{errorCode:t.errorCode})}throw new z(this.runId,t.status)}catch(e){if(z.is(e)){await new Promise(e=>setTimeout(e,1e3));continue}if(j.is(e)&&t<n){let e=r[t];t++,await new Promise(t=>setTimeout(t,e));continue}throw e}}};function ye(e){return new $(e)}export{_e as a,Q as c,Y as d,J as f,ve as i,Z as l,ye as n,me as o,he as r,ge as s,$ as t,ue as u};

package/dist/src/compiled/_chunks/workflow/sleep-De802yfX.js

@@ -1 +0,0 @@
-import{In as e}from"./wait-until-z48sPUjU.js";import{i as t}from"./attribute-changes-1LmTKuTT.js";async function n(r){let i=globalThis[e];return i||t(`sleep()`,`https://workflow-sdk.dev/docs/api-reference/workflow/sleep`,n),i(r)}export{n as t};