eve 0.12.2 → 0.13.0

package/docs/getting-started.mdx

@@ -38,10 +38,15 @@ The command:
 
 - Creates a child directory using the current workspace or launcher package manager, and uses eve's default model
 - Installs dependencies and initializes Git
-- Starts the development server and opens the interactive [terminal UI](./guides/dev-tui)
+- When a supported coding-agent REPL (Claude Code, Codex, Cursor, Droid, Gemini CLI, opencode, or Pi) is on `PATH`, asks whether to open an available REPL or start the development server; otherwise starts the server and opens the interactive [terminal UI](./guides/dev-tui)
 
 Type a message and watch the model loop run. Pass `--channel-web-nextjs` to add the Web Chat application. Every app ships the built-in HTTP channel (`agent/channels/eve.ts`) regardless.
 
+When you choose one of those REPLs, eve starts it with a project-specific
+prompt that guides the setup. The prompt distinguishes `eve dev`, which starts
+eve's HMR server and the agent's terminal REPL, from `eve dev --no-ui`, which is
+the controllable background mode for verification.
+
 `eve init` holds the terminal, so stop it with Ctrl+C to get your shell back before editing the generated agent. The command does not create a Vercel project or deploy.
 
 To add eve to an existing project, run `eve init .` from a directory that already has a `package.json` and no `agent/` files yet. eve adds the missing `eve`, `ai`, and `zod` dependencies without touching anything else the project owns. The eve dependency and the Node engine come from the same release. eve pins `engines.node` to the lowest major that release supports (for example `24.x`). It keeps an existing range only when every version that range allows stays within that major; otherwise it replaces the range and prints a warning.
@@ -186,10 +191,10 @@ See [Sessions, runs and streaming](./concepts/sessions-runs-and-streaming) for t
 
 If a coding agent (Claude Code, Cursor, and the like) is doing the setup, hand it this prompt:
 
-<CopyPrompt text="Set up an eve agent for the user. eve is a filesystem-first TypeScript framework for durable agents, published as the npm package eve. Read its docs: once eve is installed they are bundled in the package at node_modules/eve/docs; before eve is installed, read the published Introduction and Getting Started pages. If the project has no eve app, scaffold one with `npx eve@latest init <name>`; add `--channel-web-nextjs` only when the user wants Web Chat. The init command installs dependencies, initializes Git, and starts the dev server, so run it in a controllable process and stop it with Ctrl+C before editing. To add eve to an existing app, run `eve init .`, or install the dependencies by hand with `npm install eve@latest ai zod` (init adds ai and zod; the by-hand path needs all three). Make sure agent/agent.ts and agent/instructions.md exist, then add a first typed tool at agent/tools/get_weather.ts using defineTool from eve/tools with a Zod inputSchema and an inline execute. Start the dev server again, then exercise the HTTP API: create a session with POST /eve/v1/session, attach to GET /eve/v1/session/:id/stream, and send a follow-up with the returned continuationToken. Verify with the project's typecheck, adapt model and provider choices to the project, and do not commit unless the user asks.">
+<CopyPrompt text="Set up an eve agent for the user. eve is a filesystem-first TypeScript framework for durable agents, published as the npm package eve. Read its docs: once eve is installed they are bundled in the package at node_modules/eve/docs; before eve is installed, read the published Introduction and Getting Started pages. If the project has no eve app, scaffold one with `npx eve@latest init <name>`; add `--channel-web-nextjs` only when the user wants Web Chat. In a coding-agent launch, init installs dependencies and prints the project-specific dev command instead of starting the interactive terminal UI. A fresh project also initializes Git; an existing app keeps its repository and scripts. To add eve to an existing app, run `eve init .`, or install the dependencies by hand with `npm install eve@latest ai zod` (init adds ai and zod; the by-hand path needs all three). Make sure agent/agent.ts and agent/instructions.md exist, then add a first typed tool at agent/tools/get_weather.ts using defineTool from eve/tools with a Zod inputSchema and an inline execute. Start eve in a controllable background process with `npx eve dev --no-ui`, wait for the server URL, then exercise the HTTP API: create a session with POST /eve/v1/session, attach to GET /eve/v1/session/:id/stream, and send a follow-up with the returned continuationToken. Stop the dev process after verification. Verify with the project's typecheck, adapt model and provider choices to the project, and do not commit unless the user asks.">
   Set up an eve agent: read the eve docs (bundled at node_modules/eve/docs once eve is
   installed), scaffold with `npx eve@latest init <name>` (or `npm install eve@latest ai zod` in an existing app), add
