eve 0.20.0 → 0.21.0

package/docs/channels/chat-sdk.mdx

@@ -0,0 +1,209 @@
+---
+title: "Chat SDK"
+description: "Bridge any Vercel Chat SDK adapter — Slack, Discord, Telegram, WhatsApp, email, and more — to your agent through one channel, using your own credentials and state store."
+---
+
+The Chat SDK channel connects your agent to any [Vercel Chat SDK](https://chat-sdk.dev) adapter. You pick an adapter (`@chat-adapter/slack`, `@resend/chat-sdk-adapter`, and so on), register handlers for the messages you care about, and call `send` to hand each turn to eve. Use it to reach a surface eve does not ship a first-class channel for, or when you want to manage credentials and state with the Chat SDK's own primitives rather than [Vercel Connect](../guides/auth-and-route-protection). See [Channels](./overview) for the contract this builds on.
+
+You supply an adapter and a state store: the adapter owns provider auth, webhook verification, and delivery, while eve owns session dispatch, streaming, typing, and human-in-the-loop. First-class channels such as [Slack](./slack) manage credentials through Vercel Connect instead — reach for whichever fits the surface you are targeting.
+
+## Install
+
+Add eve, the Chat SDK core (`chat`), an adapter, and a state adapter. The example below uses the Resend email adapter with the in-memory state store:
+
+```bash
+npm install eve@latest chat @resend/chat-sdk-adapter @chat-adapter/state-memory
+```
+
+Swap in whichever adapter matches your surface — `@chat-adapter/slack`, `@chat-adapter/discord`, `@chat-adapter/telegram`, and so on. Any Chat SDK adapter works.
+
+## Add the channel
+
+`chatSdkChannel` returns `{ bot, channel, send }`. Register Chat SDK handlers on `bot`, call `send` from those handlers to start or resume an eve session, and export `channel` as the module default:
+
+```ts title="agent/channels/resend.ts"
+import { createMemoryState } from "@chat-adapter/state-memory";
+import { createResendAdapter } from "@resend/chat-sdk-adapter";
+import type { Message, Thread } from "chat";
+import { chatSdkChannel } from "eve/channels/chat-sdk";
+
+export const { bot, channel, send } = chatSdkChannel({
+  userName: "Resend Bot",
+  adapters: {
+    resend: createResendAdapter({
+      fromAddress: "hello@example.com",
+      fromName: "Resend Bot",
+    }),
+  },
+  state: createMemoryState(),
+  streaming: false,
+});
+
+bot.onNewMention(async (thread: Thread, message: Message) => {
+  await thread.subscribe();
+  await send(message.text, { thread });
+});
+
+bot.onSubscribedMessage(async (thread: Thread, message: Message) => {
+  await send(message.text, { thread });
+});
+
+export default channel;
+```
+
+`adapters` is a map of adapter name to adapter instance; each entry mounts its own webhook (see below). `state` takes any Chat SDK state adapter: `createMemoryState()` is fine for local development, but use a durable adapter (Redis, Upstash, etc.) in production so thread subscriptions and inbound deduplication survive restarts. `send` accepts a plain string, an AI SDK `UserContent` array, or a `SendPayload`, and must be called from inside a Chat SDK handler — it dispatches the turn on the webhook that is currently running.
+
+Deploy once the channel file is in place:
+
+```bash
+eve deploy
+```
+
+`eve deploy` links the project if needed and deploys to Vercel production.
+
+## Configure the webhook route
+
+Each adapter mounts one `POST` route at `/eve/v1/{adapterName}`, so the `resend` adapter above is served at `/eve/v1/resend`. Point your provider's webhook (the Resend inbound address, the Slack Event Subscriptions URL, etc.) at that path.
+
+Override the base path for every adapter with `route`, or pin an individual adapter's path with `routes`:
+
+```ts
+export const { bot, channel, send } = chatSdkChannel({
+  userName: "Resend Bot",
+  adapters: { resend: createResendAdapter({ fromAddress: "hello@example.com" }) },
+  state: createMemoryState(),
+  route: "/webhooks", // resend now mounts at /webhooks/resend
+  routes: { resend: "/webhooks/inbound-email" }, // …or pin it exactly
+});
+```
+
+Use `routes` when a provider requires a fixed URL or when you are migrating an existing endpoint without changing the provider's settings.
+
+## How the channel handles messages
+
+### Dispatch
+
+You choose which Chat SDK events start a turn by registering handlers on `bot` and calling `send`:
+
+- `bot.onNewMention(thread, message)` fires on a fresh `@mention` (or, for surfaces like email, a new inbound thread). Call `thread.subscribe()` when you want later replies in the same thread to keep reaching the agent.
+- `bot.onSubscribedMessage(thread, message)` fires on subsequent messages in a subscribed thread.
+- `bot.onAction`, `bot.onReaction`, and `bot.onSlashCommand` are available for adapters that emit them.
+
+`send(input, options)` starts or resumes the eve session. The `thread` you pass determines the continuation token and the persisted channel state, so replies land back on the originating thread:
+
+```ts
+bot.onNewMention(async (thread, message) => {
+  await send(message.text, { thread, title: "Support request" });
+});
+```
+
+`options` accepts `{ thread, auth?, title?, mode?, callback?, adapterName? }`. `title` sets the eve session's display title without changing the model message; `auth` attaches an authenticated principal to the turn.
+
+### Delivery
+
+The default handlers post the agent's reply back to the thread — no `events` override required. Completed assistant messages are posted as markdown (`{ markdown: … }`) so adapters render rich text and email HTML rather than a raw string.
+
+Streaming is on by default: the channel posts an initial message and edits it as tokens arrive (`message.appended`), throttled by `streamingEditIntervalMs` (default `1000`). Set `streaming: false` for surfaces that deliver one message per turn — email, for example — so the reply posts once on completion instead of editing:
+
+```ts
+chatSdkChannel({
+  userName: "Resend Bot",
+  adapters: { resend: createResendAdapter({ fromAddress: "hello@example.com" }) },
+  state: createMemoryState(),
+  streaming: false,
+});
+```
+
+Typing indicators post automatically where the adapter supports them: `Working…` on `turn.started`, and tool status on `actions.requested`.
+
+### Optional capabilities degrade gracefully
+
+Adapters do not all implement every operation. When an adapter's `startTyping` or `editMessage` throws a `NotImplementedError` (or an error with code `NOT_IMPLEMENTED`), the channel swallows it: typing indicators are skipped, and a streaming edit falls back to a single final post for the rest of the session. You never have to guard optional capabilities in your own handlers. The same predicate is exported as `isNotImplemented` if you want it in custom `events`:
+
+```ts
+import { isNotImplemented } from "eve/channels/chat-sdk";
+```
+
+Override any default by passing `events`. Handlers receive `(eventData, channel, ctx)`, with the rebuilt Chat SDK thread on `channel.thread`:
+
+```ts
+chatSdkChannel({
+  userName: "Resend Bot",
+  adapters: { resend: createResendAdapter({ fromAddress: "hello@example.com" }) },
+  state: createMemoryState(),
+  events: {
+    "message.completed"(eventData, channel) {
+      if (eventData.finishReason === "tool-calls" || !eventData.message || !channel.thread) return;
+      return channel.thread.post({ markdown: eventData.message });
+    },
+  },
+});
+```
+
+### Human-in-the-loop (HITL)
+
+HITL prompts render as a Chat SDK `Card` with buttons. Button clicks resume the parked session automatically — the channel wires `bot.onAction` for you. Change the action-id prefix with `inputActionPrefix` (default `eve_input:`) if your app already uses it, and provide `resolveInputAuth` to carry user or tenant auth across the resume:
+
+```ts
+chatSdkChannel({
+  userName: "Support Bot",
+  adapters: { slack: createSlackAdapter() },
+  state: createMemoryState(),
+  resolveInputAuth: (event) => ({
+    authenticator: "slack",
+    principalType: "user",
+    principalId: event.user?.userId ?? "unknown",
+    attributes: {},
+  }),
+});
+```
+
+### Proactive sessions
+
+Start a session without an inbound webhook through `channel.receive({ message, target, auth })` — from a schedule `run` handler, or `args.receive(channel, ...)` from another channel. The target is a serialized Chat SDK thread, or `{ threadId, adapterName }` when you only have a provider-native thread id:
+
+```ts
+await channel.receive({
+  message: "Your weekly digest is ready.",
+  target: { adapterName: "resend", threadId: "resend:user@example.com" },
+  auth: null,
+});
+```
+
+### Attachments
+
+`send` takes plain text or an AI SDK `UserContent` array. To forward a Chat SDK message's attachments, convert it with `messageToUserContent`, which returns `message.text` when there are no attachments and a `UserContent` array (text plus one file part per attachment URL) when there are:
+
+```ts
+import { messageToUserContent } from "eve/channels/chat-sdk";
+
+bot.onNewMention(async (thread, message) => {
+  await send(messageToUserContent(message), { thread });
+});
+```
+
+See [File uploads](./custom#file-uploads) for how eve stages remote file URLs before the model call.
+
+## Configuration reference
+
+| Option                    | Default      | Purpose                                                                  |
+| ------------------------- | ------------ | ------------------------------------------------------------------------ |
+| `adapters`                | —            | Map of adapter name to Chat SDK adapter instance. One webhook per entry. |
+| `state`                   | —            | Chat SDK state adapter for subscriptions, locks, and dedupe.             |
+| `userName`                | —            | Display name for the bot (a standard Chat SDK `ChatConfig` field).       |
+| `route`                   | `/eve/v1`    | Base path for generated adapter webhooks (`{route}/{adapter}`).          |
+| `routes`                  | —            | Per-adapter path overrides for fixed or migrated webhook URLs.           |
+| `streaming`               | `true`       | Post-then-edit streaming. Set `false` for one-message-per-turn surfaces. |
+| `streamingEditIntervalMs` | `1000`       | Minimum interval between streaming edits.                                |
+| `events`                  | built-in     | Per-event handlers. A supplied handler replaces that built-in default.   |
+| `inputActionPrefix`       | `eve_input:` | Prefix for default HITL button action ids.                               |
+| `resolveInputAuth`        | `null`       | Auth resolver applied when a HITL button click resumes a session.        |
+| `webhook`                 | —            | Extra Chat SDK webhook options (eve owns `waitUntil`).                   |
+
+Any other Chat SDK `ChatConfig` field (for example `concurrency`) is accepted and passed through.
+
+## What to read next
+
+- [Channels overview](./overview): the channel contract and every built-in channel
+- [Custom channels](./custom): build a channel for any surface with `defineChannel`
+- [Auth & route protection](../guides/auth-and-route-protection): authenticating inbound traffic

package/docs/channels/meta.json

@@ -10,6 +10,7 @@
     "twilio",
     "github",
     "linear",
+    "chat-sdk",
     "custom"
   ]
 }

