eve 0.25.3 → 0.26.1

package/docs/guides/frontend/nuxt.mdx

@@ -96,4 +96,4 @@ For a public demo, use `none()` (also from `eve/channels/auth`) to skip authenti
 
 - [`useEveAgent` (Vue)](./use-eve-agent-vue): the composable API
 - [Auth & route protection](../auth-and-route-protection)
-- [Deployment](../deployment)
+- [Deployment](../deployment/overview)

package/docs/guides/frontend/overview.mdx

@@ -193,10 +193,7 @@ const agent = useEveAgent({
 });
 ```
 
-Two more options tune turn behavior:
-
-- `optimistic` (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.
-- `maxReconnectAttempts` (default `3`): stream reconnection budget per turn.
+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.
 
 ## Custom reducer
 
@@ -256,7 +253,7 @@ const agent = useEveAgent({
 
 Store the full `session` object (`sessionId`, `continuationToken`, `streamIndex`), not a single field. The session cursor lets eve continue the durable conversation; the event log lets your UI render historical messages without replaying the whole stream. A database-backed chat app should usually persist stream events as they arrive with `onEvent` and then save a final snapshot in `onFinish`.
 
-For multiple chat threads, keep one saved event log and session cursor per thread. `agent`, `host`, `reducer`, `session`, `initialEvents`, `initialSession`, `auth`, `headers`, `maxReconnectAttempts`, and `optimistic` are read when the hook creates its store, so remount the chat component when switching threads, for example with `key={chat.id}`.
+For multiple chat threads, keep one saved event log and session cursor per thread. `agent`, `host`, `reducer`, `session`, `initialEvents`, `initialSession`, `auth`, `headers`, and `optimistic` are read when the hook creates its store, so remount the chat component when switching threads, for example with `key={chat.id}`.
 
 If the user can refresh or navigate immediately after pressing send, create your app-level chat row and store the pending user message before calling `send()`. After the request starts, persist the session state as soon as it contains a `sessionId`, then reconnect an interrupted in-flight turn with `session.stream({ startIndex: savedEvents.length })` from the lower-level client.
 

package/docs/guides/frontend/sveltekit.mdx

@@ -108,4 +108,4 @@ For a public demo, use `none()` (also from `eve/channels/auth`) to skip authenti
 
 - [`useEveAgent` (Svelte)](./use-eve-agent-svelte): the binding API
 - [Auth & route protection](../auth-and-route-protection)
-- [Deployment](../deployment)
+- [Deployment](../deployment/overview)

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

@@ -167,10 +167,7 @@ const agent = useEveAgent({
 });
 ```
 
