eve 0.13.6 → 0.13.8

package/docs/{connections.mdx → connections/overview.mdx}

@@ -1,6 +1,7 @@
 ---
 title: "Connections"
 description: "Expose external MCP and OpenAPI servers to the model, with connection tokens the model never sees."
+url: /connections
 ---
 
 A connection wires an agent into an external server you don't author, either an MCP server (Linear, GitHub, a warehouse) or any HTTP API with an OpenAPI document. eve handles the parts you'd otherwise hand-roll, discovering the remote tools, surfacing them to the model, and brokering auth.
@@ -9,23 +10,17 @@ Connections live under `agent/connections/`. The runtime name comes from the fil
 
 ## MCP connections
 
-`defineMcpClientConnection` points at an MCP server. Supply a `url` and a `description`:
+Use an MCP connection when the external service already exposes an MCP server. The server publishes its tools and schemas, and eve makes the matched tools callable by the model.
 
-```ts title="agent/connections/linear.ts"
-import { defineMcpClientConnection } from "eve/connections";
+Read [MCP connections](/docs/connections/mcp) for `defineMcpClientConnection`, transport requirements, and MCP tool filters.
 
-export default defineMcpClientConnection({
-  url: "https://mcp.linear.app/sse",
-  description: "Linear workspace: issues, projects, cycles, and comments.",
-  auth: {
-    getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }),
-  },
-});
-```
+## OpenAPI connections
+
+Use an OpenAPI connection when the service exposes an OpenAPI 3.x document. eve turns operations in the document into connection tools, one per operation.
 
-The `url` must speak Streamable HTTP or SSE. Write the `description` for the model, not for yourself. It shows up in `connection_search`, and the model uses it to decide which connection to query.
+Read [OpenAPI connections](/docs/connections/openapi) for `defineOpenAPIConnection`, `baseUrl`, and operation filters.
 
-### Static-token auth
+## Static-token auth
 
 `getToken` returns a `TokenResult` (`{ token, expiresAt? }`), and eve sends it as `Authorization: Bearer <token>` on every request. Because it runs on each connection attempt, you can mint a fresh token from wherever you keep secrets, including an env var, a secrets manager, an internal vault, or your own OAuth exchange. If the token has a known TTL, set `expiresAt` (milliseconds since epoch) and eve refreshes ahead of time rather than waiting for a `401`.
 
@@ -33,24 +28,28 @@ When `getToken` is the only auth, `principalType` defaults to `"app"`: one share
 
 eve resolves and caches connection tokens per step; they never land in conversation history or reach the model.
 
-### No auth
+## No auth
 
 Drop `auth` entirely for servers that need no token, such as a localhost server during development or a public one:
 
-```ts
+```ts title="agent/connections/local.ts"
+import { defineMcpClientConnection } from "eve/connections";
+
 export default defineMcpClientConnection({
   url: "http://localhost:3001/mcp",
   description: "Local dev server.",
 });
 ```
 
-We recommend using no-auth connections only for services that are intentionally public, local-only, or otherwise protected outside eve. Do not use no-auth connections for sensitive third-party services.
+Use no-auth connections only for services that are intentionally public, local-only, or otherwise protected outside eve. Do not use no-auth connections for sensitive third-party services.
 
-### Headers
+## Headers
 
-Use `headers` when the server wants a non-Bearer scheme (an API-key header) or extra configuration. Headers stack on top of `auth`:
+Use `headers` when the server wants a non-Bearer scheme (an API-key header) or extra configuration. Headers stack on top of `auth` and work for both MCP and OpenAPI connections:
+
+```ts title="agent/connections/example.ts"
+import { defineMcpClientConnection } from "eve/connections";
 
-```ts
 export default defineMcpClientConnection({
   url: "https://example.com/mcp",
   description: "Example service.",
@@ -58,24 +57,12 @@ export default defineMcpClientConnection({
 });
 ```
 
-### Tool filters
-
-To narrow which remote tools the model sees, set exactly one of `tools.allow` or `tools.block`. Filtered-out tools do not appear in `connection_search`:
-
-```ts
-export default defineMcpClientConnection({
-  url: "https://mcp.linear.app/sse",
-  description: "Linear: read-only.",
-  auth: { getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }) },
-  tools: { allow: ["search_issues", "get_issue"] },
-});
-```
-
-### Per-connection approval
+## Per-connection approval
 
 To put every tool a connection serves behind a human, use the helpers from `eve/tools/approval`:
 
