eve 0.31.3 → 0.32.0

package/docs/channels/slack.mdx

@@ -1,31 +1,26 @@
 ---
 title: "Slack"
-description: "Reach your agent from Slack app mentions and DMs, with thread anchoring, buttons, and Vercel Connect credentials."
+description: "Reach your agent from Slack app mentions and DMs with Vercel Connect-managed credentials, threaded replies, and interactive buttons."
 type: integration
 ---
 
-The Slack channel puts your agent inside a workspace. It answers `@mentions` and DMs, replies in threads, shows typing indicators, and turns human-in-the-loop (HITL) prompts into buttons. Use it when the conversation should happen where your team already works. Credentials run through [Vercel Connect](../guides/auth-and-route-protection), which handles both the outbound bot token and inbound webhook verification, so there's no `SLACK_BOT_TOKEN` or `SLACK_SIGNING_SECRET` for you to manage. See [Channels](./overview) for the contract this builds on.
+The Slack channel puts your agent inside a workspace. It answers `@mentions` and DMs, replies in threads, shows typing indicators, and turns human-in-the-loop (HITL) prompts into buttons. [Vercel Connect](https://vercel.com/kb/guide/vercel-connect) is the recommended setup: it manages the Slack bot token, verifies inbound requests, supports token rotation and multiple workspace installations, and forwards events to your agent without copying Slack secrets into your project environment. If you cannot use Vercel Connect, you can provide the bot token and signing secret through environment variables. See [Channels](./overview) for the contract this builds on.
 
-## Set up Connect
+## Add the channel
 
-Create a Slack Connect client and copy its UID (e.g. `slack/my-agent`), then attach this project as the trigger destination at eve's Slack route:
+Run the guided setup from your agent project:
 
 ```bash
-npm install -g vercel@latest
-vercel connect create slack --triggers
-vercel connect detach <uid> --yes
-vercel connect attach <uid> --triggers --trigger-path /eve/v1/slack --yes
+eve add channel/slack
 ```
 
-The `create` step provisions a destination at the default Connect path. `detach` then `attach --trigger-path /eve/v1/slack` re-points the trigger at the eve Slack route, since eve does not serve the default Connect path. `--triggers` turns on Slack Event Subscriptions; without it, Slack never delivers `app_mention` or `message.im`. You can also create the client from the [Connect dashboard](https://vercel.com/d?to=/%5Bteam%5D/~/connect&title=Go+to+Connect).
+The command recommends Vercel Connect, then scaffolds `agent/channels/slack.ts` and installs any required dependency. Choose the environment-variable option only when you need to manage the Slack bot token and signing secret yourself.
 
-## Add the channel
+### Recommended: use Vercel Connect
 
-Scaffold the channel and its dependency with `eve add channel/slack`, or set it up by hand:
+Vercel Connect setup requires an authenticated Vercel CLI and a linked Vercel project. The guided flow creates or reuses a Slack connector, waits for you to install it in a workspace, and registers `/eve/v1/slack` as a trigger destination before writing the channel file.
 
-```bash
-npm install @vercel/connect
-```
+The generated channel resolves credentials at runtime:
 
 ```ts title="agent/channels/slack.ts"
 import { connectSlackCredentials } from "@vercel/connect/eve";
@@ -38,17 +33,93 @@ export default slackChannel({
 
 `connectSlackCredentials` returns `{ botToken, webhookVerifier }`, keeping token rotation, multi-workspace tenancy, and request verification inside Connect rather than your code.
 
-If eve cannot find an authenticated Vercel session, `eve add channel/slack` asks whether to set up Vercel Connect or use portable environment credentials. The portable option adds the required names to `.env.example`. Before deploying, appropriate values must be supplied to your runtime environment.
+### Manage Slack credentials yourself
+
+Use this fallback when the agent does not run on Vercel or Vercel Connect is unavailable. In the setup command, **Use portable credentials** is the environment-variable option; eve adds `SLACK_BOT_TOKEN` and `SLACK_SIGNING_SECRET` to `.env.example`.
+
+This option does not create or install the Slack app. Configure it in [Slack app settings](https://api.slack.com/apps):
+
+1. Add the `app_mentions:read` and `chat:write` bot scopes. Add `im:history` for DMs, `files:read` for inbound attachments, and `files:write` when the agent uploads files.
+2. Install or reinstall the app, copy its Bot User OAuth Token to `SLACK_BOT_TOKEN`, and copy the signing secret from **Basic Information** to `SLACK_SIGNING_SECRET`.
+3. Set both values in `.env.local` for local development or in the target runtime's environment, then start or deploy the agent at a public URL.
+4. Under **Event Subscriptions**, set the Request URL to `https://your-agent.example/eve/v1/slack`. Subscribe to `app_mention`, plus `message.im` for DMs.
+5. Under **Interactivity & Shortcuts**, use the same Request URL when the agent uses buttons or HITL prompts.
+
+Add the matching message events and history scopes if you also want unmentioned thread replies, as described in [Continue conversations without repeated mentions](#continue-conversations-without-repeated-mentions).
+
+## Deploy
+
+Deploy the production agent after the trigger destination and channel file are ready:
+
+```bash
+eve deploy
+```
+
+`eve deploy` deploys the linked Vercel project to production. The guided flow registers the trigger destination against the production branch, which is the Vercel CLI default. Manage trigger destinations separately in the Connect dashboard when you need a different branch or environment.
+
+## Test a preview branch with Vercel Connect
+
+Use a separate connector when you want preview Slack traffic isolated from production, then register the preview branch as a trigger destination:
+
+```bash
+npm install -g vercel@latest
+vercel connect create slack --name your-agent-preview --triggers
+vercel connect attach slack/your-agent-preview \
+  --environment preview \
+  --triggers \
+  --trigger-branch your-preview-branch \
+  --trigger-path /eve/v1/slack \
+  --yes
+```
+
+Run these commands from the linked project directory. `--environment preview` makes the connector credentials available to Preview deployments. `--trigger-branch` selects the branch that receives forwarded Slack webhooks.
+
+Select the matching connector at runtime instead of leaving the generated production UID hard-coded:
+
+```ts title="agent/channels/slack.ts"
+import { connectSlackCredentials } from "@vercel/connect/eve";
+import { slackChannel } from "eve/channels/slack";
+
+const connectorUid =
+  process.env.VERCEL_ENV === "preview" ? "slack/your-agent-preview" : "slack/my-agent";
+
+export default slackChannel({
+  credentials: connectSlackCredentials(connectorUid),
+});
+```
 
-### Deploy
+Creating a connector with triggers also registers a default production destination. Remove that destination from the Connect dashboard before treating the preview connector as isolated. The guided production setup does not restrict credential environments, so also set the production connector's project access to **Production** and the preview connector's access to **Preview** in the dashboard. `vercel connect detach` removes project token access, not trigger destinations. Vercel Connect supports up to three trigger destinations per connector; see the [Vercel Connect guide](https://vercel.com/kb/guide/vercel-connect) for current limits and environment guidance.
 
-Deploy once the trigger destination and channel file are ready:
+Slack must be able to reach the preview route without an interactive authentication challenge. For a Connect trigger, exempt the branch domain with a [Deployment Protection Exception](https://vercel.com/docs/deployment-protection/methods-to-bypass-deployment-protection/deployment-protection-exceptions) when that feature is available, or use an unprotected preview domain. For a Slack app that uses environment-variable credentials, append `?x-vercel-protection-bypass=your-generated-secret` to its event and interaction request URLs. Enabling [Protection Bypass for Automation](https://vercel.com/docs/deployment-protection/methods-to-bypass-deployment-protection/protection-bypass-automation) does not bypass a request unless the sender presents that secret.
+
+## Set up Vercel Connect manually
+
+To set up the connector outside the guided flow, create it, then register eve's Slack route with the linked project:
 
 ```bash
-VERCEL_USE_EXPERIMENTAL_FRAMEWORKS=1 vercel deploy --prod
+npm install -g vercel@latest
+vercel connect create slack --name your-agent --triggers
+vercel connect attach slack/your-agent \
+  --environment production \
+  --triggers \
+  --trigger-path /eve/v1/slack \
+  --yes
 ```
 
-`VERCEL_USE_EXPERIMENTAL_FRAMEWORKS=1` lets the Vercel CLI recognize eve as a framework during the build. eve's own setup commands set the same flag.
+`--triggers` enables Slack Event Subscriptions. The attach command registers eve's route in addition to the default destination created with the connector. Remove the default destination separately in the [Connect dashboard](https://vercel.com/d?to=/%5Bteam%5D/~/connect&title=Go+to+Connect). For an existing connector, skip `create` and attach the intended route directly.
+
+## Troubleshoot Slack delivery
+
+Check the delivery path in order so you can identify where a Slack event stops:
+
+| Symptom                                                               | Check                                                                                                                                                                                  | Next action                                                                                                                                                          |
+| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `eve add channel/slack` stops before scaffolding the channel          | Read the setup error for the failed Vercel login, project link, workspace install, connector lookup, or trigger registration step.                                                     | Resolve that step, then rerun `eve add channel/slack`.                                                                                                               |
+| Setup says it could not remove an existing trigger destination        | Check the connector's destinations in the Connect dashboard. `vercel connect detach` removes project token access, not trigger destinations.                                           | Edit or remove the stale destination in the dashboard, then register `/eve/v1/slack` with `vercel connect attach`.                                                   |
+| Mentions never reach the deployment                                   | Confirm that the connector trigger destination uses the intended project and branch, enables triggers, and points to `/eve/v1/slack`.                                                  | Edit or remove stale destinations in the Connect dashboard, then register the intended destination with `vercel connect attach`.                                     |
+| Mentions work but DMs or thread replies do not                        | Check the Slack app's Event Subscriptions and OAuth scopes. DMs require `message.im` and `im:history`; channel replies require the matching message event and history scope.           | Add the missing events or scopes, then reinstall the Slack app if Slack requires it.                                                                                 |
+| A preview request receives an authentication page or protection error | Check whether the branch domain is exempt or the direct Slack request URL includes `x-vercel-protection-bypass`. Slack cannot complete an interactive Vercel Authentication challenge. | Add a Deployment Protection Exception for the branch domain, or add the automation bypass query parameter to a Slack app that uses environment-variable credentials. |
+| The webhook reaches the deployment but the agent does not reply       | Open the project's Vercel runtime logs, then inspect the session in **Agent Runs** when your team has access.                                                                          | Use the first missing or failed stage to narrow the issue to channel dispatch, the agent run, or outbound Slack delivery.                                            |
 
 ## How the channel handles inbound events
 
@@ -71,6 +142,43 @@ Only the first available handler runs. A message hook returning `null` drops the
 
 `onInteraction(action, ctx)` separately handles `block_actions` callbacks not consumed by HITL. eve attaches the triggering Slack user id to the same model message as its text, preserving speaker attribution without profile lookups.
 
+#### Restrict who can invoke the agent
+
+A valid Slack signature proves that Slack sent the event. It does not decide which channel or person your agent should trust. Fail closed in the inbound handler before returning auth, especially when the app is installed in a shared Slack Connect channel:
+
+```ts title="agent/channels/slack.ts"
+import { connectSlackCredentials } from "@vercel/connect/eve";
+import { defaultSlackAuth, slackChannel, type SlackMessage } from "eve/channels/slack";
+
+const allowedChannels = new Set(["C01234567"]);
+const allowedUsers = new Set(["U01234567"]);
+
+function isAllowedUser(message: SlackMessage) {
+  const userId = message.author?.userId;
+  return Boolean(userId && allowedUsers.has(userId));
+}
+
+export default slackChannel({
+  credentials: connectSlackCredentials("slack/my-agent"),
+  onAppMention(ctx, message) {
+    if (!isAllowedUser(message) || !allowedChannels.has(message.channelId)) {
+      return null;
+    }
+    return { auth: defaultSlackAuth(message, ctx) };
+  },
+  onDirectMessage(ctx, message) {
+    if (!isAllowedUser(message)) return null;
+    return { auth: defaultSlackAuth(message, ctx) };
+  },
+});
+```
+
+Override every enabled inbound handler; leaving `onDirectMessage` out would retain eve's default DM behavior. Slack Connect can deliver events from external users, so authorize the explicit user and current channel IDs your policy expects. If access depends on organization membership, resolve it from Slack's shared-channel and user data instead of inferring it from the request signature.
+
+Keep authorization checks inside sensitive tools too. The inbound allowlist controls who can start a turn; tool-level checks control what that authenticated Slack principal may read or change.
+
+The allowlist above gates message-started turns. Built-in HITL buttons are handled before `onInteraction`, and the person who clicks supplies the Slack auth for the resumed session. Anyone who can interact with the Slack message can answer it. Put sensitive prompts in channels limited to the intended approvers, and re-check `ctx.session.auth.current` inside a sensitive tool before performing its side effect.
+
 #### Continue conversations without repeated mentions
 
 Use `onMessage` to handle explicit mentions and continue replies in threads with an active eve session:
@@ -106,6 +214,28 @@ async onMessage(ctx, message) {
 
 Like `threadContext`, this helper calls `conversations.replies` and requires the matching Slack history scope. It observes at most the first 50 messages of the thread, and a failed fetch is logged and swallowed, so the returned list may be empty or stale — treat an unexpected empty list as "don't route" rather than "no participants".
 
+#### Load prior thread messages
+
+You get the triggering mention by default, but not the earlier replies in the thread. Enable `threadContext` to fetch and inject them with every message attributed by stable Slack user id. Use `since: "last-agent-reply"` so repeated mentions inject only what is new:
+
+```ts
+import { slackChannel } from "eve/channels/slack";
+import { connectSlackCredentials } from "@vercel/connect/eve";
+
+export default slackChannel({
+  credentials: connectSlackCredentials("slack/my-agent"),
+  threadContext: { since: "last-agent-reply" },
+});
+```
+
+`since` sets the boundary for what each mention injects and accepts three values:
+
+- `"thread-root"` (the default): every prior message in the thread, on every mention. `threadContext: {}` behaves the same.
+- `"last-agent-reply"`: only messages after this installed agent's last reply, keeping repeated mentions incremental. Replies from other Slack bots do not move the boundary.
+- A predicate `(message: SlackThreadMessage) => boolean`: only messages after the last one it matches, such as "since the last message that mentioned a particular user".
+
+`threadContext` requires the matching Slack history scope. Thread helpers reuse messages already loaded within the same inbound handler, and overlapping refreshes share one `conversations.replies` request. Omit it when the agent should see only direct mentions. `loadThreadContextMessages` remains available when you need custom filtering or non-model processing of the raw thread messages.
+
 #### Cancel an active turn
 
 Message hooks (`onMessage`, `onAppMention`, and `onDirectMessage`) receive thread-bound session operations directly on `ctx`. Call `ctx.cancel({ turnId? })` before returning `{ auth }` to stop the current turn and queue the new Slack message as replacement input, producing a debounce-like experience:
@@ -211,26 +341,6 @@ const session = await ctx.resolveSession({ target });
 
 `onEvent` covers JSON `event_callback` deliveries only. URL verification, slash commands, and interactive payloads do not reach it. Add every desired event and required OAuth scope to the Slack app's Event Subscriptions configuration; eve can only handle events Slack sends.
 
-You get the triggering mention by default, but not the earlier replies in the thread. Enable `threadContext` to fetch and inject them with every message attributed by stable Slack user id. Use `since: "last-agent-reply"` so repeated mentions inject only what is new:
-
-```ts
-import { slackChannel } from "eve/channels/slack";
-import { connectSlackCredentials } from "@vercel/connect/eve";
-
-export default slackChannel({
-  credentials: connectSlackCredentials("slack/my-agent"),
-  threadContext: { since: "last-agent-reply" },
-});
-```
-
-`since` sets the boundary for what each mention injects and accepts three values:
-
-- `"thread-root"` (the default): every prior message in the thread, on every mention. `threadContext: {}` behaves the same.
-- `"last-agent-reply"`: only messages after this installed agent's last reply, keeping repeated mentions incremental. Replies from other Slack bots do not move the boundary.
-- A predicate `(message: SlackThreadMessage) => boolean`: only messages after the last one it matches, such as "since the last message that mentioned a particular user".
-
-`threadContext` requires the matching Slack history scope. Thread helpers reuse messages already loaded within the same inbound handler, and overlapping refreshes share one `conversations.replies` request. Omit it when the agent should see only direct mentions. `loadThreadContextMessages` remains available when you need custom filtering or non-model processing of the raw thread messages.
-
 ### Slack API calls outside a handler
 
 Inside webhook-side handlers (`onAppMention`, `onEvent`, `onInteraction`, `events`),
@@ -240,7 +350,7 @@ messages, for example, has no inbound Slack request. For that, call the
 same primitive the handle uses directly:
 
 ```ts
-import { callSlackApi, resolveSlackBotToken } from "eve/channels/slack";
+import { callSlackApi } from "eve/channels/slack";
 import { connectSlackCredentials } from "@vercel/connect/eve";
 
 const { botToken } = connectSlackCredentials("slack/my-agent");
@@ -309,6 +419,10 @@ Start a session without an inbound message through `ctx.to(slack, target).send(m
 
 Inbound files behind authenticated Slack URLs are staged with `fetchFile`. See [File uploads](./custom#file-uploads) for the `fetchFile` contract.
 
+Private file downloads require the Slack bot token's `files:read` scope. Add the scope and reinstall the Slack app before sending attachments.
+
+Staged files live in the session sandbox under `/workspace/attachments`. Session history keeps a reference to that path, not a second copy of the Slack file. If the backend can no longer reattach the original sandbox, eve cannot restore the attachment bytes from history; later turns receive a missing-file result. Store files outside the sandbox when the agent must retain them independently of sandbox availability.
+
 ## What to read next
 
 - [Channels overview](./overview): the channel contract and every built-in channel

package/docs/concepts/default-harness.md

@@ -60,7 +60,7 @@ Notes:
 - **`agent`** is available only in the root session. Its child uses the root's instructions, tools, connections, and sandbox, but starts with fresh conversation history and fresh [state](../guides/state). The child receives neither `agent` nor `Workflow`; declared subagents do not receive the built-in `agent` either. See [Subagents](../subagents).
 - **`load_skill`** only pulls instructions into context. It adds no new execution surface, because behavior still comes from the tools the agent already has.
 - **`connection_search`** surfaces a connection's tools by their qualified name (e.g. `linear__list_issues`), which the model can then call directly. It's registered only when the agent has connections.
-- **`web_search`** has no local executor; the provider runs it. AI Gateway models use Parallel by default. To use Exa instead, export `webSearch({ provider: "exa" })` from `agent/tools/web_search.ts`. Direct provider models continue to use their native search implementation. To supply your own implementation, override it with `defineTool()`.
+- **`web_search`** has no local executor; the provider runs it. AI Gateway models use Exa by default. To use Parallel instead, export `webSearch({ provider: "parallel" })` from `agent/tools/web_search.ts`. Direct provider models continue to use their native search implementation. To supply your own implementation, override it with `defineTool()`.
 
 Review these built-in tools before production use. Disable, wrap, restrict, or require approval for any tool that can access the filesystem, network, shell, or sensitive data.
 
@@ -88,10 +88,10 @@ Provider-managed web search has a dedicated configuration helper instead of an e
 ```ts title="agent/tools/web_search.ts"
 import { webSearch } from "eve/tools";
 
-export default webSearch({ provider: "exa" });
+export default webSearch({ provider: "parallel" });
 ```
 
-Set `provider` to `"parallel"` or `"exa"`. Without this file, AI Gateway models use Parallel.
+Set `provider` to `"exa"` or `"parallel"`. Without this file, AI Gateway models use Exa.
 
 ## Disable a default
 

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

@@ -150,7 +150,7 @@ curl -X POST http://127.0.0.1:2000/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.
+If the session is waiting on a human-in-the-loop approval, a matching text reply such as `approve` or `cancel` 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.
 
 If the session is waiting on `ask_question`, a follow-up message clears that pending request before the model continues. An exact option match or permitted freeform response answers the question; any other message marks the question unanswered and starts the follow-up turn.
 

package/docs/connections/mcp.mdx

@@ -214,6 +214,12 @@ Return `"user-approval"` (or `true`) to pause for a person and `"not-applicable"
 
 [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.
 
+## Control result size
+
+eve sends an MCP tool's returned content to the model as the tool result. MCP connections do not expose a per-result transform equivalent to an authored tool's [`toModelOutput`](/docs/tools#shape-what-the-model-sees-with-tomodeloutput).
+
+When a remote tool returns more data than the model needs, narrow the result at the MCP server. Prefer a purpose-built search or summary tool, or return a stable handle that another call can use to fetch a smaller slice. If you do not control the server and an equivalent upstream API is available, replace only that operation with an authored tool that stores the full payload outside model context and projects the needed fields through `toModelOutput`. Block the original MCP operation through [`tools.block`](#tool-filters) so the model does not see duplicate tools.
+
 ## Troubleshooting
 
 | Symptom                                    | Check                                                                                                                                     |

package/docs/guides/dev-tui.md

@@ -1,182 +1,98 @@
 ---
 title: "Dev TUI"
-description: "Drive an eve agent locally in an interactive terminal UI. Chat, stream, approve tools, answer questions, tune the display, and point it at a deployment."
+description: "Use eve locally or connect to a deployed agent from an interactive terminal UI."
 ---
 
-`eve dev` boots the local runtime and drops you into an interactive terminal UI. You chat with the agent, watch it stream, approve its tool calls, and answer the questions it asks back.
+`eve dev` starts a local development server and opens an interactive terminal UI. Use it to talk to your agent, approve tool calls, answer its questions, and configure local development.
 
 ```bash
 eve dev
 ```
 
-On startup the TUI prints a brand line with your agent's name, plus a rotating tip (local sessions only).
+The transcript remains in your terminal scrollback after you exit. Run `/help` in the UI to see the commands available in the current session.
 
-```text
- eve weather-agent
- Use /add to install integrations from the registry.
-```
-
-If agent discovery reported problems, an error and warning count renders between the two lines. Instructions, tools, skills, and subagents are one `eve info` away, and `/help` lists every command. The TUI also runs a startup check. A fresh `eve init` starts local `eve dev` with `/model` prefilled. That input starts onboarding: the flow installs the Vercel CLI if needed, asks you to log in if needed, opens `/model`, then offers categorized next steps for channels, connections, capabilities, and observability through the registry before the first prompt. Other `eve dev` sessions show missing setup as an attention line, with each command's outcome hanging under it on a `⎿` connector.
-
-## Reading the transcript
-
-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. 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 — with its authored reasoning level and a `↯` marker when the Gateway priority tier is on (`xai/grok-4.5@xhigh ↯`) — and the linked Vercel project. The Vercel segment stays hidden until the directory is linked. Local sessions lead with a gray `:port` badge. Remote sessions lead with a padded `↗ project (environment)` badge, or the host when Vercel cannot resolve the deployment. The badge is gray while checking or unavailable, yellow while authentication is required or failed, and blue when connected. Status segments separate with plain whitespace. Remote status lines omit AI Gateway endpoint state.
-
-Errors render compactly with docs links highlighted. A code bug escaping your agent's own code shows its stack trace dim beneath the error headline. Dev-server rebuilds condense into one status row that updates in place (`tui/setup-panel.ts changed · rebuilding…`, then `· rebuilt`); only the latest rebuild shows, and paths shrink to their last two components.
-
-## 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; model, registry, and the Vercel CLI commands (`/vc:install`, `/vc:login`) use the same green square pulse as the build phase, while `/deploy` keeps a spinner. A setup waiting for browser action changes that pulse and the word "browser" to yellow. 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                                                                                                                                                         |
-| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `/model`      | Opens a configure menu that loops until Done (or Esc). See [Configure the model and provider](#configure-the-model-and-provider).                            |
-| `/add`        | Adds an integration from the registry or an item address entered directly.                                                                                   |
-| `/deploy`     | Ships the agent to Vercel production, linking the directory first when it is unlinked.                                                                       |
-| `/vc:install` | Installs the Vercel CLI. Available locally and on a remote session.                                                                                          |
-| `/vc:login`   | Logs in to Vercel locally. On a remote session, resolves the deployment's project, refreshes its OIDC token, and confirms any required Trusted Sources rule. |
-| `/loglevel`   | Switches which logs the transcript shows. See [Control what logs show](#control-what-logs-show).                                                             |
-| `/traces`     | Opens the full-screen local trace viewer. See [Inspect traces](#inspect-traces).                                                                             |
-| `/reset`      | Starts a fresh session.                                                                                                                                      |
-| `/cancel`     | Cooperatively cancels the running turn while preserving the session and settled context.                                                                     |
-| `/clear`      | Clears model-message history while preserving the current session and its durable resources. `/new` is an alias.                                             |
-| `/compact`    | Queues context compaction for the current session without sending a message.                                                                                 |
-| `/exit`       | Quits the TUI.                                                                                                                                               |
-| `/help`       | Lists the commands available for the current local or remote session.                                                                                        |
-
-`/model`, `/add`, `/deploy`, and `/traces` manage the local agent or its linked project. They are available only when `eve dev` runs the server locally, not when connected to a remote server with `--url`.
-
-### Configure the model and provider
-
-Bare `/model` opens the configure menu; its Change model row summarizes the draft (`xai/grok-4.5@high ↯`). When no provider is configured, it opens the provider picker directly and Esc returns to the configure menu. "Change model" opens a value menu — **Model**, **Reasoning effort** (a `●─◉─○` track beside the drafted level), **Service tier** (`fast ↯` or `normal`), and **Done**. Reasoning and tier adjust in place: `←`/`→` (Tab acts as `→`) move the highlighted row's value as a ring — past the top wraps to the bottom and vice versa — sliding the reasoning track over the model's supported effort levels or flipping the tier. An unset reasoning draft shows an empty track; the first `→` enters the ring at the lowest level, `←` at the highest. Picking a model snaps a drafted level the new model cannot serve to its closest supported one, clearing it when the model has no adjustable reasoning. Enter on the Model row opens the searchable Vercel AI Gateway catalog as `▏`-railed model ids, pre-selected on the model the runtime is serving; Esc backs out without changing it. A model with no adjustable reasoning says so on a disabled row, and a model the catalog prices no priority tier for shows no tier row at all. The menu's Done hands the draft to the configure menu, whose own Done commits everything through one atomic edit of your agent's authored source, reporting success only after eve confirms the new id. A completed model or provider change closes the menu and returns its result to the transcript; Done without changes or Esc closes it without one, and Esc notes any discarded draft. `/model <provider/model-id>` applies one directly, skipping the menu.
-
-The provider row opens one menu: AI Gateway via a project, AI Gateway via `AI_GATEWAY_API_KEY`, or **Other providers**. The currently-active provider renders checked with its status beneath it ("Linked to **my-project** in team **my-team**", or "`AI_GATEWAY_API_KEY` set in `.env.local`"), and the cursor opens on it with a `↵ change` badge. The key option becomes a masked input on an `⎿` rail when highlighted, with a `↵ validate` badge after it. Enter validates it without replacing the menu — a `▪ validating` badge while it checks, a red `⨯ API key is not valid` badge on rejection; retrying or editing clears that result. With a non-empty key, the first Esc or Ctrl-C clears the input and the second dismisses the menu. An accepted key is saved to `.env.local` and reported as one `AI_GATEWAY_API_KEY set.` line. The project option asks for a Vercel team, opens that team's recent projects with the project named after your agent suggested first (searching the team for it when it is not among the recents), 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 **Other providers** option shows direct-provider wiring instructions and leaves the existing setup untouched. The dev server reloads env files and refreshes the status bar automatically, with no restart needed.
-
-The provider row demands attention (a bold yellow "Configure model access" with a yellow "Not configured" hint that dims when unselected and uses the terminal foreground when selected) until a link or gateway credential is detected, then names the connection afterward (for example "AI Gateway (Linked to my-project in my-team)"). Setup menus mark the cursor row with a padded, filled-arrow inverse label that inherits the row's accent: blue normally and yellow for warning rows. In stacked menus, the selected row's description appears directly beneath that option. The completed command's outcome stays in the transcript after the panel closes. When a turn fails because AI Gateway authentication is missing or stale, the error points you at `/model` directly.
-
-### Add registry integrations
-
-`/add` groups integrations by their role: **Channels** for where people talk to your agent, **MCP connections** for external services and data, **Extensions** for reusable capabilities, and **Observability** for tracing and evaluation. Pick a category to open its searchable catalog from the official eve registry and the registry namespaces configured in `package.json`, or browse every integration. Each result shows its source beside its name, such as `Vercel` or a configured registry namespace. Select a result to review its source, packages, environment variables, and target files before adding it, or enter an official item path, configured namespace address, or HTTP(S) URL directly in the search bar. After an add attempt finishes, the panel closes instead of returning to the catalog.
+## Commands
 
-MCP connection registry items install their definition and then configure Vercel Connect through the same `/add` flow. If the directory is unlinked, setup first offers to create or link a project. Run `eve add connection/<name>` for the equivalent CLI flow.
+| Command       | Description                                                                                           |
+| ------------- | ----------------------------------------------------------------------------------------------------- |
+| `/model`      | Configure the model and its provider. Pass a model ID to set it directly: `/model provider/model-id`. |
+| `/add`        | Browse and install channels, MCP connections, extensions, and observability integrations.             |
+| `/deploy`     | Deploy the agent to Vercel production. Links the directory first if needed.                           |
+| `/vc:install` | Install the Vercel CLI.                                                                               |
+| `/vc:login`   | Log in to Vercel or restore access to a remote deployment.                                            |
+| `/loglevel`   | Choose which server and agent logs appear in the transcript.                                          |
+| `/traces`     | Open the local trace viewer. Pass a trace ID prefix to open a specific trace.                         |
+| `/reset`      | Start a fresh session.                                                                                |
+| `/cancel`     | Cancel the current turn without discarding settled context.                                           |
+| `/clear`      | Clear the session's model-message history. `/new` is an alias.                                        |
+| `/compact`    | Compact the current session's context.                                                                |
+| `/exit`       | Quit the UI.                                                                                          |
+| `/help`       | List available commands.                                                                              |
 
-## Keyboard shortcuts
+`/model`, `/add`, `/deploy`, and `/traces` are available when `eve dev` runs locally. They are unavailable when the UI connects to a server with `--url`.
 
-Chat and freeform `ask_question` inputs behave like a shell line editor.
+## Work with the agent
 
-| Key                                            | Action                                                                                                            |
-| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `Enter`                                        | Submit the message or question response. While a turn is running, queue the message for the next turn.            |
-| `Esc`                                          | While a turn runs: pop the oldest queued message and steer with it; with nothing queued, cancel the turn.         |
-| `Shift+Enter`                                  | Insert a newline without sending (needs a terminal that reports modified keys).                                   |
-| `Ctrl+C`                                       | While a turn runs, behave like Esc. At the idle chat prompt, clear input and arm exit; press again to quit.       |
-| `↑` / `↓`                                      | Move between input lines; at a chat-buffer edge, navigate messages you have sent this session.                    |
-| `←` / `→`, `Home` / `End`, `Ctrl+A` / `Ctrl+E` | Move the caret; Home/End stay within the current line.                                                            |
-| `Ctrl+U` / `Ctrl+K` / `Ctrl+W`                 | Delete to the start of the line, to its end, or through the previous word.                                        |
-| `Ctrl+L`                                       | Cycle the log display mode (`none → all → stderr → sandbox → none`) and briefly show the mode in the status line. |
-| `Ctrl+R`                                       | Redraw the screen.                                                                                                |
+Type a message and press `Enter` to send it. When the agent asks a question or requests tool approval, respond in the prompt shown by the UI. Connection authorization can open a browser; keep local `eve dev` running until the browser returns to it.
 
-In terminals that support bracketed paste, pasting multi-line text into chat or a freeform question inserts it intact and renders one row per line rather than submitting at the first line. `Shift+Enter` adds a line by hand. The input grows down to the available terminal height, then scrolls to keep the caret visible; `Enter` submits the whole response.
+While a turn is running, `Enter` queues a follow-up message. Press `Esc` or `Ctrl+C` to cancel the turn; when messages are queued, this uses the oldest queued message as the next turn instead. At an idle prompt, press `Ctrl+C` twice to exit.
 
-### Queue and steer while the agent works
+| Key           | Action                                                                              |
+| ------------- | ----------------------------------------------------------------------------------- |
+| `Enter`       | Send the current message or answer.                                                 |
+| `Shift+Enter` | Insert a newline. Requires a terminal that reports modified keys.                   |
+| `Esc`         | Cancel a running turn, or steer with the oldest queued message.                     |
+| `Ctrl+C`      | Cancel or steer during a turn; clear input, then exit on a second press, when idle. |
+| `↑` / `↓`     | Move through input lines or sent-message history.                                   |
+| `Ctrl+L`      | Cycle log display modes.                                                            |
+| `Ctrl+R`      | Redraw the screen.                                                                  |
 
-Sending a message while a turn is still running does not interrupt it — the message joins a queue of up to five, pinned in a panel directly above the input with one line per message. When the turn ends, the queued messages coalesce into the next turn's message. Submit `/cancel` during a turn to cancel it immediately without queueing the command as model input; `/cancel` also works from the idle prompt when a prior stream disconnected while its server turn may still be running.
+## Logs and traces
 
-`Esc` and `Ctrl+C` steer instead of waiting: either key pops the oldest queued message, cancels the running turn cooperatively, and submits the popped message as the replacement turn. In the transcript, a steered message carries an accent `↑` on its own line above its gutter bar; a queued message that waited for the boundary carries it below. Any remaining messages stay queued behind it. With nothing queued, either key cancels the turn immediately. A cancelled turn ends cleanly on the server and the session keeps its context; the conversation picks up at the next prompt.
+By default, the UI shows `stderr` logs. Use `/loglevel <all|stderr|sandbox|none>` to change the display; bare `/loglevel` reports the current setting. `Ctrl+L` cycles the same modes.
 
-If a turn fails terminally (the server session dies or the connection drops), the TUI starts a fresh session and notes it inline so you can keep going. Server-side context resets with the old session. Messages still queued when a turn is interrupted or fails are restored into the next prompt's input instead of being sent blind.
+Every `eve dev` process writes diagnostic logs to `.eve/logs/`, regardless of the display mode. Read them with [`eve logs`](../reference/cli#eve-logs).
 
-## Answer the agent inline
+Use `/traces` to inspect traces recorded during local development. See [Instrumentation](instrumentation#local-traces) for trace capture and retention settings.
 
-When the agent needs something from you, the TUI asks inline.
+## Display options
 
-- Tool approvals are a `y` or `n`.
-- Option questions let you pick with `↑` / `↓` and `Enter`, or you can compose a multi-line freeform answer.
-- If a tool needs an authorized [connection](../connections), the URL shows up right in the transcript, and the turn picks back up once you finish the flow. The same local `eve dev` server owns the callback route, so keep that command running until the browser returns. `eve dev --url` connects to an already-running server and does not start a local callback host.
-
-## Control what logs show
-
-By default, `eve dev` shows `stderr` and keeps stdout and sandbox lines buffered but hidden. Captured server `stdout` and `stderr` render as dim, indented log runs behind a `│` rule (consecutive lines from the same source share one label), while sandbox lifecycle lines use their own label.
-
-- `/loglevel <all|stderr|sandbox|none>` switches what the transcript shows, retroactively. Bare `/loglevel` reports the current mode.
-- `--logs <all|stderr|sandbox|none>` sets the starting mode at launch (default `stderr`).
-- `Ctrl+L` at the idle prompt cycles `none → all → stderr → sandbox → none`.
-
-Every captured line, tool failure, workflow error, and eve framework log record also lands in a private per-process diagnostic log under `.eve/logs/`, regardless of the display mode. The file is JSON Lines: each line is one JSON record with `at` and `source` fields (framework log records add `level`, `namespace`, `message`, and `fields`), so it parses with any JSONL tool — `jq -c 'select(.source=="tool")'` — even when a payload spans many stack-trace lines. Long stderr output collapses in the transcript to a one-line summary pointing at the file (the raw text stays available in the `all` mode). Read the logs with `eve logs` — see the [CLI reference](../reference/cli#eve-logs).
-
-Each log has a same-named `.dump` sibling — one JSON document with environment diagnostics (eve, Node.js, and Vercel CLI versions, the Vercel CLI path, and the size of the local session store) plus running session stats: prompts, token usage, tool calls by name, and subagent dispatches. `eve logs --dump` prints the dump and the log together as one parseable report to attach when filing an issue.
-
-## Inspect traces
-
-`/traces` opens a full-screen viewer over the local trace spool (`.eve/traces/v1`) that `eve dev` writes while you chat — see [Local traces](instrumentation#local-traces). It reads the spool files directly and refreshes about once a second, so spans from the current session stream in live. The viewer takes over the terminal's alternate screen; closing it restores the transcript exactly where you left it.
-
-The viewer opens on your current session's trace (or the most recent one). It re-tells the trace as a chat-like flow of cards: the system prompt sits at the top as a collapsed card, then user and assistant messages (assistant cards carry model, duration, token, and gateway cost metadata), and tool calls show their inputs and results inline. Work a subagent performed appears in the same flow, ordered by when it happened — between the parent's dispatch step and its resumed reply — with a dim `subagent` badge (`subagent:<name>` when the dispatch named one) on every card of the delegated turn; the delegated prompt renders as a `task` card rather than a `user` message. Error spans paint their whole card red. The header names the agent, session, span count, and duration, plus a `● live` badge while spans are still landing. `/traces <trace>` opens a specific trace by id prefix.
-
-| Key       | Action                                                                   |
-| --------- | ------------------------------------------------------------------------ |
-| `↑` / `↓` | Move the card selection (scroll the attributes panel when it has focus). |
-| `←` / `→` | Expand / collapse the selected card (only cards with hidden content).    |
-| `Enter`   | Open the attributes panel for the selected card; close it when open.     |
-| `Tab`     | Move focus between the conversation and the attributes panel.            |
-| `[` / `]` | Cycle to the next / previous trace.                                      |
-| `Esc`     | Close the panel (or unfocus it), otherwise close the viewer.             |
-| `q`       | Close the viewer.                                                        |
-
-`←`/`→` or a mouse click expands a card to its full contents (the system prompt, long payloads) and collapses it back; cards that already fit have nothing to expand. The scroll wheel scrolls the conversation (or the attributes panel when the pointer is over it). Dragging with the mouse selects text — the selection highlights as you drag, and releasing copies it to your clipboard with a `Copied to clipboard` toast in the top-right corner; `Esc` cancels an in-flight selection. The attributes panel opens on the right and stays metadata-only — status, timing, ids, and the span's non-payload OTLP attributes — since the cards already carry the payloads. Model spans capture the system prompt, the prompt messages (rendered as a chat transcript), and the response (text, tool calls, finish reason); tool-call spans capture the call arguments and result, pretty-printed — each capped at 32 KB, with provider transport metadata stripped. When a conversation's messages exceed the cap, the oldest messages are dropped and the transcript notes how many were omitted. Set `EVE_TRACES_CONTENT=off` to stop capturing payload content. With no spans yet, the viewer shows an empty state and keeps watching; if tracing is disabled (`EVE_TRACES=off`) it says so instead.
-
-## Display flags
-
-Density flags control how much of each section renders. They accept `full`, `collapsed`, `auto-collapsed`, or `hidden`.
+Use `eve dev` flags to control how much detail the UI renders:
 
 ```bash
-eve dev --tools full --assistant-response-stats tokens --context-size 200000
+eve dev --tools full --reasoning collapsed --logs all
 ```
 
-| Flag                                | Values                                             | Effect                                                  |
-| ----------------------------------- | -------------------------------------------------- | ------------------------------------------------------- |
-| `--tools <mode>`                    | `full` / `collapsed` / `auto-collapsed` / `hidden` | How tool calls render (default `auto-collapsed`).       |
-| `--reasoning <mode>`                | `full` / `collapsed` / `auto-collapsed` / `hidden` | How reasoning renders (default `full`).                 |
-| `--subagents <mode>`                | `full` / `collapsed` / `auto-collapsed` / `hidden` | How subagent sections render.                           |
-| `--connection-auth <mode>`          | `full` / `collapsed` / `auto-collapsed` / `hidden` | How connection authorization renders.                   |
-| `--assistant-response-stats <mode>` | `tokens` / `tokensPerSecond`                       | Which statistic the assistant header shows.             |
-| `--context-size <tokens>`           | a token count                                      | Model context window size, shown as a usage percentage. |
-| `--logs <mode>`                     | `all` / `stderr` / `sandbox` / `none`              | Which server and agent logs to show (default `stderr`). |
+| Flag                         | Values                                          | Description                                        |
+| ---------------------------- | ----------------------------------------------- | -------------------------------------------------- |
+| `--tools`                    | `full`, `collapsed`, `auto-collapsed`, `hidden` | Tool-call display.                                 |
+| `--reasoning`                | `full`, `collapsed`, `auto-collapsed`, `hidden` | Reasoning display.                                 |
+| `--subagents`                | `full`, `collapsed`, `auto-collapsed`, `hidden` | Subagent display.                                  |
+| `--connection-auth`          | `full`, `collapsed`, `auto-collapsed`, `hidden` | Connection-authorization display.                  |
+| `--assistant-response-stats` | `tokens`, `tokensPerSecond`                     | Assistant response statistic.                      |
+| `--context-size`             | Token count                                     | Model context-window size for the usage indicator. |
+| `--logs`                     | `all`, `stderr`, `sandbox`, `none`              | Initial log display mode.                          |
 
-Connection flags: `--host` and `--port` bind the local server, and `--no-ui` runs headless (also the automatic fallback when stdout is not a TTY). See the [CLI](../reference/cli) for the full flag list.
+Use `--host` and `--port` to bind the local server, or `--no-ui` to run without the terminal UI. See the [CLI reference](../reference/cli#eve-dev) for all options.
 
-## Remote: `eve dev <url>`
+## Connect to a deployment
 
-Pass a URL and the TUI talks to a running deployment instead of starting a local server, which is handy for a Vercel preview or your production app.
+Pass a URL to use the terminal UI with an existing eve server instead of starting one locally:
 
 ```bash
-eve dev https://<your-app>
+eve dev https://your-app.vercel.app
 ```
 
-The bare URL is shorthand for `--url`; it cannot be combined with `--host`, `--port`, or `--no-ui`. For HTTP Basic auth, put credentials in the URL; eve sends them as a Basic `Authorization` header and strips them from the server URL before connecting:
+The URL form is shorthand for `--url`. To send credentials or custom request headers, use a URL with HTTP Basic credentials or repeat `-H, --header`:
 
 ```bash
-eve dev https://user:pass@<your-app>
+eve dev https://user:pass@your-app.example.com
+eve dev https://your-app.example.com -H 'Authorization: Bearer your_token_here'
 ```
 
-For bearer tokens or custom schemes, repeat `-H, --header` to attach request headers.
-
-Query parameters in the target URL are preserved on every request, including
-session POSTs and event streams. This also supports deployment-protection URLs
-that carry their bypass credential in the query string.
-
-At startup the TUI asks Vercel to resolve the remote origin under the active scope. A resolved response is the authority for a project-scoped OIDC token—refreshing an expired development token when refresh credentials exist—or an automation-bypass secret. An unresolved host is probed anonymously. The TUI then requests `/eve/v1/info`, with a ten-second timeout. A successful response marks the remote ready. An eve OIDC challenge, Vercel Deployment Protection challenge, or `TRUSTED_SOURCES_ENVIRONMENT_MISMATCH` opens `/vc:login` automatically; ordinary network failures and server errors remain remote-availability errors and do not start an authentication flow. Esc or Ctrl-C cancels the authentication flow.
-
-In a remote session, `/vc:login` first resolves the deployment's Vercel project from its URL. If the active Vercel scope cannot resolve it, the flow asks for another team and reruns the lookup in that team's scope. If the CLI is logged out, the same panel runs the browser login first. The flow asks before adding any required Trusted Sources rule and requests a project-scoped token through `@vercel/oidc`. It does not relink the directory or modify `.env.local`. Finally, it retries `/eve/v1/info` to prove the credential works. A failure reports any login or Trusted Sources update that completed before it stopped.
-
-The project-scoped token represents the resolved project's Development environment. Vercel already allows a project's Development environment to call its own Preview deployments by default. For a Production or custom-environment target, `/vc:login` shows the exact Development-to-target rule before changing that project's Trusted Sources. Eve preserves existing entries. When it creates an explicit rule, it also carries Vercel's default self-access rows forward because saved rules replace those defaults. See Vercel's [Trusted Sources guide](https://vercel.com/docs/deployment-protection/methods-to-bypass-deployment-protection/trusted-sources), [error reference](https://vercel.com/docs/errors/trusted_sources_environment_mismatch), and [OIDC token anatomy](https://vercel.com/docs/oidc/reference#oidc-token-anatomy).
-
-`VERCEL_AUTOMATION_BYPASS_SECRET` remains available for a Protection Bypass for Automation token. See [Deploy to Vercel](./deployment/vercel#verify-the-deployment) for the smoke-test flow.
+For a Vercel deployment that needs authentication, run `/vc:login` and follow the prompt. Remote sessions do not modify the local project's Vercel link or `.env.local`.
 
 ## What to read next
 
-- [Observability](./instrumentation): OpenTelemetry, run tags, and common failures.
-- [CLI](../reference/cli): every command and flag.
+- [Instrumentation](./instrumentation): traces, OpenTelemetry, and diagnostics.
+- [CLI](../reference/cli): commands and flags.

package/docs/guides/dynamic-workflows.md

@@ -7,6 +7,8 @@ The experimental `Workflow` tool lets the model write JavaScript that coordinate
 
 A single turn can already call several subagents, and parallel tool calls dispatch concurrently. What a workflow adds is _programmatic_ coordination. The program decides how many subagents to run based on an earlier result, which output feeds which call, and how to combine everything. That is logic the model cannot express as a few one-off calls.
 
+`Workflow` is a model-facing tool, not an API for authored tools, hooks, or application code. Authored code cannot submit a Workflow program or use `Workflow` to start an arbitrary user-authored Vercel Workflow. Use the [client SDK](./client/overview) when application code needs to start or continue an eve session; use ordinary application APIs for other deterministic orchestration.
+
 ## Enable the Workflow tool
 
 Export the experimental Workflow definition from `agent/tools/workflow.ts`. The helper name carries the "experimental" warning, but the tool the model actually sees is named `Workflow`.