eve 0.10.0 → 0.11.1

package/docs/channels/twilio.mdx

@@ -4,7 +4,7 @@ description: "Reach your agent over SMS and speech-transcribed phone calls with
 type: integration
 ---
 
-The Twilio channel puts your agent on a phone number, so people can text it or call it. Inbound SMS arrives as a webhook. Inbound calls get answered with TwiML `<Gather input="speech">`, and the resulting transcript feeds the same Eve session that SMS uses, so a caller and a texter look identical downstream. Every request is checked against `X-Twilio-Signature` before anything else runs. The raw continuation token is `From:To`. See [Channels](./overview) for the contract this builds on.
+The Twilio channel puts your agent on a phone number, so people can text it or call it. Inbound SMS arrives as a webhook. Inbound calls are answered with TwiML `<Gather input="speech">`, and the resulting transcript feeds the same Eve session that SMS uses, so a caller and a texter look identical downstream. Every request is checked against `X-Twilio-Signature` before anything else runs. The raw continuation token is `From:To`. See [Channels](./overview) for the contract this builds on.
 
 ## Add the channel
 
@@ -22,7 +22,7 @@ TWILIO_ACCOUNT_SID=AC...   # required for default outbound SMS
 TWILIO_AUTH_TOKEN=...      # required for inbound signature verification
 ```
 
-If you'd rather not use env vars, pass the same values via `credentials: { accountSid, authToken }`. The channel mounts three routes:
+To skip env vars, pass the same values via `credentials: { accountSid, authToken }`. The channel mounts three routes:
 
 - `POST /eve/v1/twilio/messages`: Messaging webhook
 - `POST /eve/v1/twilio/voice`: inbound call webhook
@@ -30,15 +30,17 @@ If you'd rather not use env vars, pass the same values via `credentials: { accou
 
 Point your Twilio number's Messaging webhook at `/messages` and Voice webhook at `/voice`, using the exact public URL Twilio will call.
 
-## Affordances
+## How the channel handles messages
 
-**`allowFrom` is required.** It gates who can reach the inbound hooks. Pass a single number, a list, an async resolver, or `"*"`. The wildcard is dangerous: only use it with an explicit check inside `onText`/`onVoice`.
+### Dispatch
+
+`allowFrom` is required. It gates who can reach the inbound hooks. Pass a single number, a list, an async resolver, or `"*"`. The wildcard is dangerous; only use it with an explicit check inside `onText`/`onVoice`.
 
 ```ts
 export default twilioChannel({ allowFrom: ["+15551234567", "+15557654321"] });
 ```
 
-**Hooks.** `onText` and `onVoiceTranscription` decide dispatch and `auth`: return `{ auth }` to proceed, or `null` to drop the message. `onVoice` fires the moment a call comes in. Return `null` to reject it, or return an object to override the spoken prompt, language, `<Say voice>`, and speech-recognition options.
+`onText` and `onVoiceTranscription` decide dispatch and `auth`. Return `{ auth }` to proceed, or `null` to drop the message. `onVoice` fires the moment a call comes in. Return `null` to reject it, or return an object to override the spoken prompt, language, `<Say voice>`, and speech-recognition options.
 
 ```ts
 export default twilioChannel({
@@ -54,7 +56,27 @@ export default twilioChannel({
 });
 ```
 
-**Delivery.** The default `message.completed` handler sends the reply as SMS through Twilio's Messages API. A reply to an inbound message can reuse the webhook's `To` as the sender, but a proactive send has nothing to reuse, so it needs `messaging.from` or `messaging.messagingServiceSid`. Behind a proxy, set `webhookUrl` so signature verification matches the exact configured URL, and `publicBaseUrl` so voice TwiML can build absolute callback URLs.
+### Delivery
+
+The default `message.completed` handler sends the reply as SMS through Twilio's Messages API. A reply to an inbound message can reuse the webhook's `To` as the sender, but a proactive send has nothing to reuse, so it needs `messaging.from` or `messaging.messagingServiceSid`. Behind a proxy, set `webhookUrl` so signature verification matches the exact configured URL, and `publicBaseUrl` so voice TwiML can build absolute callback URLs.
+
+### Human-in-the-loop (HITL)
+
+SMS and voice have no native button or card affordance, so HITL prompts do not render as interactive controls. The agent's `input.requested` event reaches your `events["input.requested"]` handler if you declare one. Handle it by sending the prompt as text and mapping the caller's reply back to the input request yourself.
+
+### Proactive sessions
+
+Start a session without an inbound message through `receive(twilio, { message, target, auth })` from a schedule `run` handler, or `args.receive(twilio, ...)` from another channel. `target.phoneNumber` is required, and the channel needs `messaging.from` or `messaging.messagingServiceSid` for the outbound sender.
+
+### Attachments
+
+Inbound media attachments are not supported on this channel today.
+
+## Disclaimer
+
+As the deployer, it is your responsibility to ensure your agent complies with applicable laws.
+
+For example, you may be required to inform callers and texters that calls are recorded/transcribed and processed by an automated AI system, and obtain consent where required (including two-party-consent jurisdictions). For outbound SMS or calls you initiate, you may be required to get prior express consent, honor STOP/opt-out and quiet-hour rules, and complete required carrier registration.
 
 ## What to read next
 

package/docs/concepts/context-control.md

@@ -1,17 +1,11 @@
 ---
 title: "Context Control"
-description: "Control what the model sees and when: instructions, skills, the workspace, and subagents."
+description: "Control what an Eve agent's model sees and when, across instructions, skills, the workspace, and subagents."
 ---
 
-Eve gives you a few levers for controlling what the model sees and when it sees it.
+Eve gives you a few levers for controlling what the model sees and when. `instructions.md` (or `instructions.ts`) is always on, `skills/` are available but loaded on demand, and the workspace and sandbox are visible through tools rather than pasted into the prompt.
 
-The most useful mental model is:
-
-- `instructions.md` (or `instructions.ts`) is always on.
-- `skills/` are available but loaded on demand.
-- The workspace and sandbox are visible through tools, not pasted into the prompt.
-
-## 1. Base identity with `instructions.md`
+## Base identity with `instructions.md`
 
 Use `instructions.md` for the core contract of the agent.
 
@@ -22,9 +16,9 @@ used a tool.
 
 Keep this file focused on stable behavior that should apply on every turn.
 
-## 2. Compose instructions in TypeScript with `instructions.ts`
+## Compose instructions in TypeScript with `instructions.ts`
 
-When you want to build the instructions prompt from typed helpers, lib code, or environment-derived values, author it as a module instead of markdown.
+To build the instructions prompt from typed helpers, lib code, or environment-derived values, author it as a module instead of markdown.
 
 ```ts title="agent/instructions.ts"
 import { defineInstructions } from "eve/instructions";
@@ -37,13 +31,9 @@ export default defineInstructions({
 
 Module-backed instructions run once at build time. Eve captures the resulting markdown into the compiled manifest, so the runtime serves the same prompt every session without re-running the module.
 
-## 3. Load procedures on demand with `skills/`
-
-Skills are not part of the always-on prompt by default.
-
-Instead, Eve advertises the available skills and adds a framework-owned `load_skill` tool. When the request clearly matches a skill description, or the user names a skill explicitly, the model activates that skill, and Eve appends the skill's markdown to the active instructions for later turn work.
+## Load procedures on demand with `skills/`
 
-That is how you keep rich procedures available without bloating every turn.
+Skills stay out of the always-on prompt by default, which keeps rich procedures available without bloating every turn. Eve advertises the available skills and adds a framework-owned `load_skill` tool. When the request clearly matches a skill description, or the user names a skill explicitly, the model activates that skill, and Eve appends the skill's markdown to the active instructions for later turn work.
 
 ### Flat skill
 
@@ -62,48 +52,41 @@ 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 packaged paths show up under the runtime workspace root, so the model can inspect them with the normal file or shell tools instead of pasting all of that 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 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.
 
 See [Skills](../skills) for the full authoring model and install notes.
 
-## 4. Put runtime files in the workspace, not the prompt
+## 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. That keeps prompts smaller and makes file and command work explicit: skill files are available under the active workspace root, and the model can inspect them with the shared `bash` tool.
+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.
 
 See [Sandbox](../sandbox) for the workspace and sandbox model.
 
-## 5. Delegate to a specialist with a subagent
+## Delegate to a specialist with a subagent
 
-If a task deserves its own prompt and tool surface, use a local subagent instead of overloading the root agent. Subagents are a context-control tool too: they get their own `instructions.md`, their own tools, and their own sandbox, and they run inside their own delegated context instead of extending the root agent inline.
+If a task deserves its own prompt and tool surface, use a local subagent instead of overloading the root agent. Subagents are a context-control lever too. They get their own `instructions.md`, tools, and sandbox, and they run inside their own delegated context instead of extending the root agent inline.
 
 See [Subagents](../subagents).
 
 ## Dynamic context with `defineDynamic`
 
-The levers above are static: authored once, the same on every session. When the right context depends on who is calling (their team, tenant, plan, or feature flags), resolve it at runtime instead. `defineDynamic` in `agent/instructions/` returns the per-session system prompt, and `defineDynamic` in `agent/skills/` returns the set of skills a caller can load. Both read `ctx.session.auth` or channel metadata, so a caller on the billing team gets the billing instructions and playbook while nobody else sees them. See [Dynamic capabilities](../guides/dynamic-capabilities) for the resolver API and when each event fires.
+The levers above are static, authored once and the same on every session. When the right context depends on who is calling (their team, tenant, plan, or feature flags), resolve it at runtime instead. `defineDynamic` in `agent/instructions/` returns the per-session system prompt, and `defineDynamic` in `agent/skills/` returns the set of skills a caller can load. Both read `ctx.session.auth` or channel metadata, so a caller on the billing team gets the billing instructions and playbook while no one else sees them. See [Dynamic capabilities](../guides/dynamic-capabilities) for the resolver API and when each event fires.
 
-## Choosing the right lever
+## Recommended context layout
 
-Use:
+Pick the lever by what the context is for:
 
-- `instructions.md` for the agent's permanent identity.
+- `instructions.md` for the agent's permanent identity. Keep it short and stable.
 - `instructions.ts` when you need to compose the prompt from typed helpers at build time.
-- `skills/` for optional procedures that should load only when needed.
-- a subagent when the task needs a different specialist surface.
+- `skills/` for optional procedures that should load only when needed. Move long procedures here instead of into the always-on prompt.
+- `tools/` to expose typed integrations.
+- a subagent when the task needs a different specialist surface; use one only for real specialization boundaries.
 - the workspace or sandbox when the model should inspect files or run commands instead of relying on pasted instructions.
 
-## A good pattern
-
-For most agents:
-
-1. Keep `instructions.md` short and stable.
-2. Move long procedures into `skills/`.
-3. Expose typed integrations through `tools/`.
-4. Use subagents only for real specialization boundaries.
-
 ## What to read next
 
-- [Tools](../tools)
-- [Skills](../skills)
-- [Subagents](../subagents)
-- [Hooks](../guides/hooks)
+- [Tools](../tools): expose typed integrations the model can call.
+- [Skills](../skills): the full authoring model for on-demand procedures.
+- [Subagents](../subagents): delegate to a specialist with its own prompt and tools.
+- [Dynamic capabilities](../guides/dynamic-capabilities): resolve per-session instructions and skills with `defineDynamic`.
+- [Hooks](../guides/hooks): run code on session events to update the channel state that dynamic resolvers read.

package/docs/concepts/default-harness.md

@@ -1,13 +1,13 @@
 ---
 title: "The Harness"
-description: "The out-of-the-box agent loop and the built-in tools every Eve agent ships with, plus how to override or disable them."
+description: "The out-of-the-box Eve agent loop and the built-in tools every agent ships with, plus how to override or disable them."
 ---
 
-The default harness is what every Eve agent ships with: the framework-owned agent loop, plus a set of built-in tools the model can call without you writing a line. You extend the base harness with capabilities specific to your agent. The loop itself, how a turn runs and checkpoints and resumes, lives in [Execution model & durability](./execution-model-and-durability).
+The default harness is what every Eve agent ships with. It includes the framework-owned agent loop plus a set of built-in tools the model can call without you writing a line. You extend it with capabilities specific to your agent. The loop itself, how a turn runs and checkpoints and resumes, lives in [Execution model and durability](./execution-model-and-durability).
 
 ## Compaction
 
-A long session eventually fills the model's context window. The harness handles that for you: once the conversation crosses a fraction of the window (`thresholdPercent`, `0.9` by default), it summarizes the older turns into a compact form and keeps going, so the session continues instead of overflowing. The summary uses the active turn model unless you override it. Tune when and how it kicks in under [`compaction`](../agent-config#compaction) in `agent.ts`:
+The harness keeps a long session from overflowing the model's context window. Once the conversation crosses a fraction of the window (`thresholdPercent`, `0.9` by default), it summarizes the older turns into a compact form and keeps going. The summary uses the active turn model unless you override it. Tune when and how it kicks in under [`compaction`](../agent-config#compaction) in `agent.ts`:
 
 ```ts title="agent/agent.ts"
 export default defineAgent({
@@ -18,11 +18,11 @@ export default defineAgent({
 });
 ```
 
-Compaction also preserves the framework's own tool state automatically. When the harness compacts history, it resets read-before-write tracking (so a write afterward re-reads the file whose read evidence was summarized away) and re-injects the active todo list, so the model keeps its task list across the summary. There is no per-tool hook to configure.
+Compaction also preserves the framework's own tool state automatically. It resets read-before-write tracking (so a write afterward re-reads the file whose read evidence was summarized away) and re-injects the active todo list, so the model keeps its task list across the summary. There is no per-tool hook to configure.
 
 ## Built-in tools
 
-These ship with every agent, no imports. Discovery never runs them: the harness shows the model the tool descriptors first, then executes only what the model actually calls. The shell and file tools run inside the agent's single [sandbox](../sandbox); the rest run in the app runtime.
+These ship with every agent, no imports. The harness shows the model the tool descriptors first, then executes only what the model actually calls; discovery never runs them. The shell and file tools (`bash`, `read_file`, `write_file`, `glob`, `grep`) live in the app runtime and proxy their work into the agent's single [sandbox](../sandbox); the rest run in the app runtime. The "Where it runs" column below names where each tool's effect lands.
 
 | Tool                | Does                                                                                                                                                              | Where it runs |
 | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
@@ -46,9 +46,11 @@ Notes:
 - **`connection_search`** is the model-facing `connection__search` tool. A search surfaces a connection's tools by their qualified name (e.g. `connection__linear__list_issues`), and the model can then call them directly. It's registered only when the agent has connections.
 - **`web_search`** has no local executor; the provider runs it. To supply your own implementation, override it with `defineTool()`.
 
+Review these built-in tools before production use. Disable, wrap, restrict, or require approval for any tool that can access the filesystem, network, shell, or sensitive data.
+
 ## Override a default
 
-Author a tool at the same slug and it takes over the built-in of that name. The file `agent/tools/write_file.ts` replaces the built-in `write_file` just by existing:
+Author a tool at the same slug and it takes over the built-in of that name. The file `agent/tools/write_file.ts` replaces the built-in `write_file` by existing:
 
 ```ts title="agent/tools/write_file.ts"
 import { defineTool } from "eve/tools";
@@ -63,7 +65,7 @@ export default defineTool({
 });
 ```
 
-The framework defaults are importable from `eve/tools/defaults` (`bash`, `readFile`, `writeFile`, `glob`, `grep`, `webFetch`, `webSearch`, `todo`, `loadSkill`), so you can spread, wrap, or patch them. Skip the spread and your replacement owns its own context: a fresh `defineTool` for `todo` won't inherit the framework's durable state key.
+The framework defaults are importable from `eve/tools/defaults` (`bash`, `readFile`, `writeFile`, `glob`, `grep`, `webFetch`, `webSearch`, `todo`, `loadSkill`), so you can spread, wrap, or patch them. Skip the spread and your replacement owns its own context. A fresh `defineTool` for `todo` won't inherit the framework's durable state key.
 
 ## Disable a default
 
@@ -75,11 +77,19 @@ import { disableTool } from "eve/tools";
 export default disableTool();
 ```
 
-Misspell the filename so it matches no known framework tool and it fails at resolve time, instead of silently doing nothing.
+If the filename matches no known framework tool, resolution fails instead of silently doing nothing, so a typo surfaces at build time rather than removing the wrong tool.
+
+## When to override, disable, or author a new tool
+
+Three moves shape the harness. The right one depends on whether the model should keep the built-in capability.
+
+- **Override** when you want the same capability with different behavior. Spread the default from `eve/tools/defaults` and wrap it (logging, an extra guard, a different backend), and the model still sees a tool by that name. Spreading keeps the default's description, schema, and any framework state, such as the `todo` tool's durable state key. Drop the spread and your replacement owns its own context, losing that wiring.
+- **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
 
-There's also an experimental `Workflow` tool, shipped but off by default. To turn it on, re-export the opt-in marker from `agent/tools/workflow.ts`:
+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";

package/docs/concepts/execution-model-and-durability.md

@@ -1,9 +1,9 @@
 ---
-title: "Execution Model & Durability"
-description: "How a session runs: durable conversations, turns that checkpoint at steps, and parked work that resumes later."
+title: "Execution Model and Durability"
+description: "How an Eve session runs. Durable conversations, turns that checkpoint at steps, and parked work that resumes later."
 ---
 
-A session is a durable conversation. It can run for days, and it survives process restarts and redeploys without any work on your part. You write the capabilities (tools, instructions, channels) and Eve runs the loop.
+An Eve session is a durable conversation. It can run for days and survives process restarts and redeploys without any work on your part. You write the capabilities (tools, instructions, channels) and Eve runs the loop.
 
 ## Sessions, turns, and steps
 
@@ -13,38 +13,38 @@ Work nests in three levels:
 - **turn**: one user message and all the work it triggers (model calls, tool calls, reasoning) until the agent produces its response.
 - **step**: a durable checkpoint inside a turn (one model call and the tool calls it makes).
 
-Every turn runs as a durable workflow, built on the open-source [Workflow SDK](https://workflow-sdk.dev/) (Vercel Workflow when you deploy on Vercel). Eve checkpoints progress at each step and serializes durable state at that boundary. Your code runs inside a managed step, so tools, the sandbox, and subagents feel synchronous even though the session underneath them is durable.
+Every turn runs as a durable workflow, built on the open-source [Workflow SDK](https://workflow-sdk.dev/) (Vercel Workflow when you deploy on Vercel). Eve checkpoints progress and serializes durable state at each step boundary. Your code runs inside a managed step, so tools, the sandbox, and subagents feel synchronous even though the session underneath them is durable.
 
 ## Resuming after a crash
 
-Crash the process, hit a timeout, or redeploy mid-turn, and the run picks up from the last completed step rather than replaying the whole turn. Re-running a step from the same input is idempotent. Your tool calls don't fire twice, so a resume never doubles up a side effect (a charge, an email, a write).
+Crash the process, hit a timeout, or redeploy mid-turn, and the run picks up from the last completed step rather than replaying the whole turn. Completed steps never re-run; Eve replays the recorded result. A step interrupted mid-execution re-runs, so make non-idempotent side effects like charges or emails idempotent, or gate them with approval.
 
-There's nothing to configure here. Eve owns the workflow lifecycle, and sessions are durable by default.
+There's nothing to configure. Eve owns the workflow lifecycle, and sessions are durable by default.
 
-You don't write workflow code directly. Workflow primitives (`start()`, `resumeHook()`, etc.) are an implementation detail of Eve's runtime layer; channels, tools, and hooks never touch them. When you do need session data from your own code, there are two supported surfaces: tools read the current session's metadata (id, turn, auth, parent lineage) via `ctx.session`, and [`defineState`](../guides/session-context) reads or writes session-scoped durable state. See [State](../guides/state) for the read/write model.
+You don't write workflow code directly. Workflow primitives (`start()`, `resumeHook()`, etc.) are an implementation detail of Eve's runtime layer; channels, tools, and hooks never touch them. Two surfaces give your own code session data: tools read the current session's metadata (id, turn, auth, parent lineage) via `ctx.session`, and [`defineState`](../guides/state) reads or writes session-scoped durable state. See [State](../guides/state) for the read/write model.
 
 ## Parked work
 
-Some work has to wait: a human approving a [tool](../tools), an interactive OAuth sign-in for a [connection](../connections), or a long-running [subagent](../subagents). At those points the turn parks durably. The workflow suspends and holds no compute until the input it's waiting on shows up (a click, a callback, a child completing), even if that's much later. When it does, the conversation picks up exactly where it left off.
+Some work has to wait, including a human approving a [tool](../tools), an interactive OAuth sign-in for a [connection](../connections), or a long-running [subagent](../subagents). At those points the turn parks durably. The workflow suspends and holds no compute until the input it's waiting on arrives (a click, a callback, a child completing), even if that's much later. When it does, the conversation picks up exactly where it left off.
 
 ## Message delivery and queueing
 
-Eve does not maintain a durable FIFO queue of user messages for a session today. The `continuationToken` is a resume handle for the session's current workflow hook, not a general message-queue address.
+Eve does not maintain a durable FIFO queue of user messages for a session. The `continuationToken` is a resume handle for the session's current workflow hook, not a general message-queue address.
 
-When a session is waiting, a delivery to the current continuation token wakes the session and starts the next turn. When a turn is already active, additional deliveries may be accepted by the hook, but the runtime only drains them at specific workflow boundaries. If more than one delivery is already ready when the driver checks, Eve may fold them into the next turn; that drain is best-effort and depends on workflow and transport timing.
+When a session is waiting, a delivery to the current continuation token wakes the session and starts the next turn. When a turn is already active, the hook may accept additional deliveries, but the runtime only drains them at specific workflow boundaries. If more than one delivery is ready when the driver checks, Eve may fold them into the next turn; that drain is best-effort and depends on workflow and transport timing.
 
-That means applications should not rely on concurrent sends to the same session behaving like a typical ordered chat queue. For deterministic behavior, send one user turn at a time: wait for `session.waiting` before sending the next message to the same session. If your channel can receive bursts while the agent is working, keep your own per-session queue in the channel or app layer, then deliver the next message after the session parks again. Separate sessions can still run independently.
+So don't rely on concurrent sends to the same session behaving like a typical ordered chat queue. For deterministic behavior, send one user turn at a time and wait for `session.waiting` before sending the next message to the same session. If your channel can receive bursts while the agent is working, keep your own per-session queue in the channel or app layer, then deliver the next message after the session parks again. Separate sessions still run independently.
 
 ## Subagents
 
 A turn can hand work off to a [subagent](../subagents). Each subagent gets its own context and its own durable session; a declared subagent also gets its own sandbox, skills, and state. Nothing crosses the boundary implicitly.
 
-## Ordering
+## How Eve orders session history
 
-Conversation history within a session is append-only. Turns land in order, and the tool calls inside a turn (plus their results) keep their order too. Read a session back and you see things in the order they happened.
+Conversation history within a session is append-only. Turns land in order, and the tool calls inside a turn (plus their results) keep their order too. Read a session back and you see events in the order they happened.
 
 ## What to read next
 
-- [Sessions, runs & streaming](./sessions-runs-and-streaming): the handles you hold and the event stream you watch.
+- [Sessions and streaming](./sessions-runs-and-streaming): the handles you hold and the event stream you watch.
 - [Security model](./security-model): the trust boundaries the runtime enforces.
 - [State](../guides/state): durable per-session memory that persists across step boundaries.

package/docs/concepts/security-model.md

@@ -1,9 +1,9 @@
 ---
 title: "Security Model"
-description: "Trust boundaries, where secrets live, how credentials reach hosts, and what fails closed by default."
+description: "Eve's trust boundaries, where secrets live, how credentials reach hosts, and what fails closed by default."
 ---
 
-Your agent runs across two contexts, with a trust boundary drawn between them and every secret kept on the trusted side. This page is the mental model to use when you're deciding what an agent (and the model driving it) is allowed to reach.
+Your Eve agent runs across two contexts, with a trust boundary between them and every secret kept on the trusted side. Use this mental model when deciding what an agent (and the model driving it) is allowed to reach.
 
 ## Trust boundaries
 
@@ -16,13 +16,37 @@ Your agent runs across two contexts, with a trust boundary drawn between them an
 
 The app runtime is the trusted side. Your tool implementations, model calls, connections, state, and durable execution all run here, with `process.env` and full Node.js available. (On Vercel, this is a Vercel Function.)
 
-The sandbox is the isolated side. The model runs shell commands there through the built-in `bash`, `read_file`, `write_file`, `glob`, and `grep` tools. It gets its own `/workspace` filesystem, but no `process.env`, no secrets, and no path back into the app runtime. (On Vercel, each sandbox is a [Vercel Sandbox](https://vercel.com/docs/sandbox) microVM with hardware-level isolation.) The only thing that actually executes in the sandbox is shell commands. Even the built-in `bash`/`read_file`/`write_file` tools live in the app runtime and _proxy_ into the sandbox. The model sees tool definitions and results, never your secrets.
+The sandbox is the isolated side. The model runs shell commands there through the built-in `bash`, `read_file`, `write_file`, `glob`, and `grep` tools. It gets its own `/workspace` filesystem, but no `process.env`, no secrets, and no path back into the app runtime. (On Vercel, each sandbox is a [Vercel Sandbox](https://vercel.com/docs/sandbox) microVM with hardware-level isolation.) Only shell commands execute in the sandbox. Even the built-in `bash`/`read_file`/`write_file` tools live in the app runtime and _proxy_ into the sandbox. The model sees tool definitions and results, never your secrets.
 
 A concrete trace makes the boundary clear. When the model calls a custom `charge_card` tool, its `execute` runs in the app runtime, reads `process.env.STRIPE_KEY`, calls Stripe, and returns `{ ok: true }`. The model sees only `{ ok: true }`: the key never leaves the app runtime, and nothing about the call touches the sandbox. The built-in `write_file` is the mirror image, running in the app runtime and proxying the write into the sandbox `/workspace`. Either way the model drives the work through tool calls and their results, never by holding a credential or reaching the runtime directly.
 
+## Data flow at a glance
+
+```mermaid
+flowchart LR
+  User["User or channel provider"] --> Channel["Channel route and route auth"]
+  Channel --> Runtime["Eve app runtime and durable session"]
+  Runtime --> Model["Configured model provider or Vercel AI Gateway"]
+  Runtime --> Tools["Authored tools and connections"]
+  Tools --> Services["Customer-selected external services"]
+  Runtime --> Sandbox["Per-session sandbox"]
+  Sandbox --> Egress["Allowed sandbox network egress"]
+  Runtime --> Telemetry["Configured telemetry or eval provider"]
+```
+
+Eve sends data where your agent configuration and runtime choices send it:
+
+- Inbound channel data flows through the channel provider you configure, then into the Eve app runtime.
+- Model inputs and outputs flow to the model or routing path selected in `agent.ts`, such as a Vercel AI Gateway model id or a provider-authored `LanguageModel`.
+- Tool and connection calls flow to the external services, MCP servers, OpenAPI endpoints, and channels you configure.
+- Sandbox commands can reach network destinations allowed by the sandbox network policy.
+- Telemetry and eval data flows to the exporters and providers you configure in `instrumentation.ts` or eval settings.
+
+Eve stores durable session and workflow state needed to resume conversations, stream events, replay completed steps, and show run observability. You are responsible for deciding whether the selected channels, model providers, connected services, sandbox egress destinations, telemetry exporters, retention settings, and deletion controls are appropriate for your data and use case.
+
 ## Credential brokering
 
-Sometimes the model needs _authenticated_ network access from inside the sandbox, like a `git clone` of a private repo or an authenticated `curl`, and there's no [tool](../tools) or [connection](../connections) to route it through. That's what credential brokering is for. On the Vercel Sandbox backend, auth headers get injected at the sandbox's network firewall for matching domains. The secret stays in the app runtime; the sandbox process only ever sees the response. See [Vercel Sandbox Credential Brokering](https://vercel.com/docs/sandbox/concepts/firewall#credentials-brokering) for the platform mechanism, and [Sandbox](../sandbox) for the Eve policy API.
+Credential brokering gives the model _authenticated_ network access from inside the sandbox, like a `git clone` of a private repo or an authenticated `curl`, when there's no [tool](../tools) or [connection](../connections) to route it through. On the Vercel Sandbox backend, auth headers get injected at the sandbox's network firewall for matching domains. The secret stays in the app runtime; the sandbox process only ever sees the response. See [Vercel Sandbox Credential Brokering](https://vercel.com/docs/sandbox/concepts/firewall#credentials-brokering) for the platform mechanism, and [Sandbox](../sandbox) for the Eve policy API.
 
 ## Connection credentials
 
@@ -30,7 +54,7 @@ Sometimes the model needs _authenticated_ network access from inside the sandbox
 
 ## Channel verification
 
-A [channel](../channels/overview) is your agent's front door, which makes authenticating inbound traffic its job. The built-in platform channels follow two rules here, and so must any channel you write yourself:
+A [channel](../channels/overview) is your agent's front door, so authenticating inbound traffic is its job. The built-in platform channels follow two rules, and so must any channel you write yourself:
 
 - **Verify signatures in constant time.** Platform channels (Slack, GitHub,
   Telegram, Twilio) verify the platform's HMAC signature over the raw request body
@@ -46,11 +70,11 @@ A custom channel that accepts dashboard-style webhooks should follow the same sh
 
 ## Authored markdown is data
 
-[Skill](../skills) and [schedule](../schedules) files are markdown with YAML frontmatter, and Eve treats that frontmatter strictly as data. The code-capable engines (`---js` / `---javascript`, which would `eval()` the frontmatter body the moment the file is parsed) are disabled. A fence like that throws rather than running. Frontmatter has to parse to a plain YAML object.
+[Skill](../skills) and [schedule](../schedules) files are markdown with YAML frontmatter, and Eve treats that frontmatter strictly as data. The code-capable engines (`---js` / `---javascript`, which would `eval()` the frontmatter body the moment the file is parsed) are disabled, so such a fence throws rather than running. Frontmatter has to parse to a plain YAML object.
 
 ## Auth fails closed
 
-Routes reject unauthenticated traffic by default: if no `AuthFn` in the walk accepts the request, it gets a `401`, and admitting anonymous callers takes an explicit `none()`. The scaffold's `placeholderAuth()` keeps a half-configured app closed in production until you replace it. See [Auth & route protection](../guides/auth-and-route-protection) for the full walk and verifiers.
+Routes reject unauthenticated traffic by default. If no `AuthFn` in the walk accepts the request, it gets a `401`, and admitting anonymous callers takes an explicit `none()`. The scaffold's `placeholderAuth()` keeps a half-configured app closed in production until you replace it. See [Auth & route protection](../guides/auth-and-route-protection) for the full walk and verifiers.
 
 ## Pre-production checklist
 
@@ -75,5 +99,5 @@ Before exposing an agent to real traffic:
 
 - [Auth & route protection](../guides/auth-and-route-protection): the full auth walk and verifier helpers
 - [Sandbox](../sandbox): backends, network policy, and brokering config
-- [Execution model & durability](./execution-model-and-durability): how durable sessions run
+- [Execution model and durability](./execution-model-and-durability): how durable sessions run
 - [Connections](../connections): static-token and OAuth connections

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

@@ -7,7 +7,7 @@ Every Eve app speaks the same stable HTTP API to a [durable session](./execution
 
 ## The two handles
 
-Two handles do two jobs here, and mixing them up is the most common mistake. One handle creates and resumes a session; a different one streams and inspects it.
+Two handles do two jobs, and mixing them up is the most common mistake. One handle creates and resumes a session; a different one streams and inspects it.
 
 - **`continuationToken`**: the resume handle. Use it to send a follow-up message to the same conversation. Owned by the channel.
 - **`sessionId` / `runId`**: the stream-and-inspect handle. Use it to attach to the event stream and watch a run. Owned by the runtime.
@@ -19,17 +19,17 @@ React, Vue, and Svelte apps reach for [`useEveAgent()`](../guides/frontend/overv
 ## Start a session
 
 ```bash
-curl -X POST http://127.0.0.1:2000/eve/v1/session \
+curl -X POST http://127.0.0.1:3000/eve/v1/session \
   -H 'content-type: application/json' \
   -d '{"message":"Summarize the latest forecast."}'
 ```
 
-Eve responds right away. The JSON body carries a `sessionId` and a `continuationToken`, and the `x-eve-session-id` header tells you which durable session to stream.
+Eve responds right away. The JSON body carries a `sessionId` and a `continuationToken`, and the `x-eve-session-id` header names the durable session to stream.
 
 ## Stream a session
 
 ```bash
-curl http://127.0.0.1:2000/eve/v1/session/<sessionId>/stream
+curl http://127.0.0.1:3000/eve/v1/session/<sessionId>/stream
 ```
 
 The stream is newline-delimited JSON (NDJSON), one event per line:
@@ -64,6 +64,8 @@ The stream is newline-delimited JSON (NDJSON), one event per line:
 
 `reasoning.appended` and `message.appended` stream deltas as they arrive, and each one carries both the new delta and the cumulative text for the current block. The finalized block shows up on `message.completed` and `reasoning.completed`, which is the compatibility path for clients that don't render incremental streaming.
 
+Note: consider the privacy, confidentiality, and user-experience implications for displaying, storing, or transmitting reasoning events in your application.
+
 `message.completed` can fire more than once in a turn: the agent often emits interim assistant text before a tool call. To tell tool-call narration from a terminal reply, check `message.completed.data.finishReason`. `step.completed.data.finishReason` mirrors the step outcome, and usage lives on `step.completed`.
 
 A delegated subagent publishes progress on its own child-session stream. The parent only emits `subagent.called` with a `childSessionId`, which a client uses to attach.
@@ -75,7 +77,7 @@ A delegated subagent publishes progress on its own child-session stream. The par
 Once the session is waiting (you'll see `session.waiting`), POST your follow-up to the session endpoint with the stored continuation token:
 
 ```bash
-curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId> \
+curl -X POST http://127.0.0.1:3000/eve/v1/session/<sessionId> \
   -H 'content-type: application/json' \
   -d '{"continuationToken":"<token>","message":"Now send the short version."}'
 ```
@@ -86,10 +88,10 @@ For deterministic ordering, send one follow-up at a time and wait for the next `
 
 ## Reconnect and rewind
 
-The stream is durable. Every event is recorded before a step completes, so it's all replayable. Pass `startIndex` to reconnect by event count and pick up where you dropped off, or rewind to the start:
+The stream is durable. Every event is recorded before a step completes, so the whole stream is replayable. Pass `startIndex` to reconnect by event count and pick up where you dropped off, or rewind to the start:
 
 ```bash
-curl "http://127.0.0.1:2000/eve/v1/session/<sessionId>/stream?startIndex=<count>"
+curl "http://127.0.0.1:3000/eve/v1/session/<sessionId>/stream?startIndex=<count>"
 ```
 
 ## Use the client from TypeScript
@@ -103,7 +105,7 @@ Start with the [TypeScript SDK](../guides/client/overview) guide. It covers basi
 `GET /eve/v1/info` returns a JSON inspection snapshot for the running agent: model, instructions, authored and framework tools, skills, channels, schedules, subagents, sandbox, connections, hooks, workflow, and workspace metadata. Local development accepts loopback requests; deployed Vercel targets require the route's OIDC auth.
 
 ```bash
-curl http://127.0.0.1:2000/eve/v1/info
+curl http://127.0.0.1:3000/eve/v1/info
 ```
 
 The route uses the same default auth chain as the eve channel (`[localDev(), vercelOidc()]`). Locally it answers anonymously; a deployed Vercel target requires a valid OIDC bearer, with a same-project bypass for in-deployment callers. See [auth & route protection](../guides/auth-and-route-protection).
@@ -117,7 +119,7 @@ Every stream event runs four steps, in this order:
 3. **Hooks**: authored [hooks](../guides/hooks) subscribed to the event fire.
 4. **Dynamic resolvers**: [dynamic](../guides/dynamic-capabilities) tool, skill, and instruction resolvers fire, and `ctx.channel.metadata` already holds the freshly projected metadata from step 2.
 
-The order isn't incidental, it's structural. By the time a resolver or hook reads channel metadata, the channel has already updated its state and the projection is current.
+The order is structural, not incidental. By the time a resolver or hook reads channel metadata, the channel has already updated its state and the projection is current.
 
 ## What to read next