eve 0.34.0 → 0.35.0

package/docs/README.md

@@ -34,26 +34,24 @@ Casing convention:
 Read in this order:
 
 1. [Getting Started](./getting-started.mdx)
-2. [Installation](./installation.mdx)
-3. [Project Structure](./project-structure.mdx)
-4. [Project Layout](./reference/project-layout.md)
-5. [`agent.ts`](./agent-config.md)
-6. [TypeScript API](./reference/typescript-api.md)
-7. [Context Control](./concepts/context-control.md)
-8. [Skills](./skills.mdx)
-9. [Tools](./tools/overview.mdx)
-10. [Connections](./connections/overview.mdx)
-11. [Sandboxes](./sandbox.mdx)
-12. [Channels](./channels/overview.mdx)
-13. [Session Context](./reference/typescript-api.md)
-14. [Sessions And Streaming](./concepts/sessions-runs-and-streaming.md)
-15. [TypeScript SDK](./guides/client/overview.mdx)
-16. [Subagents](./subagents.mdx)
-17. [Schedules](./schedules.mdx)
-18. [Evals](./evals/overview.mdx)
-19. [Auth And Route Protection](./guides/auth-and-route-protection.md)
-20. [Vercel Deployment](./guides/deployment/overview.md)
-21. [CLI, Build, And Debugging](./reference/cli.md)
+2. [Tutorial](./tutorial/first-agent.mdx)
+3. [Agents](./agent-config.md)
+4. [TypeScript API Reference](./reference/typescript-api.md)
+5. [Context Control](./concepts/context-control.md)
+6. [Skills](./skills.mdx)
+7. [Tools](./tools/overview.mdx)
+8. [Connections](./connections/overview.mdx)
+9. [Sandboxes](./sandbox.mdx)
+10. [Channels](./channels/overview.mdx)
+11. [Session Context](./guides/session-context.md)
+12. [Sessions and Streaming](./concepts/sessions-runs-and-streaming.md)
+13. [Client SDK](./guides/client/overview.mdx)
+14. [Subagents](./subagents/index.mdx)
+15. [Schedules](./schedules.mdx)
+16. [Evals](./evals/overview.mdx)
+17. [Authentication](./guides/auth-and-route-protection.md)
+18. [Deployment](./guides/deployment/overview.md)
+19. [CLI](./reference/cli.md)
 
 ## The public mental model
 

package/docs/agent-config.md

@@ -1,9 +1,9 @@
 ---
-title: "agent.ts"
-description: "Set the agent's runtime config in agent.ts with defineAgent, including the model, reasoning effort, and compaction."
+title: "Agents"
+description: "Configure an eve agent's model, reasoning effort, compaction, limits, and runtime behavior in agent.ts."
 ---
 
-An agent's `agent.ts` calls `defineAgent` (from `eve`) to set its runtime config.
+An eve app has one root agent assembled from the files under `agent/`. Its optional `agent.ts` calls `defineAgent` (from `eve`) when you need to configure the model or other runtime behavior. Declared [subagents](./subagents) have their own `agent.ts` and capabilities; this page covers the configuration shared by root agents and subagents.
 
 ## Set the model
 
@@ -229,7 +229,7 @@ installed package must stay external in hosted output, list it in
 
 ## Other defineAgent fields
 
-`defineAgent` takes a few more fields, all optional. For the exported types, see the [TypeScript API](./reference/typescript-api).
+`defineAgent` takes a few more fields, all optional. For the exported types, see the [TypeScript API Reference](./reference/typescript-api).
 
 | Field          | Type                                    | Default          | Description                                                                                                                                                                                                   |
 | -------------- | --------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -257,5 +257,5 @@ During `eve dev`, ordinary dependencies are bundled into each retained runtime g
 ## What to read next
 
 - [Default harness](./concepts/default-harness) for the loop and built-in tools this config drives
-- [TypeScript API](./reference/typescript-api) for every `defineAgent` field and type
+- [TypeScript API Reference](./reference/typescript-api) for every `defineAgent` field and type
 - [Subagents](./subagents) for the `description` requirement and child-agent config

package/docs/channels/eve.mdx

@@ -36,15 +36,13 @@ The session routes use only durable session IDs. Create a session explicitly, th
 
 ### Start and continue a session
 
