eve 0.29.3 → 0.29.5

package/docs/guides/acp.md

@@ -0,0 +1,91 @@
+---
+title: "Use eve through ACP"
+description: "Use local or deployed eve agents from Agent Client Protocol clients."
+---
+
+Agent Client Protocol (ACP) clients can launch an authored eve application as a local subprocess. eve serves stable ACP v1 over stdio while its normal development server remains the execution runtime.
+
+```sh
+eve acp
+```
+
+Without a URL, the client starts one process from the eve application root. It supervises a local development server, and closing the ACP connection stops that owned server. To bridge ACP to a deployed eve agent, pass its URL:
+
+```sh
+eve acp https://agent.example.com
+```
+
+For a recognized Vercel deployment, eve verifies the exact origin and resolves a short-lived project-scoped OIDC token from the local Vercel session. If login or a Trusted Sources change is required, run `eve dev <url>` and complete `/vc:login` before launching ACP. `VERCEL_AUTOMATION_BYPASS_SECRET` remains available for deployments configured with a Protection Bypass for Automation token.
+
+## Configure Zed
+
+Open the eve application root as the Zed workspace. In **Agent Settings → External Agents**, add a custom agent:
+
+```json
+{
+  "agent_servers": {
+    "eve-local": {
+      "type": "custom",
+      "command": "pnpm",
+      "args": ["exec", "eve", "acp"],
+      "env": {}
+    }
+  }
+}
+```
+
+Use an absolute command path if Zed cannot find `pnpm` in its environment. The workspace must be the same directory as the eve application root; eve rejects a different `session/new.cwd` instead of running the wrong application.
+
+Disable Zed project MCP servers for this agent. The initial eve adapter does not accept client-provided MCP servers.
+
+## Supported behavior
+
+ACP clients receive:
+
+- streamed assistant text and reasoning;
+- tool-call requests and results;
+- one-time tool approval and denial requests;
+- fixed-choice and freeform questions when the client supports ACP form elicitation;
+- cooperative turn cancellation;
+- independent concurrent ACP sessions;
+- session closure and process cleanup.
+
+Development rebuilds retain normal eve semantics. In-flight work stays pinned to its generation, and the next turn uses the newest successful generation.
+
+## Security and capability limits
+
+ACP mode does not give the agent access to the editor's host filesystem or terminal. `session/new.cwd` identifies the eve application being launched; it is not mounted into the agent sandbox.
+
+The initial adapter does not support:
+
+- a deployed ACP HTTP or WebSocket endpoint;
+- ACP authentication (remote bridges use the deployed eve agent's existing HTTP authentication);
+- ACP v2;
+- client filesystem or terminal methods;
+- client-provided MCP servers;
+- images, audio, files, or embedded resources in prompts;
+- session loading, listing, resumption, or durable ACP IDs across process restarts;
+- ACP model or mode configuration.
+
+The agent continues to use the connections, tools, credentials, and sandbox policy authored in the eve application. Prompt text and ACP metadata never establish an authenticated end-user principal.
+
+## Diagnose a connection
+
+ACP reserves stdout for newline-delimited JSON-RPC. eve sends compilation output, server logs, and diagnostics to stderr so they cannot corrupt the protocol stream.
+
+For a quick headless smoke test, run an ACP client such as `acpx` from the application root. `acpx` launches the ACP process itself; do not start `eve acp` separately.
+
+```sh
+npx acpx@latest \
+  --agent 'pnpm exec eve acp' \
+  exec 'Reply with exactly: ACP works'
+```
+
+When testing from the eve source checkout, use an authored fixture rather than the monorepo root, which does not provide an `eve` executable:
+
+```sh
+cd apps/fixtures/weather-agent
+npx acpx@latest --agent 'pnpm exec eve acp' exec 'Reply with exactly: ACP works'
+```
+
+If startup fails, inspect the ACP client's logs together with eve's stderr. A non-empty client MCP configuration, a mismatched working directory, and unsupported prompt content produce explicit protocol errors before model work begins.

package/docs/guides/client/streaming.mdx

@@ -19,6 +19,20 @@ const result = await response.result();
 
 Cancellation does not replace stream consumption. Continue reading the response to observe its terminal `turn.cancelled` and `session.waiting` boundary and to advance the client session cursor normally.
 
+Between turns, `session.compact()` queues context compaction without sending model input. An accepted request reports the session id; consume the durable stream through the following `session.waiting` boundary before sending the next turn. `compaction.completed` confirms that summarization succeeded; without it, eve preserves the previous history. A never-started session returns `no_active_session` as a successful no-op.
+
+```ts
+const compaction = await session.compact();
+console.log(compaction.status);
+```
+
+Use `session.clear()` to remove model-message history while retaining the session and its durable resources. Consume `context.cleared` and the following `session.waiting` before sending the next turn.
+
+```ts
+const cleared = await session.clear();
+console.log(cleared.status);
+```
+
 ## Aggregate a turn
 
 Use `result()` when you only need the final turn summary:
@@ -180,6 +194,30 @@ Because a tail-relative cursor cannot be bounded, `follow: false` throws when co
 
 `stream()` throws if the session has no `sessionId`, because there's no stream to attach to before the first send.
 
+## Snapshot a session
+
+Use `snapshot()` when you need the complete event prefix and its matching cursor
+as one value, such as when hydrating a server-rendered chat:
+
+```ts
+const session = client.session({ sessionId, streamIndex: 0 });
+const snapshot = await session.snapshot();
+
+// snapshot.events contains event indexes 0 through snapshot.session.streamIndex - 1.
+```
+
+The read pins the durable tail when it opens, just like
+`stream({ follow: false })`. Events written afterward are not included, and
+`snapshot.session.streamIndex` is the exact index from which a live consumer can
+continue. `snapshot()` always reads from index `0`; use a bounded stream directly
+when you only need the unread suffix from an existing cursor.
+
+Unlike `stream()`, `snapshot()` does not advance or reset the originating
+`ClientSession`. Its returned session includes a continuation token only when
+the captured prefix ends in `session.waiting`, or when completed sessions are
+explicitly preserved by the client. Active and terminal snapshots remain
+inspectable at their returned stream cursor but cannot accept another turn.
+
 ## Abort a request
 
 Pass an `AbortSignal` to cancel the POST or stream. Aborting is local transport cancellation: turns are resumable across disconnects, so detaching never stops the server-side turn — it keeps running and remains attachable by index. To stop the turn itself, POST the session's [cancel route](../../channels/eve#routes) and watch the stream settle with `turn.cancelled` followed by `session.waiting`.

package/docs/guides/dev-tui.md

@@ -35,13 +35,16 @@ Each command echoes as an invocation line, asks through a bordered panel that ta
 | Command       | Does                                                                                                                                                         |
 | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `/model`      | Opens a configure menu that loops until Done (or Esc). See [Configure the model and provider](#configure-the-model-and-provider).                            |
-| `/add`        | Searches registry integrations or adds an item address entered directly.                                                                                     |
+| `/add`        | Adds an integration from the registry or an item address entered directly.                                                                                   |
 | `/deploy`     | Ships the agent to Vercel production, linking the directory first when it is unlinked.                                                                       |
 | `/vc:install` | Installs the Vercel CLI. Available locally and on a remote session.                                                                                          |
 | `/vc:login`   | Logs in to Vercel locally. On a remote session, resolves the deployment's project, refreshes its OIDC token, and confirms any required Trusted Sources rule. |
 | `/loglevel`   | Switches which logs the transcript shows. See [Control what logs show](#control-what-logs-show).                                                             |
 | `/traces`     | Opens the full-screen local trace viewer. See [Inspect traces](#inspect-traces).                                                                             |
-| `/new`        | Starts a fresh session.                                                                                                                                      |
+| `/reset`      | Starts a fresh session.                                                                                                                                      |
+| `/cancel`     | Cooperatively cancels the running turn while preserving the session and settled context.                                                                     |
+| `/clear`      | Clears model-message history while preserving the current session and its durable resources.                                                                 |
+| `/compact`    | Queues context compaction for the current session without sending a message.                                                                                 |
 | `/exit`       | Quits the TUI.                                                                                                                                               |
 | `/help`       | Lists the commands available for the current local or remote session.                                                                                        |
 
@@ -55,11 +58,11 @@ The provider row opens one menu: AI Gateway via a project, AI Gateway via `AI_GA
 
 The provider row demands attention (a bold yellow "Configure model access" with a yellow "Not configured" hint that dims when unselected and uses the terminal foreground when selected) until a link or gateway credential is detected, then names the connection afterward (for example "AI Gateway (Linked to my-project in my-team)"). Setup menus mark the cursor row with a padded, filled-arrow inverse label that inherits the row's accent: blue normally and yellow for warning rows. In stacked menus, the selected row's description appears directly beneath that option. The completed command's outcome stays in the transcript after the panel closes. When a turn fails because AI Gateway authentication is missing or stale, the error points you at `/model` directly.
 
-### Browse registry integrations
+### Add registry integrations
 
-`/add` first organizes integrations by what they add: a way to chat, tools and data, capabilities, or observability. Pick a category to open its searchable catalog from the official eve registry and the registry namespaces configured in `package.json`, or browse everything. Each integration shows its source beside its name, such as `Vercel` or a configured registry namespace. Select a result to review its source, packages, environment variables, and target files before adding it, or type an official item path, configured namespace address, or HTTP(S) URL directly into the search bar. After an add attempt finishes, the panel closes instead of returning to the catalog.
+`/add` groups integrations by their role: **Channels** for where people talk to your agent, **MCP connections** for external services and data, **Extensions** for reusable capabilities, and **Observability** for tracing and evaluation. Pick a category to open its searchable catalog from the official eve registry and the registry namespaces configured in `package.json`, or browse every integration. Each result shows its source beside its name, such as `Vercel` or a configured registry namespace. Select a result to review its source, packages, environment variables, and target files before adding it, or enter an official item path, configured namespace address, or HTTP(S) URL directly in the search bar. After an add attempt finishes, the panel closes instead of returning to the catalog.
 
-Connection registry items install their definition and then configure Vercel Connect through the same `/add` flow. If the directory is unlinked, setup first offers to create or link a project. Run `eve add connection/<name>` for the equivalent CLI flow.
+MCP connection registry items install their definition and then configure Vercel Connect through the same `/add` flow. If the directory is unlinked, setup first offers to create or link a project. Run `eve add connection/<name>` for the equivalent CLI flow.
 
 ## Keyboard shortcuts
 
@@ -81,9 +84,9 @@ In terminals that support bracketed paste, pasting multi-line text into chat or
 
 ### Queue and steer while the agent works
 
-Sending a message while a turn is still running does not interrupt it — the message joins a queue of up to five, pinned in a panel directly above the input with one line per message. When the turn ends, the queued messages coalesce into the next turn's message.
+Sending a message while a turn is still running does not interrupt it — the message joins a queue of up to five, pinned in a panel directly above the input with one line per message. When the turn ends, the queued messages coalesce into the next turn's message. Submit `/cancel` during a turn to cancel it immediately without queueing the command as model input; `/cancel` also works from the idle prompt when a prior stream disconnected while its server turn may still be running.
 
-`Esc` steers instead of waiting: it pops the oldest queued message, cancels the running turn cooperatively, and submits the popped message as the replacement turn. In the transcript, a steered message carries an accent `↑` on its own line above its gutter bar; a queued message that waited for the boundary carries it below. Any remaining messages stay queued behind it. With nothing queued, the first `Esc` arms cancellation and a second `Esc` cancels the turn. Unlike `Ctrl+C` — which drops the stream client-side — a cancelled turn ends cleanly on the server and the session keeps its context; the conversation picks up at the next prompt.
+`Esc` steers instead of waiting: it pops the oldest queued message, cancels the running turn cooperatively, and submits the popped message as the replacement turn. In the transcript, a steered message carries an accent `↑` on its own line above its gutter bar; a queued message that waited for the boundary carries it below. Any remaining messages stay queued behind it. With nothing queued, one `Esc` cancels the turn immediately. Unlike `Ctrl+C` — which drops the stream client-side — a cancelled turn ends cleanly on the server and the session keeps its context; the conversation picks up at the next prompt.
 
 If a turn fails terminally (the server session dies or the connection drops), the TUI starts a fresh session and notes it inline so you can keep going. Server-side context resets with the old session. Messages still queued when a turn is interrupted or fails are restored into the next prompt's input instead of being sent blind.
 

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,52 @@ 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.
+
+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 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 +204,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/meta.json

@@ -11,6 +11,7 @@
     "dynamic-workflows",
     "remote-agents",
     "dev-tui",
+    "acp",
     "frontend",
     "client"
   ]

package/docs/reference/cli.md

@@ -15,6 +15,7 @@ The `eve` binary (`bin: eve`) runs from your app root, and every command first l
 | `eve start`                   | Serve the built `.output/` app; prints the listening URL                                                                                              |
 | `eve dev`                     | Start the local dev server and open the terminal UI                                                                                                   |
 | `eve dev <url>`               | Connect the UI to an existing server URL (e.g. a remote deployment) instead of booting a local server                                                 |
+| `eve acp [url]`               | Serve the local application or an existing eve server URL as a stable ACP v1 agent over stdio                                                         |
 | `eve logs [logid]`            | Print an `eve dev` diagnostic log (the most recent when `logid` is omitted)                                                                           |
 | `eve logs ls`                 | List `eve dev` diagnostic logs, most recent first                                                                                                     |
 | `eve traces ls`               | List locally captured agent traces, most recent first                                                                                                 |
@@ -183,6 +184,8 @@ Pass a bare URL and the UI connects to that server instead of booting a local on
 | `--context-size <tokens>`           | number | none               | Model context window size, shown as a usage percentage                                    |
 | `--logs <mode>`                     | enum   | `stderr`           | Server/agent logs to show: `all` \| `stderr` \| `sandbox` \| `none`                       |
 
+`eve acp` reserves stdin and stdout for newline-delimited JSON-RPC and sends diagnostics to stderr. Without a URL, it supervises an isolated local development server. With a URL, it bridges ACP to that server's existing eve HTTP API and accepts the same URL credentials and request headers as `eve dev <url>`. Pass `--scope <team>` when the active Vercel scope does not own the deployment; `EVE_VERCEL_SCOPE` provides the same value for managed harnesses. See [Use eve through ACP](../guides/acp) for client configuration and capability limits.
+
 A fresh `eve init` passes `--input /model`. That bare local input starts onboarding: the TUI installs the Vercel CLI if needed, asks you to log in if needed, opens `/model`, then offers categorized registry next steps before the first prompt. Other input stays editable in the prompt.
 
 For a URL target protected by HTTP Basic auth, put the credentials in the URL. eve sends them as a Basic `Authorization` header and strips them from the server URL before connecting:

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.3",
+  "version": "0.29.5",
   "private": false,
   "description": "Filesystem-first framework for durable backend AI agents that run anywhere.",
   "keywords": [
@@ -293,6 +293,7 @@
     "undici": "8.9.0"
   },
   "devDependencies": {
+    "@agentclientprotocol/sdk": "1.3.0",
     "@ai-sdk/anthropic": "^4.0.18",
     "@ai-sdk/google": "^4.0.21",
     "@ai-sdk/mcp": "^2.0.16",
@@ -384,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",