eve 0.27.6 → 0.27.7

package/docs/guides/client/streaming.mdx

@@ -157,6 +157,21 @@ for await (const event of session.stream({ startIndex: -1 })) {
 
 Tail-relative attachments do not automatically reconnect or advance the session's stored absolute `streamIndex`. Break after the event you need when using one as a tail lookup.
 
+## Bounded catch-up reads
+
+Pass `follow: false` to read from the cursor to the durable tail and then stop, instead of following the live stream (the default):
+
+```ts
+for await (const event of session.stream({ follow: false })) {
+  console.log(event.type);
+}
+// Returns once every event recorded before the stream opened is consumed.
+```
+
+The first connection pins the bound to the tail the server reports at open time; events recorded afterward are not part of the read. Reconnects during the read keep that original bound, and the session's stored `streamIndex` still advances past the consumed events, so a follow-up `stream()` or `send()` picks up exactly where the bounded read ended. When the cursor is already at or past the tail, the iterator returns immediately without yielding.
+
+Because a tail-relative cursor cannot be bounded, `follow: false` throws when combined with a negative `startIndex`. It also fails if the server does not report the durable tail (an agent running an older eve version).
+
 `stream()` throws if the session has no `sessionId`, because there's no stream to attach to before the first send.
 
 ## Abort a request

package/docs/installation.mdx

@@ -0,0 +1,60 @@
+---
+title: "Installation"
+description: "Create an eve project, configure a model credential, and run it locally."
+contentType: "How-to"
+---
+
+Create an eve project with `eve init`. The scaffold installs dependencies, creates the agent files, and starts the local development server.
+
+## Configure a model credential
+
+The default scaffolded model routes through the Vercel AI Gateway. Set `AI_GATEWAY_API_KEY`, or link a Vercel project to use `VERCEL_OIDC_TOKEN`.
+
+You can also use a direct provider model. Install its AI SDK provider package and set that provider's API key before you run the agent.
+
+Choose a model, provider, and channel that meet your data-processing and compliance requirements.
+
+## Create a project
+
+Run `eve init` with a project name:
+
+```bash
+npx eve@latest init my-agent
+```
+
+The command creates `my-agent/`, installs dependencies, initializes Git, and starts eve's development server. If a supported coding-agent REPL is available, eve offers to open it instead.
+
+## Run the agent
+
+From the project root, run the generated development command:
+
+```bash
+cd my-agent
+npm run dev
+```
+
+The terminal UI sends messages to your agent. Stop the server with Ctrl+C when you need your shell for another command.
+
+## Add eve to an existing project
+
+Run `eve init .` from a project with a `package.json` and no existing `agent/` files:
+
+```bash
+npx eve@latest init .
+```
+
+eve adds the missing `eve`, `ai`, and `zod` dependencies without changing files the project already owns.
+
+## Install manually
+
+Install the runtime dependencies when you do not want to use the scaffold:
+
+```bash
+npm install eve@latest ai zod
+```
+
+Declare Node.js 24 in `package.json`, then create `agent/agent.ts` and `agent/instructions.md`. [Project structure](/docs/project-structure) shows the required layout, and [`agent.ts`](./agent-config) documents the runtime configuration.
+
+## Continue building
+
+Read [Project structure](/docs/project-structure) before adding instructions, tools, connections, or channels.

package/docs/meta.json

@@ -1,8 +1,10 @@
 {
   "pages": [
-    "introduction",
+    "---Getting Started---",
     "getting-started",
-    "---",
+    "installation",
+    "project-structure",
+    "---Build Your Agent---",
     "agent-config",
     "instructions",
     "tools",
@@ -14,12 +16,11 @@
     "subagents",
     "schedules",
     "evals",
-    "---",
+    "---Learn More---",
+    "tutorial",
     "guides",
     "concepts",
     "patterns",
-    "---",
-    "reference",
-    "tutorial"
+    "reference"
   ]
 }

package/docs/project-structure.mdx

@@ -0,0 +1,53 @@
+---
+title: "Project Structure"
+description: "Learn the files eve discovers and how their paths define agent capabilities."
+contentType: "Conceptual"
+---
+
+eve builds an agent from files under `agent/`. A file's location determines what eve loads, and most paths also determine the capability's name.
+
+## Start with two files
+
+A minimal agent needs an instructions file and optional runtime configuration:
+
+```text
+my-agent/
+├── package.json
+├── agent/
+│   ├── agent.ts
+│   └── instructions.md
+└── evals/
+```
+
+`agent/instructions.md` is the agent's always-on system prompt. `agent/agent.ts` selects the model and configures runtime behavior. Omit `agent.ts` when the defaults are sufficient.
+
+## Add capabilities as directories
+
+Add a directory when the agent needs that capability:
+
+| Path                                | Purpose                                       |
+| ----------------------------------- | --------------------------------------------- |
+| [`tools/`](./tools)                 | Typed functions the model can call            |
+| [`skills/`](./skills)               | Procedures the model loads when useful        |
+| [`channels/`](./channels/overview)  | HTTP and messaging entry points               |
+| [`connections/`](/docs/connections) | MCP and OpenAPI services                      |
+| [`sandbox/`](./sandbox)             | Controlled workspace files and commands       |
+| [`subagents/`](./subagents)         | Specialist agents the root agent delegates to |
+| [`schedules/`](./schedules)         | Recurring work                                |
+| `lib/`                              | Shared code imported by agent files           |
+
+The `evals/` directory sits beside `agent/`. It holds the checks that measure whether the agent completes its tasks. See [Evals](./evals/overview).
+
+## Let paths name capabilities
+
+The path supplies the name. This tool file becomes the `get_weather` tool:
+
+```text
+agent/tools/get_weather.ts
+```
+
+The same rule applies to connections, skills, and subagents. You do not add a duplicate `name` or `id` field to the definition.
+
+## Use the full layout reference
+
+[Project layout](./reference/project-layout) lists every supported slot, the root and subagent boundaries, and the file-discovery rules.

package/docs/tutorial/meta.json

@@ -1,5 +1,5 @@
 {
-  "title": "Build an Agent",
+  "title": "Tutorial",
   "pages": [
     "first-agent",
     "how-it-runs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve",
-  "version": "0.27.6",
+  "version": "0.27.7",
   "private": false,
   "description": "Filesystem-first framework for durable backend AI agents that run anywhere.",
   "keywords": [

package/docs/introduction.mdx

@@ -1,103 +0,0 @@
----
-title: "Introduction"
-description: "How an eve agent is laid out as files, what runs when a message arrives, and the building blocks you add as it grows."
----
-
-eve is a framework for building durable agents as ordinary files in a TypeScript project.
-
-Instead of one large configuration object, each part of your agent gets a clear home. Instructions go in one file, tools in one folder, channels in another. eve discovers that structure and turns it into an agent that runs locally, serves HTTP, connects to other platforms, and keeps working across many turns.
-
-## An eve project at a glance
-
-A small eve app looks like this:
-
-```text
-my-agent/
-├── package.json
-└── agent/
-    ├── agent.ts
-    ├── instructions.md
-    ├── tools/
-    │   └── get_weather.ts
-    ├── skills/
-    │   └── plan_a_trip.md
-    └── channels/
-        └── slack.ts
-```
-
-You can understand most eve projects by reading that tree:
-
-- `instructions.md` tells the agent who it is and how it should behave.
-- [`agent.ts`](./agent-config) chooses the model and configures runtime options.
-- [`tools/`](./tools) holds typed functions the model can call.
-- [`skills/`](./skills) holds longer procedures the model loads only when they are useful.
-- [`channels/`](./channels/overview) connect the agent to HTTP clients, Slack, Discord, and the other places people talk to it.
-
-Start with only `instructions.md` and `agent.ts`. Add the other folders when the agent needs them.
-
-## The files are the interface
-
-eve is [filesystem-first](./reference/project-layout). A file's location says what it does, and its path usually gives it a name. For example, this file:
-
-```text
-agent/tools/get_weather.ts
-```
-
-defines a tool named `get_weather`:
-
-```ts
-import { defineTool } from "eve/tools";
-import { z } from "zod";
-
-export default defineTool({
-  description: "Get the weather for a city.",
-  inputSchema: z.object({ city: z.string() }),
-  async execute({ city }) {
-    return { city, condition: "Sunny" };
-  },
-});
-```
-
-There is no separate registry to keep in sync. Add the file and eve discovers it; move or rename it and its identity moves with it. See [Tools](./tools) for the complete API.
-
-## What happens when a message arrives
-
-The same flow runs whether a message comes from a web app, the terminal, or Slack. eve turns the platform input into a message, gives the model its instructions, skills, tools, and conversation history, runs the work (calling tools and subagents as needed), saves the session and streams events, then delivers the result back in the form the platform expects.
-
-That keeps agent behavior portable. Your weather tool does not need to know whether the question came from a browser or from Slack.
-
-## Durable by default
-
-An eve session is more than one request and one response. It can:
-
-- Stream progress while work is happening
-- Call tools and subagents
-- Pause for [approval or a human answer](./tools)
-- Resume after that answer arrives
-- Keep durable state across turns
-
-Under the hood, eve uses the open-source [Workflow SDK](https://workflow-sdk.dev) to make sessions durable, resumable, and crash-safe. eve handles that machinery so your tools focus on the work itself.
-
-## Grow the project by adding capabilities
-
-As the agent grows, each concern still has a predictable home:
-
-| Path                            | Add it when you need...                          |
-| ------------------------------- | ------------------------------------------------ |
-| [`connections/`](./connections) | Tools from external MCP or OpenAPI services      |
-| [`hooks/`](./guides/hooks)      | Code that reacts to lifecycle and stream events  |
-| [`sandbox/`](./sandbox)         | A controlled workspace for files and commands    |
-| [`subagents/`](./subagents)     | Specialist agents the root agent can delegate to |
-| [`schedules/`](./schedules)     | Recurring or scheduled work                      |
-| `lib/`                          | Shared code imported by the other agent files    |
-
-The result stays readable before it runs. The directory tells you what the agent can do.
-
-## What to read next
-
-- [Getting started](./getting-started): scaffold and run your first agent
-- [Tools](./tools): the typed actions your agent calls
-- [Instructions](./instructions): the always-on system prompt that shapes behavior
-- [Channels](./channels/overview): reach the agent from Slack, Discord, or a web UI
-- [Connections](./connections): pull in tools from external services
-- [Project layout](./reference/project-layout): every authored slot under `agent/`