+Start a session with an initial message, then use the returned `sessionId` for every follow-up and control operation:
+
 ```bash
 curl -X POST https://<deployment>/eve/v1/session \
   -H "Content-Type: application/json" \
   -d '{"message":"What is the weather in Paris?"}'
 # {"ok":true,"sessionId":"wrun_A","status":"accepted"}
-
-curl -X POST https://<deployment>/eve/v1/session/wrun_A \
-  -H "Content-Type: application/json" \
-  -d '{"message":"How about tomorrow?"}'
 ```
 
 The first request requires `message`. A follow-up request accepts exactly one of
@@ -65,69 +63,25 @@ creates or follows a replacement session.
 
 ### Stream events
 
-Stream responses are newline-delimited JSON (`application/x-ndjson; charset=utf-8`), one event object per line:
-
-```bash
-curl -N https://<deployment>/eve/v1/session/wrun_A/stream
-# {"type":"turn.started",...}
-# {"type":"message.appended","data":{"messageDelta":"It is ",...}}
-# {"type":"message.completed",...}
-```
+Stream a session as newline-delimited JSON from `GET /eve/v1/session/:sessionId/stream`. The [session protocol](../concepts/sessions-runs-and-streaming#stream-a-session) defines the event set, envelopes, cursors, and reconnection behavior.
 
 ### Cancel a turn
 
-Cancel a session's in-flight turn with an empty body, or scope the cancel to the turn you observed by passing the `turnId` stamped on that turn's stream events:
+Post to `/eve/v1/session/:sessionId/cancel` to request cancellation of the active turn. You can include the observed `turnId` to keep a late request from cancelling a newer turn. Cancellation is asynchronous; confirm it on the stream as `turn.cancelled` followed by `session.waiting`.
 
-```bash
-curl -X POST https://<deployment>/eve/v1/session/wrun_A/cancel
-# {"ok":true,"sessionId":"wrun_A","status":"accepted"}
-```
-
-Cancellation is asynchronous: `"accepted"` means the live session durably queued the request. Confirm an actual cancellation on the stream as `turn.cancelled` followed by `session.waiting`—never as a failure. Active local and remote subagents are cancelled recursively before the parent settles. Content emitted before cancellation stays on the event stream, while durable model history keeps only content that had already settled. The session accepts the next message normally.
-
-An accepted cancellation returns HTTP `202` with `sessionId`. An inactive target
-returns HTTP `200` with `{"ok":true,"status":"no_active_turn"}`.
-
-A live session also returns `"accepted"` when it is already parked; the driver consumes that late or duplicate cancel as a no-op. An unknown or terminal session returns `"no_active_turn"`. A `turnId` naming any other turn is likewise accepted and consumed as a no-op, so a guarded cancel racing a turn boundary cannot stop a turn the caller never saw.
+See [Cancel the in-flight turn](../concepts/sessions-runs-and-streaming#cancel-the-in-flight-turn) for response statuses, HTTP status codes, subagent cancellation, and race behavior.
 
 ### Clear context
 
-Clear one session's model-message history without replacing the session:
-
-```bash
-curl -X POST https://<deployment>/eve/v1/session/wrun_A/clear
-# {"ok":true,"sessionId":"wrun_A","status":"accepted"}
-```
-
-An accepted clear emits `context.cleared` followed by `session.waiting`. The next message uses the same session without prior model messages; the system prompt, tools, skills, durable state, limits, and session-scoped sandbox remain.
+Post to `/eve/v1/session/:sessionId/clear` to remove model-message history while preserving the session ID, system prompt, tools, skills, durable state, limits, and sandbox. See [Compact, clear, and reset](../concepts/sessions-runs-and-streaming#compact-clear-and-reset).
 
 ### Compact context
 
-Compact one session's context without sending a message:
-
-```bash
-curl -X POST https://<deployment>/eve/v1/session/wrun_A/compact
-# {"ok":true,"sessionId":"wrun_A","status":"accepted"}
-```
-
-Compaction is asynchronous. A successful operation emits `compaction.requested` and `compaction.completed`, then returns through `session.waiting`. When a turn is active, compaction waits for it to settle. If summarization fails, the session still returns to `session.waiting` with its previous history.
+Post to `/eve/v1/session/:sessionId/compact` to summarize context without sending a user message. The operation waits for an active turn to settle and reports its result on the stream. See [Compact, clear, and reset](../concepts/sessions-runs-and-streaming#compact-clear-and-reset).
 
 ### Reset a session
 
-Reset terminally retires the exact session ID:
-
-```bash
-curl -X POST https://<deployment>/eve/v1/session/wrun_A/reset \
-  -H "Content-Type: application/json" \
-  -d '{"reason":"Start over"}'
-# {"ok":true,"previousSessionId":"wrun_A","status":"reset"}
-```
-
-After reset, the old ID cannot accept another message. Start a replacement explicitly with `POST /eve/v1/session`.
-
-The control routes never create sessions. `compact`, `clear`, and `reset` return `"no_active_session"` when the ID is already inactive. Session message and control request/response bodies do not accept or return continuation tokens. For compatibility, the streamed `session.waiting` event retains `data.continuationToken`: it is the channel-local token for a channel-addressed session and the immutable session ID for an ID-only session. New clients should continue through their fixed session handle instead of reading this field.
-
-See [Sessions, runs & streaming](../concepts/sessions-runs-and-streaming) for the complete event set, operation results, and cursor behavior.
+Post to `/eve/v1/session/:sessionId/reset` to terminally retire that session. Reset never replaces the ID automatically; create a new session explicitly for a fresh conversation. See [Compact, clear, and reset](../concepts/sessions-runs-and-streaming#compact-clear-and-reset).
 
 ## CORS
 
@@ -199,11 +153,11 @@ always dispatches and therefore always produces or continues a session.
 
 The browser side of this API lives in the [Frontend](../guides/frontend/overview) docs, where `useEveAgent` drives the eve channel from React UI.
 
-For scripts, server-to-server calls, evals, tests, and custom clients, use the [TypeScript SDK](../guides/client/overview). It wraps the ID-addressed session routes, stream cursor, and reconnect loop.
+For scripts, server-to-server calls, evals, tests, and custom clients, use the [Client SDK](../guides/client/overview). It wraps the ID-addressed session routes, stream cursor, and reconnect loop.
 
 ## What to read next
 
 - [Frontend](../guides/frontend/overview): drive the eve channel from browser UI with `useEveAgent`
-- [TypeScript SDK](../guides/client/overview): call the eve channel from TypeScript
+- [Client SDK](../guides/client/overview): call the eve channel from TypeScript
 - [Auth & route protection](../guides/auth-and-route-protection): the route auth policy
 - [Sessions, runs & streaming](../concepts/sessions-runs-and-streaming): the routes this channel exposes

package/docs/channels/github.mdx

@@ -58,7 +58,7 @@ GITHUB_WEBHOOK_SECRET=...    # verifies the webhook signature
 GITHUB_APP_SLUG=...          # supplies botName when it is not set in config
 ```
 
-`appId`/`privateKey`/`webhookSecret` also take a lazy resolver function if you'd rather fetch them on demand.
+`appId`/`privateKey`/`webhookSecret` also take a lazy resolver function if you'd rather fetch them on demand, and so does `botName`: it resolves on first use inside request handling, caches on success, and retries on the next event after a failure, so a resolver that depends on request-scoped credentials works in production. When `botName` is not configured, the channel falls back to the credentials' `appSlug`, then to `GITHUB_APP_SLUG`.
 
 Point the GitHub App webhook URL at `https://<deployment>/eve/v1/github`. For comment-invoked turns, subscribe to `issue_comment` and `pull_request_review_comment`; add `issues`, `pull_request`, `check_suite`, `check_run`, or `workflow_run` if you wire up their opt-in hooks. After installing the App for the repository, a new comment that includes `@botName` starts a turn. This is a text invocation token, not a GitHub-native mention: GitHub may display the App as `botName[bot]`, but it may not autocomplete or link `@botName`.
 

package/docs/channels/meta.json

@@ -1,5 +1,6 @@
 {
   "title": "Channels",
+  "defaultOpen": false,
   "pages": [
     "overview",
     "eve",

package/docs/concepts/context-control.md

@@ -1,92 +1,68 @@
 ---
 title: "Context Control"
-description: "Control what an eve agent's model sees and when, across instructions, skills, the workspace, and subagents."
+description: "Choose what an eve agent's model sees and when, across instructions, skills, tools, the workspace, and subagents."
 ---
 
-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.
+Control context by putting information in the narrowest surface that needs it. Keep permanent rules in instructions, load optional procedures as skills, let the model inspect runtime files through sandbox tools, and delegate specialist work to a subagent.
 
-## Base identity with `instructions.md`
-
-Use `instructions.md` for the core contract of the agent.
-
-```md
-You are a careful support assistant. Be concise, verify facts before replying, and explain when you
-used a tool.
-```
-
-Keep this file focused on stable behavior that should apply on every turn.
+## Recommended context layout
 
-## Compose instructions in TypeScript with `instructions.ts`
+| Need                                                 | Use                                                    | What the model sees                                                              |
+| ---------------------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------- |
+| Permanent identity, rules, or constraints            | System-role [instructions](../instructions)            | System context on every model call                                               |
+| Durable application or retrieved context             | User-role [instructions](../instructions)              | A message added to conversation history at its lifecycle boundary                |
+| A procedure needed only for some tasks               | A [skill](../skills)                                   | Its description until the model loads the full skill                             |
+| A typed action or external operation                 | A [tool](../tools) or [connection](../connections)     | The callable schema and the result of each call                                  |
+| Files or command execution                           | The [sandbox workspace](../sandbox)                    | A workspace hint, then files and command output the model requests through tools |
+| A specialist with a separate prompt and capabilities | A [subagent](../subagents)                             | Only the subagent's final result in the parent context                           |
+| Instructions or capabilities that vary by caller     | A [dynamic capability](../guides/dynamic-capabilities) | The values resolved for the active session                                       |
 
-To build the instructions prompt from typed helpers, lib code, or environment-derived values, author it as a module instead of markdown.
+## Base identity with `instructions.md`
 
-```ts title="agent/instructions.ts"
-import { defineInstructions } from "eve/instructions";
-import { buildInstructionsPrompt } from "./lib/prompts";
+Use system-role instructions for stable behavior that should apply throughout a session, such as the agent's role, tone, and standing constraints. Markdown is the default. Keep instructions short enough to justify including them on every model call.
 
-export default defineInstructions({
-  markdown: buildInstructionsPrompt(),
-});
-```
+### Compose instructions in TypeScript with `instructions.ts`
 
-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.
+Use `instructions.ts` when you need typed helpers, build-time composition, or a user-role message. User-role instructions become ordinary durable history rather than system context. See [Instructions](../instructions) for both formats, directory composition, and runtime resolution.
 
 ## Load procedures on demand with `skills/`
 
-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.
+Use skills for optional procedures that would otherwise make the always-on prompt unnecessarily large. eve advertises each skill's description and loads the full instructions only when the model calls `load_skill`.
 
 ### Flat skill
 
-```md title="agent/skills/get-weather.md"
-Use the weather tool before answering forecast or temperature questions.
-```
+Use a markdown file for a self-contained procedure.
 
 ### Packaged skill
 
-```md title="agent/skills/research/SKILL.md"
----
-description: Research unfamiliar topics before answering with confidence.
----
-
-When the task is novel or ambiguous, gather evidence first, then answer with the key facts and 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 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.
+Use a directory with `SKILL.md` when the procedure also needs references, assets, or scripts. See [Skills](../skills) for both formats, installation, runtime files, and dynamic skills.
 
 ## 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, 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.
+Do not paste a file tree or large working dataset into the prompt. Seed files into the sandbox workspace and let the model inspect them through `bash`, `read_file`, `glob`, and the other sandbox-backed tools. Skill package files use a separate runtime skill directory.
 
-See [Sandbox](../sandbox) for the workspace and sandbox model.
+See [Sandbox](../sandbox) for workspace seeding, runtime access, backends, and lifecycle behavior.
 
 ## 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 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.
+Use a subagent when work needs its own instructions, tools, skills, state, or sandbox. The child runs in a separate context instead of adding its working history to the parent. The parent receives the result of the delegation.
 
-See [Subagents](../subagents).
+See [Subagents](../subagents) for the distinction between root-agent copies and declared specialists, including their isolation boundaries.
 
 ## Dynamic context with `defineDynamic`
 
-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.
+Use `defineDynamic` when instructions, skills, tools, subagents, or the model depend on the active principal, tenant, channel, or feature state. Dynamic resolvers can read session auth and channel metadata before returning the capabilities available to that session.
 
-## Recommended context layout
+See [Dynamic capabilities](../guides/dynamic-capabilities) for the resolver API, supported slots, and execution order.
 
-Pick the lever by what the context is for:
+## Compaction and clear
 
-- `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. 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.
+User-role instructions follow the normal history lifecycle. Compaction can summarize them, and clear removes them without rerunning their static definitions or dynamic resolvers. System-role instructions remain outside history and continue to apply after either operation.
 
 ## What to read next
 
-- [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.
+- [Instructions](../instructions): author the always-on system prompt.
+- [Skills](../skills): provide procedures that load on demand.
+- [Sandbox](../sandbox): give the model files and command execution.
+- [Subagents](../subagents): isolate specialist work.
+- [Dynamic capabilities](../guides/dynamic-capabilities): vary context and capabilities by session.

package/docs/concepts/default-harness.md

@@ -57,7 +57,7 @@ The model-facing file tools accept absolute paths and paths beginning with `$HOM
 
 Notes:
 
-- **`agent`** is available only in the root session. Its child uses the root's instructions, tools, connections, and sandbox, but starts with fresh conversation history and fresh [state](../guides/state). The child receives neither `agent` nor `Workflow`; declared subagents do not receive the built-in `agent` either. See [Subagents](../subagents).
+- **`agent`** is available only in the root session. Its child uses the root's instructions, tools, connections, and sandbox, but starts with fresh conversation history and fresh [state](./state). The child receives neither `agent` nor `Workflow`; declared subagents do not receive the built-in `agent` either. See [Subagents](../subagents).
 - **`load_skill`** only pulls instructions into context. It adds no new execution surface, because behavior still comes from the tools the agent already has.
 - **`connection_search`** surfaces a connection's tools by their qualified name (e.g. `linear__list_issues`), which the model can then call directly. It's registered only when the agent has connections.
 - **`web_search`** has no local executor; the provider runs it. AI Gateway models use Exa by default. To use Parallel instead, export `webSearch({ provider: "parallel" })` from `agent/tools/web_search.ts`. Direct provider models continue to use their native search implementation. To supply your own implementation, override it with `defineTool()`.
@@ -125,7 +125,7 @@ import { experimental_workflow } from "eve/tools";
 export default experimental_workflow({ maxSubagents: 100 });
 ```
 
-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 the configured `maxSubagents` calls (default 100). See [Dynamic workflows](../guides/dynamic-workflows).
+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 the configured `maxSubagents` calls (default 100). See [Workflow Tool](../subagents/workflow-tool).
 
 ## The opt-in `sleep` tool
 

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

@@ -17,7 +17,7 @@ Every turn runs as a durable workflow, built on the open-source [Workflow SDK](h
 
 The Workflow SDK is not inherently tied to Vercel. In local development and in a self-deployed `eve start` process, eve uses the SDK's local world by default; that world persists workflow runs on disk under `.eve/.workflow-data` and dispatches through the same Nitro-hosted workflow routes. On Vercel, the same workflow code runs against Vercel Workflow instead, which adds platform features such as latest production deployment routing and dashboard run metadata.
 
-When a Vercel production deployment changes, the next model turn in an existing session uses that deployment's current instructions, model, and tools. The durable session keeps its conversation history and authored state, so identity-based channels such as Telegram private chats and Twilio phone-number conversations adopt agent updates without requiring a new session.
+When a Vercel production deployment changes, the next model turn in an existing session uses that deployment's current system-role instructions, model, and tools. Static user-role instructions stay pinned in the durable conversation history and are not seeded again. Identity-based channels such as Telegram private chats and Twilio phone-number conversations therefore adopt agent behavior updates without duplicating or rewriting their existing context.
 
 Nitro hosts the HTTP routes and workflow entrypoints. It does not supply the workflow state store or the sandbox runtime. Those are separate adapters: Workflow uses the active world implementation, and Sandbox uses the backend from `agent/sandbox` or `defaultBackend()`.
 
@@ -60,7 +60,7 @@ Crash the process, hit a timeout, or redeploy mid-turn, and the run picks up fro
 
 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. 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.
+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`](./state) reads or writes session-scoped durable state. See [State](./state) for the read/write model.
 
 ## Parked work
 
@@ -91,10 +91,10 @@ A turn can hand work off to a [subagent](../subagents). Each subagent gets its o
 
 ## 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 events in the order they happened.
+Conversation history within a session is append-only. Static user-role instructions lead fresh-session history. Dynamic user-role instructions land at their session or turn boundary before the current delivery. Turns follow in order, and the tool calls inside a turn (plus their results) keep their order too. Read a session back and you see messages in the order they happened.
 
 ## What to read next
 
 - [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.
+- [State](./state): durable per-session memory that persists across step boundaries.

package/docs/concepts/meta.json

@@ -1,8 +1,10 @@
 {
-  "title": "Concepts",
+  "title": "Core Concepts",
+  "defaultOpen": false,
   "pages": [
     "execution-model-and-durability",
     "sessions-runs-and-streaming",
+    "state",
     "default-harness",
     "context-control",
     "security-model"

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

@@ -14,7 +14,7 @@ or creates a replacement implicitly.
 Authored channels also have channel-local continuation tokens. A token addresses
 whichever session currently owns a platform conversation, such as a Slack thread.
 That identity stays behind the channel boundary and is never accepted or returned
-by the eve HTTP session API. See [Custom channels](../channels/custom#address-and-session-handles).
+by the eve HTTP session API. See [Custom channels](../channels/custom#channel-operations-and-session-handles).
 
 Sessions last 30 days by default; configure `limits.sessionTimeoutMs` in
 `agent.ts`, or set it to `false` to disable the deadline. At expiration, eve
@@ -45,8 +45,8 @@ The stream is newline-delimited JSON (NDJSON), one event per line:
 
 | Event                     | Meaning                                                                                                          |
 | ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `session.started`         | A durable session was created.                                                                                   |
-| `turn.started`            | A new turn began.                                                                                                |
+| `session.started`         | A durable session was created; carries `trace` when the runtime is traced.                                       |
+| `turn.started`            | A new turn began; carries the active `trace` when the runtime is traced.                                         |
 | `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.                    |
@@ -73,6 +73,8 @@ The stream is newline-delimited JSON (NDJSON), one event per line:
 | `session.failed`          | The session failed.                                                                                              |
 | `session.completed`       | The session reached a terminal end.                                                                              |
 
+The optional `data.trace` on session and turn starts contains eve-owned W3C trace coordinates: `traceId`, `spanId`, and `traceFlags`. Use it to correlate stream consumers such as eval reporters with an observability backend. An uninstrumented target omits it.
+
 `reasoning.appended` and `message.appended` stream incremental output as it arrives. When the durable stream writer is busy, eve may coalesce adjacent deltas of the same type; the text remains in source order, and any other event forms an ordering barrier. Each append 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.
 
 `action.partial` carries one complete preliminary output snapshot from an authored async-generator tool. A later partial for the same `callId` replaces it, and `action.result` is the final snapshot. When the durable writer is busy, eve may keep only the newest adjacent partial for a call. Treat partials as last-write-wins: a durable step can retry and replay overlapping event runs. Provider-executed tool progress and MCP progress notifications are not projected as `action.partial` events.
@@ -148,7 +150,15 @@ curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId> \
   -d '{"message":"Now send the short version."}'
 ```
 
-The follow-up reuses the same durable session: same history, same state. Message sends default to cancellation-backed `"steer"`; if a turn is active, eve buffers the follow-up, cancels that turn, and starts the message under a new turn ID. Channels and TypeScript `Session.send(...)` calls can select `turnPolicy: "queue"` when active work should finish first. Structured `inputResponses` never steer.
+The follow-up reuses the same durable session: same history, same state. A follow-up accepts exactly one of `message` or `inputResponses`. Use structured responses to answer one or more pending human-input requests by ID:
+
+```bash
+curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId> \
+  -H 'content-type: application/json' \
+  -d '{"inputResponses":[{"requestId":"req_A","optionId":"approve"}]}'
+```
+
+Message sends default to cancellation-backed `"steer"`; if a turn is active, eve buffers the follow-up, cancels that turn, and starts the message under a new turn ID. Channels and TypeScript `Session.send(...)` calls can select `turnPolicy: "queue"` when active work should finish first. Structured `inputResponses` never steer.
 
 If one pending batch is waiting on a human-in-the-loop approval, a matching text reply such as `approve` or `cancel` answers it. Unrelated text starts an ordinary turn immediately without denying the tool call; the approval stays pending and answerable. A later structured `inputResponses` answer keyed by its `requestId` still resumes the original tool call, even after intervening turns.
 
@@ -190,9 +200,11 @@ curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/reset \
   -d '{"reason":"Start over"}'
 ```
 
-Compaction summarizes context, clear removes model-message history in place,
-and reset terminally retires the session. A reset ID never becomes a new session;
-create another session explicitly for a fresh conversation.
+Compaction summarizes context without adding a user message. User-role instructions are ordinary history and may be represented by the summary; system-role instructions remain outside it. If a turn is active, eve queues the request until that turn settles. A successful compaction emits `compaction.requested` and `compaction.completed`, followed by `session.waiting`; if summarization fails, the session returns to waiting with its previous history.
+
+Clear removes model-message history in place, including static and dynamic user-role instructions, while preserving the session identity, system-role instructions, tools, skills, durable state, limits, and sandbox. It does not rerun instruction definitions or resolvers. It emits `context.cleared` followed by `session.waiting`.
+
+Reset terminally retires the exact session ID. A reset ID never becomes a new session; create another session explicitly for a fresh conversation. Compact, clear, and reset return `"no_active_session"` when the target is already inactive.
 
 ## Reconnect and rewind
 
@@ -227,11 +239,11 @@ The lookup is opt-in; requests without the parameter get no header. The TypeScri
 
 For scripts, server-to-server calls, tests, evals, and custom UIs, `eve/client` wraps these routes in a typed client so you don't hand-roll the POST and NDJSON stream loop.
 
-Start with the [TypeScript SDK](../guides/client/overview) guide. It covers basic usage, sending messages, session state, streaming, and per-turn `outputSchema` results.
+Start with the [Client SDK](../guides/client/overview) guide. It covers basic usage, sending messages, session state, streaming, and per-turn `outputSchema` results.
 
 ## Inspect the agent over HTTP
 
-`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. It uses the resolved `eveChannel()` route auth when `agent/channels/eve.ts` authors one; otherwise it falls back to the framework default of Vercel OIDC plus local development access.
+`GET /eve/v1/info` returns a JSON inspection snapshot for the running agent: model, static instructions, authored and framework tools, skills, channels, schedules, subagents, sandbox, connections, hooks, workflow, and workspace metadata. Static instructions are an ordered array whose entries expose `content` and `role`; dynamic resolver output is runtime context and is not included. The route uses the resolved `eveChannel()` auth when `agent/channels/eve.ts` authors one; otherwise it falls back to the framework default of Vercel OIDC plus local development access.
 
 ```bash
 curl http://127.0.0.1:2000/eve/v1/info
@@ -254,5 +266,5 @@ The order is structural, not incidental. By the time a resolver or hook reads ch
 
 - [Execution model & durability](./execution-model-and-durability): what makes a session durable and how parked work resumes.
 - [Channels](../channels/overview): how platform addresses map to durable sessions.
-- [TypeScript SDK](../guides/client/overview): call these routes from scripts and server-side code.
+- [Client SDK](../guides/client/overview): call these routes from scripts and server-side code.
 - [Frontend](../guides/frontend/overview): `useEveAgent` instead of raw routes.

package/docs/{guides → concepts}/state.md

@@ -46,7 +46,7 @@ export default defineTool({
 
 ## Reset state between turns
 
-State is durable by default and does not reset between turns. If you want a clean slate every turn, overwrite it from a lifecycle [hook](./hooks) on `turn.started`:
+State is durable by default and does not reset between turns. If you want a clean slate every turn, overwrite it from a lifecycle [hook](../guides/hooks) on `turn.started`:
 
 ```ts title="agent/hooks/reset-budget.ts"
 import { defineHook } from "eve/hooks";
@@ -73,7 +73,7 @@ Every [subagent](../subagents) starts with its own fresh state, whether it's a b
 
 ## What to read next
 
-- Read state inside dynamic resolvers → [Dynamic capabilities](./dynamic-capabilities)
+- Read state inside dynamic resolvers → [Dynamic capabilities](../guides/dynamic-capabilities)
 - How step durability works → [Execution model & durability](../concepts/execution-model-and-durability)
-- The `ctx` accessors available alongside state → [TypeScript API](../reference/typescript-api)
+- The `ctx` accessors available alongside state → [TypeScript API Reference](../reference/typescript-api)
 - Tenant-scoped long-term memory in your own store → [Multi-tenant memory](../patterns/multi-tenant-memory)