eve 0.22.6 → 0.24.0

package/docs/guides/dynamic-workflows.md

@@ -9,10 +9,12 @@ A single turn can already call several subagents, and parallel tool calls dispat
 
 ## Enable the Workflow tool
 
-Re-export the opt-in marker as the default export of `agent/tools/workflow.ts`. The marker name carries the "experimental" warning, but the tool the model actually sees is named `Workflow`.
+Export the experimental Workflow definition from `agent/tools/workflow.ts`. The helper name carries the "experimental" warning, but the tool the model actually sees is named `Workflow`.
 
 ```ts title="agent/tools/workflow.ts"
-export { ExperimentalWorkflow as default } from "eve/tools";
+import { experimental_workflow } from "eve/tools";
+
+export default experimental_workflow();
 ```
 
 Without that file, the `Workflow` tool stays off. It earns its keep only when the agent has subagents (or the built-in `agent`) worth coordinating:
@@ -55,18 +57,15 @@ A workflow reaches only this agent's own agents: the built-in `agent` (a copy of
 
 Workflow orchestration is capped in two independent ways.
 
-**Per-program call budget.** One Workflow program may dispatch at most `limits.maxSubagents` subagent calls in total, counted across the whole program — sequential and parallel calls alike. The default is 100. Calls beyond the budget do not start a child session; they resolve inside the program with a `WORKFLOW_SUBAGENT_LIMIT_REACHED` error result, and the budget is stated in the tool's description so the model sizes its fan-out to fit.
+**Per-program call budget.** One Workflow program may dispatch at most `maxSubagents` subagent calls in total, counted across the whole program — sequential and parallel calls alike. Configure it on `experimental_workflow`; the default is 100. Calls beyond the budget do not start a child session; they resolve inside the program with a `WORKFLOW_SUBAGENT_LIMIT_REACHED` error result, and the budget is stated in the tool's description so the model sizes its fan-out to fit.
 
-```ts title="agent/agent.ts"
-export default defineAgent({
-  model: "anthropic/claude-sonnet-5",
-  limits: {
-    maxSubagents: 4,
-  },
-});
+```ts title="agent/tools/workflow.ts"
+import { experimental_workflow } from "eve/tools";
+
+export default experimental_workflow({ maxSubagents: 4 });
 ```
 
-**Root-only, one level of orchestration.** Only the root session ever sees the `Workflow` tool. The subagents a workflow spawns are ordinary delegated child sessions: they never receive the `Workflow` tool themselves, so a workflow cannot recursively spawn more workflows. Direct (non-workflow) delegation by those children stays subject to the usual `limits.maxSubagentDepth` cap (see [Subagents](../subagents)).
+**Root-only orchestration.** Only the root session receives `Workflow`. Children started by a workflow receive neither `Workflow` nor the built-in `agent`, so Workflow programs cannot recurse. A declared child can still call subagents defined in its own directory (see [Subagents](../subagents)).
 
 ## Where the JavaScript runs
 

package/docs/guides/instrumentation.md

@@ -94,7 +94,7 @@ The callback receives:
 - `channel`: the channel's `kind` and the metadata projected by the active channel
 - `modelInput`: the final instructions and messages passed to the model call
 
-A channel exposes its identity through `kind`, the discriminant you narrow on. For authored channels it is `channel:<name>`, where `<name>` is the channel's filename under `agent/channels/`, so `agent/channels/support.ts` is `channel:support`. Framework channels use `http`, `schedule`, or `subagent`, and an unrecognized or absent kind normalizes to `unknown`. The kind is also emitted as the `eve.channel.kind` span attribute. eve emits compiler-owned typings keyed by the channel filename, so you can narrow either by checking `input.channel.kind === "channel:support"` or by using `isChannel(input.channel, supportChannel)`.
+A channel exposes its identity through `kind`. For authored channels it is `channel:<name>`, where `<name>` is the channel's filename under `agent/channels/`, so `agent/channels/support.ts` is `channel:support`. Framework channels use `http`, `schedule`, or `subagent`, and an unrecognized or absent kind normalizes to `unknown`. The kind is also emitted as the `eve.channel.kind` span attribute. To access an authored channel's metadata with its precise type, import the channel definition and narrow with `isChannel(input.channel, supportChannel)`.
 
 Channel metadata is channel-owned. Built-in channels expose only the fields they choose to make observable; Slack, for example, projects `channelId`, `teamId`, `threadTs`, and `triggeringUserId` from its durable channel state. User-authored channels expose their own projection by returning `metadata(state)` from `defineChannel`. Runtime instrumentation never falls back to raw channel state.
 

package/docs/reference/cli.md

@@ -93,7 +93,7 @@ Run this first when something behaves unexpectedly. It confirms a file was disco
 eve build
 ```
 
