eve 0.34.0 → 0.35.0

package/docs/guides/frontend/use-eve-agent-vue.mdx

@@ -1,94 +1,66 @@
 ---
 title: "useEveAgent (Vue)"
-description: "Vue composable that drives an eve agent session from the browser."
+description: "Use the eve Vue composable and its Vue-specific reactive interface."
 ---
 
-`useEveAgent()` from `eve/vue` is how a Vue app talks to an eve session. It opens a long-lived session, sends turns, and folds every stream event into reactive data you can bind in a template. Nuxt auto-imports it through the [module](./nuxt), and the [frontend overview](./overview) covers the shared model.
+`useEveAgent()` from `eve/vue` exposes the shared eve frontend client as Vue computed refs and methods. Read the [frontend overview](./overview) for session behavior, messages, human input, authorization, callbacks, reducers, and persistence. This page covers the Vue-specific interface.
 
-## Basic usage
-
-Import the composable from `eve/vue`. Its state is exposed as `ComputedRef`s, so you read it unwrapped in templates:
-
-```vue
-<script setup lang="ts">
-import { useEveAgent } from "eve/vue";
-
-const { data } = useEveAgent();
-</script>
-
-<template>
-  <div v-for="message in data.messages" :key="message.id">
-    <p>{{ message.role }}: {{ message.parts }}</p>
-  </div>
-</template>
-```
+Nuxt users normally receive the composable as an auto-import after registering the [`eve/nuxt` module](./nuxt).
 
-## What it returns
-
-| Property  | Type                                           | Description                                                               |
-| --------- | ---------------------------------------------- | ------------------------------------------------------------------------- |
-| `data`    | `ComputedRef<TData>`                           | Projected state. With the default reducer, `EveMessageData` (`messages`). |
-| `status`  | `ComputedRef<UseEveAgentStatus>`               | `"ready"`, `"submitted"`, `"streaming"`, or `"error"`.                    |
-| `error`   | `ComputedRef<Error \| undefined>`              | Last transport-level error.                                               |
-| `events`  | `ComputedRef<readonly MessageStreamEvent[]>`   | Raw server events for this session.                                       |
-| `session` | `ComputedRef<ClientSessionState \| undefined>` | Fixed session ID and stream cursor.                                       |
-| `send`    | `(message, options?) => Promise<void>`         | Send text or a multi-part message.                                        |
-| `respond` | `(inputResponses, options?) => Promise<void>`  | Answer pending HITL input requests.                                       |
-| `stop`    | `() => void`                                   | Abort the client's in-flight stream.                                      |
-| `reset`   | `() => void`                                   | Clear state and start a new session.                                      |
+## Basic usage
 
-The first five are `ComputedRef`s; the rest are methods. Destructure whatever you need, since refs keep their reactivity through destructuring. Read them with `.value` in `<script>`, and unwrapped in `<template>`.
-
-## Send a message
+Import the composable from `eve/vue`. Its state is exposed as `ComputedRef`s, so templates unwrap it automatically:
 
 ```vue
 <script setup lang="ts">
-import { ref } from "vue";
 import { useEveAgent } from "eve/vue";
+import { computed, ref } from "vue";
 
-const { send } = useEveAgent();
+const { data, status, send } = useEveAgent();
 const message = ref("");
+const isBusy = computed(() => status.value === "submitted" || status.value === "streaming");
 
 async function handleSubmit() {
   const text = message.value.trim();
-  if (!text) return;
+  if (!text || isBusy.value) return;
   message.value = "";
   await send(text);
 }
 </script>
 
 <template>
+  <div v-for="item in data.messages" :key="item.id">
+    <p>{{ item.role }}: {{ item.parts }}</p>
+  </div>
   <form @submit.prevent="handleSubmit">
-    <input v-model="message" placeholder="Type a message..." />
-    <button type="submit">Send</button>
+    <input v-model="message" :disabled="isBusy" />
+    <button type="submit" :disabled="isBusy">Send</button>
   </form>
 </template>
 ```
 
