eve 0.15.5 → 0.16.1

package/dist/src/setup/scaffold/update/connections.js

@@ -1,4 +1,4 @@
-import{endpointForProtocol}from"../connections/catalog.js";import{pathExists,writeTextFile}from"../files.js";import{patchPackageJson}from"./package-json.js";import{resolveVersionToken}from"../version-tokens.js";import{getSupportedModuleBaseName,matchesSupportedModuleBaseName}from"./module-files.js";import{join}from"node:path";import{readFile,readdir,writeFile}from"node:fs/promises";const CONNECT_PACKAGE_NAME=`@vercel/connect`,USER_AUTHORED_CONNECTION_DIR=`agent/connections`;function resolveAuth(e){return e.auth??{kind:`none`}}function envKeysForAuth(e){switch(e.kind){case`bearer-env`:return[e.envVar];case`header`:return e.headers.map(e=>e.envVar);case`connect`:case`none`:return[]}}function authBlock(e){switch(e.kind){case`connect`:return`  auth: connect("${e.connector}"),\n`;case`bearer-env`:return`  auth: { getToken: async () => ({ token: process.env.${e.envVar}! }) },\n`;case`header`:return`  headers: () => ({\n${e.headers.map(e=>`    "${e.header}": process.env.${e.envVar}!,`).join(`
+import{endpointForProtocol}from"../connections/catalog.js";import{pathExists,writeTextFile}from"../files.js";import{patchPackageJson}from"./package-json.js";import{resolveVersionToken}from"../version-tokens.js";import{getSupportedModuleBaseName,matchesSupportedModuleBaseName}from"./module-files.js";import{join}from"node:path";import{readFile,readdir,writeFile}from"node:fs/promises";const DEFAULT_CONNECT_PACKAGE_VERSION=`0.2.2`,CONNECT_PACKAGE_NAME=`@vercel/connect`,USER_AUTHORED_CONNECTION_DIR=`agent/connections`;function resolveAuth(e){return e.auth??{kind:`none`}}function envKeysForAuth(e){switch(e.kind){case`bearer-env`:return[e.envVar];case`header`:return e.headers.map(e=>e.envVar);case`connect`:case`none`:return[]}}function authBlock(e){switch(e.kind){case`connect`:return`  auth: connect("${e.connector}"),\n`;case`bearer-env`:return`  auth: { getToken: async () => ({ token: process.env.${e.envVar}! }) },\n`;case`header`:return`  headers: () => ({\n${e.headers.map(e=>`    "${e.header}": process.env.${e.envVar}!,`).join(`
 `)}\n  }),\n`;case`none`:return``}}function renderMcpTemplate(e,t,n){return`${n.kind===`connect`?`import { connect } from "@vercel/connect/eve";
 import { defineMcpClientConnection } from "eve/connections";
 `:`import { defineMcpClientConnection } from "eve/connections";
@@ -15,7 +15,7 @@ export default defineOpenAPIConnection({
   spec: "${e.spec}",
 ${i}  description: "${t}",
 ${authBlock(n)}});
-`}function renderTemplate(e,t,n,r){return e===`mcp`?renderMcpTemplate(t,n,r):renderOpenApiTemplate(t,n,r)}function isJsonObject(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}async function ensureConnectDependency(e,n){if(!await pathExists(e))return[];let i=JSON.parse(await readFile(e,`utf8`));return(isJsonObject(i)&&isJsonObject(i.dependencies)?i.dependencies[CONNECT_PACKAGE_NAME]:void 0)===n?[]:(await patchPackageJson(e,{dependencies:{[CONNECT_PACKAGE_NAME]:n}}),[{path:e,dependencies:[CONNECT_PACKAGE_NAME],devDependencies:[],scripts:[]}])}function envKeyPresent(e,t){return RegExp(`^\\s*(?:export\\s+)?${t}\\s*=`,`m`).test(e)}async function seedEnvPlaceholders(e,n){if(n.length===0)return[];let r=``;await pathExists(e)&&(r=await readFile(e,`utf8`));let i=n.filter(e=>!envKeyPresent(r,e));if(i.length===0)return[];let a=`${r.length>0&&!r.endsWith(`
+`}function renderTemplate(e,t,n,r){return e===`mcp`?renderMcpTemplate(t,n,r):renderOpenApiTemplate(t,n,r)}function isJsonObject(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}async function ensureConnectDependency(e,n){if(!await pathExists(e))return[];let i=JSON.parse(await readFile(e,`utf8`));return(isJsonObject(i)&&isJsonObject(i.dependencies)?i.dependencies[CONNECT_PACKAGE_NAME]:void 0)===n?[]:(await patchPackageJson(e,{dependencies:{[CONNECT_PACKAGE_NAME]:n}}),[{path:e,dependencies:[CONNECT_PACKAGE_NAME],devDependencies:[],scripts:[]}])}async function ensureConnectionDependencies(e){let t=resolveVersionToken(`connectPackageVersion`,e.connectPackageVersion??DEFAULT_CONNECT_PACKAGE_VERSION);return ensureConnectDependency(join(e.projectRoot,`package.json`),t)}function envKeyPresent(e,t){return RegExp(`^\\s*(?:export\\s+)?${t}\\s*=`,`m`).test(e)}async function seedEnvPlaceholders(e,n){if(n.length===0)return[];let r=``;await pathExists(e)&&(r=await readFile(e,`utf8`));let i=n.filter(e=>!envKeyPresent(r,e));if(i.length===0)return[];let a=`${r.length>0&&!r.endsWith(`
 `)?`
 `:``}${i.map(e=>`${e}=`).join(`
-`)}\n`;return await writeFile(e,r+a,`utf8`),i}async function ensureConnection(r){let a=r.slug??r.entry.slug,o=resolveAuth(r.entry),s=endpointForProtocol(r.entry,r.protocol);if(s===null)throw Error(`Connection "${a}" is missing a ${r.protocol===`mcp`?`mcp.url`:`openapi.spec`} endpoint for protocol "${r.protocol}".`);let c=join(r.projectRoot,USER_AUTHORED_CONNECTION_DIR,`${a}.ts`),l=envKeysForAuth(o),u=await pathExists(c);if(!r.force&&u)return{slug:a,protocol:r.protocol,action:`skipped`,filePath:c,filesWritten:[],filesSkipped:[c],packageJsonUpdated:[],envKeysAdded:[],envKeysRequired:l};let d=[];if(o.kind===`connect`){let e=resolveVersionToken(`connectPackageVersion`,r.connectPackageVersion??`0.2.2`);d.push(...await ensureConnectDependency(join(r.projectRoot,`package.json`),e))}await writeTextFile(c,renderTemplate(r.protocol,s,r.entry.description,o),{force:!0});let f=await seedEnvPlaceholders(join(r.projectRoot,`.env.local`),l),p={slug:a,protocol:r.protocol,action:u?`overwritten`:`created`,filePath:c,filesWritten:[c],filesSkipped:[],packageJsonUpdated:d,envKeysAdded:f,envKeysRequired:l};return u&&(p.filesOverwritten=[c]),p}async function listAuthoredConnections(e){let t=join(e,USER_AUTHORED_CONNECTION_DIR),n;try{n=await readdir(t,{withFileTypes:!0})}catch(e){if(e.code===`ENOENT`)return[];throw e}let r=[];for(let e of n){if(e.isFile()){let t=getSupportedModuleBaseName(e.name);t!==null&&r.push(t);continue}if(e.isDirectory())try{(await readdir(join(t,e.name))).some(e=>matchesSupportedModuleBaseName(e,`connection`))&&r.push(e.name)}catch{}}return r.sort()}export{ensureConnection,listAuthoredConnections};
+`)}\n`;return await writeFile(e,r+a,`utf8`),i}async function ensureConnection(r){let a=r.slug??r.entry.slug,o=resolveAuth(r.entry),s=endpointForProtocol(r.entry,r.protocol);if(s===null)throw Error(`Connection "${a}" is missing a ${r.protocol===`mcp`?`mcp.url`:`openapi.spec`} endpoint for protocol "${r.protocol}".`);let c=join(r.projectRoot,USER_AUTHORED_CONNECTION_DIR,`${a}.ts`),l=envKeysForAuth(o),u=await pathExists(c);if(!r.force&&u)return{slug:a,protocol:r.protocol,action:`skipped`,filePath:c,filesWritten:[],filesSkipped:[c],packageJsonUpdated:[],envKeysAdded:[],envKeysRequired:l};let d=[];if(o.kind===`connect`){let e=resolveVersionToken(`connectPackageVersion`,r.connectPackageVersion??DEFAULT_CONNECT_PACKAGE_VERSION);d.push(...await ensureConnectDependency(join(r.projectRoot,`package.json`),e))}await writeTextFile(c,renderTemplate(r.protocol,s,r.entry.description,o),{force:!0});let f=await seedEnvPlaceholders(join(r.projectRoot,`.env.local`),l),p={slug:a,protocol:r.protocol,action:u?`overwritten`:`created`,filePath:c,filesWritten:[c],filesSkipped:[],packageJsonUpdated:d,envKeysAdded:f,envKeysRequired:l};return u&&(p.filesOverwritten=[c]),p}async function listAuthoredConnections(e){let t=join(e,USER_AUTHORED_CONNECTION_DIR),n;try{n=await readdir(t,{withFileTypes:!0})}catch(e){if(e.code===`ENOENT`)return[];throw e}let r=[];for(let e of n){if(e.isFile()){let t=getSupportedModuleBaseName(e.name);t!==null&&r.push(t);continue}if(e.isDirectory())try{(await readdir(join(t,e.name))).some(e=>matchesSupportedModuleBaseName(e,`connection`))&&r.push(e.name)}catch{}}return r.sort()}export{ensureConnection,ensureConnectionDependencies,listAuthoredConnections};

package/docs/channels/custom.mdx

@@ -55,6 +55,25 @@ Declare routes with the `POST()` and `GET()` helpers. Each route handler receive
 
 Event handlers like `"message.completed"` are declared under the `events` key. They receive `(eventData, channel, ctx)`, where `eventData` is the event payload, `channel` carries platform handles and session continuation operations, and `ctx` is the eve `SessionContext`. Every channel kind shares this signature. The one exception is `session.failed`, which receives only `(eventData, channel)` with no `ctx`.
 
+## CORS
+
+Custom HTTP channels leave CORS untouched unless you opt in. Pass `cors: true`
+for permissive browser access with preflight handling, or pass a serializable
+CORS options object to narrow origins, methods, and headers:
+
+```ts
+import { defineChannel, POST } from "eve/channels";
+
+export default defineChannel({
+  cors: {
+    origin: ["https://app.example.com"],
+    methods: ["POST"],
+    allowHeaders: ["authorization", "content-type"],
+  },
+  routes: [POST("/message", async () => new Response("ok"))],
+});
+```
+
 ## WebSocket routes
 
 Use `WS()` when a custom channel needs a WebSocket endpoint. The route handler runs once per upgrade request and returns lifecycle hooks for that connection:

package/docs/channels/eve.mdx

@@ -12,7 +12,7 @@ import { eveChannel } from "eve/channels/eve";
 import { localDev, vercelOidc } from "eve/channels/auth";
 
 export default eveChannel({
-  auth: [localDev(), vercelOidc()],
+  auth: [vercelOidc(), localDev()],
 });
 ```
 
@@ -45,6 +45,29 @@ curl -N https://<deployment>/eve/v1/session/ses_01h.../stream
 
 See [Sessions, runs & streaming](../concepts/sessions-runs-and-streaming) for the full request and stream flow, including the complete event set.
 
+## CORS
+
+The eve channel leaves CORS untouched by default. Pass `cors: true` to enable
+permissive browser CORS with preflight handling, or pass an options object to
+narrow origins, methods, and headers. Route auth still runs on the actual
+session requests.
+
+Enable or narrow CORS only when browser clients call the channel directly:
+
+```ts title="agent/channels/eve.ts"
+import { eveChannel } from "eve/channels/eve";
+import { localDev, vercelOidc } from "eve/channels/auth";
+
+export default eveChannel({
+  auth: [vercelOidc(), localDev()],
+  cors: {
+    origin: "https://app.example.com",
+    methods: ["GET", "POST"],
+    allowedHeaders: ["authorization", "content-type"],
+  },
+});
+```
+
 ## Authentication
 
 The `auth` option decides who can call these routes. The built-in helpers cover development and trusted infrastructure:
@@ -54,7 +77,7 @@ The `auth` option decides who can call these routes. The built-in helpers cover
 
 Neither admits browser users or external clients in production. For a public app, wire the channel to your own auth (Clerk, Auth.js, your own OIDC/JWT verification, an API-key verifier, or any custom `AuthFn`). Vercel OIDC is optional; use it only when Vercel-issued deployment tokens are part of your trust model.
 
-`eve init` scaffolds an `agent/channels/eve.ts` with a production placeholder so you replace it before going live. The generated channel allows Vercel OIDC and localhost, and includes `placeholderAuth()`, which returns a setup-focused 401 in production until you swap it for real auth. Delete the file and eve falls back to `[localDev(), vercelOidc()]`, which still does not admit browser users in production.
+`eve init` scaffolds an `agent/channels/eve.ts` with a production placeholder so you replace it before going live. The generated channel checks Vercel OIDC before falling back to localhost access, and includes `placeholderAuth()`, which returns a setup-focused 401 in production until you swap it for real auth. Delete the file and eve falls back to `[vercelOidc(), localDev()]`, which still does not admit browser users in production.
 
 For the full auth model and helper list, see [Auth & route protection](../guides/auth-and-route-protection).
 
@@ -67,7 +90,7 @@ import { eveChannel, defaultEveAuth } from "eve/channels/eve";
 import { localDev, vercelOidc } from "eve/channels/auth";
 
 export default eveChannel({
-  auth: [localDev(), vercelOidc()],
+  auth: [vercelOidc(), localDev()],
   onMessage(ctx, message) {
     const callerId = ctx.eve.caller?.principalId ?? "anonymous";
     return {

package/docs/concepts/sessions-runs-and-streaming.md

@@ -84,6 +84,8 @@ curl -X POST http://127.0.0.1:3000/eve/v1/session/<sessionId> \
 
 The follow-up reuses the same durable session: same history, same state.
 
+If the session is waiting on a human-in-the-loop approval, a matching text reply such as `approve` or `deny` answers the approval. Other follow-up text is held until the approval is answered, so an unrelated message does not implicitly deny the pending tool call.
+
 For deterministic ordering, send one follow-up at a time and wait for the next `session.waiting` event before sending another message to the same session. See [message delivery and queueing](./execution-model-and-durability#message-delivery-and-queueing) for the current runtime contract.
 
 ## Reconnect and rewind
@@ -108,7 +110,7 @@ Start with the [TypeScript SDK](../guides/client/overview) guide. It covers basi
 curl http://127.0.0.1:3000/eve/v1/info
 ```
 
-The route uses the same default auth chain as the eve channel (`[localDev(), vercelOidc()]`). Locally it answers anonymously; a deployed Vercel target requires a valid OIDC bearer, with a same-project bypass for in-deployment callers. See [auth & route protection](../guides/auth-and-route-protection).
+The route uses the same default auth chain as the eve channel (`[vercelOidc(), localDev()]`). A local Vercel OIDC bearer takes precedence; other local requests fall back to development access. A deployed Vercel target requires a valid OIDC bearer, with a same-project bypass for in-deployment callers. See [auth & route protection](../guides/auth-and-route-protection).
 
 ## Dispatch order
 

package/docs/connections/mcp.mdx

@@ -1,21 +1,71 @@
 ---
 title: "MCP Connections"
-description: "Connect an eve agent to a remote MCP server and control which tools the model can discover."
+description: "Connect an eve agent to a remote MCP server, authorize it with Vercel Connect or static credentials, and control which tools the model can discover."
 ---
 
-MCP connections point eve at an MCP server you do not author. The server publishes its tools and schemas, and eve exposes matched tools to the model through `connection_search`.
+MCP connections point eve at a remote MCP server you do not author. The server publishes its tools and schemas, and eve exposes matching tools to the model through `connection_search`.
 
-Use MCP when the service already has an MCP server, when the server needs to own tool schemas dynamically, or when one connection should expose a family of related remote tools.
+Use MCP when the service already has an MCP server, when the server owns tool schemas dynamically, or when one connection should expose a family of related remote tools. Use an [OpenAPI connection](./openapi) instead when the service publishes an HTTP API contract and you want eve to generate one tool per operation.
 
 ## Define an MCP connection
 
-`defineMcpClientConnection` needs a `url` and a `description`:
+Create one file under `agent/connections/`. The filename becomes the runtime connection name, so `agent/connections/linear.ts` registers as `linear`, and discovered tools are called as `linear__<tool>`.
 
 ```ts title="agent/connections/linear.ts"
+import { connect } from "@vercel/connect/eve";
 import { defineMcpClientConnection } from "eve/connections";
 
 export default defineMcpClientConnection({
-  url: "https://mcp.linear.app/sse",
+  url: "https://mcp.linear.app/mcp",
+  description: "Linear workspace: issues, projects, cycles, and comments.",
+  auth: connect("mcp.linear.app/linear"),
+});
+```
+
+The `url` must speak Streamable HTTP or SSE. Write the `description` for the model, not for yourself: it is the main signal `connection_search` uses when deciding which connection to query.
+
+## Use Vercel Connect for OAuth
+
+For OAuth-backed MCP servers, prefer [Vercel Connect](https://vercel.com/docs/connect). Connect owns the browser consent flow, encrypted token storage, refresh, and project access. The `connect()` helper from `@vercel/connect/eve` plugs that lifecycle into eve's connection auth, so credentials never land in model context or conversation history.
+
+From the Vercel project or agent app that will run the connection:
+
+```bash
+npm install @vercel/connect
+vercel link
+vercel connect create mcp.linear.app --name linear
+vercel connect attach <connector-uid> --yes
+vercel env pull
+```
+
+Use the connector UID returned by the CLI in `connect("<connector-uid>")`. For Linear, the MCP runtime endpoint is `https://mcp.linear.app/mcp`, while the managed Connect service identifier is `mcp.linear.app`; those are related but not interchangeable.
+
+By default, `connect("...")` is user-scoped. The first tool call for a new user emits an `authorization.required` event with a URL to visit, parks the turn, and resumes after the callback completes. The active eve session must already have a user principal from route auth or from a platform channel. If there is no authenticated user, the connection fails with `reason: "principal_required"`.
+
+If the MCP server should act as the agent itself instead of the signed-in user, make the connector app-scoped:
+
+```ts title="agent/connections/linear.ts"
+import { connect } from "@vercel/connect/eve";
+import { defineMcpClientConnection } from "eve/connections";
+
+export default defineMcpClientConnection({
+  url: "https://mcp.linear.app/mcp",
+  description: "Linear workspace: issues, projects, cycles, and comments.",
+  auth: connect({ connector: "mcp.linear.app/linear", principalType: "app" }),
+});
+```
+
+App-scoped Connect auth is non-interactive. eve asks Connect for one shared app token; if the connector is missing or cannot issue an app token, the tool call fails terminally so an operator can fix setup.
+
+## Static tokens and headers
+
+Use `auth.getToken` when you already have a bearer token, API key, service account token, or out-of-band OAuth flow. eve sends the returned token as `Authorization: Bearer <token>`.
+
+```ts title="agent/connections/linear.ts"
+import { defineMcpClientConnection } from "eve/connections";
+
+export default defineMcpClientConnection({
+  url: "https://mcp.linear.app/mcp",
   description: "Linear workspace: issues, projects, cycles, and comments.",
   auth: {
     getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }),
@@ -23,39 +73,131 @@ export default defineMcpClientConnection({
 });
 ```
 
-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.
+Use `headers` for non-Bearer auth schemes or extra server configuration:
+
+```ts title="agent/connections/private-docs.ts"
+import { defineMcpClientConnection } from "eve/connections";
+
+export default defineMcpClientConnection({
+  url: "https://docs.example.com/mcp",
+  description: "Internal docs: search pages, owners, and recent changes.",
+  headers: {
+    "X-Api-Key": process.env.DOCS_API_KEY!,
+  },
+});
+```
 
-The file path provides the connection name. `agent/connections/linear.ts` registers as `linear`, and remote tools appear as `linear__<tool>` after discovery.
+`auth` and `headers` can also be functions that receive the active session context. Use that when credentials, tenants, or routing depend on the caller.
+
+## No auth
+
+Omit `auth` and `headers` only for intentionally public or local-only servers:
+
+```ts title="agent/connections/local.ts"
+import { defineMcpClientConnection } from "eve/connections";
+
+export default defineMcpClientConnection({
+  url: "http://localhost:3001/mcp",
+  description: "Local dev MCP server.",
+});
+```
+
+Do not use a no-auth connection for sensitive third-party services unless another layer protects the endpoint.
 
 ## 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`:
+MCP servers can expose broad read and write surfaces. Narrow what the model can discover with exactly one of `tools.allow` or `tools.block`:
 
 ```ts title="agent/connections/linear.ts"
+import { connect } from "@vercel/connect/eve";
 import { defineMcpClientConnection } from "eve/connections";
 
 export default defineMcpClientConnection({
-  url: "https://mcp.linear.app/sse",
-  description: "Linear: read-only.",
-  auth: { getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }) },
+  url: "https://mcp.linear.app/mcp",
+  description: "Linear: read issue and project data.",
+  auth: connect("mcp.linear.app/linear"),
   tools: { allow: ["search_issues", "get_issue"] },
 });
 ```
 
-Use `allow` for the smallest safe surface, especially on MCP servers that expose write tools alongside read tools. Use `block` only when the server has a broad stable surface and you need to hide a few tools.
+Prefer `allow` for the smallest safe surface, especially when the server exposes write tools. Use `block` when the server has a broad stable surface and only a few tools should be hidden.
+
+## Approval gates
+
+For MCP tools that can create, modify, delete, message, transmit, purchase, or access sensitive data, add a human approval gate:
+
+```ts title="agent/connections/linear.ts"
+import { connect } from "@vercel/connect/eve";
+import { defineMcpClientConnection } from "eve/connections";
+import { once } from "eve/tools/approval";
+
+export default defineMcpClientConnection({
+  url: "https://mcp.linear.app/mcp",
+  description: "Linear workspace.",
+  auth: connect("mcp.linear.app/linear"),
+  approval: once(),
+});
+```
+
+`once()` asks the first time in a session, `always()` asks on every tool call, and `never()` allows calls without approval. Authorization and approval work together: eve records approval before an OAuth park, then resumes without asking again for the same approved call.
+
+The `once()`, `always()`, and `never()` helpers from `eve/tools/approval` gate every tool the connection serves the same way. See [Connections](/docs/connections#per-connection-approval) for those, and [Human-in-the-loop](/docs/human-in-the-loop) for the full pause-and-resume contract.
+
+### Gate specific tools by name or input
+
+A remote MCP server usually mixes read tools with destructive or publishing ones, so a blanket `always()` would prompt on every harmless call. Pass a custom policy instead — the same [`Approval`](/docs/human-in-the-loop#approvals) shape authored tools use — to gate only the calls that matter. The policy receives `{ session, toolName, toolInput, approvedTools }` and returns an approval status, synchronously or as a promise.
+
+This connection always gates deletes, gates a publish only when the call actually schedules a post, and lets everything else through:
+
+```ts title="agent/connections/social.ts"
+import { defineMcpClientConnection } from "eve/connections";
+
+// Bare tool names whose effects are irreversible — always gate these.
+const DELETE_TOOLS = ["delete_draft", "delete_thread"];
+// Tools that can publish — gate only when the call schedules a post.
+const PUBLISH_TOOLS = ["create_draft", "edit_draft"];
+
+// Read `requestBody.publish_at` without trusting the input's shape.
+const publishesNow = (input: unknown): boolean => {
+  const body = (input as { requestBody?: { publish_at?: unknown } })?.requestBody;
+  return typeof body?.publish_at === "string" && body.publish_at.length > 0;
+};
+
+export default defineMcpClientConnection({
+  url: "https://mcp.example.com/mcp",
+  description: "Social publishing: draft, schedule, and manage posts.",
+  auth: { getToken: async () => ({ token: process.env.SOCIAL_API_KEY! }) },
+  approval: ({ toolName, toolInput }) => {
+    if (DELETE_TOOLS.some((t) => toolName.includes(t))) return "user-approval";
+    if (PUBLISH_TOOLS.some((t) => toolName.includes(t))) {
+      return publishesNow(toolInput) ? "user-approval" : "not-applicable";
+    }
+    return "not-applicable";
+  },
+});
+```
+
+Two details are specific to connection tools:
+
+- **`toolName` arrives qualified**, not as the bare remote name. An MCP tool surfaces to the policy as `<connection>__<tool>` (e.g. `social__delete_draft`), so match the bare tool name with `.includes()` or `.endsWith()` rather than `===`.
+- **`toolInput` is the raw input the model produced**, typed as `Record<string, unknown> | undefined`. With an authored tool you define the `inputSchema`, so its approval policy gets input typed and checked against your schema; a connection tool's schema is published by the remote MCP server, not you, so the shape is one you neither own nor can rely on. It is also `undefined` whenever the model's input isn't an object. Read nested fields defensively — as `publishesNow` does — instead of trusting the shape.
 
-## Auth, headers, and approval
+Return `"user-approval"` (or `true`) to pause for a person and `"not-applicable"` (or `false`) to run without a prompt; return `"approved"` or `"denied"` to decide automatically without involving anyone.
 
-MCP connections support the shared connection options:
+[Human-in-the-loop](/docs/human-in-the-loop#approvals) covers the full set of statuses, how `approvedTools` and `session.auth` factor in, and how a gated call pauses and resumes durably.
 
-- `auth` for static tokens, Vercel Connect, self-hosted interactive OAuth, or a per-caller provider resolver.
-- `headers` for static or per-caller API-key schemes and extra server configuration.
-- `approval` for human-in-the-loop gates before connection tools run.
+## Troubleshooting
 
-See [Connections](/docs/connections) for the shared auth, headers, and approval shapes.
+| Symptom                                    | Check                                                                                                                                     |
+| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `principal_required`                       | A user-scoped `connect("...")` ran without an authenticated user. Return `principalType: "user"` from route auth, or use app-scoped auth. |
+| The model does not find the remote tool    | Improve the connection `description`, then check `tools.allow` / `tools.block`.                                                           |
+| OAuth works locally but fails after deploy | Attach the Connect connector to the deployed Vercel project and verify the UID in `connect("...")`.                                       |
+| The server rejects requests                | Confirm the MCP URL, transport support, auth scheme, and any required headers.                                                            |
 
 ## What to read next
 
+- [Connections](../connections): shared auth, headers, approval, and per-caller patterns.
 - [OpenAPI connections](./openapi): generate tools from OpenAPI operations.
-- [Auth & route protection](../guides/auth-and-route-protection): the full interactive-OAuth flow with Vercel Connect.
+- [Auth & route protection](../guides/auth-and-route-protection): route auth and the full interactive OAuth lifecycle.
 - [Security model](../concepts/security-model): how connection credentials stay out of the model's reach.

package/docs/connections/openapi.mdx

@@ -1,13 +1,15 @@
 ---
 title: "OpenAPI Connections"
-description: "Turn an OpenAPI 3.x document into eve connection tools, one tool per operation."
+description: "Turn an OpenAPI 3.x or Swagger 2.0 document into eve connection tools, authorize calls, and control which operations the model can discover."
 ---
 
-OpenAPI connections turn any OpenAPI 3.x document into connection tools, one per operation. Use OpenAPI when a service already publishes an HTTP API contract and you want eve to derive the model-facing tools from that contract.
+OpenAPI connections turn an OpenAPI 3.x or Swagger 2.0 document into connection tools, one per operation. Use OpenAPI when a service publishes an HTTP API contract and you want eve to derive model-facing tools from that contract.
+
+Use an [MCP connection](./mcp) instead when the service already exposes an MCP server, when the server should own tool schemas dynamically, or when the remote service has richer MCP semantics than its raw HTTP API.
 
 ## Define an OpenAPI connection
 
-`defineOpenAPIConnection` takes an HTTPS URL that eve fetches at runtime, or an inline parsed object:
+Create one file under `agent/connections/`. The filename becomes the runtime connection name, so `agent/connections/petstore.ts` registers as `petstore`, and generated operation tools are called as `petstore__<operation>`.
 
 ```ts title="agent/connections/petstore.ts"
 import { defineOpenAPIConnection } from "eve/connections";
@@ -19,24 +21,120 @@ export default defineOpenAPIConnection({
 });
 ```
 
-Each operation becomes `<connection>__<operationId>` (e.g. `petstore__getInventory`). When an operation has no `operationId`, eve derives a deterministic `<method>_<sanitized-path>` name instead.
+Each operation becomes `<connection>__<operationId>`, for example `petstore__getInventory`. When an operation has no `operationId`, eve derives a deterministic `<method>_<sanitized-path>` name instead.
+
+`spec` can be an HTTPS URL that eve fetches at runtime, or an inline parsed OpenAPI object. Prefer a URL when the provider owns the contract and updates it; prefer an inline object for private APIs, generated specs you pin in source control, or small hand-authored contracts.
+
+## Base URL and servers
+
+eve resolves operation paths against `baseUrl` when you provide one. Otherwise, it derives the base URL from the spec:
+
+- OpenAPI 3.x: the first usable `servers` entry
+- Swagger 2.0: `schemes`, `host`, and `basePath`
+
+Use `baseUrl` when the spec is missing server data, points at the wrong environment, uses a relative server URL you do not want, or needs to be pinned for this agent.
+
+```ts title="agent/connections/crm.ts"
+import { defineOpenAPIConnection } from "eve/connections";
+
+export default defineOpenAPIConnection({
+  spec: "https://api.example.com/openapi.json",
+  baseUrl: "https://api.example.com",
+  description: "CRM accounts, contacts, and opportunities.",
+});
+```
+
+## Use Vercel Connect for OAuth
+
+For OAuth-backed APIs, prefer [Vercel Connect](https://vercel.com/docs/connect). Connect owns browser consent, encrypted token storage, refresh, and project access. The `connect()` helper from `@vercel/connect/eve` plugs that lifecycle into eve's connection auth, so tokens never reach model context or conversation history.
+
+Create or attach a connector for the API provider from the Vercel project or agent app that will run the connection:
+
+```bash
+npm install @vercel/connect
+vercel link
+vercel connect create github --name github
+vercel connect attach <connector-uid> --yes
+vercel env pull
+```
+
+Then use the connector UID returned by the CLI:
+
+```ts title="agent/connections/github.ts"
+import { connect } from "@vercel/connect/eve";
+import { defineOpenAPIConnection } from "eve/connections";
+
+export default defineOpenAPIConnection({
+  spec: "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json",
+  baseUrl: "https://api.github.com",
+  description: "GitHub repositories, issues, pull requests, and users.",
+  auth: connect("github/github"),
+});
+```
+
+By default, `connect("...")` is user-scoped. The active eve session must have a user principal from route auth or from a platform channel before the first operation call. If the API should act as the agent itself, make the connector app-scoped:
+
+```ts
+auth: connect({ connector: "github/github", principalType: "app" });
+```
+
+Use `tokenParams` on `connect(...)` when the provider requires explicit OAuth scopes, audiences, resource indicators, or authorization details.
+
+## Static tokens and headers
+
+Use `auth.getToken` when you already have a bearer token, API key, service account token, or out-of-band OAuth flow. eve sends the returned token as `Authorization: Bearer <token>`.
+
+```ts title="agent/connections/crm.ts"
+import { defineOpenAPIConnection } from "eve/connections";
+
+export default defineOpenAPIConnection({
+  spec: "https://api.example.com/openapi.json",
+  baseUrl: "https://api.example.com",
+  description: "CRM accounts, contacts, and opportunities.",
+  auth: {
+    getToken: async () => ({ token: process.env.CRM_TOKEN! }),
+  },
+});
+```
+
+Use `headers` for non-Bearer auth schemes, version headers, or tenant routing:
+
+```ts title="agent/connections/notion.ts"
+import { defineOpenAPIConnection } from "eve/connections";
+
+export default defineOpenAPIConnection({
+  spec: "https://developers.notion.com/openapi.json",
+  baseUrl: "https://api.notion.com",
+  description: "Notion pages, databases, comments, and users.",
+  headers: {
+    Authorization: `Bearer ${process.env.NOTION_API_KEY!}`,
+    "Notion-Version": "2022-06-28",
+  },
+});
+```
 
-The file path provides the connection name. `agent/connections/petstore.ts` registers as `petstore`, so operation tools are qualified under `petstore__`.
+`auth` and `headers` can also be functions that receive the active session context. Use that when credentials, tenants, or routing depend on the caller.
 
-## OpenAPI fields
+## Operation filters
 
-OpenAPI connections use the shared connection fields from [Connections](/docs/connections), plus two OpenAPI-specific fields:
+Most OpenAPI specs describe far more than the model should use. Narrow generated tools with exactly one of `operations.allow` or `operations.block`:
 
-| 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. |
+```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! }) },
+  operations: { allow: ["getInventory", "placeOrder"] },
+});
+```
 
-Use `baseUrl` when the spec's `servers` list is absent, points at the wrong environment, or needs to be pinned for this agent.
+Filters match `operationId`. If an operation does not declare one, use the deterministic name eve derives from the method and path.
 
 ## Path parameters
 
-When an operation path contains dynamic segments, declare each segment as an OpenAPI path parameter. eve exposes path, query, header, and cookie parameters as top-level tool inputs, then substitutes `in: "path"` values into the matching `{name}` placeholder before making the request.
+When an operation path contains dynamic segments, the spec must declare matching OpenAPI path parameters. eve exposes path, query, header, and cookie parameters as top-level tool inputs, then substitutes `in: "path"` values into the matching `{name}` placeholder before making the request.
 
 ```ts title="agent/connections/cart.ts"
 import { defineOpenAPIConnection } from "eve/connections";
@@ -48,12 +146,18 @@ export default defineOpenAPIConnection({
     openapi: "3.0.3",
     info: { title: "Cart API", version: "1.0.0" },
     paths: {
-      "/api/{dynamicsegment}/somethingelse": {
+      "/api/{cartId}/items/{itemId}": {
         get: {
-          operationId: "getSomethingElse",
+          operationId: "getCartItem",
           parameters: [
             {
-              name: "dynamicsegment",
+              name: "cartId",
+              in: "path",
+              required: true,
+              schema: { type: "string" },
+            },
+            {
+              name: "itemId",
               in: "path",
               required: true,
               schema: { type: "string" },
@@ -67,37 +171,30 @@ export default defineOpenAPIConnection({
 });
 ```
 
-The parameter `name` must exactly match the placeholder inside the path. If the spec omits the `in: "path"` parameter, the generated tool has no input for that segment and eve cannot fill it in from query parameters.
+The parameter `name` must exactly match the placeholder inside the path. If the spec omits an `in: "path"` parameter, the generated tool has no input for that segment and eve cannot fill it in from query parameters.
 
-## Operation filters
+## Approval gates
 
-To narrow which generated tools the model sees, set exactly one of `operations.allow` or `operations.block`:
+Generated operation tools can mutate state just like authored tools. Add an approval gate when operations can create, modify, delete, message, transmit, purchase, or access sensitive data:
 
-```ts title="agent/connections/petstore.ts"
+```ts title="agent/connections/crm.ts"
 import { defineOpenAPIConnection } from "eve/connections";
+import { once } from "eve/tools/approval";
 
 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! }) },
-  operations: { allow: ["getInventory", "placeOrder"] },
+  spec: "https://api.example.com/openapi.json",
+  baseUrl: "https://api.example.com",
+  description: "CRM accounts, contacts, and opportunities.",
+  auth: { getToken: async () => ({ token: process.env.CRM_TOKEN! }) },
+  approval: once(),
 });
 ```
 
-Filters match `operationId`. If an operation does not declare one, use the deterministic name eve derives from the method and path.
-
-## Auth, headers, and approval
-
-OpenAPI connections support the shared connection options:
-
-- `auth` for static tokens, Vercel Connect, self-hosted interactive OAuth, or a per-caller provider resolver.
-- `headers` for static or per-caller API-key schemes and extra server configuration.
-- `approval` for human-in-the-loop gates before generated operation tools run.
-
-See [Connections](/docs/connections) for the shared auth, headers, and approval shapes.
+Combine `approval` with `operations.allow` for the smallest practical surface.
 
 ## What to read next
 
+- [Connections](../connections): shared auth, headers, approval, and per-caller patterns.
 - [MCP connections](./mcp): connect to remote MCP servers.
-- [Auth & route protection](../guides/auth-and-route-protection): the full interactive-OAuth flow with Vercel Connect.
+- [Auth & route protection](../guides/auth-and-route-protection): route auth and the full interactive OAuth lifecycle.
 - [Security model](../concepts/security-model): how connection credentials stay out of the model's reach.

package/docs/connections/overview.mdx

@@ -110,7 +110,7 @@ import { defineMcpClientConnection } from "eve/connections";
 import { once } from "eve/tools/approval";
 
 export default defineMcpClientConnection({
-  url: "https://mcp.linear.app/sse",
+  url: "https://mcp.linear.app/mcp",
   description: "Linear workspace.",
   auth: { getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }) },
   approval: once(),
@@ -130,7 +130,7 @@ import { connect } from "@vercel/connect/eve";
 import { defineMcpClientConnection } from "eve/connections";
 
 export default defineMcpClientConnection({
-  url: "https://mcp.linear.app/sse",
+  url: "https://mcp.linear.app/mcp",
   description: "Linear workspace: issues, projects, cycles, and comments.",
   auth: connect("linear/myagent"),
 });
@@ -147,7 +147,7 @@ import { connect } from "@vercel/connect/eve";
 import { defineMcpClientConnection } from "eve/connections";
 
 export default defineMcpClientConnection({
-  url: "https://mcp.linear.app/sse",
+  url: "https://mcp.linear.app/mcp",
   description: "Linear workspace: issues, projects, cycles, and comments.",
   auth: connect({ connector: "linear/myagent", principalType: "app" }),
 });
@@ -176,7 +176,7 @@ import {
 } from "eve/connections";
 
 export default defineMcpClientConnection({
-  url: "https://mcp.linear.app/sse",
+  url: "https://mcp.linear.app/mcp",
   description: "Linear workspace.",
   auth: defineInteractiveAuthorization<{ verifier: string }>({
     // Probed before every tool call. Return a token to run the tool;