-```ts
+```ts title="agent/connections/linear.ts"
+import { defineMcpClientConnection } from "eve/connections";
 import { once } from "eve/tools/approval";
 
 export default defineMcpClientConnection({
@@ -86,32 +73,9 @@ export default defineMcpClientConnection({
 });
 ```
 
-`never()` lets every call through, `once()` asks for approval the first time in a session, and `always()` asks every time. The pause and resume is the same human-in-the-loop flow covered in [Tools](./tools).
-
-For connection tools that can create, modify, delete, transmit, purchase, message, or access sensitive data, use approval, tool allow-lists, or other safeguards appropriate to the action.
-
-## OpenAPI connections
-
-`defineOpenAPIConnection` turns any OpenAPI 3.x document into connection tools, one per operation. Pass an HTTPS URL eve fetches at runtime, or an inline parsed object:
-
-```ts title="agent/connections/petstore.ts"
-import { defineOpenAPIConnection } from "eve/connections";
-
-export default defineOpenAPIConnection({
-  spec: "https://petstore3.swagger.io/api/v3/openapi.json",
-  description: "Pet store inventory and orders.",
-  auth: { getToken: async () => ({ token: process.env.PETSTORE_TOKEN! }) },
-});
-```
-
-Each operation becomes `<connection>__<operationId>` (e.g. `petstore__getInventory`). When an operation has no `operationId`, eve derives a deterministic `<method>_<sanitized-path>` name instead.
-
-`auth`, `headers`, and `approval` work exactly as they do for MCP. There are two fields specific to OpenAPI:
+`never()` lets every call through, `once()` asks for approval the first time in a session, and `always()` asks every time. The pause and resume is the same human-in-the-loop flow covered in [Tools](/docs/tools).
 
-| Field        | Purpose                                                                                                                 |
-| ------------ | ----------------------------------------------------------------------------------------------------------------------- |
-| `baseUrl`    | Base URL operation paths resolve against. Optional; defaults to the document's first usable `servers` entry.            |
-| `operations` | Filter keyed on `operationId` (`allow` or `block`). Mirrors `tools` on MCP connections, but names operations not tools. |
+For connection tools that can create, modify, delete, transmit, purchase, message, or access sensitive data, use approval, allow-lists, or other safeguards appropriate to the action.
 
 ## Interactive OAuth via Vercel Connect
 
@@ -128,7 +92,7 @@ export default defineMcpClientConnection({
 });
 ```
 
-`"linear/myagent"` is the UID you chose when registering the Connect client. Connect-managed OAuth is user-scoped by default, so the runtime resolves the per-user token before each tool call. The full setup (Connect client provisioning, project linking, the runtime consent flow) lives in [Auth & route protection](./guides/auth-and-route-protection).
+`"linear/myagent"` is the UID you chose when registering the Connect client. Connect-managed OAuth is user-scoped by default, so the runtime resolves the per-user token before each tool call. The full setup (Connect client provisioning, project linking, the runtime consent flow) lives in [Auth & route protection](/docs/guides/auth-and-route-protection).
 
 ## Self-hosted interactive OAuth
 
@@ -236,7 +200,8 @@ A tool can require both sign-in (`auth`) and a human approval. The model's appro
 
 ## What to read next
 
+- [MCP connections](/docs/connections/mcp): connect to remote MCP servers.
+- [OpenAPI connections](/docs/connections/openapi): generate tools from OpenAPI operations.
 - [Integrations](/integrations): browse every channel and connection eve ships, in one gallery.
-- [Tools](./tools): authored tools live alongside connection-provided tools; the same approval helpers apply.
-- [Auth & route protection](./guides/auth-and-route-protection): the full interactive-OAuth flow with Vercel Connect.
-- [Security model](./concepts/security-model): how connection credentials stay out of the model's reach.
+- [Tools](/docs/tools): authored tools live alongside connection-provided tools; the same approval helpers apply.
+- [Security model](/docs/concepts/security-model): how connection credentials stay out of the model's reach.

package/docs/getting-started.mdx

@@ -5,12 +5,6 @@ description: "Install eve, scaffold your first agent, give it a tool, and run it
 
 eve is a filesystem-first framework for durable agents. You write capabilities under `agent/`, and eve runs the model loop, persists every session, and serves the agent over HTTP and platform channels. You'll scaffold an app, add a tool, run it locally, then create, stream, and continue a session over HTTP.
 
-<Callout>
-  eve is currently in beta and subject to the [Vercel beta
-  terms](https://vercel.com/docs/release-phases/public-beta-agreement); the framework, APIs,
-  documentation, and behavior may change before general availability.
-</Callout>
-
 ## Prerequisites
 
 - Node 24 or newer

package/docs/introduction.mdx

@@ -7,12 +7,6 @@ eve is a framework for building durable agents as ordinary files in a TypeScript
 
 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.
 
-<Callout>
-  eve is currently in beta and subject to the [Vercel beta
-  terms](https://vercel.com/docs/release-phases/public-beta-agreement); the framework, APIs,
-  documentation, and behavior may change before general availability.
-</Callout>
-
 ## An eve project at a glance
 
 A small eve app looks like this:
@@ -90,7 +84,7 @@ As the agent grows, each concern still has a predictable home:
 
 | Path                            | Add it when you need...                          |
 | ------------------------------- | ------------------------------------------------ |
-| [`connections/`](./connections) | Tools from external MCP servers                  |
+| [`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 |
@@ -105,5 +99,5 @@ The result stays readable before it runs. The directory tells you what the 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 MCP servers
+- [Connections](./connections): pull in tools from external services
 - [Project layout](./reference/project-layout): every authored slot under `agent/`

package/docs/reference/typescript-api.md

@@ -30,25 +30,26 @@ export default defineTool({
 
 ## The define\* helpers
 
-| Helper                                                 | Import from                                   | Authored at                          | Guide                                                  |
-| ------------------------------------------------------ | --------------------------------------------- | ------------------------------------ | ------------------------------------------------------ |
-| `defineAgent`                                          | `eve`                                         | `agent/agent.ts`                     | [agent.ts](../agent-config)                            |
-| `defineTool`                                           | `eve/tools`                                   | `agent/tools/<name>.ts`              | [Tools](../tools)                                      |
-| `defineDynamic`                                        | `eve/tools`, `eve/skills`, `eve/instructions` | `agent/{tools,skills,instructions}/` | [Dynamic capabilities](../guides/dynamic-capabilities) |
-| `defineMcpClientConnection`, `defineOpenAPIConnection` | `eve/connections`                             | `agent/connections/<name>.ts`        | [Connections](../connections)                          |
-| `defineChannel`                                        | `eve/channels`                                | `agent/channels/<name>.ts`           | [Custom channels](../channels/custom)                  |
-| `eveChannel`, `slackChannel`, and the other platforms  | `eve/channels/<platform>`                     | `agent/channels/<platform>.ts`       | [Channels](../channels/overview)                       |
-| `defineSkill`                                          | `eve/skills`                                  | `agent/skills/<name>.ts`             | [Skills](../skills)                                    |
-| `defineInstructions`                                   | `eve/instructions`                            | `agent/instructions.ts`              | [Instructions](../instructions)                        |
-| `defineHook`                                           | `eve/hooks`                                   | `agent/hooks/<slug>.ts`              | [Hooks](../guides/hooks)                               |
-| `defineSchedule`                                       | `eve/schedules`                               | `agent/schedules/<name>.ts`          | [Schedules](../schedules)                              |
-| `defineState`                                          | `eve/context`                                 | tools, hooks, lifecycle              | [Session context](../guides/session-context)           |
-| `defineSandbox`                                        | `eve/sandbox`                                 | `agent/sandbox.ts`                   | [Sandbox](../sandbox)                                  |
-| `defineInstrumentation`                                | `eve/instrumentation`                         | `agent/instrumentation.ts`           | [instrumentation.ts](../guides/instrumentation)        |
-| `defineRemoteAgent`                                    | `eve`                                         | `agent/subagents/<id>/agent.ts`      | [Remote agents](../guides/remote-agents)               |
-| `defineEval`                                           | `eve/evals`                                   | `evals/*.eval.ts`                    | [Evals](../evals/overview)                             |
-| `defineEvalConfig`                                     | `eve/evals`                                   | `evals/evals.config.ts`              | [Evals](../evals/overview)                             |
-| `useEveAgent`                                          | `eve/react`, `eve/vue`, `eve/svelte`          | frontend                             | [Frontend](../guides/frontend/overview)                |
+| Helper                                                | Import from                                   | Authored at                          | Guide                                                  |
+| ----------------------------------------------------- | --------------------------------------------- | ------------------------------------ | ------------------------------------------------------ |
+| `defineAgent`                                         | `eve`                                         | `agent/agent.ts`                     | [agent.ts](../agent-config)                            |
+| `defineTool`                                          | `eve/tools`                                   | `agent/tools/<name>.ts`              | [Tools](../tools)                                      |
+| `defineDynamic`                                       | `eve/tools`, `eve/skills`, `eve/instructions` | `agent/{tools,skills,instructions}/` | [Dynamic capabilities](../guides/dynamic-capabilities) |
+| `defineMcpClientConnection`                           | `eve/connections`                             | `agent/connections/<name>.ts`        | [MCP connections](../connections/mcp)                  |
+| `defineOpenAPIConnection`                             | `eve/connections`                             | `agent/connections/<name>.ts`        | [OpenAPI connections](../connections/openapi)          |
+| `defineChannel`                                       | `eve/channels`                                | `agent/channels/<name>.ts`           | [Custom channels](../channels/custom)                  |
+| `eveChannel`, `slackChannel`, and the other platforms | `eve/channels/<platform>`                     | `agent/channels/<platform>.ts`       | [Channels](../channels/overview)                       |
+| `defineSkill`                                         | `eve/skills`                                  | `agent/skills/<name>.ts`             | [Skills](../skills)                                    |
+| `defineInstructions`                                  | `eve/instructions`                            | `agent/instructions.ts`              | [Instructions](../instructions)                        |
+| `defineHook`                                          | `eve/hooks`                                   | `agent/hooks/<slug>.ts`              | [Hooks](../guides/hooks)                               |
+| `defineSchedule`                                      | `eve/schedules`                               | `agent/schedules/<name>.ts`          | [Schedules](../schedules)                              |
+| `defineState`                                         | `eve/context`                                 | tools, hooks, lifecycle              | [Session context](../guides/session-context)           |
+| `defineSandbox`                                       | `eve/sandbox`                                 | `agent/sandbox.ts`                   | [Sandbox](../sandbox)                                  |
+| `defineInstrumentation`                               | `eve/instrumentation`                         | `agent/instrumentation.ts`           | [instrumentation.ts](../guides/instrumentation)        |
+| `defineRemoteAgent`                                   | `eve`                                         | `agent/subagents/<id>/agent.ts`      | [Remote agents](../guides/remote-agents)               |
+| `defineEval`                                          | `eve/evals`                                   | `evals/*.eval.ts`                    | [Evals](../evals/overview)                             |
+| `defineEvalConfig`                                    | `eve/evals`                                   | `evals/evals.config.ts`              | [Evals](../evals/overview)                             |
+| `useEveAgent`                                         | `eve/react`, `eve/vue`, `eve/svelte`          | frontend                             | [Frontend](../guides/frontend/overview)                |
 
 A few non-`define*` helpers round out the set: `disableTool` and `ExperimentalWorkflow` from `eve/tools` (see [Default harness](../concepts/default-harness)), the route verbs `GET`/`POST`/`PUT`/`PATCH`/`DELETE`/`WS` from `eve/channels`, the approval predicates `always`/`once`/`never` from `eve/tools/approval`, and the channel auth helpers `localDev`/`vercelOidc`/`placeholderAuth` from `eve/channels/auth`. To wrap a built-in tool, import its default value from `eve/tools/defaults` (`bash`, `readFile`, `writeFile`, `glob`, `grep`, `webFetch`, `webSearch`, `todo`, `loadSkill`). `AgentWorkflowDefinition` and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape.
 

package/docs/tutorial/connect-a-warehouse.mdx

@@ -33,7 +33,7 @@ Once Connect is enabled on your account, wire it up:
 3. Link the client to your project.
 4. Run `vercel link` and `vercel env pull` so `VERCEL_OIDC_TOKEN` is available locally.
 
-For the full reference, see [Connections](../connections).
+For the full reference, see [MCP connections](../connections/mcp).
 
 ## What the user sees
 
@@ -49,8 +49,8 @@ The first time, the model picks a warehouse tool but there's no token yet, so th
 
 Right before each request to the MCP server, eve resolves the bearer and sends it as `Authorization: Bearer <token>`. The model only ever sees tool names, descriptions, and results. The credential stays out of its reach.
 
-If you want more control, gate the connection behind approval (`approval: once()`) or narrow which tools the model sees (`tools.allow`). See [Connections](../connections).
+If you want more control, gate the connection behind approval (`approval: once()`) or narrow which tools the model sees (`tools.allow`). See [MCP connections](../connections/mcp).
 
 → Next: [Run analysis](./run-analysis)
 
-Learn more: [Connections](../connections) · [Auth and route protection](../guides/auth-and-route-protection)
+Learn more: [MCP connections](../connections/mcp) · [Auth and route protection](../guides/auth-and-route-protection)

package/docs/tutorial/ship-it.mdx

@@ -148,7 +148,7 @@ Across the nine steps you built and shipped one agent, and along the way you use
 
 ## Next steps
 
-- [Connections](../connections) for tool allowlists and per-connection approval.
+- [MCP connections](../connections/mcp) for tool allowlists and per-connection approval.
 - [Sandbox](../sandbox) for backends, lifecycle, and network policy.
 - [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.

package/package.json

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