-For anything beyond plain text, reach for `send()`. Attachments follow the AI SDK `UserContent` format. Send file data as a base64 `data:` URL so it survives the JSON transport:
+## What it returns
 
-```vue
-<script setup lang="ts">
-import { useEveAgent } from "eve/vue";
+The state fields are computed refs; the commands are ordinary methods:
 
-const { send } = useEveAgent();
-
-async function onFileChange(event: Event) {
-  const file = (event.target as HTMLInputElement).files?.[0];
-  if (!file) return;
-  const bytes = new Uint8Array(await file.arrayBuffer());
-  const base64 = btoa(String.fromCodePoint(...bytes));
-  await send([
-    { type: "text", text: "Describe this image." },
-    { type: "file", data: `data:${file.type};base64,${base64}`, mediaType: file.type },
-  ]);
-}
-</script>
-```
+| Property                           | Vue shape                                      |
+| ---------------------------------- | ---------------------------------------------- |
+| `data`                             | `ComputedRef<TData>`                           |
+| `status`                           | `ComputedRef<UseEveAgentStatus>`               |
+| `error`                            | `ComputedRef<Error \| undefined>`              |
+| `events`                           | `ComputedRef<readonly MessageStreamEvent[]>`   |
+| `session`                          | `ComputedRef<ClientSessionState \| undefined>` |
+| `send`, `respond`, `stop`, `reset` | Methods                                        |
+
+Destructuring preserves reactivity because each state value remains a ref. Read refs with `.value` in `<script>` and without `.value` in a template. The [shared returned-state reference](./overview#returned-state) describes what each value and command does.
+
+## Send a message
+
+Call `send(text)` for text or pass content parts for attachments. The API and transport behavior match the [shared sending guide](./overview#sending-and-streaming); only reactive access differs in Vue.
 
 ## Human-in-the-loop prompts
 
-A tool opts into approval with `approval` ([Tools](../../tools)). When it triggers, the pending request shows up on a `dynamic-tool` part at `part.toolMetadata?.eve?.inputRequest`. Scan every message because an unrelated turn can add newer messages while the approval stays open, then answer through the same session with `respond(inputResponses)`:
+Pending requests appear in `data.value.messages`. Use the Vue exports when narrowing message parts, then answer through `respond()`:
 
 ```vue
 <script setup lang="ts">
@@ -132,101 +104,30 @@ const pendingRequests = computed(() =>
 </template>
 ```
 
-For a question with `allowFreeform`, bind a text input and send `{ requestId, text }`. The [React hook reference](./overview) covers the shared behavior.
+See [Human-in-the-loop prompts](./overview#human-in-the-loop-prompts) for request semantics and rendering guidance.
 
 ## Stop, reset, and resume
 
-`stop()` aborts the in-flight stream; the server-side turn keeps running and remains attachable — to stop the turn itself, POST the session's [cancel route](../../channels/eve#routes). `reset()` wipes state and starts a fresh session. To survive a reload, pass `initialSession` to restore a saved session and `onSessionChange` to persist the cursor as it moves:
-
-```ts
-const agent = useEveAgent({
-  initialSession: savedSessionState,
-  initialEvents: savedEvents,
-  onSessionChange: (session) => {
-    localStorage.setItem("eve-session", JSON.stringify(session));
-  },
-});
-```
+Call `stop()` to detach the browser stream without cancelling server-side work, and `reset()` to clear local state and start a new session. Pass `initialSession` and `initialEvents` to restore a saved conversation. See [Resumable sessions](./overview#resumable-sessions) for the persistence contract and [Sending and streaming](./overview#sending-and-streaming) for cancellation behavior.
 
 ## Custom host and credentials
 
-When your eve server lives somewhere other than the same origin, point at it with `host` and attach credentials through `auth` or `headers`. Pass a function and it re-resolves before each request:
-
-```ts
-const agent = useEveAgent({
-  host: "https://agent.example.com",
-  headers: async () => ({
-    authorization: `Bearer ${await getAccessToken()}`,
-  }),
-});
-```
+Pass `host`, `auth`, or `headers` to the composable using the same options as the other frontend bindings. See [Custom hosts and headers](./overview#custom-hosts-and-headers).
 
 ## Attach page context per turn
 
-`clientContext` adds ephemeral context for the next model call and nothing more. Strings (or an array of strings) become user-role context messages; an object is JSON-serialized into one. It rides along with a message or HITL response, never dispatches a turn on its own, and never lands in durable session history. Pass it in the second argument to `send()` or `respond()`:
-
-```ts
-await send("What should I do on this screen?", {
-  clientContext: { route: "/billing", plan: "pro", seatsUsed: 4 },
-});
-```
-
-To attach the same context to every turn without threading it through each call site, pass `prepareSend`. It runs right before each send and returns the (possibly augmented) turn:
-
-```ts
-const agent = useEveAgent({
-  prepareSend: (input) => ({
-    ...input,
-    clientContext: { route: location.pathname },
-  }),
-});
-```
+Pass `clientContext` to `send()` or `respond()`, or use `prepareSend` to add context before every turn. See [Attach page context per turn](./overview#attach-page-context-per-turn).
 
 ## Lifecycle callbacks
 
-The composable takes a few per-turn callbacks:
-
-- `onEvent(event)`: fires for each eve stream event as it arrives.
-- `onError(error)`: fires with the last `Error` when a turn fails.
-- `onFinish(snapshot)`: fires with the final snapshot once a turn settles.
-- `onSessionChange(session)`: fires when the session cursor advances. Persist it to resume across reloads.
-
-```ts
-const agent = useEveAgent({
-  onEvent: (event) => console.debug(event.type),
-  onError: (error) => console.error(error.message),
-  onFinish: (snapshot) => console.log(snapshot.status),
-});
-```
-
-The `optimistic` option (default `true`) projects submitted user messages into `data` before eve confirms them with a `message.received` event. These are reducer-facing projection events only; `events` stays the authoritative eve stream.
+Pass `onEvent`, `onError`, `onFinish`, or `onSessionChange` when the application needs lifecycle notifications. See [Lifecycle callbacks](./overview#lifecycle-callbacks) for callback timing and optimistic projection behavior.
 
 ## Custom reducer
 
-The default reducer projects events into `{ messages }` (`EveMessageData`). To shape `data` differently, pass a `reducer` implementing `EveAgentReducer<TData>`:
-
-```ts
-import { useEveAgent } from "eve/vue";
-import type { EveAgentReducer } from "eve/vue";
-
-interface ToolLog {
-  readonly toolCalls: number;
-}
-
-const toolCounter: EveAgentReducer<ToolLog> = {
-  initial: () => ({ toolCalls: 0 }),
-  reduce: (data, event) =>
-    event.type === "actions.requested" ? { toolCalls: data.toolCalls + 1 } : data,
-};
-
-const agent = useEveAgent({ reducer: toolCounter });
-// agent.data.value is ToolLog
-```
-
-`reduce(data, event)` receives both authoritative eve stream events and client projection events (`client.message.submitted`, `client.message.failed`, `client.input.responded`). Handle the client events too if you want optimistic and HITL state in your projection. Otherwise, return `data` unchanged for them.
+Import `EveAgentReducer` from `eve/vue` when projecting events into application-specific state. The resulting `data` remains a `ComputedRef<TData>`. See [Custom reducer](./overview#custom-reducer) for the reducer contract and client projection events.
 
 ## What to read next
 
-- [Nuxt](./nuxt): module setup
-- [Frontend overview](./overview): the shared integration model
-- [Sessions, runs & streaming](../../concepts/sessions-runs-and-streaming)
+- [Nuxt](./nuxt): register the module and mount the eve runtime.
+- [Frontend overview](./overview): use the shared frontend API.
+- [Sessions, runs, and streaming](../../concepts/sessions-runs-and-streaming): understand the underlying session protocol.

package/docs/guides/instrumentation.md

@@ -1,5 +1,5 @@
 ---
-title: "instrumentation.ts"
+title: "Observability"
 description: "Trace an agent with OpenTelemetry in instrumentation.ts, read the workflow run tags eve emits, and debug discovery with eve info and the common-failures table."
 ---
 
@@ -48,11 +48,11 @@ Any OTel-compatible backend works (Braintrust, PostHog, Raindrop, Arize, Honeyco
 
 Three more fields control what the AI SDK records inside those spans (see the AI SDK's [telemetry reference](https://ai-sdk.dev/docs/ai-sdk-core/telemetry)):
 
-- `recordInputs` records full message history on each step span (defaults to `true`). Set it to `false` if inputs contain sensitive content or you want to reduce span payload size.
-- `recordOutputs` records model outputs on spans (defaults to `true`). Set it to `false` to disable output recording.
+- `recordInputs` records full message history on each step span. It defaults to `false`; set it to `true` to include input content.
+- `recordOutputs` records model outputs on spans. It defaults to `false`; set it to `true` to include output content.
 - `functionId` overrides the function name on spans (defaults to the agent name).
 
-For sensitive, regulated, or production data, set `recordInputs` and `recordOutputs` to `false` unless you have reviewed the exporter and its data-retention path.
+eve records metadata without model or tool inputs and outputs by default. Enable either content category only after reviewing the exporter and its data-retention path.
 
 You are responsible for ensuring any observability or eval provider is approved for the data exported to it.
 
@@ -173,20 +173,20 @@ Tag writes are best-effort: a failure is logged once per process and then swallo
 
 These tags power the **Agent Runs** tab in the Vercel dashboard. When you deploy on Vercel, the platform auto-detects `eve` as the framework and surfaces an Agent Runs view under your project's **Observability** tab, where you can browse sessions and drill into each conversation's trace, with no `instrumentation.ts` required. The tab is currently gated per team. See [Deploy to Vercel](./deployment/vercel#inspect-agent-runs) for enablement. Agent Runs is separate from the OpenTelemetry export above. Use OTel when you want spans in Braintrust, PostHog, Datadog, or another third-party backend.
 
-Note: By default, telemetry records full message history and model outputs You may need to disclose these data flows in your privacy materials if utilized.
-
 ## Local traces
 
 Without an `instrumentation.ts`, `eve dev` records spans to disk — one trace per session, with turns, model steps, and tool calls. Read them two ways:
 
-- [`/traces`](dev-tui#inspect-traces) in the dev TUI: a live viewer that replays the trace as a conversation.
+- [`/traces`](dev-tui#logs-and-traces) in the dev TUI: a live trace viewer that replays captured content as a conversation.
 - [`eve traces`](../reference/cli#eve-traces): a span tree in the terminal, `eve traces ls` to list. Works after `eve dev` exits.
 
+Local traces omit model and tool inputs and outputs by default. Set `EVE_TRACES_CONTENT=on` in `.env.local` to capture that content.
+
 Writing `instrumentation.ts` replaces this: your `setup` takes over and nothing is recorded locally. For span attributes, retention, and the `EVE_TRACES*` variables, see [`eve traces`](../reference/cli#eve-traces).
 
 ## Debugging
 
-`eve info` is the fastest way to see what eve actually picked up: the active tools, skills, subagents, schedules, routes, and discovery diagnostics. eve also writes inspectable artifacts under `.eve/`, kept even when discovery hits errors:
+`eve info` is the fastest way to see what eve actually picked up: ordered static instructions with their roles, plus the active tools, skills, subagents, schedules, routes, and discovery diagnostics. Dynamic instruction results exist only at runtime and are not part of this static inspection. eve also writes inspectable artifacts under `.eve/`, kept even when discovery hits errors:
 
 | Artifact                        | Tells you                                   |
 | ------------------------------- | ------------------------------------------- |
@@ -199,13 +199,13 @@ When `eve build` fails on discovery errors, the CLI prints the full diagnostics
 
 ### Common failures
 
-| Symptom                                       | Likely cause and fix                                                                                                                                                                                                                                                        |
-| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Tool not discovered (the model never sees it) | Run `eve info`. Confirm the file is in the right slot (`agent/tools/<name>.ts`) and default-exports `defineTool(...)`, and check `.eve/diagnostics.json` for shape errors. `schedules/` are root-only.                                                                      |
-| Model won't call a tool it should             | Tighten the tool `description` and `inputSchema`; put procedural guidance in a [skill](../skills), not the description. Confirm it's in the active set with `eve info`.                                                                                                     |
-| Stuck on `session.waiting`                    | The turn is parked for input. Answer the pending approval or question, or POST a follow-up to `/eve/v1/session/:sessionId`.                                                                                                                                                 |
-| 401 on production routes                      | Expected: auth fails closed. Replace `placeholderAuth()` with your route policy. Use `vercelOidc()` only for Vercel-issued tokens; otherwise configure `httpBasic()`, JWT/OIDC helpers, or a custom `AuthFn`. See [Auth and route protection](./auth-and-route-protection). |
-| Build fails with discovery errors             | Read the printed diagnostics and `.eve/diagnostics.json`; confirm the root-vs-subagent boundary is valid and secrets come from env vars.                                                                                                                                    |
+| Symptom                                       | Likely cause and fix                                                                                                                                                                                                                                             |
+| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Tool not discovered (the model never sees it) | Run `eve info`. Confirm the file is in the right slot (`agent/tools/<name>.ts`) and default-exports `defineTool(...)`, and check `.eve/diagnostics.json` for shape errors. `schedules/` are root-only.                                                           |
+| Model won't call a tool it should             | Tighten the tool `description` and `inputSchema`; put procedural guidance in a [skill](../skills), not the description. Confirm it's in the active set with `eve info`.                                                                                          |
+| Stuck on `session.waiting`                    | The turn is parked for input. Answer the pending approval or question, or POST a follow-up to `/eve/v1/session/:sessionId`.                                                                                                                                      |
+| 401 on production routes                      | Expected: auth fails closed. Replace `placeholderAuth()` with your route policy. Use `vercelOidc()` only for Vercel-issued tokens; otherwise configure `httpBasic()`, JWT/OIDC helpers, or a custom `AuthFn`. See [Authentication](./auth-and-route-protection). |
+| Build fails with discovery errors             | Read the printed diagnostics and `.eve/diagnostics.json`; confirm the root-vs-subagent boundary is valid and secrets come from env vars.                                                                                                                         |
 
 ## What to read next
 

package/docs/guides/meta.json

@@ -6,14 +6,10 @@
     "instrumentation",
     "hooks",
     "session-context",
-    "state",
     "dynamic-capabilities",
-    "dynamic-workflows",
     "remote-agents",
     "dev-tui",
-    "acp",
     "frontend",
-    "client",
-    "ucp"
+    "client"
   ]
 }

package/docs/guides/remote-agents.md

@@ -20,14 +20,14 @@ export default defineRemoteAgent({
 
 `defineRemoteAgent` accepts:
 
-| Parameter          | Type                                          | Required | Default           | Description                                                                                                                                              |
-| ------------------ | --------------------------------------------- | -------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `url`              | `string \| (() => string \| Promise<string>)` | Yes      | n/a               | Base URL of the remote eve deployment to call. A string is baked at compile time; a function is resolved at runtime (see [Runtime URLs](#runtime-urls)). |
-| `description`      | `string`                                      | Yes      | n/a               | Model-visible delegation description.                                                                                                                    |
-| `auth`             | `OutboundAuthFn`                              | No       | none              | Outbound auth hook from `eve/agents/auth`.                                                                                                               |
-| `forwardPrincipal` | `boolean`                                     | No       | `false`           | Forward the dispatching turn's session principal to the remote deployment (see [Forwarding the caller identity](#forwarding-the-caller-identity)).       |
-| `headers`          | `HeadersValue`                                | No       | none              | Static or lazily resolved request headers.                                                                                                               |
-| `path`             | `string`                                      | No       | `/eve/v1/session` | Route appended to `url` for the create-session request.                                                                                                  |
+| Parameter          | Type                                          | Required | Default           | Description                                                                                                                                                                          |
+| ------------------ | --------------------------------------------- | -------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `url`              | `string \| (() => string \| Promise<string>)` | Yes      | n/a               | Base URL of the remote eve deployment to call. A string is baked at compile time; a function is resolved at runtime (see [Runtime URLs](#runtime-urls)).                             |
+| `description`      | `string`                                      | Yes      | n/a               | Model-visible delegation description.                                                                                                                                                |
+| `auth`             | `OutboundAuthFn`                              | No       | none              | Outbound auth hook from `eve/agents/auth`.                                                                                                                                           |
+| `forwardPrincipal` | `boolean`                                     | No       | `false`           | Forward the dispatching turn's session principal to the remote deployment (see [Forwarding the caller identity](#forwarding-the-caller-identity)).                                   |
+| `headers`          | `HeadersValue`                                | No       | none              | Static or lazily resolved request headers.                                                                                                                                           |
+| `path`             | `string`                                      | No       | `/eve/v1/session` | Route appended to `url` for the create-session request.                                                                                                                              |
 | `outputSchema`     | `StandardSchema \| JSON Schema`               | No       | none              | Structured return type the caller requires. Enforced by the remote agent like any task-mode output schema. Set it on the definition to apply to every call, or override it per call. |
 
 ## Dynamic remote agents
@@ -135,5 +135,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)
+- Have the model orchestrate remote agents programmatically → [Workflow Tool](../subagents/workflow-tool)
 - Securing the receiving deployment → [Auth & route protection](./auth-and-route-protection)

package/docs/guides/session-context.md

@@ -1,20 +1,22 @@
 ---
 title: "Session Context"
-description: "Runtime helpers: ctx.session, ctx.getSandbox, ctx.getSkill, and defineState."
+description: "Use ctx.session and runtime accessors inside eve-managed execution."
 ---
 
-eve exposes runtime state through the `ctx` parameter passed to tool `execute`, hook handlers, channel event handlers, and connection auth/header resolvers:
+eve passes a runtime `ctx` to tool executors, hook handlers, channel event handlers, and connection auth and header resolvers. Use it to inspect the active session and reach resources bound to that execution.
 
-- `ctx.session`: session metadata, turn, auth, and parent lineage
-- `ctx.getSandbox()`: live sandbox handle for the current agent
-- `ctx.getSkill(identifier)`: handle for a named skill visible to the current agent
-- `defineState(name, initial)`: typed durable state with `get()` and `update()` (imported from `eve/context`)
+| Accessor                     | Provides                                                  | Full guide                                      |
+| ---------------------------- | --------------------------------------------------------- | ----------------------------------------------- |
+| `ctx.session`                | Session identity, turn metadata, auth, and parent lineage | This page                                       |
+| `ctx.getSandbox()`           | The current agent's live sandbox handle                   | [Sandbox](../sandbox)                           |
+| `ctx.getSkill(identifier)`   | A handle for a skill visible to the current agent         | [Skills](../skills#read-skill-files-at-runtime) |
+| `defineState(name, initial)` | Durable typed state shared by runtime code in one session | [State](../concepts/state)                      |
 
-These APIs work only inside active authored runtime execution, including tools, channel event handlers, and authored hooks. They throw when called outside a managed context.
+These APIs work only during eve-managed runtime execution. Calling them during module evaluation, discovery, or a build throws.
 
 ## `ctx.session`
 
-`ctx.session` exposes durable runtime metadata about the current execution.
+`ctx.session` describes the durable session and active turn:
 
 ```ts title="agent/tools/who_called_me.ts"
 import { defineTool } from "eve/tools";
@@ -37,132 +39,61 @@ export default defineTool({
 });
 ```
 
-Public session fields:
+Public fields include:
 
-- `auth.current`
-- `auth.initiator`
-- `id`
-- `turn.id`
-- `turn.sequence`
-- optional `parent`
+- `id`: the durable session ID.
+- `turn.id`: the current turn ID.
+- `turn.sequence`: the turn's position in the session.
+- `auth.current`: the caller for the active inbound turn.
+- `auth.initiator`: the caller that started the session.
+- `parent`: the parent call, session, root session, and turn for a child subagent session.
 
-Behavior:
-
-- `auth.current` is the caller for the active inbound turn.
-- `auth.initiator` is the caller that started the durable session.
-- Unprotected agents expose both as `null`.
-- Top-level schedule sessions expose the framework app principal (`principalId: "eve:app"`, `principalType: "runtime"`).
-- `parent` is present for child subagent sessions and includes the parent `callId`, `sessionId`, `rootSessionId`, and `turn`.
+Unprotected agents expose `auth.current` and `auth.initiator` as `null`. Top-level schedule sessions use the framework app principal (`principalId: "eve:app"`, `principalType: "runtime"`). See [Authentication](./auth-and-route-protection#what-reaches-ctxsessionauth) for how inbound identity becomes session auth.
 
 ## `ctx.getSandbox()`
 
-`ctx.getSandbox()` returns a live handle for the current agent's sandbox.
+Call `ctx.getSandbox()` when authored runtime code needs filesystem or process access in the current agent's sandbox:
 
 ```ts
 const sandbox = await ctx.getSandbox();
 const result = await sandbox.run({ command: "npm test" });
 ```
 
-Behavior:
-
-- It takes no arguments. Each agent has exactly one sandbox.
-- It is async because eve binds or restores sandbox state lazily.
-- It only works when sandbox access is attached to the active runtime path.
-- Visibility is node-local. A subagent sees its own sandbox, not the parent's.
-- The returned `RuntimeSandboxSession` extends the ordinary sandbox I/O surface
-  with `stop()`. It is exported from `eve/sandbox`.
-
-Call `stop()` to release sandbox compute while preserving the durable session
-and its filesystem:
-
-```ts
-const sandbox = await ctx.getSandbox();
-await sandbox.stop();
-```
-
-Each backend implements this with its native lifecycle operation. Treat the
-stop as the end of sandbox work in the current callback; a later callback calls
-`ctx.getSandbox()` normally and eve reopens the same durable session. Vercel
-also supports using the same handle again: its next command or file operation
-automatically resumes the sandbox, just as it would after an inactivity
-timeout. No separate eve reconnect state is created, and provider failures
-reject the returned promise.
-
-`SandboxSession` also exposes `resolvePath(path)`, which returns the live backend-native path for a logical `/workspace/...` location. Use it when authored code needs that path before passing it to shell code or a child process.
-
-See [Sandbox](../sandbox) for lifecycle details.
+The accessor is asynchronous because eve may need to bind or restore the sandbox. A subagent sees its own sandbox, not its parent's. The returned runtime handle can also stop compute while preserving the durable sandbox state. See [Sandbox](../sandbox#using-the-sandbox) for the I/O API and lifecycle.
 
 ## `ctx.getSkill(identifier)`
 
-`ctx.getSkill(identifier)` returns a handle for a named skill visible to the current agent.
+Call `ctx.getSkill(identifier)` to read a packaged skill's supporting files:
 
 ```ts
 const skill = ctx.getSkill("research");
 const notes = await skill.file("references/checklist.md").text();
 ```
 
-Behavior:
-
-- It is synchronous. File content is read lazily from the active sandbox.
-- It only works when sandbox access is attached to the active runtime path.
-- `identifier` is the path-derived skill id.
-- Visibility follows the current agent's sandbox.
-- A missing skill surfaces when a file accessor reads a missing sandbox path.
-- The returned handle exposes `name` and `file(relativePath)`.
-
-See [Skills](../skills) for the full authoring model.
+The accessor is synchronous; file content is read lazily from the active sandbox. Visibility follows the current agent. See [Skills](../skills#read-skill-files-at-runtime) for the complete handle behavior.
 
 ## Custom state with `defineState`
 
-Use `defineState` when your agent needs durable typed state that tools, hooks, and channel handlers can share. State survives workflow step boundaries. Declare the handle at module scope so every importer shares it:
-
-```ts title="agent/lib/budget.ts"
-import { defineState } from "eve/context";
-
-interface BudgetState {
-  readonly count: number;
-  readonly cap: number;
-}
-
-export const budget = defineState<BudgetState>("myapp.budget", () => ({
-  count: 0,
-  cap: 25,
-}));
-```
-
-`get()` reads the current value (returning `initial()` on first access), and `update(fn)` applies a function to it. Both throw outside a managed scope. See [State](./state) for the full read/write model and examples from tools and hooks.
+Use `defineState` for durable per-session values that tools, hooks, and channel handlers share. Unlike the `ctx` accessors, import it from `eve/context` and declare the handle at module scope. Its `get()` and `update()` methods still require active eve execution. See [State](../concepts/state) for the read, update, reset, and subagent-isolation model.
 
 ## Where these APIs work
 
-Safe places:
-
-- inside `defineTool(...).execute(input, ctx)`
-- inside connection `auth: (ctx) => provider` and `headers: (ctx) => values` resolvers
-- inside authored callbacks eve runs inside the runtime
-- after asynchronous boundaries inside the same authored execution chain
-
-Unsafe places:
+Runtime context is available:
 
-- top-level module evaluation
-- build scripts
-- discovery-time code paths
+- inside `defineTool(...).execute(input, ctx)`;
+- inside connection `auth` and `headers` resolvers;
+- inside channel and hook callbacks that receive `ctx`;
+- after asynchronous boundaries within the same authored execution chain.
 
-If you call them outside an active eve runtime context, they throw immediately with a message explaining the required scope.
+Runtime context is not available during top-level module evaluation, build scripts, or discovery. Declare reusable definitions and state handles at module scope, but call their context-dependent methods only from an eve-managed callback.
 
 ## How it works
 
-The framework sets up a context container before invoking authored code:
-
-1. The runtime populates durable seed values (auth, session id, compiled bundle).
-2. Before each step, the framework derives step-local values (session metadata, sandbox access, skill access) from the durable state.
-3. Authored code runs inside the managed scope, so `ctx` and `defineState` accessors resolve automatically.
-4. After the step, the framework commits mutable state (for example sandbox changes) back to the durable session.
-
-The framework manages this lifecycle. Authored code only uses `ctx` and the public accessors.
+eve establishes the managed context before invoking authored runtime code and keeps it available across asynchronous work in that execution chain. The framework binds durable session data and step-local resources, then commits mutable state at the step boundary. Authored code uses the public accessors rather than managing this lifecycle.
 
 ## What to read next
 
-- [State](./state)
-- [Sessions, runs & streaming](../concepts/sessions-runs-and-streaming)
-- [Subagents](../subagents)
-- [Skills](../skills)
+- [State](../concepts/state): durable typed values scoped to one session.
+- [Sandbox](../sandbox): runtime filesystem and process access.
+- [Skills](../skills): load procedures and read packaged skill files.
+- [Sessions, runs, and streaming](../concepts/sessions-runs-and-streaming): the durable session and event contract.

package/docs/install-integrations.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Install Integrations"
+title: "Add Integrations"
 description: "Discover and install extensions and other integrations from eve and third-party sources."
 contentType: "How-to"
 ---