-Two more options tune turn behavior:
-
-- `optimistic` (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.
-- `maxReconnectAttempts` (default `3`): stream reconnection budget per turn.
+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.
 
 ## Custom reducer
 

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

@@ -180,10 +180,7 @@ const agent = useEveAgent({
 });
 ```
 
-Two more options tune turn behavior:
-
-- `optimistic` (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.
-- `maxReconnectAttempts` (default `3`): stream reconnection budget per turn.
+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.
 
 ## Custom reducer
 

package/docs/guides/instrumentation.md

@@ -138,7 +138,7 @@ Per-turn usage tags are written on each step of a turn, accumulating cumulative
 
 Tag writes are best-effort: a failure is logged once per process and then swallowed, so a broken tag emit never breaks the agent.
 
-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 [Deployment](./deployment#view-runs-in-the-dashboard) for enablement. Agent Runs is separate from the OpenTelemetry export above. Use OTel when you want spans in Braintrust, Datadog, or another third-party backend.
+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, 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.
 

package/docs/reference/cli.md

@@ -1,6 +1,6 @@
 ---
 title: "CLI"
-description: "Reference for every eve CLI command: init, info, build, start, dev, link, deploy, eval, channels, and extension."
+description: "Reference for every eve CLI command: init, info, build, start, dev, logs, link, deploy, eval, channels, and extension."
 ---
 
 The `eve` binary (`bin: eve`) runs from your app root, and every command first loads `.env`/`.env.local` from that root. Running `eve` with no command runs `eve dev`.
@@ -15,6 +15,8 @@ The `eve` binary (`bin: eve`) runs from your app root, and every command first l
 | `eve start`                   | Serve the built `.output/` app; prints the listening URL                                                                                              |
 | `eve dev`                     | Start the local dev server and open the terminal UI                                                                                                   |
 | `eve dev <url>`               | Connect the UI to an existing server URL (e.g. a remote deployment) instead of booting a local server                                                 |
+| `eve logs [logid]`            | Print an `eve dev` diagnostic log (the most recent when `logid` is omitted)                                                                           |
+| `eve logs ls`                 | List `eve dev` diagnostic logs, most recent first                                                                                                     |
 | `eve link`                    | Link the directory to a Vercel project and pull AI Gateway credentials                                                                                |
 | `eve deploy`                  | Deploy the agent to Vercel production (links first if needed)                                                                                         |
 | `eve eval`                    | Run evals against the local app or a remote target                                                                                                    |
@@ -173,6 +175,26 @@ Local dev records the last ready URL per resolved app root in `.eve/dev-server-s
 
 Local dev keeps immutable runtime source snapshots under `.eve/dev-runtime/snapshots/` so in-flight turns hold a consistent code revision while new turns pick up rebuilds. The terminal REPL keeps its logical session across successful rebuilds, so the next turn continues the conversation on the latest generation; use `/new` to start a fresh session. After a generation is superseded, `eve dev` retains it for at least 30 minutes and also retains the five most recently superseded generations, regardless of the configured Workflow World. The active generation is never pruned. Old runtime snapshots and local sandbox templates are pruned in the background. For manual cleanup, stop `eve dev` before deleting `.eve/dev-runtime/snapshots/` or `.eve/sandbox-cache/local/templates/`. A turn that remains unfinished beyond the automatic retention window can no longer resume after its generation is pruned.
 
+## `eve logs`
+
+```bash
+eve logs            # print the most recent diagnostic log
+eve logs ls         # list logs, most recent first
+eve logs <logid>    # print a specific log
+eve logs --dump     # prepend the log's environment dump
+eve logs --events   # interleave session events from the local workflow store
+```
+
+Each interactive `eve dev` process writes a private diagnostic log under `.eve/logs/` capturing stderr, stdout (including sandbox and rebuild lines), tool failures, workflow errors, and eve framework log records — regardless of what the transcript shows. The file is JSON Lines — every line is one JSON record with `at` and `source` fields. `eve logs` reads those files back.
+
+A log id is the file name without `.log` (for example `dev-2026-07-15T12-00-00.000Z-123`). `eve logs <logid>` also accepts the file name, the `.eve/logs/...` path printed in the dev transcript, or any unambiguous prefix of the id with or without the `dev-` lead — so `eve logs 2026-07-15` works when a single log matches. An ambiguous prefix fails and lists the candidates.
+
+`eve logs` prints nothing but records — no path banner on either stream — so `eve logs 2>&1 | jq -c .` always parses. Discover ids and file paths with `eve logs ls`; `eve logs ls --json` emits a machine-readable array with `id`, `path`, `startedAt`, and `sizeBytes`.
+
+`eve logs --events` resolves session events (`session.started`, `turn.failed`, message deltas, …) from the local workflow store (`.eve/.workflow-data`) at query time and interleaves them into the output by timestamp as `source: "event"` records — the log file itself never stores them, so nothing is duplicated at capture time. Selection is by the log's time window (its start through the next log's start), so events from concurrently running `eve dev` processes may appear.
+
+Each log has a same-named `.dump` sibling holding environment diagnostics and session stats as one JSON document. `eve logs --dump` (with or without a log id) prepends that document to the JSONL log body; the combined output is a valid JSON value stream (`eve logs --dump | jq -c .`), one self-contained report to attach to an issue. When a log has no dump, the flag is silently a no-op.
+
 ## `eve link`
 
 ```bash
@@ -251,4 +273,4 @@ Related: [Project layout](./project-layout) · [instrumentation.ts](../guides/in
 
 - [Project layout](./project-layout): what `eve info` discovers
 - [instrumentation.ts](../guides/instrumentation): tracing and the error catalog
-- [Deployment](../guides/deployment): `eve build` and `eve start` in production
+- [Deployment](../guides/deployment/overview): `eve build` and `eve start` in production

package/docs/tutorial/ship-it.mdx

@@ -153,4 +153,4 @@ Across the nine steps you built and shipped one agent, and along the way you use
 - [Dynamic capabilities](../guides/dynamic-capabilities) for schema-derived dynamic tools, a read-only analyst subagent, and model-authored report workflows on this same example.
 - [Auth and route protection](../guides/auth-and-route-protection) for production auth patterns.
 
-Learn more: [Frontend](../guides/frontend/overview) · [Auth and route protection](../guides/auth-and-route-protection) · [Deployment](../guides/deployment)
+Learn more: [Frontend](../guides/frontend/overview) · [Auth and route protection](../guides/auth-and-route-protection) · [Deployment](../guides/deployment/overview)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve",
-  "version": "0.25.3",
+  "version": "0.26.1",
   "private": false,
   "description": "Filesystem-first framework for durable backend AI agents that run anywhere.",
   "keywords": [
@@ -323,6 +323,7 @@
     "jose": "6.2.3",
     "jsonc-parser": "3.3.1",
     "just-bash": "3.0.1",
+    "marked": "17.0.6",
     "microsandbox": "0.5.5",
     "next": "16.3.0-preview.6",
     "picocolors": "1.1.1",

package/docs/guides/deployment.md

@@ -1,210 +0,0 @@
----
-title: "Deployment"
-description: "A production checklist for shipping an eve agent on Vercel or your own host, covering build output, env and secrets, sandbox backend, auth, deploy, and verify."
----
-
-eve runs the same way locally, on Vercel, and on a long-running Node host, so taking an agent from `eve dev` to production is mostly mechanical. Work through this checklist in order.
-
-## 1. Build
-
-`eve build` compiles the agent and writes the host output:
-
-```bash
-eve build
-```
-
-When `VERCEL` is set (every hosted Vercel build sets it), `eve build` writes the [Vercel Build Output](https://vercel.com/docs/build-output-api) bundle under `.vercel/output`. A plain local `eve build` skips that bundle. Either way you get eve's compiled framework artifacts under `.eve/`, including the discovery manifest, compiled manifest, diagnostics, and module map. Open those to see which authored surface a deployment will load. For the artifact guide and what to do when `eve build` fails, see [Observability](./instrumentation).
-
-### How portability works
-
-Nitro is the HTTP host layer. It gives eve a build artifact that can serve the health, session, stream, channel, callback, and schedule routes outside the dev server. Workflow execution and sandbox execution are separate runtime adapters; they are not hidden Vercel dependencies inside Nitro.
-
-On Vercel, eve emits Vercel Build Output, the Workflow SDK runs on Vercel Workflow, and `defaultBackend()` selects Vercel Sandbox. Outside Vercel, `eve start` serves the standard Nitro Node output, the Workflow SDK uses its local world by default, and `defaultBackend()` selects a local sandbox backend in availability order. That local workflow world persists run state on disk and has no direct coupling to Vercel; Vercel-only behavior such as latest-deployment routing and dashboard run attributes is additive.
-
-Advanced self-hosted deployments can select a different installed Workflow world package in the root `agent.ts`:
-
-```ts title="agent/agent.ts"
-import { defineAgent } from "eve";
-
-export default defineAgent({
-  model: "anthropic/claude-opus-4.8",
-  experimental: {
-    workflow: {
-      world: "@acme/eve-workflow-world",
-    },
-  },
-});
-```
-
-The world package should read credentials and host-specific options from runtime environment variables. It should export a default factory or `createWorld()` function. See [Workflow Worlds](https://workflow-sdk.dev/worlds) for the underlying SDK abstraction.
-
-## 2. Environment variables and secrets
-
-Set these in your deployment environment or secret manager, never in source or compiled artifacts:
-
-- **A model credential.** The lowest-setup Vercel option is the Vercel AI Gateway. Link a Vercel project, and gateway model ids like `anthropic/claude-opus-4.8` authenticate through Vercel OIDC, with no provider keys to manage. Outside Vercel, either set `AI_GATEWAY_API_KEY` for gateway-routed models or configure a direct provider model with an [AI SDK provider package](https://ai-sdk.dev/docs/foundations/providers-and-models) and set that provider's key, for example `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`.
-- **Route-auth secrets**, for example `ROUTE_AUTH_BASIC_PASSWORD` and any JWT/OIDC signing keys referenced by your channel's `auth` (see [Auth and route protection](./auth-and-route-protection)).
-
-Route-auth secrets are never serialized into the compiled discovery or module-map artifacts. The runtime re-materializes them from the authored channel definition instead. If your deployment sits behind Vercel preview protection and you want to drive it with `eve dev`, set `VERCEL_AUTOMATION_BYPASS_SECRET` locally before launching.
-
-## 3. Model routing
-
-The shape of `model` in `agent/agent.ts` decides whether eve calls the Vercel AI Gateway or a provider endpoint directly.
-
-A string model id is gateway-routed:
-
-```ts title="agent/agent.ts"
-import { defineAgent } from "eve";
-
-export default defineAgent({
-  model: "anthropic/claude-opus-4.8",
-});
-```
-
-That works on Vercel with project OIDC or anywhere else with `AI_GATEWAY_API_KEY`. Passing a provider key through `modelOptions.providerOptions.gateway.byok` also still sends the request through the Gateway; it only changes which upstream key the Gateway uses.
-
-To avoid the Gateway entirely, install the [AI SDK package](https://ai-sdk.dev/docs/foundations/providers-and-models) for the provider you want to call, pass that provider's model object, and set that provider's normal environment variable:
-
-```bash
-npm install @ai-sdk/anthropic
-```
-
-```ts title="agent/agent.ts"
-import { anthropic } from "@ai-sdk/anthropic";
-import { defineAgent } from "eve";
-
-export default defineAgent({
-  model: anthropic("claude-opus-4-8"),
-});
-```
-
-With that shape, the model call goes directly to Anthropic and the runtime reads `ANTHROPIC_API_KEY`. Direct Anthropic model ids use hyphens (`claude-opus-4-8`), unlike the dotted Gateway id (`anthropic/claude-opus-4.8`). The same pattern works for OpenAI after installing `@ai-sdk/openai`, using `openai("...")`, and setting `OPENAI_API_KEY`. This is the usual choice when self-deploying without any Vercel-managed services.
-
-## 4. Sandbox backend
-
-On Vercel, the [sandbox](../sandbox) runs on hosted [Vercel Sandbox](https://vercel.com/docs/sandbox) infrastructure. Attach the backend on the sandbox definition:
-
-```ts title="agent/sandbox/sandbox.ts"
-import { defineSandbox } from "eve/sandbox";
-import { vercel } from "eve/sandbox/vercel";
-
-export default defineSandbox({
-  backend: vercel(),
-});
-```
-
-Leave `backend` off and eve falls back to `defaultBackend()`, which picks the Vercel backend on hosted builds and the local backend everywhere else. One definition, both environments.
-
-For a self-deployed process, leave `defaultBackend()` in place or choose an explicit non-Vercel backend such as Docker or microsandbox. If those do not match your infrastructure, write a custom `SandboxBackend` adapter that creates sessions in your own container, VM, or isolation service. Do not pin `vercel()` unless that process should create hosted Vercel sandboxes.
-
-## 5. Build-time sandbox prewarm
-
-During Vercel-targeted builds, eve prewarms reusable Vercel sandbox templates so the first session doesn't pay the cold-start cost. This includes hosted builds and local `vercel build` runs:
-
-- Prewarm runs for hosted Vercel builds and linked local `vercel build` runs.
-- A sandbox with no `bootstrap()` and no workspace seed files gets skipped.
-- Seed-only templates are keyed by skills and workspace file contents, so unchanged seeds reuse a template across deploys.
-- Templates with a `bootstrap()` are keyed by the optional resolved `revalidationKey()` plus the authored sandbox source and seed contents, so matching inputs reuse a template across deploys.
-- Each template shows up in the build log as either `reused cached` or `built`.
-- Prewarming only covers template construction. `onSession()` still runs at runtime, once per session.
-- **If build-time prewarm fails, the build fails.**
-
-Local builds must be linked to a Vercel project with credentials that can provision Vercel Sandbox templates. If authentication or template provisioning fails, eve fails the build rather than emitting output that would fail after deployment.
-
-## 6. Auth
-
-Swap any scaffolded `placeholderAuth()` for your real policy before the first production browser request hits the app. Both the framework default and the placeholder reject production browser traffic, so an unconfigured app fails closed rather than serving open routes. The production policy can be a shipped helper (`httpBasic()`, `jwtHmac()`, `jwtEcdsa()`, `oidc()`, `vercelOidc()`) or a custom `AuthFn` that validates your own sessions, API keys, or identity provider. See [Auth and route protection](./auth-and-route-protection) for the ordered auth walk and the fail-closed guarantee.
-
-If you self-deploy outside Vercel, do not rely on `vercelOidc()` as the only production authenticator. Use your own route policy, such as Basic auth, JWT/OIDC verification for your identity provider, or a custom verifier.
-
-## 7. Deploy on Vercel
-
-Deploy with the [Vercel CLI](https://vercel.com/docs/cli) or by pushing to a Git-connected project:
-
-```bash
-vercel deploy
-```
-
-The deployed app serves the same stable health, session, and stream routes you've been hitting locally.
-
-## 8. Deploy without Vercel
-
-eve can also run as a normal Node service behind your own process manager, container platform, or reverse proxy:
-
-```bash
-eve build
-PORT=3000 eve start --host 0.0.0.0
-```
-
-Eve writes the standard Nitro output under `.output/` instead of Vercel Build Output. `eve start` serves that built app and respects `PORT`, or the `--port` flag. Put TLS, routing, autoscaling, and log collection around that process the same way you would for any other Node HTTP service.
-
-Self-deployed agents should make the Vercel-specific choices explicit:
-
-- Let the Workflow SDK use its default local world, which stores workflow state under `.eve/.workflow-data`; configure your host so that directory is on persistent storage, or select another world with `experimental.workflow.world` in the root `agent.ts`. When you select a custom world, install a world package built against the same `@workflow/*` line as your eve release (currently the `5.0.0-beta` line). The npm `latest` tag may lag, so pin the version explicitly, for example `pnpm add @workflow/world-postgres@5.0.0-beta.x`. The Workflow SDK rejects worlds with an incompatible runtime protocol during initialization.
-- If you put a reverse proxy or ingress in front of eve, forward **both** `/eve/` and `/.well-known/workflow/`. The workflow world delivers run callbacks to `/.well-known/workflow/v1/flow`; a proxy restricted to `/eve/` lets sessions start but silently stalls runs forever, because the callbacks never reach eve.
-- Install the AI SDK package for your provider, then use a direct provider model object and `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` when you want no Gateway dependency.
-- Use `AI_GATEWAY_API_KEY` if you still want Gateway routing from a non-Vercel host.
-- Replace `vercelOidc()` with auth that your host can verify.
-- Use `defaultBackend()`, a pinned non-Vercel sandbox backend such as Docker or microsandbox, or your own `SandboxBackend` adapter.
-- If the agent defines schedules, the default `eve build && eve start` path starts Nitro's schedule runner, and Vercel wires schedules to Vercel Cron automatically. If you adapt the output to a custom HTTP-only host or preset, make sure it also runs Nitro scheduled tasks, or trigger the same work from your own scheduler.
-- Treat Vercel Cron, Vercel Sandbox prewarm, Vercel Deployment Protection bypass, and the Agent Runs dashboard as Vercel-only conveniences.
-
-The HTTP contract is unchanged: health, session creation, streaming, channels, tools, and subagents use the same routes under `/eve/`, and the workflow dispatch route lives under `/.well-known/workflow/`. A reverse proxy must preserve both prefixes. Any client that can reach and authenticate to those routes can talk to the agent.
-
-## 9. Verify the deployment
-
-Smoke-test the live routes. Health first:
-
-```bash
-curl https://<your-app>/eve/v1/health
-```
-
-Then a real turn:
-
-```bash
-curl -X POST https://<your-app>/eve/v1/session \
-  -H 'content-type: application/json' \
-  -d '{"message":"Hello from production"}'
-```
-
-The POST returns a JSON body whose `sessionId` identifies the new session. Attach to that session's stream with it:
-
-```bash
-curl https://<your-app>/eve/v1/session/<sessionId>/stream
-```
-
-Or drive the deployment interactively with the dev TUI, which is handy for preview and production smoke tests:
-
-```bash
-eve dev https://<your-app>
-```
-
-(Set `VERCEL_AUTOMATION_BYPASS_SECRET` locally first if the deployment uses preview protection.)
-
-## View runs in the dashboard
-
-Once the agent is deployed, the platform auto-detects `eve` as the framework and surfaces an **Agent Runs** tab under your project's **Observability** view in the Vercel dashboard. From there you can browse sessions and drill into each conversation's trace.
-
-> The Agent Runs tab is currently gated. Your Vercel team needs the feature enabled before it appears. If you don't see it, reach out to your Vercel contact to get your team enabled.
-
-Agent Runs is separate from the OpenTelemetry exporters configured in [Observability](./instrumentation). Those still work and are the recommended path if you want spans in Braintrust, Datadog, or another third-party backend.
-
-## How eve sits behind a host framework
-
-You can deploy an eve app on its own, or mount it inside a host web framework that owns the rest of the site (marketing pages, a dashboard, other API routes). The host keeps its own routing and serves eve's routes through the framework integration. Either way, the agent surface and HTTP contract are identical. For mounting eve in Next.js (`withEve`) and the other supported frameworks, see [Frontend](./frontend/nextjs).
-
-## Checklist
-
-- [ ] `eve build` succeeds, and writes `.vercel/output` when `VERCEL` is set.
-- [ ] Provider keys and route-auth secrets are set in the deployment environment.
-- [ ] The sandbox backend matches the environment (`vercel()` or `defaultBackend()`).
-- [ ] On Vercel, build-time prewarm reused or built templates without failing.
-- [ ] `placeholderAuth()` is replaced with your real policy.
-- [ ] `vercel deploy` succeeds, or your self-hosted process starts with `eve start`.
-- [ ] The health, session, and stream routes respond on the deployment URL.
-
-## What to read next
-
-- [Auth and route protection](./auth-and-route-protection): secure the routes you deployed
-- [Observability](./instrumentation): tracing, run tags, and common failures
-- [Sandbox](../sandbox): backends, lifecycle, and credential brokering