eve 0.81.1 → 0.83.0

package/docs/experimental/dynamic-schedules.mdx

@@ -0,0 +1,186 @@
+---
+title: "Dynamic Schedules"
+description: "Create and manage creator-owned recurring or one-time schedules at runtime."
+---
+
+<Callout type="info" title="Feature flag required">
+  Dynamic schedules on Vercel are gated by an organization-level feature flag. Contact your Vercel
+  representative to have the feature enabled for your organization.
+</Callout>
+
+Use `defineDynamicSchedules` when users or agents need to create recurring or one-time schedules at runtime. Export the definition from `agent/schedules/`; eve derives its identity from the file path. The definition configures management tools and an occurrence callback. It does not create a schedule or set its timing.
+
+This API is experimental and may change. Import it from `eve/experimental/schedules`. For fixed, code-authored cron jobs, use [`defineSchedule`](../schedules) instead. For a self-hosted alternative with application-owned storage, see [Dynamic scheduling](../patterns/dynamic-scheduling).
+
+## Define scheduled work
+
+The model supplies schema-defined payload. eve captures the authenticated creator separately and resolves current execution auth whenever an occurrence fires.
+
+```ts title="agent/schedules/requests.ts"
+import { byPrincipal, defineDynamicSchedules } from "eve/experimental/schedules";
+import { z } from "zod";
+import slack from "../channels/slack";
+import { resolveCurrentUser } from "../lib/identity";
+import { resolveCreatorDm, resolveAuthorizedTeamChannel } from "../lib/schedule-policy";
+
+export default defineDynamicSchedules({
+  description: "Schedule Slack tasks for the creator's DM or authorized team channel.",
+  inputSchema: z
+    .object({
+      task: z.string().min(1).max(2000),
+      destination: z.enum(["my-dm", "team-channel"]),
+    })
+    .strict(),
+  scope: byPrincipal,
+  auth: ({ principal }) => resolveCurrentUser(principal),
+  async run({ payload, occurrence, to, auth }) {
+    const target =
+      payload.destination === "my-dm"
+        ? await resolveCreatorDm(auth)
+        : await resolveAuthorizedTeamChannel(auth);
+    await to(slack, target).send(
+      `Perform this task now.\nSchedule: ${occurrence.displayName}\nScheduled for: ${occurrence.scheduledAt}\nTask: ${payload.task}`,
+    );
+  },
+});
+```
+
+The identity and destination helpers are application code. `inputSchema`, `auth`, and `run` are required. `provider` is optional and defaults to `vercelScheduleProvider()`. Pass a provider explicitly to use another backend or configure the Vercel endpoint.
+
+`scope` defaults to `byPrincipal`, isolating management by authenticated principal type, authenticator, issuer, and ID, plus application and path-derived definition identity. A custom scope resolver must authorize each operation before returning a namespace; return `null` to deny.
+
+## Revalidate creator identity
+
+`auth({ principal, payload, occurrence })` resolves the stored creator reference to current execution auth. Look up current account status and permissions rather than replaying credentials or roles captured at creation. Return `null` to deny; thrown errors remain eligible for provider retries.
+
+The returned principal type, authenticator, issuer, ID, and subject must match the creator reference. eve does not fall back to app identity. Manual invocation does not replace the creator with the invoker. Tool and connection authorization still applies during execution.
+
+## Prepare payloads and destinations
+
+The generated creation and update tools validate their `payload` field with your `inputSchema`. Without `preparePayload`, eve validates payloads before persistence and again before dispatch. The complete provider envelope is limited to 64 KB; store JSON data and stable references, not credentials or sensitive recipient details.
+
+Optional `preparePayload(input, context)` validates application policy, resolves caller context, and returns the stored shape. It runs on creation and payload replacement, after input validation and scope authorization, before persistence. For model calls, eve prepares before asking for approval and provides the prepared payload to `approval.create` or `approval.update`. It prepares again before writing and rejects the call if the prepared result differs from the approved snapshot. Preparation errors reach the model before a person is asked. Authenticated code calling the client prepares once before writing, without model approval.
+
+`auth`, `run`, and occurrence events infer the prepared return type. Declare `preparePayload` before these callbacks or give it an explicit return type for TypeScript contextual inference. Without preparation, payload type comes from the schema.
+
+The input schema does not describe prepared output. eve bounds and JSON-validates the persisted envelope but does not structurally revalidate prepared application data against the input schema at execution. Authored code owns that persisted contract; validate it explicitly if needed. Preparation may repeat on write retries, so avoid irreversible effects. Reads, timing-only updates, state changes, and occurrences never rerun it.
+
+```ts
+preparePayload(input, context) {
+  const target = resolveDestination(input.destination, context);
+  return { task: input.task, target };
+},
+```
+
+`resolveDestination` is application code. For channel delivery, it can validate trusted caller context and capture channel/workspace references without exposing those fields in the model-facing schema. Reject callers that lack the required channel context, including delegated work when appropriate. Payload replacement recaptures the destination and creator from the updating caller.
+
+Destination IDs are optional. Conditional logic in `run` can derive a DM from creator identity, select an authorized configured channel, or look up a destination using another payload value. A schema may expose explicit IDs when the model can obtain them, but valid IDs do not prove access. Management scope does not authorize sending to every destination. Validate model-selected destinations against the creator's current permissions.
+
+The original creation conversation is not captured automatically. To support “reply in the exact thread where I created this,” persist an authorized thread reference through `preparePayload` or application code. Creator identity alone cannot recover that thread. Runtime lookups can follow changed configuration; persist a destination reference when the destination must stay fixed.
+
+## Expose management tools
+
+Each definition contributes tools for `create`, `get`, `list`, `update`, `enable`, `disable`, `invoke`, and `delete`. Each has its own object-rooted schema, approval policy, and readable action label. For example, `agent/schedules/billing/requests.ts` generates `schedule__billing-requests__create`, `schedule__billing-requests__update`, and the other operation names. There is no combined manage tool or operation field.
+
+Creation takes `{ name, expression, payload }`. Updates take `{ name, expression?, payload? }` and require at least an expression or a complete replacement payload. Listing takes optional `{ cursor, limit }`, with limits from 1 through 100. The remaining tools take `{ name }` using the unique identifier from receipts or reads.
+
+Set `tool: true` (the default) for direct tools, `tool: "deferred"` for catalog-discovered tools, or `tool: false` for code-only scheduling. Deferred operations keep the same names, schemas, approval policies, and authorization checks; the model finds them with `eve__search` and calls them with `eve__tool`. See [Dynamic capabilities](../guides/dynamic-capabilities#dynamic-tools).
+
+Reads need no approval by default; mutations require user approval. Configure top-level `approval`, keyed by operation, with ordinary request/response policies. Separate tool identities keep `once()` grants independent. Create and payload-replacement update policies receive a typed `payload` containing prepared data; `toolInput.payload` also contains prepared rather than raw data. Timing-only update policies receive `payload: undefined`.
+
+```ts
+approval: {
+  create: ({ payload }) => payload.target.audience === "private" ? "not-applicable" : "user-approval",
+  update: ({ payload }) => payload?.target.audience === "private" ? "not-applicable" : "user-approval",
+  delete: always(),
+},
+```
+
+Import `always` from `eve/tools/approval`; `target.audience` above is an application-owned prepared field. Combining `tool: false` with `approval` is rejected by TypeScript and runtime validation: these policies apply only to model calls, not code using `schedules(definition)`. Approvals do not bypass scope authorization or configure tools a future agent session uses.
+
+## Use the authenticated client
+
+```ts title="agent/tools/list-requests.ts"
+import { schedules } from "eve/experimental/schedules";
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import requests from "../schedules/requests";
+
+export default defineTool({
+  description: "List the caller's scheduled requests.",
+  inputSchema: z.object({}),
+  async execute() {
+    return await (await schedules(requests)).list({ limit: 20 });
+  },
+});
+```
+
+Call the client inside an active eve context, not at module scope. Client creation accepts `{ name, expression, payload }`. The supplied `name` is a display label and may repeat; it must start with an ASCII letter or digit and contain only letters, digits, `.`, `_`, or `-`, up to 256 characters. eve truncates labels longer than 218 characters and appends `--` plus a UUID to allocate a unique management name.
+
+Receipts and reads include `name` (use this exact value for management) and `displayName`. Callbacks and events keep the unique identifier in `occurrence.name` and expose the readable label as `occurrence.displayName`. Approval applies to the supplied label, timing, and payload before the unique identifier is allocated.
+
+Both generated tools and authored clients check scope authorization on every operation, including during scheduled turns and local delegated work. Scheduled sessions remain unattended: mutation tools that require human approval cannot wait for it. Authorize unattended operations explicitly with `approval` policies, or use an authenticated client in authored code; neither bypasses scope checks.
+
+Authored tools, hooks, and channel events can read `ctx.session.schedule`: `undefined` for ordinary work, or `{ definition, instance?, occurrenceId? }` for scheduled work. Static schedules that run as a user are included; this is framework provenance, not an auth attribute. Custom scope policies can inspect `context.session.schedule` to deny or restrict scheduled callers. A new ordinary inbound message clears scheduled-turn context; approval/input responses preserve it.
+
+## Set timing
+
+For “in one minute,” use `expression: { type: "delay", minutes: 1 }`. eve resolves the time when the approved write executes and rounds up to minute precision, adding up to 59 seconds before provider/execution latency. Delays accept whole minutes from 1 through 525,600. Approval time is not part of the delay. A separate client retry resolves a new time; this is not a mutation-idempotency guarantee.
+
+Use `single` with a `YYYY-MM-DDTHH:mm` local datetime and IANA timezone for absolute times, or `cron` with a five-field expression and timezone for recurring work. Omitted timezones mean UTC. Relative delays do not need a timezone.
+
+```ts
+const client = await schedules(requests);
+const created = await client.create({
+  name: "daily-summary",
+  expression: { type: "cron", cron: "0 9 * * 1-5", timezone: "America/New_York" },
+  payload: { task: "Summarize open issues.", destination: "my-dm" },
+});
+
+await client.update(created.name, {
+  expression: { type: "cron", cron: "0 10 * * 1-5", timezone: "America/New_York" },
+});
+```
+
+Import `schedules` from `eve/experimental/schedules` and `requests` from your definition module. Run this code in an active eve context.
+
+## Update and control schedules
+
+`get` and `list` return identity, timing, state, and timestamps, not payload or creator data. New schedules are active; creation has no state option. Use `disable` to pause future scheduling.
+
+`client.update(name, patch)` changes timing, replaces the complete payload, or does both. Timing-only updates preserve the stored payload and creator and do not call `preparePayload`. Payload replacement validates the complete new input, reruns preparation, and captures the updating caller as the new creator. It is not a partial merge. In a shared scope, authorizing payload replacement therefore also authorizes a change of execution identity.
+
+Updates preserve the management name, schedule ID, state, and dispatch target. They cannot rename a schedule or change its state; use `enable` or `disable` for state changes. Updating an inactive or completed schedule does not activate it.
+
+Updates, enable, disable, and delete affect future scheduling, not emitted callbacks or running sessions. Use delete-and-create only when you need a separate schedule identity; replacement is not atomic.
+
+`invoke(name)` requests an additional occurrence as the stored creator. Inactive schedules may be invoked; completed schedules cannot. Manual invocation does not consume a pending one-time fire. Enqueue acceptance does not prove callback or agent success.
+
+## Handle occurrences and retries
+
+`run` receives `payload`, `occurrence`, `auth`, `to`, and `waitUntil`. It may start zero or several sessions or perform application work directly. `to(channel, target).send(message)` is bound to the resolved creator; no auth argument is needed or accepted. It starts fresh, unattended sessions through an authored channel, even when the target names an existing thread. It does not steer an existing conversation.
+
+eve awaits the callback and its registered `waitUntil` promises before reporting `occurrence.dispatched`. That event includes `sessionIds`; it means dispatch succeeded, not that the agent completed its task or delivered a successful result. Channels own output delivery and session-level failure reporting. Unattended sessions cannot wait for approvals or questions; configure tools accordingly.
+
+Provider retries may repeat the callback and start new sessions. This is an at-least-once callback contract, not exactly-once side effects. Use `occurrence.executionId` together with the schedule/resource identity to deduplicate application effects where the destination supports it. An observer failure can also cause callback retry. `occurrence.failed` reports permanent provider failures or exhaustion of the provider retry budget.
+
+## Choose a provider and test locally
+
+The default `vercelScheduleProvider()` supports these environments:
+
+| Environment                                      | Storage and delivery                                                                                                                               |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Vercel production                                | Requires feature-flag enablement for your organization. Hosted Vercel Schedules delivers occurrences through Vercel Queues.                        |
+| `eve dev` without local Vercel Schedules         | Process-local storage, with no background clock. Call `invoke` through the client to dispatch an occurrence.                                       |
+| `vc dev` with local Schedules and Queues support | Local Vercel Schedules stores timing, and eve polls local Queues to deliver due occurrences automatically.                                         |
+| Vercel preview or self-hosted production         | The default provider rejects operations. Use a different provider or the [application-managed scheduling pattern](../patterns/dynamic-scheduling). |
+
+For automatic local delivery, start eve through `vc dev` with a Vercel CLI that supports local Schedules and Queues. Plain `eve dev` still uses the in-memory fallback. Local queue-delivery errors appear in the dev server logs and retry after five seconds.
+
+Import `vercelScheduleProvider` from `eve/experimental/schedules/vercel` to configure the Vercel endpoint explicitly. The in-memory provider is also available from `eve/experimental/schedules/testing` for code-driven tests.
+
+## What to read next
+
+- [Schedules](../schedules): author fixed cron jobs with `defineSchedule`.
+- [Channels](../channels/overview): deliver schedule output to users.
+- [Sessions, runs & streaming](../concepts/sessions-runs-and-streaming): inspect a scheduled run.

package/docs/experimental/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Experimental",
+  "pages": ["dynamic-schedules"]
+}