-  a typed tool at agent/tools/get_weather.ts, run it with `npm run dev`, then create a session, stream
+  a typed tool at agent/tools/get_weather.ts, run it with `npx eve dev --no-ui`, then create a session, stream
   it, and send a follow-up.
 </CopyPrompt>
 

package/docs/guides/auth-and-route-protection.md

@@ -222,7 +222,7 @@ Route auth does not enforce session ownership. If multiple users or tenants can
 
 ## Tool and connection auth
 
-Tool and connection auth is how your agent reaches an external service that wants an interactive sign-in, like an OAuth MCP server. Both a connection and an individual tool can declare an `auth` strategy; eve drives the sign-in, caches the token per step, and re-runs the call once the caller authorizes.
+Tool and connection auth is how your agent reaches an external service that wants an interactive sign-in, like an OAuth MCP server. Connections declare `auth` on the connection definition. Tools should resolve providers inline with `ctx.getToken(provider)` and call `ctx.requireAuth(provider)` only when a downstream service rejects a token; eve drives the sign-in, caches the token per step, and re-runs the call once the caller authorizes.
 
 ### On a connection
 
@@ -236,7 +236,7 @@ import { once } from "eve/tools/approval";
 export default defineMcpClientConnection({
   url: "https://mcp.linear.app/mcp",
   description: "Linear: project management, issue tracking, and team workflows.",
-  auth: connect("oauth/linear"),
+  auth: connect("linear/myagent"),
   approval: once(),
 });
 ```
@@ -245,19 +245,20 @@ The first call that needs the connection kicks off an OAuth sign-in, surfaced as
 
 ### On a single tool
 
-When one tool calls a service behind OAuth, it can declare its own `auth` and skip the separate connection. `auth` takes the same shapes: `connect("...")` for Vercel Connect-backed OAuth, a custom interactive definition, or a plain `{ getToken }` for static credentials.
+When one tool calls a service behind OAuth, keep the auth provider at the call site and skip the separate connection. Providers take the same shapes as connection `auth`: `connect("...")` for Vercel Connect-backed OAuth, a custom interactive definition, or a plain `{ getToken }` for static credentials.
 
 ```ts title="agent/tools/list_okta_groups.ts"
 import { defineTool } from "eve/tools";
 import { connect } from "@vercel/connect/eve";
 import { z } from "zod";
 
