eve 0.12.2 → 0.12.3

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,62 @@ 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 instead of the tool's legacy top-level `auth`.
+- `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)`.
+
+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.
 
-- `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.
+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.
 
-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.
+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.
 
-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.
+Older tools may still declare a top-level `auth` field and call `ctx.getToken()` or `ctx.requireAuth()` without arguments. That compatibility path is deprecated; prefer inline providers for new tools.
 
 ## 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                                                                                                                              |
 | ----------- | --------------------------------------------------------------------------------------------------------------------------------- |

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                                                                                                                            |
 | ---------------------- | ---- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |

package/docs/reference/typescript-api.md

@@ -56,13 +56,15 @@ 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` |
+| `ctx.getToken()`            | Deprecated compatibility path for a tool's legacy top-level `auth`           |
+| `ctx.requireAuth()`         | Deprecated compatibility path for a tool's legacy top-level `auth`           |
 
 ## Imports at a glance
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve",
-  "version": "0.12.2",
+  "version": "0.12.3",
   "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.