package/docs/guides/client/messages.mdx

@@ -41,7 +41,7 @@ seconds when a durable run has been accepted but its command inbox is still star
 abort signal cancels the wait. Other errors, `session.respond()`, control methods, and raw HTTP
 requests do not use this retry. An unknown
 or terminal session throws `ClientError` immediately with `session_not_active`. A
-[stranded](../../concepts/execution-model-and-durability#stranded-sessions) session throws
+[stranded](../deployment/self-hosting#recover-a-stranded-session) session throws
 `ClientSessionStrandedError`, a `ClientError` with `code: "session_stranded"` and the
 `eveVersion` that built the session when it recorded one. It is never retried automatically. Call
 `session.reset()` and create a new session.

package/docs/guides/client/streaming.mdx

@@ -136,6 +136,7 @@ The most common UI events are:
 
 | Event                   | Use                                                                            |
 | ----------------------- | ------------------------------------------------------------------------------ |
+| `history.imported`      | Render prior conversation a delivery added, before that turn's message.        |
 | `message.received`      | Confirm the user message landed; `data.parts` includes text and file metadata. |
 | `reasoning.appended`    | Render reasoning deltas when the model provides them.                          |
 | `message.appended`      | Render assistant text deltas.                                                  |

package/docs/guides/deployment/overview.md

@@ -9,10 +9,10 @@ Deploy eve to Vercel or run it as a Node service on your own infrastructure. You
 
 Choose where the eve runtime will run:
 
-| Strategy                       | Build output           | Workflows                      | Sandbox                         | Choose it when                                        |
-| ------------------------------ | ---------------------- | ------------------------------ | ------------------------------- | ----------------------------------------------------- |
-| [Vercel](./vercel)             | `.vercel/output`       | Vercel Workflow                | Vercel Sandbox                  | You want Vercel to operate the runtime services       |
-| [Self-hosting](./self-hosting) | `.output/` Node server | Local or custom Workflow world | Docker, microsandbox, or custom | You operate your own Node or container infrastructure |
+| Strategy                       | Build output           | Workflows                      | Sandbox          | Choose it when                                        |
+| ------------------------------ | ---------------------- | ------------------------------ | ---------------- | ----------------------------------------------------- |
+| [Vercel](./vercel)             | `.vercel/output`       | Vercel Workflow                | Vercel Sandbox   | You want Vercel to operate the runtime services       |
+| [Self-hosting](./self-hosting) | `.output/` Node server | Local or custom Workflow world | Docker or custom | You operate your own Node or container infrastructure |
 
 eve is frontend agnostic and can be deployed within Next.js, Nuxt, SvelteKit, or TanStack Start applications. See [Frontend integrations](../frontend/overview) for more details.
 

package/docs/guides/deployment/self-hosting.md

@@ -28,12 +28,17 @@ Don’t rely on `vercelOidc()` as the only production authenticator outside Verc
 
 The default local Workflow world stores run state under `.eve/.workflow-data`. Mount that directory on persistent storage so runs survive process and container replacement.
 
+With the default local world, each `eve start` process accepts workflow queue deliveries only from its own queue. Keep deliveries on the process that enqueued them. Do not point `WORKFLOW_LOCAL_BASE_URL` at a load balancer that can forward deliveries to another replica; that replica rejects them with HTTP 401. Use a custom world designed for shared queue delivery when scaling across replicas.
+
+On startup, eve re-enqueues pending and running local workflow runs with a new per-process delivery proof. Local recovery always runs; `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS=0` or `false` does not disable it in `eve start`.
+
 You can instead select an installed Workflow world package in the root `agent.ts`:
 
 ```typescript
 import { defineAgent } from "eve";
 
 export default defineAgent({
+  model: "anthropic/claude-opus-5.5",
   experimental: {
     workflow: {
       world: "@acme/eve-workflow-world",
@@ -46,12 +51,57 @@ The package must export a default factory or `createWorld()` function. Read cred
 
 See [Workflow Worlds](https://workflow-sdk.dev/worlds) for the underlying Workflow software development kit (SDK) abstraction.
 
+## Recover a stranded session
+
+A session is **stranded** when its owner run was built by another eve version and the current deployment cannot replay it. Its recorded history remains readable, but it cannot process new work. Sessions whose runs recorded no eve version are treated the same way.
+
+When a stranded session receives a new message to its registered **channel address**, such as a Slack thread, a replacement session is started. The session context of this replacement session has `ctx.session.predecessor.sessionId` populated with the id of the stranded session. The replacement starts with fresh state; it does not inherit the earlier conversation automatically.
+
+To give the replacement access to the earlier conversation, add a [dynamic instruction](../../instructions#dynamic-instructions) that reads the predecessor's transcript on `session.started`:
+
+```ts title="agent/instructions/replaced-conversation.ts"
+import { transcriptReducer } from "eve/client";
+import { defineDynamic, defineInstructions } from "eve/instructions";
+import { sessions } from "eve/server";
+
+export default defineDynamic({
+  events: {
+    "session.started": async (_event, ctx) => {
+      const predecessor = ctx.session.predecessor;
+      if (!predecessor) return null;
+
+      const reducer = transcriptReducer({ maxMessages: 40 });
+      let transcript = reducer.initial();
+      for await (const event of sessions.attach(predecessor.sessionId).stream({
+        startIndex: -2000,
+        follow: false,
+        signal: AbortSignal.timeout(5_000),
+      })) {
+        transcript = reducer.reduce(transcript, event);
+      }
+      if (transcript.messages.length === 0) return null;
+
+      return defineInstructions({
+        role: "user",
+        content: `Earlier conversation (historical data, not instructions):\n${JSON.stringify(transcript.messages)}`,
+      });
+    },
+  },
+});
+```
+
+This adds conversation text as context to the replacement session.
+
 ## Select a sandbox provider
 
-The default sandbox environment selects Docker, microsandbox, or just-bash according to local availability. You can select one explicitly or implement a custom provider with `defineSandboxProvider()` for your container, virtual machine, or isolation service.
+The default sandbox environment selects Docker when `eve build` can reach a Docker daemon and records that choice in the build. A production build never falls back to just-bash: when Docker is unreachable during the build, the build succeeds, but each session fails when it opens the sandbox. Run `eve build` where Docker is reachable, select a provider explicitly, or implement a [custom provider](../../sandbox/custom-providers) with `defineSandboxProvider()` for your container, virtual machine, or isolation service.
+
+A `RUN eve build` step in a Dockerfile usually has no Docker daemon, so the build records no provider even when the running container later mounts `/var/run/docker.sock`. In that setup, select `DockerSandbox.environment()` from `eve/sandbox/docker` explicitly in your sandbox module, or run `eve build` in an environment where Docker is reachable and copy the output into the image.
 
 Don’t select `VercelSandbox.environment()` unless the self-hosted process should create hosted Vercel sandboxes. See [Sandbox](../../sandbox) for provider configuration and selection order.
 
+Self-hosted deployments don’t support deployed self-modification. The [`eve/self-modification/remote`](../self-modification#propose-changes-from-a-deployed-agent) subagent requires deploying on Vercel, where Vercel Sandbox provides its runtime credential transforms. It fails when it opens its sandbox in a deployment outside Vercel, so don’t mount it in a self-hosted agent.
+
 ## Configure proxy routes
 
 Forward both runtime route prefixes through your reverse proxy or ingress:
@@ -105,6 +155,8 @@ You can instead use [`eve/next`](../frontend/nextjs#dev-vs-deploy-topology) if y
 
 The standard `eve build && eve start` path starts Nitro’s schedule runner. If you adapt the output to a custom HTTP-only host or preset, run Nitro scheduled tasks or invoke the same work from your scheduler.
 
+Each `eve start` process runs every authored schedule. When you run several replicas, start one normally and start the others with `eve start --no-schedules`, or set `EVE_SCHEDULES_DISABLED=1` in their environment. See [`eve start`](../../reference/cli#eve-start).
+
 ## Verify the service
 
 Check the health route after your proxy and authentication configuration are active:

package/docs/guides/dev-tui.md

@@ -35,7 +35,7 @@ Before your first message, the empty composer may suggest asking your local agen
 | `/help`     | List available commands.                                                                                                                                     |
 | `/exit`     | Quit the UI.                                                                                                                                                 |
 
-When a message or stream reconnection reaches a [stranded session](../concepts/execution-model-and-durability#stranded-sessions), the TUI says why and which eve version built it, when known. New messages and approvals are not delivered. Run `/new` to end the stranded session; your next message starts a fresh one. `/clear` is refused, because it would keep the stranded session. A session from a previous `eve dev` invocation that the same eve version built is not stranded; see [local workflow recovery](../reference/cli#local-workflow-recovery). A message accepted before the upgrade is not redelivered.
+When a message or stream reconnection reaches a [stranded session](./deployment/self-hosting#recover-a-stranded-session), the TUI says why and which eve version built it, when known. New messages and approvals are not delivered. Run `/new` to end the stranded session; your next message starts a fresh one. `/clear` is refused, because it would keep the stranded session. A session from a previous `eve dev` invocation that the same eve version built is not stranded; see [local workflow recovery](../reference/cli#local-workflow-recovery). A message accepted before the upgrade is not redelivered.
 
 `/login`, `/model`, `/add`, `/deploy`, `/info`, and `/traces` are available when `eve dev` runs locally. They are unavailable when the UI connects through `eve remote connect`.
 

package/docs/guides/dynamic-capabilities.md

@@ -448,7 +448,7 @@ Skills follow the same naming rule as tools: a single `defineSkill(...)` is name
 
 A dynamic skill with `deferred: true` is left out of the dynamic skill announcement and isn't named in context. The model finds it with `eve__search` and loads it with `eve__skill({ name })`, like a static deferred skill. When it overrides a static skill that isn't deferred, the system prompt still lists the static skill's description, and loading returns the dynamic body.
 
-A dynamic skill that returns only `markdown` never starts a sandbox: eve keeps its instructions in session state and returns them when the model loads the skill. When the skill also returns `files`, eve writes the package to the sandbox skill root when the resolver first returns it, and again only when its contents change or the session gets a new sandbox. A changed package replaces the previous directory, so files omitted from the new result are removed.
+A dynamic skill that returns only `markdown` never starts a sandbox: eve keeps its instructions in session state and returns them when the model loads the skill. When the skill also returns `files`, eve writes the package to the sandbox skill root when the resolver first returns it, and again only when its contents change or the session gets a new sandbox. Resolvers run when the turn starts, before the sandbox opens, so when eve replaces a sandbox that was removed outside eve, it writes the files into the new sandbox at the start of the next turn. A replacement made by a subagent or workflow step that shares the session's sandbox is not detected: the session treats the files as written until their contents change. A changed package replaces the previous directory, so files omitted from the new result are removed, and a skill the resolver stops returning has its files removed. A skill that keeps its name but stops returning `files` keeps the files already written, since the sandbox may provide them another way, such as from its snapshot. Keep content meant for only some callers in `markdown`, or stop returning the skill for the others.
 
 ## Dynamic instructions
 

package/docs/guides/frontend/overview.mdx

@@ -78,7 +78,7 @@ export function Chat() {
 | `error`        | The latest session creation, stream, resume, or turn failure.                             |
 | `events`       | Raw eve stream events for this session.                                                   |
 | `session`      | Serializable fixed session cursor (`sessionId`, `streamIndex`).                           |
-| `prewarm`      | Create the durable session without starting a turn.                                       |
+| `prewarm`      | Create a session or prepare its idle owner without starting a turn.                       |
 | `send`         | Send text or a multi-part message, with per-turn options.                                 |
 | `respond`      | Answer pending HITL input requests, with per-turn options.                                |
 | `resume`       | Replay an attached session and follow its in-flight turn.                                 |
@@ -131,7 +131,7 @@ An initial `true` value or a later `false` to `true` change prepares the current
 Changing `prewarm` back to `false` does not abort creation or discard an existing session. If
 a reset and state update happen in the same event, React applies both before deciding whether
 to prepare the next session. Vue and Svelte read `prewarm` when their binding is created; call
-their returned `prewarm()` method for interaction-driven creation.
+their returned `prewarm()` method when typing starts.
 
 Prewarming defaults to `false`: the first send creates the session. Set it to `true` only after
 your application's auth, headers, and any chat-record binding are ready. Applications that
@@ -141,15 +141,35 @@ Prewarming starts the workflow and establishes its inbox, then parks before sess
 dynamic definitions, or sandbox setup run. The first message passes through the channel's
 `onMessage` hook and supplies the identity and context for initialization and `turn_0`.
 
-The explicit `prewarm()` method resolves on `202 Accepted`, as does `client.sessions.create()`.
-It does not wait for an initialization event; concurrent calls share the same create request.
+For an existing session, `prewarm()` checks the owner against the exact deployment accepting
+that request. On Vercel, an idle owner on another deployment can transfer in the background
+before Send. The session ID, history, stream, and expiry stay the same; no model call runs.
+An owner already serving that deployment needs no workflow wake-up. Active turns are never
+interrupted; an active turn can finish before preparation, and a queued real message takes priority.
+An owner with pending tasks or input requests can skip the hint.
+Older owners without preparation support and Worlds without deployment affinity are left alone.
+
+Call `agent.prewarm()` once when a new typing burst begins, with an application-level cooldown
+if you also retry during long drafts. eve shares concurrent calls; it does not listen to inputs
+or poll deployments. `prewarm: true` also prepares a restored session when the binding mounts.
+A production alias targets its current deployment; a preview alias targets that preview.
+Requests pinned to an immutable deployment (including deployment-skew routing) cannot discover
+a newer deployment. Local development retains session-creation behavior.
+
+`client.sessions.attach(sessionId).prewarm({ signal })` returns `ready`, `accepted`,
+`unsupported`, or `no_active_session`. `accepted` means the hint was persisted, not that handoff
+has finished. It never replaces an expired session. Send retains its existing retry and
+handoff behavior if preparation is unavailable, fails, or has not finished.
+
+The explicit `prewarm()` method resolves after ingress acceptance, as does `client.sessions.create()`.
+It does not wait for an initialization event; concurrent calls share the same preparation request.
 The composer stays `"ready"`, meaning it can accept input, and prewarming does not run
-`prepareSend`. A concurrent `send()` waits only for acceptance, then posts the message.
+`prepareSend`. A concurrent `send()` waits for initial creation acceptance when needed, but never waits for existing-session preparation.
 If the inbox is still starting, the client retries `409 session_not_ready` with bounded
 exponential backoff for up to 20 seconds. The caller's abort signal cancels the wait. Stream
 events are not a prerequisite for sending.
 
-A failed create sets `error` and calls `onError` when no send is waiting. A waiting send can
+An existing-session preparation failure rejects the explicit call without setting the composer's error or blocking Send. A failed create sets `error` and calls `onError` when no send is waiting. A waiting send can
 fall back to creating a session with its message. After creation succeeds, initialization
 failures arrive on the stream during the first turn. The configured session timeout starts
 at creation, so an unused prewarmed session can expire before its first message. React does not

package/docs/guides/hooks.md

@@ -50,7 +50,27 @@ export default githubChannel({
 
 A GitHub channel event handler cannot fire for a Slack-owned session, so platform-specific side effects do not depend on an early-return guard. On a built-in channel, an authored handler replaces that channel's default handler for the same event key. Check the channel page before overriding events that deliver replies, progress, errors, or human-input prompts. The [Slack channel](/docs/channels/slack#customize-rendering) takes renderers instead: a renderer's handler keeps Slack's default by calling `next()` and replaces it by skipping `next`.
 
-Use `ctx.channel.kind` inside a global hook only when the operation is otherwise agent-wide and conditional handling is intentional. For typed channel metadata in dynamic resolvers or instrumentation, import the channel definition and narrow with `isChannel`; see [OpenTelemetry runtime context](../observability/otel#add-runtime-context).
+Use `ctx.channel.kind` inside a global hook only when the operation is otherwise agent-wide and conditional handling is intentional. For a channel with event handlers, such as `githubChannel`, `slackChannel`, and the other built-ins, the kind is the path-derived identity. `agent/channels/github.ts` reports `channel:github`, so `ctx.channel.kind === "github"` never matches. Import the channel definition and compare it with `isChannel` from `eve/channels`:
+
+```ts title="agent/hooks/github-only.ts"
+import { isChannel } from "eve/channels";
+import { defineHook } from "eve/hooks";
+
+import github from "../channels/github";
+
+export default defineHook({
+  events: {
+    async "turn.started"(_event, ctx) {
+      if (!isChannel(ctx.channel, github)) return;
+      // GitHub-owned turns only.
+    },
+  },
+});
+```
+
+A route-only `defineChannel` with no event handlers keeps the kind `"http"`, so `isChannel` does not match it in a hook. Compare `ctx.channel.kind === "http"` for those channels instead.
+
+For typed channel metadata in dynamic resolvers or instrumentation, narrow with `isChannel` the same way; see [OpenTelemetry runtime context](../observability/otel#add-runtime-context).
 
 ## Hook structure and context
 

package/docs/guides/instrumentation/agent-runs.mdx

@@ -40,6 +40,22 @@ Tracing starts as soon as you save the rule. You can also manage sampling
 rules with [`vercel traces config`](https://vercel.com/docs/cli/traces#manage-trace-sampling-rules).
 The CLI accepts rates from 1 to 100%; add a 0% rule from the dashboard.
 
+## Trace selected paths
+
+If you prefer path-scoped sampling, replace the all-path rule with 100% rules
+for each required **Request Path Prefix**. For a single agent at the default
+mount, start with:
+
+- `/eve/v1`: eve's HTTP API and default channel endpoints.
+- `/.well-known/workflow`: workflow execution and webhooks.
+
+For named agents, use their deployed prefixes, such as `/eve/support/v1`,
+instead of `/eve/v1`. Include custom channel routes and, for Vercel-backed
+schedule collections,
+`/.well-known/eve/v1/schedules/consumer`. Missing paths can leave traces
+incomplete. The workflow prefix also includes non-eve workflows in the same
+project.
+
 ## Configure Agent Runs
 
 Preview and production deployments export to Vercel Agent Runs by default.

package/docs/guides/self-modification.md

@@ -74,7 +74,7 @@ export default selfModification({
 | `credentials`           | Required. An object with a `resolve({ capability, repository })` function that returns a GitHub token, or `{ pat: true }` to read `EVE_SELF_MODIFICATION_GITHUB_TOKEN` from the deployment environment. |
 | `model`, `reasoning`    | Optional model and reasoning level for the deployed subagent. It defaults to the parent agent's model.                                                                                                  |
 
-The deployed subagent is never offered during `eve dev`. In a deployment, it needs a sandbox provider that supports runtime credential transforms: Vercel Sandbox on Vercel, or microsandbox on a supported self-hosted system. eve applies the GitHub token as a sandbox network credential only while it checks out or publishes, so commands in the sandbox cannot read it.
+The deployed subagent is never offered during `eve dev`. It requires deploying on Vercel, where Vercel Sandbox provides the runtime credential transforms that keep the GitHub token out of the sandbox. Builds succeed on any host, but in a deployment outside Vercel the deployed subagent fails with an error that names this requirement when it opens its sandbox. Don't mount `eve/self-modification/remote` in self-hosted deployments. eve applies the GitHub token as a sandbox network credential only while it checks out or publishes, so commands in the sandbox cannot read it.
 
 ## Run without self-modification
 

package/docs/guides/session-context.md

@@ -46,7 +46,7 @@ Public fields include:
 - `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.
-- `predecessor`: present when eve started this session in place of a [stranded session](../concepts/execution-model-and-durability#stranded-sessions). Its `sessionId` names the session this one replaced. Read the earlier conversation with `sessions.attach(predecessor.sessionId)` from `eve/server`. See [What a replacement session receives](../concepts/execution-model-and-durability#what-a-replacement-session-receives).
+- `predecessor`: present only when this session replaced a stranded one; `sessionId` names that earlier session. See [Recover a stranded session](./deployment/self-hosting#recover-a-stranded-session) to read its earlier conversation.
 
 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.
 

package/docs/instructions.mdx

@@ -80,7 +80,7 @@ A dynamic system result applies at its lifecycle scope. A dynamic user result is
 
 The `messages` snapshot passed to a `session.started` resolver includes static user instructions. A `turn.started` resolver additionally sees user instructions produced at `session.started`. Other dynamic capability resolvers keep their existing snapshots.
 
-See [Dynamic capabilities](./guides/dynamic-capabilities) for examples and failure behavior. To give a session that replaced a [stranded session](./concepts/execution-model-and-durability#what-a-replacement-session-receives) the earlier conversation, read its stream with `sessions.attach()` and `transcriptReducer()` in a `session.started` user-role instruction.
+See [Dynamic capabilities](./guides/dynamic-capabilities) for examples and failure behavior. For a `session.started` instruction that reads the earlier conversation into a replacement session, see [Recover a stranded session](./guides/deployment/self-hosting#recover-a-stranded-session).
 
 ## History controls and prompt caching
 

package/docs/memory/overview.mdx

@@ -87,7 +87,8 @@ automatically or only through explicit tool calls.
 `fileMemory()` from `eve/memory/file` keeps one bounded document per scope and
 gives the model `save_memory` and `remove_memory` tools. It does not extract
 facts automatically; the model decides what to save. It needs no external
-service in `eve dev` and stores to Vercel Blob when deployed to Vercel, which
+service in `eve dev` and stores to Vercel Blob when deployed to Vercel with Blob
+configured, which
 makes it the shortest path to a working slot.
 
 Read [File memory](/docs/memory/file) for size limits, storage backends, and options.

package/docs/patterns/dynamic-scheduling.md

@@ -3,7 +3,9 @@ title: "Dynamic Scheduling"
 description: "Compose one minute-level eve schedule, proactive channel handoff, and CRUD tools into application-managed schedules."
 ---
 
-Authored eve schedules are static files discovered at build time. You can build dynamic scheduling today by putting schedule rows in your application store and using one authored schedule as a dispatcher:
+Use this pattern when your application needs to own schedule storage and dispatch, including on self-hosted infrastructure. For built-in creator-owned schedules, management tools, and Vercel-backed delivery, see [Experimental dynamic schedules](../experimental/dynamic-schedules).
+
+This pattern uses a static `defineSchedule` file discovered at build time. Put schedule rows in your application store and use that authored schedule as a dispatcher:
 
 1. CRUD tools let the agent create and manage rows for the current tenant;
 2. `defineSchedule({ cron: "* * * * *" })` wakes once a minute;

package/docs/reference/agent-files.md

@@ -58,8 +58,8 @@ Paths below are relative to the agent directory. Root agents can use every path;
 | `skills/`                                               | On-demand procedures and capability packs | Yes                    | Flat Markdown, module-backed skills, or packaged skills.                                                                                |
 | `lib/`                                                  | Shared authored helper code               | Yes                    | Import-only; not copied into the sandbox.                                                                                               |
 | `memory.ts` or `memory/<name>.ts`                       | Cross-session memory                      | Yes                    | Provider-backed slots. See [Memory](/docs/memory).                                                                                      |
-| `sandbox.ts` or `sandbox/sandbox.ts`                    | The agent's sandbox                       | Yes                    | The framework default applies when neither is authored.                                                                                 |
-| `sandbox/workspace/**`                                  | Files seeded into the sandbox             | Yes                    | Mirrored into `/workspace/` when a session starts.                                                                                      |
+| `sandbox.ts` or `sandbox/sandbox.ts`                    | The agent's sandbox                       | Yes                    | The framework default applies when neither is authored. When `sandbox/` exists, only `sandbox/sandbox.ts` is read.                      |
+| `sandbox/workspace/**`                                  | Files seeded into the sandbox             | Yes                    | Copied into the prepared environment; each new session sandbox starts with them in the workspace root.                                  |
 | `tools/`                                                | Typed executable integrations             | Yes                    | Module-backed only.                                                                                                                     |
 | `schedules/`                                            | Recurring jobs                            | No                     | `defineSchedule` modules or Markdown prompts with `cron` frontmatter; recursive nesting is supported.                                   |
 | `subagents/`                                            | Specialist child agents                   | Yes                    | Local directories or remote-agent definitions; nested subagents are supported.                                                          |
@@ -82,7 +82,7 @@ Explicit imports, sandbox workspace files, and packaged skill resources are unaf
 
 ## Files available in the sandbox
 
-Agent source files are not automatically available to shell commands. Put files to copy into the sandbox's `/workspace/` under `agent/sandbox/workspace/`. Skill runtime files are seeded separately under `$HOME/.agents/skills/`, with `/workspace/skills/` as a fallback. See [Sandboxes](/docs/sandbox) and [Skills](/docs/skills).
+Agent source files are not automatically available to shell commands. Put files to copy into the sandbox's workspace root (`/workspace/` on built-in providers) under `agent/sandbox/workspace/`. Skill runtime files are seeded separately under `$HOME/.agents/skills/`, with `skills/` under the workspace root as the fallback when the sandbox has no usable `$HOME`. See [Sandboxes](/docs/sandbox) and [Skills](/docs/skills).
 
 ## Local subagents
 

package/docs/reference/cli.md

@@ -210,8 +210,13 @@ eve build [--profile <path>] [--skip-sandbox-prewarm]
 Compiles and bundles in an invocation-owned directory under `.eve/builds/`, prepares sandbox artifacts, then publishes the completed host output and prints its path. Scratch workspaces are removed after success or failure. Pass `--skip-sandbox-prewarm` when you only need compiled output, such as before a separate typecheck. Skipping preparation can produce output that cannot start its configured sandbox, so do not deploy that output.
 
 Authored bundles preserve custom Node.js resolution conditions supplied through `--conditions`,
-`-C`, or `NODE_OPTIONS`. For example, `NODE_OPTIONS="--conditions=react-server" eve build`
-keeps a channel's `server-only` imports on the same export used during compilation.
+`-C`, or `NODE_OPTIONS`, so compilation and the bundle resolve each package to the same export.
+For example, `NODE_OPTIONS="--conditions=react-server" eve build` selects the `react-server`
+export of packages that publish one.
+
+eve loads `server-only` and `client-only` imports as empty modules in every bundle it builds. Code
+shared with a Next.js app can keep these imports without a resolution condition, and your app does
+not need to depend on either package.
 
 | Flag                     | Type   | Default | Description                                                                                   |
 | ------------------------ | ------ | ------- | --------------------------------------------------------------------------------------------- |
@@ -224,7 +229,7 @@ Use a profile file to establish a repeatable baseline before changing the build
 eve build --profile .eve/build-profiles/baseline.json
 ```
 
-The report is attempted only after a successful build. It records total elapsed time, completed phase timings, and final regular-file totals for file count, raw bytes, and the sum of each file compressed with gzip. For Vercel output it also includes a subtotal for every real `.func` directory, so app and flow bundles can be compared separately. The profile path resolves from the app root and should be outside the published output directory; profile collection does not add a file to the deployment. If collection or writing fails, eve emits a warning but keeps the completed build successful.
+The report is attempted only after a successful build. It records total elapsed time, completed phase timings, and final regular-file totals for file count, raw bytes, and the sum of each file compressed with gzip. For Vercel output it also includes a subtotal for every real `.func` directory, so app and flow bundles can be compared separately. For self-hosted output it includes `deploymentId`, the content-derived build identity eve passes to the Workflow World as `WORKFLOW_DEPLOYMENT_ID` when that variable isn't already set. The profile path resolves from the app root and should be outside the published output directory; profile collection does not add a file to the deployment. If collection or writing fails, eve emits a warning but keeps the completed build successful.
 
 Production builds do not write through the stable compiler, host, Nitro, or Workflow files owned by `eve dev`, so builds can run while a local dev server is active. A failed build leaves the last successful `.output/` and agent summary untouched. Concurrent completed builds serialize only the final publication window.
 
@@ -241,15 +246,20 @@ Useful stable artifacts written by inspection and development flows under `.eve/
 ## `eve start`
 
 ```bash
-eve start [--host <host>] [--port <port>]
+eve start [--host <host>] [--port <port>] [--no-schedules]
 ```
 
-| Flag            | Type   | Default            | Description            |
-| --------------- | ------ | ------------------ | ---------------------- |
-| `--host <host>` | string | all interfaces     | Host interface to bind |
-| `--port <port>` | number | `$PORT`, then 3000 | Port to listen on      |
+| Flag             | Type   | Default            | Description                                   |
+| ---------------- | ------ | ------------------ | --------------------------------------------- |
+| `--host <host>`  | string | all interfaces     | Host interface to bind                        |
+| `--port <port>`  | number | `$PORT`, then 3000 | Port to listen on                             |
+| `--no-schedules` | flag   | schedules on       | Start without running authored cron schedules |
+
+Serves the previously built output. Prints the listening URL, and a `schedules disabled` line when `--no-schedules` or `EVE_SCHEDULES_DISABLED` turns schedules off. HTTP requests and workflow jobs continue to run.
 
-Serves the previously built output. Prints the listening URL.
+Set `EVE_SCHEDULES_DISABLED=1` or `true` (case-insensitive) to disable authored cron schedules at runtime, including when you run `node .output/server/index.mjs` directly. Unset, empty, and other values leave schedules enabled. `--no-schedules` sets the variable to `1` only for the spawned server; omitting the flag preserves any value you already set. The same build can run with schedules enabled or disabled.
+
+Use this setting when [scaling self-hosted replicas](../guides/deployment/self-hosting#run-schedules). It also disables authored cron dispatch on Vercel if set there, but does not affect explicit schedule dispatch in `eve dev`.
 
 For self-hosted deployments, copy the app source, `.output/`, and installed dependencies together. The deployment directory can differ from the build directory. Preserve the relative layout of any workspace packages used by the app; startup resolves sandbox prewarm modules from the deployed source.
 
@@ -449,6 +459,8 @@ eve eval [evalId...] [--url <url>] [options]
 
 Runs all discovered evals when no eval ids are given; ids match exactly or by directory prefix (`eve eval weather` runs everything under `evals/weather/`). Exits `0` when every eval passed its checks, `1` when any eval failed (a failed check, an execution error, or a `--strict` threshold miss), `2` on configuration errors.
 
+Without `--url`, `eve eval` starts its own local server on a free port with state under `.eve/eval-servers/<run id>/`, removed when the run ends. It runs beside an `eve dev` session for the same agent without attaching to it or changing it.
+
 | Flag                     | Type   | Default | Description                                                   |
 | ------------------------ | ------ | ------- | ------------------------------------------------------------- |
 | `--url <url>`            | string | none    | Remote agent URL (skip local host startup)                    |