+const oktaAuth = connect("okta/myagent");
+
 export default defineTool({
   description: "List the caller's Okta groups.",
   inputSchema: z.object({}),
-  auth: connect("okta"),
   async execute(_input, ctx) {
-    const { token } = await ctx.getToken();
+    const { token } = await ctx.getToken(oktaAuth);
     const res = await fetch("https://api.okta-proxy.internal/groups", {
       headers: { authorization: `Bearer ${token}` },
     });
@@ -266,14 +267,60 @@ export default defineTool({
 });
 ```
 
-Declaring `auth` adds two accessors to the tool's `ctx`:
+This same inline shape naturally handles tools that need more than one credential:
+
+```ts title="agent/tools/sync_ticket.ts"
+import { connect } from "@vercel/connect/eve";
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+
+const githubAuth = connect("github/myagent");
+const linearAuth = connect("linear/myagent");
+
+export default defineTool({
+  description: "Sync GitHub context into Linear.",
+  inputSchema: z.object({ issueId: z.string() }),
+  async execute({ issueId }, ctx) {
+    const { token: githubToken } = await ctx.getToken(githubAuth);
+    const { token: linearToken } = await ctx.getToken(linearAuth);
+
+    const repo = await fetch("https://api.github.com/user/repos", {
+      headers: { authorization: `Bearer ${githubToken}` },
+    });
+    if (repo.status === 401) ctx.requireAuth(githubAuth);
+
+    return updateLinearIssue(issueId, linearToken, await repo.json());
+  },
+});
+```
+
+Configure provider-specific OAuth targeting on the provider itself. For Vercel Connect, pass `tokenParams` to `connect(...)` when you need explicit OAuth scopes, resource indicators, or rich authorization requests:
+
+```ts
+const githubAuth = connect({
+  connector: "github/myagent",
+  tokenParams: {
+    authorizationDetails: [
+      {
+        type: "github_app_installation",
+        org: "acme",
+        repositories: ["agent-runtime"],
+      },
+    ],
+  },
+});
+```
+
+The tool's `ctx` exposes provider-scoped auth accessors:
+
+- `ctx.getToken(provider, options?)` resolves an inline provider such as `connect("github/myagent")`. It uses the same cache, callback, and sign-in machinery as connection auth, scoped to that provider's tool-qualified auth key.
+- `ctx.requireAuth(provider, options?)` evicts the cached token for that inline provider and starts a fresh authorization challenge. Use it after a downstream `401` rejects a token returned by `ctx.getToken(provider)`.
 
-- `ctx.getToken()` resolves the bearer for the declared strategy, checking the per-step token cache first. With an interactive strategy, a cache miss suspends the turn on a framework-owned callback URL, shows a "Sign in" affordance, and re-runs the tool once the OAuth callback completes.
-- `ctx.requireAuth()` throws `ConnectionAuthorizationRequiredError` to gate the tool on authorization before any token resolves. The runtime turns that into the same consent prompt.
+Throw `ConnectionAuthorizationRequiredError` from an inline provider's `getToken` to trigger the consent flow for that provider. If a downstream request later rejects an already-resolved token, call `ctx.requireAuth(provider)` to evict and re-authorize it.
 
-Throw `ConnectionAuthorizationRequiredError` anywhere in `execute` (directly, via `requireAuth()`, or implicitly from `getToken()`) and you trigger the consent flow, keyed by the tool's name. Calling either accessor on a tool that does not declare `auth` throws.
+Vercel Connect providers usually supply their own display name in the authorization challenge. Set `displayName` in the inline options only when you need to override what users see, for example `ctx.getToken(customAuth, { displayName: "Salesforce" })`. It is presentation-only.
 
-By default the sign-in affordance title-cases the tool's path-derived name, so a tool file named `sfdc_lookup.ts` renders "Sign in with Sfdc_lookup". Set `displayName` on the `auth` definition to control what users see instead, for example `auth: { ...connect("sfdc"), displayName: "Salesforce" }`. It is presentation-only. The tool's name still keys the authorization scope, token cache, and callback URL, and a definition-level `displayName` wins over one the strategy stamps on the challenge.
+Inline providers derive a stable tool-qualified auth key from Vercel Connect metadata when available. If you pass multiple custom providers that do not carry provider metadata, give each one an explicit auth key, for example `ctx.getToken(auth, { authKey: "github" })`. This `authKey` controls eve's cache and callback keys; it is not an OAuth scope.
 
 ## What to read next
 

package/docs/guides/dev-tui.md

@@ -22,7 +22,7 @@ If agent discovery reported problems, an error and warning count renders between
 
 The conversation streams straight into your terminal's normal scrollback, so you keep native scrolling, copy and paste, and a transcript that persists after you exit. The scrollback holds your prompts, the agent's replies, reasoning, tool calls, nested subagents, connection-authorization prompts, and any captured `stdout`, `stderr`, or sandbox lifecycle lines.
 
-Each turn renders without boxes. A colored gutter glyph marks who is speaking, tool calls collapse to a one-line summary (`✓ get_weather  city="SF" → 73°F`), and a subagent's work is indented beneath its `◆` header. When input is ready, the prompt stays bare until you type. While a turn or setup action owns the terminal, only its live status shows.
+Each turn renders without boxes. A colored gutter glyph marks who is speaking, tool calls collapse to a one-line summary (`✓ get_weather  city="SF" → 73°F`), and a subagent's work is indented beneath its `◆` header. When input is ready, the prompt stays bare until you type. A green circle-dot pulses while the agent is waiting to answer and disappears when reasoning or answer content begins.
 
 A persistent line beneath the prompt or status shows the model, the session's token flow (`↑ 394.4K ↓ 4.3K`), the linked Vercel project and team (`▲ my-agent (acme)`), and a yellow `/deploy pending` marker once a channel added this session still needs `/deploy`. The Vercel segment stays hidden until the directory is linked.
 
@@ -30,7 +30,7 @@ Errors render compactly with docs links highlighted. A code bug escaping your ag
 
 ## Slash commands
 
-Each command echoes as an invocation line, asks through a bordered panel that takes the input area's place (one question at a time, separate from the chat transcript), and finishes with a one-line `⎿` result. Loading states stay on the ephemeral status line instead of piling into the transcript. Setup menus render the selected option with a filled arrow and an inverse label padded by one space on each side. The label is blue normally and yellow for warning rows.
+Each command echoes as an invocation line, asks through a bordered panel that takes the input area's place (one question at a time, separate from the chat transcript), and finishes with a one-line `⎿` result. Loading states stay on the ephemeral status line instead of piling into the transcript; model and channel setup use the same green square pulse as the build phase. Setup menus render the selected option with a filled arrow and an inverse label padded by one space on each side. Text prompts use a blinking block cursor over the character at the caret. The selected label is blue normally and yellow for warning rows.
 
 | Command     | Does                                                                                                                              |
 | ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
@@ -48,7 +48,7 @@ Each command echoes as an invocation line, asks through a bordered panel that ta
 
 Bare `/model` opens the configure menu. When no provider is configured, it opens the provider questions directly; Esc returns to the configure menu. "Change model" runs the same searchable model picker setup uses (the Vercel AI Gateway catalog, pre-selected on the model the runtime is serving). A model change is written into your agent's authored source, and the command reports success only after eve confirms the new id. `/model <provider/model-id>` applies one directly, skipping the menu.
 
-The provider row opens the provider questions: which model provider to use, and how to connect. Picking something other than Vercel AI Gateway shows wiring instructions for your own provider and stops there, leaving any existing setup untouched. For Vercel AI Gateway, you either paste your own `AI_GATEWAY_API_KEY` (saved straight to `.env.local`) or connect via a project. Connecting via a project asks for a Vercel team, opens that team's existing-project list (picking again re-links), then pulls the project's environment so an AI Gateway credential lands in `.env.local`. The dev TUI reloads env files, re-reads the runtime's model endpoint, and clears the setup warning automatically; no restart is needed.
+The provider row opens the provider questions: which model provider to use, and how to connect. Picking something other than Vercel AI Gateway shows wiring instructions for your own provider and stops there, leaving any existing setup untouched. For Vercel AI Gateway, you either paste your own `AI_GATEWAY_API_KEY` (saved straight to `.env.local`) or connect via a project. Connecting via a project asks for a Vercel team, opens that team's recent projects, and lets you search all projects for older matches. Vercel links the selected project, eve verifies its project ID, then pulls its environment into `.env.local`. The dev TUI reloads env files, re-reads the runtime's model endpoint, and clears the setup warning automatically; no restart is needed.
 
 The provider row demands attention (a bold yellow "Configure provider" with "Required to enable the agent") until a link or gateway credential is detected, then names the connection afterward (for example "AI Gateway (Linked to my-project in my-team)"). Each action's latest outcome stays visible beneath the menu (for example "✓ Model changed to openai/gpt-5.5"). When a turn fails because AI Gateway authentication is missing or stale, the error points you at `/model` directly.
 

package/docs/reference/cli.md

@@ -33,9 +33,9 @@ The optional `target` decides the mode:
 
 - A name (`eve init my-agent`) scaffolds a fresh project in a new `my-agent/` directory.
 - An existing directory, including `.` for the current one (`eve init .`), adds an agent to that project. The project needs a `package.json`, the `agent/` files must not exist yet, and the missing `eve`, `ai`, and `zod` dependencies are added without touching anything else.
-- Omitting the target scaffolds or updates the current directory, the same as `eve init .`.
+- Omitting the target scaffolds or updates the current directory, the same as `eve init .`. The exception is a coding agent (Claude Code, Cursor, and the like): running `eve init` with no target prints a setup guide instead of scaffolding, since a bare invocation means the agent has not chosen what to build yet.
 
-Either mode installs dependencies, initializes Git, and runs `eve dev` through the detected project package manager. Fresh projects inherit a parent workspace manager when one is present; otherwise they use the manager that launched `eve init`.
+Both scaffold modes install dependencies. A fresh project initializes Git; an existing project keeps its repository and scripts. On an interactive human terminal, when a supported coding-agent CLI (`claude`, `codex`, `cursor-agent`, `droid`, `gemini`, `opencode`, or `pi`) is on `PATH`, `eve init` offers the available REPLs and `eve dev` (the default). Each REPL receives a project-specific prompt that guides the user through building the agent. It also explains that bare `eve dev` starts HMR and the agent's terminal REPL, while `eve dev --no-ui` is the controllable verification path. Without any of those executables, human invocations run `eve dev` through the detected project package manager. Fresh projects inherit a parent workspace manager when one is present; otherwise they use the manager that launched `eve init`. Coding-agent invocations print the same project-specific handoff, and the agent can run that command with `--no-ui` for headless verification.
 
 | Flag                   | Type | Default | Description                                                                                                                            |
 | ---------------------- | ---- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
@@ -119,7 +119,7 @@ Local dev keeps immutable runtime source snapshots under `.eve/dev-runtime/snaps
 eve link
 ```
 
-Links the current directory to an existing Vercel project. You select a team and then a project, and eve pulls the project's environment so an AI Gateway credential (`VERCEL_OIDC_TOKEN` or `AI_GATEWAY_API_KEY`) lands in `.env.local`, then verifies one actually did. Running it again re-links: the pickers always run, and the new choice wins. The command is interactive only; in CI, use `vercel link --project <name> --yes` instead. A running `eve dev` reloads env files automatically, so you don't need to restart after the pull.
+Links the current directory to an existing Vercel project. You select a team and then one of its recent projects; type a project name and choose **Search for '<name>'** to search the rest of that team's projects. Vercel links the selected project, eve verifies its project ID, and then pulls the project's environment so an AI Gateway credential (`VERCEL_OIDC_TOKEN` or `AI_GATEWAY_API_KEY`) lands in `.env.local`. Running it again re-links: the pickers always run, and the new choice wins. The command is interactive only; in CI, use `vercel link --project <name> --yes --non-interactive` instead. A running `eve dev` reloads env files automatically, so you don't need to restart after the pull.
 
 ## `eve deploy`
 

package/docs/reference/typescript-api.md

@@ -56,13 +56,13 @@ A few non-`define*` helpers round out the set: `disableTool` and `ExperimentalWo
 
 `ctx` is passed to your tool `execute`, hook handlers, and channel event handlers. It is live only while authored code is running, so reaching for it at module top level throws. See [Session context](../guides/session-context) for the full model.
 
-| Member                     | Use                                                                           |
-| -------------------------- | ----------------------------------------------------------------------------- |
-| `ctx.session`              | Current session, turn, auth, and optional parent lineage (read-only)          |
-| `ctx.getSandbox()`         | Live sandbox handle for the current agent                                     |
-| `ctx.getSkill(identifier)` | Handle for a named skill visible to the current agent                         |
-| `ctx.getToken()`           | Resolve the bearer token for a tool's declared `auth` (throws without `auth`) |
-| `ctx.requireAuth()`        | Force the tool's authorization flow before proceeding                         |
+| Member                      | Use                                                                          |
+| --------------------------- | ---------------------------------------------------------------------------- |
+| `ctx.session`               | Current session, turn, auth, and optional parent lineage (read-only)         |
+| `ctx.getSandbox()`          | Live sandbox handle for the current agent                                    |
+| `ctx.getSkill(identifier)`  | Handle for a named skill visible to the current agent                        |
+| `ctx.getToken(provider)`    | Resolve a bearer token for an inline auth provider such as `connect("...")`  |
+| `ctx.requireAuth(provider)` | Evict and re-authorize an inline provider, commonly after a downstream `401` |
 
 ## Imports at a glance
 

package/package.json

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

package/dist/src/cli/commands/init-agent-handoff.md

@@ -1,12 +0,0 @@
-Before editing the scaffold, read the relevant guide in
-`{{projectPath}}/node_modules/eve/docs/`.
-
-Then open `{{projectPath}}/agent/instructions.md` and replace the placeholder
-with what the user said the agent should do (the purpose you collected). This
-is the agent's always-on system prompt.
-
-Do not start `eve dev` because it is interactive. Give the user this command to
-run when they are ready:
-
-    cd {{projectPath}}
-    {{devCommand}}

package/dist/src/cli/commands/init-agent-instructions.md

@@ -1,16 +0,0 @@
-# Set up an eve agent
-
-Ask the user these questions one at a time. Use the coding harness's prompt
-tools when available. Do not guess.
-
-1. What should the agent do?
-2. Create a new project or add the agent to an existing directory?
-   For a new project, propose a name and ask the user to confirm it. For an
-   existing project, ask for the directory.
-3. For a new project, include Web Chat?
-
-Then run:
-
-    {{initCommand}} <target>
-
-Add `--channel-web-nextjs` if the user wants Web Chat.