-No flags. Compiles to `.eve/` and builds the host output, then prints the built output path.
+Compiles to `.eve/` and builds the host output, then prints the built output path.
 
 Useful artifacts written under `.eve/` (preserved even on partial failure):
 

package/docs/reference/typescript-api.md

@@ -52,7 +52,7 @@ export default defineTool({
 | `mockModel`                                           | `eve/evals`                                   | Deterministic fixture agent models   | [Evals](../evals/overview)                             |
 | `useEveAgent`                                         | `eve/react`, `eve/vue`, `eve/svelte`          | frontend                             | [Frontend](../guides/frontend/overview)                |
 
-A few non-`define*` helpers round out the set: `disableTool` and `ExperimentalWorkflow` from `eve/tools` (see [Default harness](../concepts/default-harness)), the route verbs `GET`/`POST`/`PUT`/`PATCH`/`DELETE`/`WS` from `eve/channels`, the approval policies `always`/`once`/`never` from `eve/tools/approval`, and the channel auth helpers `localDev`/`vercelOidc`/`placeholderAuth` from `eve/channels/auth`. To wrap a built-in tool, import its default value from `eve/tools/defaults` (`bash`, `readFile`, `writeFile`, `glob`, `grep`, `webFetch`, `webSearch`, `todo`, `loadSkill`). `AgentReasoningDefinition` is exported from `eve` for the top-level `defineAgent({ reasoning })` setting. `AgentLimitsDefinition` is exported for `defineAgent({ limits })`. `AgentWorkflowDefinition` and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape.
+A few non-`define*` helpers round out the set: `disableTool` and `experimental_workflow` from `eve/tools` (see [Default harness](../concepts/default-harness)), the route verbs `GET`/`POST`/`PUT`/`PATCH`/`DELETE`/`WS` from `eve/channels`, the approval policies `always`/`once`/`never` from `eve/tools/approval`, and the channel auth helpers `localDev`/`vercelOidc`/`placeholderAuth` from `eve/channels/auth`. To wrap a built-in tool, import its default value from `eve/tools/defaults` (`bash`, `readFile`, `writeFile`, `glob`, `grep`, `webFetch`, `webSearch`, `todo`, `loadSkill`). `AgentReasoningDefinition` is exported from `eve` for the top-level `defineAgent({ reasoning })` setting. `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.
 
 ## Runtime context (`ctx`)
 
@@ -68,32 +68,32 @@ A few non-`define*` helpers round out the set: `disableTool` and `ExperimentalWo
 
 ## Imports at a glance
 
-| Import                                                      | Holds                                                                |
-| ----------------------------------------------------------- | -------------------------------------------------------------------- |
-| `eve`                                                       | `defineAgent`, `defineRemoteAgent`, agent config types               |
-| `eve/tools`                                                 | `defineTool`, `defineDynamic`, `disableTool`, `ExperimentalWorkflow` |
-| `eve/tools/defaults`                                        | the built-in tools as plain values                                   |
-| `eve/tools/approval`                                        | `always`, `once`, `never`                                            |
-| `eve/connections`                                           | `defineMcpClientConnection`, `defineOpenAPIConnection`               |
-| `eve/channels`                                              | `defineChannel`, route verbs                                         |
-| `eve/channels/eve`                                          | `eveChannel`                                                         |
-| `eve/channels/auth`                                         | `localDev`, `vercelOidc`, `placeholderAuth`                          |
-| `eve/channels/{slack,discord,teams,telegram,twilio,github}` | platform channel factories                                           |
-| `eve/hooks`                                                 | `defineHook`                                                         |
-| `eve/schedules`                                             | `defineSchedule`                                                     |
-| `eve/skills`                                                | `defineSkill`, `defineDynamic`                                       |
-| `eve/instructions`                                          | `defineInstructions`, `defineDynamic`                                |
-| `eve/context`                                               | `defineState`, session and state types                               |
-| `eve/sandbox`                                               | `defineSandbox`, backends                                            |
-| `eve/instrumentation`                                       | `defineInstrumentation`, `isChannel`                                 |
-| `eve/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`, 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/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

@@ -1,13 +1,13 @@
 ---
 title: "Subagents"
-description: "Delegate work to child agents, either a copy of the agent itself or declared specialists with their own sandbox and skills."
+description: "Delegate work to root-agent copies or declared specialists with their own tools and sandbox."
 ---
 
-A subagent is a child agent that one agent delegates a focused subtask to. Split work into one to run it in parallel, to give the child a narrower set of tools, or to give a specialist its own identity. There are two kinds, the built-in `agent` tool (a copy of the agent itself) and declared subagents (specialists with their own directory).
+eve supports two ways to delegate work: the root-only built-in `agent` tool, which runs a fresh copy of the root agent, and declared subagents, which are specialists with their own directories. Use a subagent to run independent work in parallel, narrow the available tools, or give a task to a specialist.
 
 ## The built-in `agent` tool
 
-Every agent gets an `agent` tool by default. The model calls it to delegate a subtask to a copy of itself:
+The root session receives `agent` by default. The model calls it to delegate a task to a fresh copy of the root agent:
 
 ```ts
 {
@@ -16,11 +16,13 @@ Every agent gets an `agent` tool by default. The model calls it to delegate a su
 }
 ```
 
-The copy shares the parent's sandbox and tools, and a child's file writes are immediately visible to the parent. That is what makes parallel calls natural: emit multiple `agent` calls in one response to fan out a small, fixed set of independent subtasks. eve runs that batch concurrently and returns every result before the parent continues. Give children non-overlapping write scopes when they work in the shared sandbox. The copy inherits auth and connections, but starts with fresh conversation history and fresh state. If a declared subagent calls `agent`, the child is a copy of _that_ subagent, not the root.
+The copy uses the root's instructions, connections, auth, and sandbox. It receives the same tools except for the root-only `agent` and `Workflow`, and starts with fresh conversation history and fresh state. Its file writes are immediately visible to the root. To run independent tasks in parallel, emit multiple `agent` calls in one response; eve runs the batch concurrently and returns every result before the root continues. Give parallel children non-overlapping write scopes.
+
+`agent` is intentionally root-only. Copies created by it cannot call `agent`, and declared subagents never receive the built-in tool. If a stale or forced recursive call reaches execution, eve rejects it instead of starting another child session.
 
 The parent transfers data to the child through the `message` input it gives the subagent. Do not include sensitive data in a subagent request unless that child and its inherited tools, connections, sandbox, and telemetry path are appropriate for that data.
 
-An authored tool at `agent/tools/agent.ts` takes priority over the built-in.
+An authored root tool at `agent/tools/agent.ts` takes priority over the built-in.
 
 ## Declared subagents
 
@@ -55,10 +57,10 @@ agent/subagents/researcher/
 
 A declared subagent inherits nothing from the root's authored slots. Discovery treats its directory as its own agent root, so it has only the instructions, tools, connections, skills, sandbox, hooks, and nested subagents authored under `agent/subagents/<id>/`. An absent slot falls back to the framework default, not to the root's version.
 
-| Slot         | Built-in `agent` tool         | Declared subagent                      |
+| Slot         | Root built-in `agent` tool    | Declared subagent                      |
 | ------------ | ----------------------------- | -------------------------------------- |
 | Instructions | Inherited (copy of the agent) | Own `instructions.{md,ts}`, optional   |
-| Tools        | Inherited                     | Own `tools/`                           |
+| Tools        | Inherited except root-only    | Own `tools/`                           |
 | Connections  | Inherited                     | Own `connections/`                     |
 | Skills       | Inherited                     | Own `skills/`                          |
 | Sandbox      | Shared with parent            | Own `sandbox/`, else framework default |
@@ -69,32 +71,17 @@ A declared subagent inherits nothing from the root's authored slots. Discovery t
 
 For a declared subagent this means duplicating anything the child needs. When two subagents need the same procedure, copy the markdown under each `skills/` directory, or share typed helpers via `lib/`. The sandbox does not inherit from the parent; it falls back to the framework default unless the subagent authors `subagents/<id>/sandbox.ts` or seeds files via `subagents/<id>/sandbox/workspace/`.
 
-The built-in `agent` tool is the exception. Its children share the parent's sandbox and tools because they are copies of the same agent working on the same files.
+The root built-in `agent` tool is the exception. Its children share the root's sandbox and tools because they are copies of the same agent working on the same files.
 
 `defineState` is never shared, for either kind. Each child starts with fresh durable state.
 
 ## What the parent sees
 
-eve lowers every subagent (built-in copy, declared, or [remote](./guides/remote-agents)) into a model-visible tool with the same `{ message, outputSchema? }` shape. The parent packs `message` with everything the child needs, since the child never sees the parent's history. Set `outputSchema` to run the child in task mode, returning structured output as the tool result.
-
-Subagent delegation is capped by default at one child-session level. Increase
-or lower that limit with `limits.maxSubagentDepth`:
-
-```ts title="agent/agent.ts"
-export default defineAgent({
-  model: "anthropic/claude-sonnet-5",
-  limits: {
-    maxSubagentDepth: 4,
-  },
-});
-```
-
-The root session is depth 0. With `maxSubagentDepth: 4`, eve may create child sessions
-at depths 1 through 4; a session already at depth 4 cannot delegate again.
+eve lowers every subagent visible to the current agent (the root built-in copy, declared, or [remote](./guides/remote-agents)) into a model-visible tool with the same `{ message, outputSchema? }` shape. The parent packs `message` with everything the child needs, since the child never sees the parent's history. Set `outputSchema` to run the child in task mode, returning structured output as the tool result.
 
-At the configured depth, eve stops advertising subagent tools, including declared local subagents, remote-agent tools, the built-in `agent` tool, and the `Workflow` orchestration tool when it would only expose subagents. If a stale or forced subagent call still reaches execution, eve blocks it and returns an error tool result instead of starting another child session.
+Declared subagents can call nested subagents defined under their own directories. eve does not apply a separate depth limit; nesting ends where the authored directory tree ends. The built-in `agent` follows the stricter root-only rule above, so `limits.maxSubagentDepth` no longer exists.
 
-`Workflow` is root-only. Delegated subagent sessions can still call their own visible subagent tools until the depth cap, but they do not receive the `Workflow` orchestration wrapper. The number of subagent calls one Workflow program may dispatch is capped separately by `limits.maxSubagents` (default 100); see [Dynamic workflows](./guides/dynamic-workflows).
+`Workflow` is also root-only. Child sessions can still call their own declared or remote subagents, but they receive neither `Workflow` nor the built-in `agent`. The Workflow tool's `maxSubagents` option caps the number of calls made by one program (default 100); see [Dynamic workflows](./guides/dynamic-workflows).
 
 A declared subagent's tool name is the bare path-derived name, with no prefix. `agent/subagents/researcher/` registers as the tool `researcher`. Unlike connection tools (`<connection>__<tool>`), it carries no namespace, so the model, approvals, logs, and evals all reference it by that name. Its input schema is:
 

package/docs/tools/overview.mdx

@@ -38,6 +38,7 @@ When a tool returns structured data, add an optional `outputSchema`. With Zod or
 
 - `ctx.session`: session metadata, turn, auth, parent lineage.
 - `ctx.callId`: the id of the current tool call, carried by the call's [stream events](/docs/concepts/sessions-runs-and-streaming) and approval context.
+- `ctx.toolName`: the final runtime name the model called, including any namespace qualification.
 - `ctx.abortSignal`: aborts when the active turn is cancelled. Pass it to cancellation-aware work; sandbox sessions from `ctx.getSandbox()` are already bound to it.
 - `ctx.getSandbox()`: the live [sandbox](/docs/sandbox) handle.
 - `ctx.getSkill(id)`: read a packaged [skill](/docs/skills)'s metadata and files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve",
-  "version": "0.22.6",
+  "version": "0.24.0",
   "private": false,
   "description": "Filesystem-first framework for durable backend AI agents that run anywhere.",
   "keywords": [

package/dist/src/compiler/channel-instrumentation-types.d.ts

@@ -1,8 +0,0 @@
-import type { CompiledAgentManifest } from "#compiler/manifest.js";
-interface ChannelInstrumentationTypesSourceInput {
-    readonly manifest: CompiledAgentManifest;
-    readonly typesPath: string;
-}
-export declare const CHANNEL_INSTRUMENTATION_TYPES_FILE_NAME = "channel-instrumentation-types.d.ts";
-export declare function createChannelInstrumentationTypesSource(input: ChannelInstrumentationTypesSourceInput): string;
-export {};

package/dist/src/compiler/channel-instrumentation-types.js

@@ -1,2 +0,0 @@
-import{dirname,join,relative}from"node:path";const CHANNEL_INSTRUMENTATION_TYPES_FILE_NAME=`channel-instrumentation-types.d.ts`;function createChannelInstrumentationTypesSource(e){let t=collectChannelInstrumentationDeclarations(e);return[`// Generated by eve. Do not edit by hand.`,`import type { InferChannelMetadata } from "eve/channels";`,``,`declare module "eve/channels" {`,...t.length===0?[`  interface ChannelMetadataMap {}`,`  interface ChannelReferenceMap {}`]:[`  interface ChannelMetadataMap {`,...t.map(e=>`    readonly ${JSON.stringify(e.kind)}: InferChannelMetadata<${renderImportedChannelType(e)}>;`),`  }`,`  interface ChannelReferenceMap {`,...t.map(e=>`    readonly ${JSON.stringify(e.kind)}: ${renderImportedChannelType(e)};`),`  }`],`}`,``].join(`
-`)}function collectChannelInstrumentationDeclarations(t){let n=dirname(t.typesPath),r=new Map;for(let e of[...t.manifest.channels].filter(e=>e.kind===`channel`).sort(compareCompiledChannels)){let i=`channel:${e.name}`;r.has(i)||r.set(i,{exportName:e.exportName,importSpecifier:createChannelImportSpecifier({agentRoot:t.manifest.agentRoot,channel:e,fromDirectory:n}),kind:i})}return[...r.values()]}function compareCompiledChannels(e,t){return e.name.localeCompare(t.name)||e.logicalPath.localeCompare(t.logicalPath)||(e.exportName??``).localeCompare(t.exportName??``)||e.sourceId.localeCompare(t.sourceId)||e.method.localeCompare(t.method)||e.urlPath.localeCompare(t.urlPath)}function createChannelImportSpecifier(e){let r=join(e.agentRoot,toRuntimeImportLogicalPath(e.channel.logicalPath)),i=relative(e.fromDirectory,r).replaceAll(`\\`,`/`);return i.startsWith(`.`)?i:`./${i}`}function toRuntimeImportLogicalPath(e){return e.endsWith(`.mts`)?`${e.slice(0,-4)}.mjs`:e.endsWith(`.cts`)?`${e.slice(0,-4)}.cjs`:e.endsWith(`.ts`)?`${e.slice(0,-3)}.js`:e}function renderImportedChannelType(e){let t=e.exportName??`default`,n=`import(${JSON.stringify(e.importSpecifier)})`;return isIdentifierName(t)?`typeof ${n}.${t}`:`typeof ${n}[${JSON.stringify(t)}]`}function isIdentifierName(e){return/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(e)}export{CHANNEL_INSTRUMENTATION_TYPES_FILE_NAME,createChannelInstrumentationTypesSource};