package/docs/concepts/context-control.md

@@ -52,13 +52,13 @@ When the task is novel or ambiguous, gather evidence first, then answer with the
 remaining uncertainty.
 ```
 
-Packaged skills are useful when you also want sibling files such as `references/`, `assets/`, or `scripts/` under the same skill directory. Those paths show up under the runtime workspace root, so the model can inspect them with the normal file or shell tools instead of pasting their content into the prompt.
+Packaged skills are useful when you also want sibling files such as `references/`, `assets/`, or `scripts/` under the same skill directory. Those files are available under the runtime skill root, normally `$HOME/.agents/skills/<skill>/`. Relative references inside a `SKILL.md` resolve from that specific skill directory, so `references/checklist.md` means `$HOME/.agents/skills/<skill>/references/checklist.md` unless eve has fallen back to `/workspace/skills/<skill>/`.
 
 See [Skills](../skills) for the full authoring model and install notes.
 
 ## Put runtime files in the workspace, not the prompt
 
-eve does not inline the entire authored surface into the prompt. Instead, it gives the model a shallow workspace hint and runtime tools to inspect deeper when needed. Skill files are available under the active workspace root, and the model inspects them with the shared `bash` tool, which keeps prompts smaller and makes file and command work explicit.
+eve does not inline the entire authored surface into the prompt. Instead, it gives the model a shallow workspace hint, a separate skill-root hint, and runtime tools to inspect deeper when needed. Skill package files are outside `/workspace` in the normal case, and the model inspects them with the shared `bash` tool, which keeps prompts smaller and makes file and command work explicit.
 
 See [Sandbox](../sandbox) for the workspace and sandbox model.
 

package/docs/concepts/default-harness.md

@@ -87,6 +87,16 @@ Three moves shape the harness. The right one depends on whether the model should
 - **Disable** when the model should not have the capability at all. A `disableTool()` sentinel removes the built-in, and the model never sees it. Reach for this to lock down `bash` or `web_fetch` in an agent that should not run shell commands or fetch arbitrary URLs.
 - **Author a new tool** when you want a capability the harness does not ship. Give it a fresh slug under `agent/tools/` and it joins the built-ins instead of replacing one. See [Tools](../tools) for the authoring model.
 
+## The opt-in `Workflow` tool
+
+An experimental `Workflow` tool ships but stays off by default. To turn it on, re-export the opt-in marker from `agent/tools/workflow.ts`:
+
+```ts
+export { ExperimentalWorkflow as default } from "eve/tools";
+```
+
+With it on, the model can orchestrate the agent's own subagents from model-authored JavaScript, all as one durable step. The tool is root-only — delegated subagent sessions never see it — and one program may dispatch at most `limits.maxSubagents` subagent calls (default 100). See [Dynamic workflows](../guides/dynamic-workflows).
+
 ## What to read next
 
 - [Tools](../tools): define your own tools, gate them on approval, and shape their output with `toModelOutput`

package/docs/concepts/sessions-runs-and-streaming.md

@@ -38,7 +38,7 @@ The stream is newline-delimited JSON (NDJSON), one event per line:
 | ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
 | `session.started`         | A durable session was created.                                                                                   |
 | `turn.started`            | A new turn began.                                                                                                |
-| `message.received`        | An inbound user message was accepted.                                                                            |
+| `message.received`        | An inbound user message was accepted; carries flattened text plus structured text/file parts.                    |
 | `step.started`            | A model step began.                                                                                              |
 | `actions.requested`       | The model requested one or more actions, including tool calls; calls stream before execution.                    |
 | `action.result`           | A tool call returned.                                                                                            |

package/docs/guides/client/messages.mdx

@@ -98,6 +98,10 @@ const response = await session.send({
 await response.result();
 ```
 
