eve 0.22.6 → 0.23.0

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`. `limits.maxSubagents` separately caps the number of calls made by one Workflow 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve",
-  "version": "0.22.6",
+  "version": "0.23.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};