+The stream confirms the turn with `message.received`. Its `data.message` remains the flattened
+summary for compatibility, and `data.parts` contains structured text and file metadata for clients
+that render attachments. File parts never include raw bytes or internal sandbox paths.
+
 ## Answer human input requests
 
 Tools can pause for approval or ask the user a question. The stream emits `input.requested` with one or more requests. Reply through the same session with `inputResponses`:

package/docs/guides/client/streaming.mdx

@@ -61,21 +61,26 @@ function handleEvent(event: HandleMessageStreamEvent) {
 
 The most common UI events are:
 
-| Event                | Use                                                              |
-| -------------------- | ---------------------------------------------------------------- |
-| `message.received`   | Confirm the user message landed.                                 |
-| `reasoning.appended` | Render reasoning deltas when the model provides them.            |
-| `message.appended`   | Render assistant text deltas.                                    |
-| `actions.requested`  | Show tool calls as the model requests them, before execution.    |
-| `action.result`      | Show tool call results.                                          |
-| `input.requested`    | Pause the UI for approval or a question answer.                  |
-| `result.completed`   | Read structured output from an [output schema](./output-schema). |
-| `session.waiting`    | Enable the composer for the next turn.                           |
-| `session.completed`  | Mark the conversation terminal.                                  |
-| `session.failed`     | Mark the conversation failed.                                    |
+| Event                | Use                                                                            |
+| -------------------- | ------------------------------------------------------------------------------ |
+| `message.received`   | Confirm the user message landed; `data.parts` includes text and file metadata. |
+| `reasoning.appended` | Render reasoning deltas when the model provides them.                          |
+| `message.appended`   | Render assistant text deltas.                                                  |
+| `actions.requested`  | Show tool calls as the model requests them, before execution.                  |
+| `action.result`      | Show tool call results.                                                        |
+| `input.requested`    | Pause the UI for approval or a question answer.                                |
+| `result.completed`   | Read structured output from an [output schema](./output-schema).               |
+| `session.waiting`    | Enable the composer for the next turn.                                         |
+| `session.completed`  | Mark the conversation terminal.                                                |
+| `session.failed`     | Mark the conversation failed.                                                  |
 
 For the complete event table, see [Sessions, runs & streaming](../../concepts/sessions-runs-and-streaming).
 
+When a submitted message includes attachments, `message.received.data.message` stays the
+flattened compatibility summary, while `message.received.data.parts` carries renderable text and
+file metadata. File parts never include raw bytes or internal sandbox paths; `url` appears only for
+client-resolvable `http(s)` and `data:` URLs.
+
 ## Authorization pauses
 
 `authorization.required` is different from the normal `session.waiting` boundary. It means a connection needs OAuth or another authorization challenge before the parked turn can continue. Chat UIs should render the authorization prompt, disable ordinary text input for that session, and persist the event with the rest of the chat history.

package/docs/guides/dynamic-workflows.md

@@ -0,0 +1,87 @@
+---
+title: "Dynamic Workflows"
+description: "The experimental Workflow tool: let the model orchestrate its own subagents from model-authored JavaScript as one durable step."
+---
+
+The experimental `Workflow` tool lets the model write JavaScript that coordinates the agent's own subagents as a single durable step. The program can run them in sequence, feed one result into the next, fan out over a list, and combine the results. You enable the capability and the model decides and runs the orchestration.
+
+A single turn can already call several subagents, and parallel tool calls dispatch concurrently. What a workflow adds is _programmatic_ coordination. The program decides how many subagents to run based on an earlier result, which output feeds which call, and how to combine everything. That is logic the model cannot express as a few one-off calls.
+
+## Enable the Workflow tool
+
+Re-export the opt-in marker as the default export of `agent/tools/workflow.ts`. The marker name carries the "experimental" warning, but the tool the model actually sees is named `Workflow`.
+
+```ts title="agent/tools/workflow.ts"
+export { ExperimentalWorkflow as default } from "eve/tools";
+```
+
+Without that file, the `Workflow` tool stays off. It earns its keep only when the agent has subagents (or the built-in `agent`) worth coordinating:
+
+```ts title="agent/subagents/analyst/agent.ts"
+import { defineAgent } from "eve";
+
+export default defineAgent({
+  description: "Analyzes one metric: queries, computes, writes a short finding.",
+  model: "anthropic/claude-opus-4.8",
+});
+```
+
+When asked for a weekly business review, the model picks the metrics, runs one `analyst` per metric in parallel, and combines the findings. The program below is the kind of JavaScript the model authors. It fans `analyst` out over a runtime-decided list of metrics and merges the results:
+
+```js
+const metrics = ["revenue", "signups", "churn"];
+const findings = await Promise.all(
+  metrics.map((metric) => tools.analyst({ message: `Summarize last week's ${metric}.` })),
+);
+return findings.join("\n\n");
+```
+
+Each `tools.analyst(...)` call dispatches a child subagent, so the parent stream records one `subagent.called` per metric and one `subagent.completed` as each finishes:
+
+```json
+{ "type": "subagent.called", "data": { "name": "analyst", "toolName": "analyst", "callId": "call_1", "childSessionId": "ses_a1", "sequence": 0 } }
+{ "type": "subagent.called", "data": { "name": "analyst", "toolName": "analyst", "callId": "call_2", "childSessionId": "ses_a2", "sequence": 1 } }
+{ "type": "subagent.called", "data": { "name": "analyst", "toolName": "analyst", "callId": "call_3", "childSessionId": "ses_a3", "sequence": 2 } }
+{ "type": "subagent.completed", "data": { "subagentName": "analyst", "callId": "call_1", "output": "..." } }
+{ "type": "subagent.completed", "data": { "subagentName": "analyst", "callId": "call_2", "output": "..." } }
+{ "type": "subagent.completed", "data": { "subagentName": "analyst", "callId": "call_3", "output": "..." } }
+```
+
+## What a workflow can orchestrate
+
+A workflow reaches only this agent's own agents: the built-in `agent` (a copy of itself), declared [subagents](../subagents), and [remote agents](./remote-agents). That is the whole list. No files, network, shell, skills, or connections. A workflow is a coordination layer over subagents, not a place to do other work. Each call can still request structured output via `outputSchema`, exactly like a direct subagent delegation.
+
+## Caps on workflow-spawned subagents
+
+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.
+
+```ts title="agent/agent.ts"
+export default defineAgent({
+  model: "anthropic/claude-sonnet-5",
+  limits: {
+    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)).
+
+## Where the JavaScript runs
+
+The orchestration code never touches the agent's process. The runtime hands the program text to a small isolated JavaScript engine (a QuickJS sandbox) and runs it there. Nothing from the host realm crosses in, so there is no `process`, no `globalThis` from the agent, and no `import`/`require`. The program can reach exactly two things, the agent functions bridged in as `tools.<name>` and the ordinary language built-ins.
+
+That is an allowlist, not a denylist. The sandbox cannot read files, open a socket, or see an environment variable because those are not present, not because each one is blocked in turn. When the program calls an agent function, that call bridges back out to the runtime, which dispatches it exactly like a direct delegation. The orchestration glue stays inside the sandbox.
+
+## Durability, approvals, and observability
+
+- **Durable.** The whole orchestration counts as one step. Subagents dispatched together run concurrently, and if a run parks (suspends durably without holding compute; see [Execution model & durability](../concepts/execution-model-and-durability)) on a long-running or human-gated child, it resumes where it left off after a restart.
+- **Approval-safe.** A subagent that needs human approval (HITL, human-in-the-loop) mid-run surfaces its request to the user, and the workflow picks back up once that is answered, same as direct delegation.
+- **Observable.** Every orchestrated subagent emits the usual `subagent.called` / `subagent.completed` events on the parent stream and gets its own child session and stream. The telemetry matches direct delegation, so existing dashboards and cost attribution keep working.
+
+## What to read next
+
+- Declare the subagents a workflow orchestrates → [Subagents](../subagents)
+- Call another deployment as one of those agents → [Remote agents](./remote-agents)
+- The `agent/tools/` opt-in mechanism → [Default harness](../concepts/default-harness)

package/docs/guides/frontend/overview.mdx

@@ -74,7 +74,7 @@ export function Chat() {
 
 Most chat UIs only need `data.messages` and `status`. Drop down to `events` when you need the authoritative wire events directly, for example to persist an audit log or build a custom projection.
 
-`data.messages` are `EveMessage[]` following the AI SDK `UIMessage` convention, so they drop straight into any AI SDK UI primitive that accepts a `UIMessage[]`. Parts include user text, assistant text, reasoning, tool calls, tool results, input requests, and connection authorization prompts.
+`data.messages` are `EveMessage[]` following the AI SDK `UIMessage` convention, so they drop straight into any AI SDK UI primitive that accepts a `UIMessage[]`. Parts include user text, user file attachments, assistant text, reasoning, tool calls, tool results, input requests, and connection authorization prompts.
 
 ## Sending and streaming
 
@@ -98,6 +98,10 @@ await agent.send({
 
 Assistant text, reasoning, tool calls, and tool results stream into `data` as they arrive, and `status` moves from `ready` to `submitted` to `streaming` and back. Call `stop()` to abort the active request, and `reset()` to clear local state so the next send starts a fresh durable session.
 
+After eve confirms an attachment turn with `message.received`, the default reducer projects each
+received attachment as a `file` part on the user message. The part includes `mediaType`, optional
+`filename` and `size`, and a `url` only when the original attachment was browser-resolvable.
+
 ## Human-in-the-loop prompts
 
 Tools opt into approval with `approval`, and the model can also ask a question with `ask_question` — see [Human-in-the-loop](/docs/human-in-the-loop) for the server-side model. Either way the stream emits an `input.requested` event, and the pending request rides on a `dynamic-tool` part of the latest message at `part.toolMetadata?.eve?.inputRequest`. Read it, then answer through the same session with `send()`:

package/docs/guides/meta.json

@@ -8,6 +8,7 @@
     "session-context",
     "state",
     "dynamic-capabilities",
+    "dynamic-workflows",
     "remote-agents",
     "dev-tui",
     "frontend",

package/docs/guides/remote-agents.md

@@ -60,4 +60,5 @@ Both failure paths surface to the parent as a failed tool result, so the caller
 ## What to read next
 
 - Local delegation and the isolation boundary → [Subagents](../subagents)
+- Have the model orchestrate remote agents programmatically → [Dynamic workflows](./dynamic-workflows)
 - Securing the receiving deployment → [Auth & route protection](./auth-and-route-protection)

package/docs/reference/project-layout.md

@@ -54,7 +54,7 @@ The Subagents column states whether a local subagent (`subagents/<id>/`) can aut
 | `channels/`                                             | HTTP / messaging entrypoints                | No        | Root-only.                                                                                                                                                                                                            |
 | `connections/`                                          | External service connections (MCP, OpenAPI) | Yes       | One connection per file; name derived from filename.                                                                                                                                                                  |
 | `hooks/`                                                | Lifecycle and stream-event subscribers      | Yes       | Module-backed only. Recursive directories supported.                                                                                                                                                                  |
-| `skills/`                                               | On-demand procedures and capability packs   | Yes       | Flat markdown, module-backed skills, or packaged skills. Seeded into `/workspace/skills/...`.                                                                                                                         |
+| `skills/`                                               | On-demand procedures and capability packs   | Yes       | Flat markdown, module-backed skills, or packaged skills. Seeded into `$HOME/.agents/skills/...`, with `/workspace/skills/...` as a fallback if `$HOME` is unavailable.                                                |
 | `lib/`                                                  | Shared authored helper code                 | Yes       | Import-only; not mounted into the workspace.                                                                                                                                                                          |
 | `sandbox.ts` or `sandbox/sandbox.ts`                    | The agent's single sandbox                  | Yes       | Use top-level `sandbox.ts` for a definition-only override; use `sandbox/sandbox.ts` + `sandbox/workspace/**` to also seed files. Framework default applies when neither is authored.                                  |
 | `sandbox/workspace/**`                                  | Files seeded into the sandbox               | Yes       | Mirrored into `/workspace/...` at session bootstrap.                                                                                                                                                                  |
@@ -62,13 +62,14 @@ The Subagents column states whether a local subagent (`subagents/<id>/`) can aut
 | `schedules/`                                            | Recurring jobs                              | No        | Each schedule is `<name>.ts` (default-exported `defineSchedule`) or `<name>.md` (frontmatter `cron:` + prompt body). Recursive nesting supported. Root-only.                                                          |
 | `subagents/`                                            | Specialist child agents                     | Yes       | Each child is its own local package under `subagents/<id>/`. Nested subagents are supported.                                                                                                                          |
 
-## What reaches the runtime workspace
+## What reaches the runtime sandbox
 
-eve does not mount the whole tree. Only two sources land in the sandbox workspace:
+eve does not mount the whole tree. Authored workspace files land in the sandbox workspace:
 
-- `skills/` files → `/workspace/skills/...`
 - `agent/sandbox/workspace/**` → `/workspace/...` at session bootstrap
 
+Skill files land outside the workspace, under `$HOME/.agents/skills/...`. If `$HOME` is unavailable, eve falls back to `/workspace/skills/...`. Packaged skill references such as `references/checklist.md` resolve relative to the directory containing that skill's `SKILL.md`.
+
 Everything in `lib/` stays import-only source code and never reaches the workspace.
 
 ## Local subagent layout

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` 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 `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.
 
 ## Runtime context (`ctx`)
 
@@ -68,31 +68,31 @@ A few non-`define*` helpers round out the set: `disableTool` from `eve/tools` (s
 
 ## Imports at a glance
 
-| Import                                                      | Holds                                                     |
-| ----------------------------------------------------------- | --------------------------------------------------------- |
-| `eve`                                                       | `defineAgent`, `defineRemoteAgent`, agent config types    |
-| `eve/tools`                                                 | `defineTool`, `defineDynamic`, `disableTool`              |
-| `eve/tools/defaults`                                        | the built-in tools as plain values                        |
-| `eve/tools/approval`                                        | `always`, `once`, `never`                                 |
-| `eve/connections`                                           | `defineMcpClientConnection`, `defineOpenAPIConnection`    |
-| `eve/channels`                                              | `defineChannel`, route verbs                              |
-| `eve/channels/eve`                                          | `eveChannel`                                              |
-| `eve/channels/auth`                                         | `localDev`, `vercelOidc`, `placeholderAuth`               |
-| `eve/channels/{slack,discord,teams,telegram,twilio,github}` | platform channel factories                                |
-| `eve/hooks`                                                 | `defineHook`                                              |
-| `eve/schedules`                                             | `defineSchedule`                                          |
-| `eve/skills`                                                | `defineSkill`, `defineDynamic`                            |
-| `eve/instructions`                                          | `defineInstructions`, `defineDynamic`                     |
-| `eve/context`                                               | `defineState`, session and state types                    |
-| `eve/sandbox`                                               | `defineSandbox`, backends                                 |
-| `eve/instrumentation`                                       | `defineInstrumentation`, `isChannel`                      |
-| `eve/evals`                                                 | `defineEval`, `defineEvalConfig`, `mockModel`, eval types |
-| `eve/evals/expect`                                          | `includes`, `equals`, `matches`, `similarity`             |
-| `eve/evals/reporters`                                       | `Braintrust`, `JUnit`, `EvalReporter`                     |
-| `eve/evals/loaders`                                         | `loadJson`, `loadYaml`                                    |
-| `eve/react`, `eve/vue`, `eve/svelte`                        | `useEveAgent`                                             |
-| `eve/next`, `eve/nuxt`, `eve/sveltekit`                     | framework bundler plugins                                 |
-| [`eve/client`](../guides/client/overview)                   | `Client`, `ClientSession`                                 |
+| Import                                                      | Holds                                                                |
+| ----------------------------------------------------------- | -------------------------------------------------------------------- |
+| `eve`                                                       | `defineAgent`, `defineRemoteAgent`, agent config types               |
+| `eve/tools`                                                 | `defineTool`, `defineDynamic`, `disableTool`, `ExperimentalWorkflow` |
+| `eve/tools/defaults`                                        | the built-in tools as plain values                                   |
+| `eve/tools/approval`                                        | `always`, `once`, `never`                                            |
+| `eve/connections`                                           | `defineMcpClientConnection`, `defineOpenAPIConnection`               |
+| `eve/channels`                                              | `defineChannel`, route verbs                                         |
+| `eve/channels/eve`                                          | `eveChannel`                                                         |
+| `eve/channels/auth`                                         | `localDev`, `vercelOidc`, `placeholderAuth`                          |
+| `eve/channels/{slack,discord,teams,telegram,twilio,github}` | platform channel factories                                           |
+| `eve/hooks`                                                 | `defineHook`                                                         |
+| `eve/schedules`                                             | `defineSchedule`                                                     |
+| `eve/skills`                                                | `defineSkill`, `defineDynamic`                                       |
+| `eve/instructions`                                          | `defineInstructions`, `defineDynamic`                                |
+| `eve/context`                                               | `defineState`, session and state types                               |
+| `eve/sandbox`                                               | `defineSandbox`, backends                                            |
+| `eve/instrumentation`                                       | `defineInstrumentation`, `isChannel`                                 |
+| `eve/evals`                                                 | `defineEval`, `defineEvalConfig`, `mockModel`, eval types            |
+| `eve/evals/expect`                                          | `includes`, `equals`, `matches`, `similarity`                        |
+| `eve/evals/reporters`                                       | `Braintrust`, `JUnit`, `EvalReporter`                                |
+| `eve/evals/loaders`                                         | `loadJson`, `loadYaml`                                               |
+| `eve/react`, `eve/vue`, `eve/svelte`                        | `useEveAgent`                                                        |
+| `eve/next`, `eve/nuxt`, `eve/sveltekit`                     | framework bundler plugins                                            |
+| [`eve/client`](../guides/client/overview)                   | `Client`, `ClientSession`                                            |
 
 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/sandbox.mdx

@@ -82,7 +82,7 @@ agent/sandbox/
     scripts/run.sh          ← lands at /workspace/scripts/run.sh
 ```
 
-Every file under `workspace/` mirrors into the sandbox cwd with its structure intact, and eve lists the top-level entries to the model in the prompt automatically. One subtree is off limits. Skill discovery already seeds skill files under `/workspace/skills/`, so authoring `agent/sandbox/workspace/skills/...` is rejected; put those under `agent/skills/` instead.
+Every file under `workspace/` mirrors into the sandbox cwd with its structure intact, and eve lists the top-level entries to the model in the prompt automatically. `agent/skills/` files are materialized separately under `$HOME/.agents/skills/`, so `agent/sandbox/workspace/skills/...` is an ordinary workspace subtree when you choose to author one.
 
 ## Overriding the sandbox
 

package/docs/skills.mdx

@@ -9,6 +9,8 @@ A skill is a model-loadable procedure that follows the `SKILL.md` convention. It
 
 eve scans the files under `agent/skills/` and exposes each one's description to the model alongside a framework-owned `load_skill` tool. When a request matches a skill's description (or you name the skill outright), the model calls `load_skill`, and eve appends that skill's markdown to the active turn's context.
 
+At runtime, skill package files are placed under `$HOME/.agents/skills/<skill>/`. If `$HOME` is unavailable in a sandbox, eve falls back to `/workspace/skills/<skill>/`. `load_skill` reads `SKILL.md` automatically; any sibling references inside that file, such as `references/checklist.md`, are relative to the directory containing that specific `SKILL.md`.
+
 The description is a routing hint, not a label. Write it as the task that should trigger activation:
 
 ```md
@@ -68,7 +70,7 @@ const research = ctx.getSkill("research");
 const checklist = await research.file("references/checklist.md").text();
 ```
 
-The handle exposes the skill's `name` and `file(relativePath)`; file content is read lazily from the active sandbox.
+The handle exposes the skill's `name` and `file(relativePath)`; file content is read lazily from the active sandbox, relative to that skill package directory.
 
 ## Dynamic skills
 

package/docs/subagents.mdx

@@ -94,7 +94,7 @@ at depths 1 through 4; a session already at depth 4 cannot delegate again.
 
 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.
 
-`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.
+`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).
 
 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:
 
@@ -118,3 +118,4 @@ Split out a subagent when the task needs a different prompt or specialist role,
 ## What to read next
 
 - [Remote agents](./guides/remote-agents): call another eve deployment as a subagent.
+- [Dynamic workflows](./guides/dynamic-workflows): have the model orchestrate its subagents programmatically (fan-out, map-reduce).

package/package.json

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