eve 0.55.0 → 0.57.0

package/docs/concepts/execution-model-and-durability.mdx

@@ -13,7 +13,7 @@ Work nests in three levels:
 - **turn**: one user message and all the work it triggers (model calls, tool calls, reasoning) until the agent produces its response.
 - **step**: a durable checkpoint inside a turn. By default, it contains one model call and the inline tool calls that follow it.
 
-Every turn runs as a durable workflow, built on the open-source [Workflow SDK](https://workflow-sdk.dev/) (Vercel Workflow when you deploy on Vercel). eve checkpoints progress and serializes durable state at each step boundary. Your code runs inside a managed step, so tools, the sandbox, and subagents feel synchronous even though the session underneath them is durable.
+Every session runs as one durable workflow, built on the open-source [Workflow SDK](https://workflow-sdk.dev/) (Vercel Workflow when you deploy on Vercel). The session workflow executes each turn and checkpoints progress at step boundaries. Your code runs inside a managed step, so tools, the sandbox, and subagents feel synchronous even though the session underneath them is durable.
 
 The experimental
 [`workflow.modelCallsPerStep`](../agent-config#workflow-checkpoint-batching)
@@ -21,9 +21,40 @@ agent setting can group several sequential model-and-tool cycles into one
 Workflow step. This reduces checkpoint overhead but makes the entire group one
 replay unit.
 
-The Workflow SDK is not inherently tied to Vercel. In local development and in a self-deployed `eve start` process, eve uses the SDK's local world by default; that world persists workflow runs on disk under `.eve/.workflow-data` and dispatches through the same Nitro-hosted workflow routes. On Vercel, the same workflow code runs against Vercel Workflow instead, which adds platform features such as latest production deployment routing and dashboard run metadata.
+The Workflow SDK is not inherently tied to Vercel. In local development and in a self-deployed `eve start` process, eve uses the SDK's local world by default; that world persists workflow runs on disk under `.eve/.workflow-data` and dispatches through the same Nitro-hosted workflow routes. On Vercel, the same workflow code runs against Vercel Workflow instead, which adds deployment-aware routing and dashboard run metadata.
 
-When a Vercel production deployment changes, the next model turn in an existing session uses that deployment's current system-role instructions, model, and tools. Static user-role instructions stay pinned in the durable conversation history and are not seeded again. Identity-based channels such as Telegram private chats and Twilio phone-number conversations therefore adopt agent behavior updates without duplicating or rewriting their existing context.
+When a Vercel production deployment changes, a new delivery to an idle session hands the session's settled state to the exact deployment that accepted the request. This applies whether the delivery arrives through the session ID or through any channel continuation address the session has claimed. The session keeps its original ID and event stream, while the next model turn uses that deployment's current system-role instructions, model, and tools. Static user-role instructions stay pinned in the durable conversation history and are not seeded again. A successful handoff restarts the session's original configured [`sessionTimeoutMs`](../agent-config#runtime-limits) duration; disabled timeouts stay disabled. Failed or skipped handoffs keep the existing deadline.
+
+Before taking ownership, the target deployment validates the checkpoint's stored tasks and subagent handles and checks that no pending work remains. This includes settled tasks. If that validation fails, the previous owner recovers the session and processes the triggering delivery. Task and handle state preserve unknown metadata fields, while known fields and lifecycle rules must still be valid. Authored session state remains opaque to this validation.
+
+eve does not move live work between deployments. A session with a running turn, pending human input or authorization, queued messages, or active tasks and subagents stays on its current deployment. After that work settles, a later delivery can move the idle session; the earlier deployment signal is not remembered.
+
+### Upgrading sessions from the former execution model
+
+You can upgrade directly from a release that used a session driver and separate
+turn workflows. When an existing driver next dispatches a turn to this deployment,
+eve imports its committed conversation into the current runtime. The session
+keeps its ID, history, authored state, usage, limits, and original event stream.
+Subsequent turns use the new deployment's instructions, model, and tools.
+
+This is a one-time interruption of pending work. Old tool calls, subagents,
+input requests, and authorization attempts are abandoned; start that work again
+if it is still needed. Messages already buffered exclusively inside the old
+driver are not imported. The triggering message is preserved without repeating
+committed tool effects.
+
+Import supports drivers started on eve 0.45 or later. A session from an older
+release reports itself inactive on its next message, and its channel starts a
+fresh session.
+
+Keep the original deployment available until these sessions end. Their old
+drivers remain waiting to keep the original streams open; the current runtime
+owns subsequent turns. Import restarts the original configured session timeout;
+disabled timeouts stay disabled. A driver
+that has not reached its next turn dispatch has not migrated yet.
+
+Transparent rollback to the former execution model is unsupported. Retire and
+restart affected sessions before rolling back.
 
 Nitro hosts the HTTP routes and workflow entrypoints. It does not supply the workflow state store or the sandbox runtime. Those are separate adapters: Workflow uses the active world implementation, and Sandbox uses the backend from `agent/sandbox` or `defaultBackend()`.
 
@@ -70,9 +101,9 @@ executions from the same batch. Approval, input, blocking coordination, and
 background-task boundaries still force a checkpoint before eve waits or
 acknowledges the work.
 
-Steering does not replay or discard the whole batch. eve aborts the active
-model-and-tool cycle, commits earlier completed cycles in the batch, and starts
-the replacement turn from that state in the next Workflow step.
+Steering can interrupt pending model generation before assistant output begins.
+An executing tool finishes safely, then the batch yields before another model
+call so the owner can apply accepted steering within the same turn.
 
 Durability itself needs no configuration. eve owns the workflow lifecycle, and
 sessions are durable by default; checkpoint batching is an explicit
@@ -102,15 +133,33 @@ ID-addressed HTTP delivery and a channel-address delivery both target the
 session's current command inbox; neither is a general message queue.
 
 Only one active session can own a channel continuation token. A channel-created
-session commits both its stable session-ID alias and its channel alias before
-processing the first turn, and fails creation if another run already owns the
-channel alias. Rekeying replaces only that channel alias. An HTTP-created
-session has the stable ID alias and no channel continuation token. Competing
-channel input is not forwarded to the owner.
+session claims both its stable session-ID inbox and its initial channel address
+before processing the first turn, and fails creation if another run already
+owns the channel address. Aliasing adds another continuation address to the
+same session; every previously claimed address remains active until the session
+ends or resets. An ID-only HTTP session has the stable inbox and no channel
+continuation address. When cold starts race for the same address, the losing
+candidate forwards its accepted message to the owner and exits.
+
+Channel delivery attempts to resume the address before creating a session.
+After Workflow accepts the delivery, eve resolves the stable session ID for
+the returned handle. That identity lookup does not block workflow resumption.
+ID-addressed delivery already knows the session ID and needs no hook metadata
+lookup. An ambiguous delivery failure does not trigger session creation.
+
+While a handoff is in progress, the session's addresses are briefly unowned.
+The releasing owner leaves a short-lived marker for each address, so a
+delivery that lands in that interval retries until the successor claims the
+address instead of being reported as an inactive session. A channel therefore
+never starts a replacement session for an address that is mid-handoff.
+
+When a session is waiting, a delivery through its ID or any claimed channel address wakes it and starts the next turn. Message sends default to `turnPolicy: "steer"`. Before assistant output begins, the session owner signals pending model generation to stop, then applies the correction within the same turn and with the same turn ID. This includes model requests that perform provider-managed search before answering; interrupted search work may run again. Reasoning and search progress do not count as assistant output.
+
+An executing eve tool finishes and commits its result before steering reaches the next model request. Steering does not cancel the turn or its background tasks. After assistant output starts, steering applies at the next committed workflow boundary and preserves streamed text. A message that reaches the boundary after the turn has settled starts another turn.
 
-When a session is waiting, a delivery through its ID or current channel address wakes it and starts the next turn. Message sends default to `turnPolicy: "steer"`: while a turn is active, the session driver durably buffers the replacement before requesting cooperative cancellation. The interrupted turn emits `turn.cancelled` followed by `session.waiting`, then the replacement starts with a new turn ID. Partial output and completed side effects are not rolled back.
+Once eve publishes an input request or begins publishing turn completion or failure, eve finishes committing that boundary before applying new messages.
 
-`turnPolicy: "queue"` preserves the message until the active turn settles. If several deliveries are ready when the driver checks, eve may fold adjacent messages into the next turn while preserving their arrival order. Pure `inputResponses` deliveries do not steer; they remain available to the pending request they address.
+`turnPolicy: "queue"` preserves the message until the active turn settles. If several deliveries are ready when the owner checks, eve may fold adjacent messages into the next turn while preserving their arrival order. Pure `inputResponses` deliveries do not steer; they remain available to the pending request they address.
 
 Every built-in and custom channel accepts a default `turnPolicy`, and imperative message sends can override it. The policy is part of the same durable delivery command as the message, so concurrent senders cannot separate replacement ownership from cancellation intent. Separate sessions still run independently.
 

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

@@ -11,15 +11,22 @@ The HTTP API and TypeScript client use one durable `sessionId` for messages,
 controls, and streams. Every operation targets that exact session; none follows
 or creates a replacement implicitly.
 
+The session ID currently identifies the original Workflow run that owns the
+event stream. A deployment handoff changes the executing run, not the session
+ID or stream. Stream namespaces belong to a run; eve does not support
+caller-assigned session IDs or globally addressed streams.
+
 Authored channels also have channel-local continuation tokens. A token addresses
 whichever session currently owns a platform conversation, such as a Slack thread.
 That identity stays behind the channel boundary and is never accepted or returned
 by the eve HTTP session API. See [Custom channels](../channels/custom#channel-operations-and-session-handles).
 
 Sessions last 30 days by default; configure `limits.sessionTimeoutMs` in
-`agent.ts`, or set it to `false` to disable the deadline. At expiration, eve
+`agent.ts`, or set it to `false` to disable the deadline. A successful deployment
+handoff or legacy-session import restarts the original configured duration.
+Ordinary messages and process restarts keep the existing deadline. At expiration, eve
 lets an active turn settle, emits `session.completed`, and releases the
-continuation so the next qualifying channel message starts fresh. Stored
+session's continuation addresses so the next qualifying channel message starts fresh. Stored
 session data is not deleted. See [Agent config](../agent-config#runtime-limits).
 
 React, Vue, and Svelte apps reach for [`useEveAgent()`](../guides/frontend/overview) instead of calling these routes by hand. Next.js and Nuxt apps can proxy them to the eve runtime from the same origin.
@@ -164,7 +171,7 @@ Three more things to know:
 - **Ids identify events, not intent.** Two events with identical payloads — the `step.failed` → `turn.failed` → `session.failed` cascade, or two identical text deltas in one step — are distinct events with distinct ids. Deduplicate on `meta.id` only; matching on content would drop real data.
 - **A subagent's event is re-emitted, not shared.** When a parent forwards a child's event onto its own stream, the parent's copy is a separate event with its own id. Correlate the two streams through `subagent.called.data.childSessionId`.
 
-Authored [hooks](../guides/hooks) receive the same envelope, but observe each event as it is emitted rather than as it is read — so a hook sees a retry as new events, and `meta.id` is a key for a stored row rather than a retry guard. Two things a hook does not have to defend against: a turn that parks for human input resumes without re-emitting anything it already sent, and a retried turn dispatch cannot double-stream a turn, because only one turn run can claim a session's turn inbox.
+Authored [hooks](../guides/hooks) receive the same envelope, but observe each event as it is emitted rather than as it is read — so a hook sees a retry as new events, and `meta.id` is a key for a stored row rather than a retry guard. Two things a hook does not have to defend against: a turn that parks for human input resumes without re-emitting anything it already sent, and a retried turn dispatch cannot double-stream a turn, because one session owner executes it.
 
 ## Send a follow-up message
 
@@ -184,7 +191,7 @@ curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId> \
   -d '{"inputResponses":[{"requestId":"req_A","optionId":"approve"}]}'
 ```
 
-Message sends default to cancellation-backed `"steer"`; if a turn is active, eve buffers the follow-up, cancels that turn, and starts the message under a new turn ID. Channels and TypeScript `Session.send(...)` calls can select `turnPolicy: "queue"` when active work should finish first. Structured `inputResponses` never steer.
+Message sends default to `"steer"`. Before assistant output begins, eve interrupts pending model generation and continues the same turn with the correction. Reasoning and provider search progress do not count as assistant output. An executing eve tool finishes safely, and its result is preserved before the correction reaches the next model call. After assistant output starts, steering applies at the next committed workflow boundary; text already streamed remains visible. Channels and TypeScript `Session.send(...)` calls can select `turnPolicy: "queue"` when the active turn should finish first. Structured `inputResponses` answer their addressed requests.
 
 If the session is waiting on a human-in-the-loop approval, respond with the channel’s Approve or Cancel controls. Text messages do not decide an approval; unrelated text starts an ordinary turn while the approval stays pending and answerable. A later structured `inputResponses` answer keyed by its `requestId` still resumes the original tool call, even after intervening turns.
 
@@ -194,7 +201,7 @@ A structured response matches any currently pending request by ID, not only the
 
 One delivery can answer requests from several batches. eve resumes approval-bearing batches in durable order and carries later answers forward until each batch can resume.
 
-Multiple replacement messages retain their durable arrival order and may be folded into the same replacement turn when they arrive before cancellation settles. See [message delivery and steering](./execution-model-and-durability#message-delivery-and-steering) for the current runtime contract.
+Multiple steering messages retain their durable arrival order and may be folded into one input at the next boundary. A message accepted after turn settlement starts the next turn. See [message delivery and steering](./execution-model-and-durability#message-delivery-and-steering).
 
 ## Cancel the in-flight turn
 
@@ -244,6 +251,8 @@ Reset terminally retires the exact session ID. A reset ID never becomes a new se
 
 The stream is durable. Every event is recorded before a step completes, so consumers can reconnect from their cursor when an HTTP connection ends. A nonnegative `startIndex` is an absolute event count: use it to pick up where you dropped off or pass `0` to rewind to the start.
 
+When automatic reconnection is enabled and `startIndex` is nonnegative, the TypeScript client requests renewable leases over that durable stream. A server that supports leases sends transport heartbeats during quiet periods, then ends the response so the client reconnects from its current cursor. This bounds server-side stream readers even when a host does not report that the client disconnected. The lease renewal and heartbeats are transport details: they do not stop the run or appear as session events. Tail-relative reads and streams with reconnection disabled do not request leases.
+
 If a reconnect overlaps events you already handled, [`meta.id`](#the-event-envelope) identifies the duplicates: it is unchanged across reconnects and rewinds, so a consumer keyed on it can replay safely.
 
 ```bash

package/docs/connections/mcp.mdx

@@ -125,7 +125,10 @@ const publishesNow = (input: unknown): boolean => {
 export default defineMcpClientConnection({
   url: "https://mcp.example.com/mcp",
   description: "Social publishing: draft, schedule, and manage posts.",
-  auth: { getToken: async () => ({ token: process.env.SOCIAL_API_KEY! }) },
+  auth: {
+    credentialOwner: "app",
+    getToken: async () => ({ token: process.env.SOCIAL_API_KEY! }),
+  },
   approval: ({ toolName, toolInput }) => {
     if (DELETE_TOOLS.some((t) => toolName.includes(t))) return "user-approval";
     if (PUBLISH_TOOLS.some((t) => toolName.includes(t))) {

package/docs/connections/openapi.mdx

@@ -17,7 +17,10 @@ import { defineOpenAPIConnection } from "eve/connections";
 export default defineOpenAPIConnection({
   spec: "https://petstore3.swagger.io/api/v3/openapi.json",
   description: "Pet store inventory and orders.",
-  auth: { getToken: async () => ({ token: process.env.PETSTORE_TOKEN! }) },
+  auth: {
+    credentialOwner: "app",
+    getToken: async () => ({ token: process.env.PETSTORE_TOKEN! }),
+  },
 });
 ```
 
@@ -102,7 +105,10 @@ import { defineOpenAPIConnection } from "eve/connections";
 export default defineOpenAPIConnection({
   spec: "https://petstore3.swagger.io/api/v3/openapi.json",
   description: "Pet store inventory and orders.",
-  auth: { getToken: async () => ({ token: process.env.PETSTORE_TOKEN! }) },
+  auth: {
+    credentialOwner: "app",
+    getToken: async () => ({ token: process.env.PETSTORE_TOKEN! }),
+  },
   operations: { allow: ["getInventory", "placeOrder"] },
 });
 ```

package/docs/connections/overview.mdx

@@ -69,6 +69,7 @@ export default defineMcpClientConnection({
   url: "https://mcp.linear.app/mcp",
   description: "Linear workspace.",
   auth: {
+    credentialOwner: "app",
     getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }),
   },
 });
@@ -76,7 +77,7 @@ export default defineMcpClientConnection({
 
 If the token has a known TTL, set `expiresAt` (milliseconds since epoch) and eve refreshes ahead of time rather than waiting for a `401`.
 
-When `getToken` is the only auth, `principalType` defaults to `"app"`: one shared credential keyed across all sessions. Switch to `principalType: "user"` when each end-user carries their own token.
+When `getToken` is the only auth, `credentialOwner` defaults to `"app"`: one shared credential keyed across all sessions. Set `credentialOwner: "user"` when each end-user carries their own token.
 
 eve resolves and caches connection tokens per step; they never land in conversation history or reach the model.
 
@@ -86,11 +87,13 @@ A connection credential can belong to the agent or to the person using it. This
 
 | Credential owner | Use when                                                                       | Auth shape                                                                                                                                                   |
 | ---------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| App              | The agent should use one shared service, bot, installation, or app credential. | `auth: { getToken }` defaults to `principalType: "app"`, or use `connect({ connector: "linear/myagent", principalType: "app" })` with Vercel Connect.        |
-| User             | Each end-user should authorize and use their own third-party account.          | `connect("linear/myagent")`, `connect({ connector: "linear/myagent", principalType: "user" })`, or `auth: { principalType: "user", getToken }`.              |
+| App              | The agent should use one shared service, bot, installation, or app credential. | `auth: { getToken }` defaults to `credentialOwner: "app"`, or use `connect({ connector: "linear/myagent", principalType: "app" })` with Vercel Connect.      |
+| User             | Each end-user should authorize and use their own third-party account.          | `connect("linear/myagent")`, `connect({ connector: "linear/myagent", principalType: "user" })`, or `auth: { credentialOwner: "user", getToken }`.            |
 | User from a job  | Background work should use the same user's OAuth grant that started the work.  | Start or resume the session through a channel whose route auth resolved that user, or pass an explicit user auth context when dispatching through a channel. |
 
-`principalType: "user"` does not mean "ask any human later." It means "key this credential to the authenticated user already attached to the eve session." If the run was started by a schedule, a same-project runtime token, `localDev()`, or another internal runtime path without an end-user principal, a user-scoped connection fails with `reason: "principal_required"` instead of starting OAuth. In that case, either authenticate the inbound channel as a user or configure the connection as app-scoped.
+`credentialOwner: "user"` does not mean "ask any human later." It means "key this credential to the authenticated user already attached to the eve session." If the run was started by a schedule, a same-project runtime token, `localDev()`, or another internal runtime path without an end-user principal, a user-scoped connection fails with `reason: "principal_required"` instead of starting OAuth. In that case, either authenticate the inbound channel as a user or configure the connection as app-scoped.
+
+`credentialOwner` is eve's field for raw getToken-only connection auth. Existing non-interactive raw `principalType` definitions still work, but are deprecated. Interactive auth and `connect()` from `@vercel/connect/eve` continue to use `principalType: "user"`; that field also remains correct for route-auth session identities.
 
 ## No auth
 
@@ -132,7 +135,7 @@ export default defineOpenAPIConnection({
   spec: "https://warehouse.example.com/openapi.json",
   description: "The caller's tenant-scoped warehouse.",
   auth: (ctx) => ({
-    principalType: "user",
+    credentialOwner: "user",
     getToken: async () => ({
       token: await tenantToken(ctx.session.auth.current),
     }),
@@ -151,7 +154,7 @@ headers: {
 }
 ```
 
-Use `principalType: "user"` for per-user tokens so eve rejects unauthenticated callers and keys its step-local token cache by user. The resolver supplements route auth; it does not authenticate the inbound request. Static auth objects and header maps remain available when every caller shares the same configuration.
+Use `credentialOwner: "user"` for per-user tokens so eve rejects unauthenticated callers and keys its step-local token cache by user. The resolver supplements route auth; it does not authenticate the inbound request. Static auth objects and header maps remain available when every caller shares the same configuration.
 
 ## Per-connection approval
 
@@ -223,16 +226,16 @@ App-scoped Connect auth is non-interactive. eve asks Vercel Connect for an app t
 
 ### Troubleshooting Vercel Connect auth
 
-| Symptom                                      | What it means                                                                                                                     | Fix                                                                                                                                       |
-| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `reason: "principal_required"`               | A user-scoped connection ran without an authenticated user on the active session.                                                 | Return `principalType: "user"` from the channel's route auth, or change the connection to `principalType: "app"` if it should be shared.  |
-| `authorization.required` appears but no UI   | eve parked the turn for OAuth, but the channel or frontend is not rendering the challenge.                                        | Render the challenge from the stream event and continue the same session after the callback.                                              |
-| OAuth works locally but fails after deploy   | The project may not be linked to the Connect client, or the deployed runtime may not have the expected Vercel OIDC/project scope. | Run Connect setup from the consuming project directory, link the project, deploy again, and verify the connector UID in `connect("...")`. |
-| A scheduled or internal run needs user OAuth | Schedules and runtime callers do not automatically carry an end-user principal.                                                   | Dispatch through a user-authenticated channel when work is user-owned, or use app-scoped auth for agent-owned background work.            |
+| Symptom                                      | What it means                                                                                                                     | Fix                                                                                                                                                             |
+| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `reason: "principal_required"`               | A user-scoped connection ran without an authenticated user on the active session.                                                 | Return `principalType: "user"` from the channel's route auth, or use `connect({ connector, principalType: "app" })` if the Connect credential should be shared. |
+| `authorization.required` appears but no UI   | eve parked the turn for OAuth, but the channel or frontend is not rendering the challenge.                                        | Render the challenge from the stream event and continue the same session after the callback.                                                                    |
+| OAuth works locally but fails after deploy   | The project may not be linked to the Connect client, or the deployed runtime may not have the expected Vercel OIDC/project scope. | Run Connect setup from the consuming project directory, link the project, deploy again, and verify the connector UID in `connect("...")`.                       |
+| A scheduled or internal run needs user OAuth | Schedules and runtime callers do not automatically carry an end-user principal.                                                   | Dispatch through a user-authenticated channel when work is user-owned, or use app-scoped auth for agent-owned background work.                                  |
 
 ## Self-hosted interactive OAuth
 
-To run your own OAuth, use `defineInteractiveAuthorization` from `eve/connections`, which takes a three-method form and needs no Vercel Connect. eve mints a callback URL, parks (durably suspends) the turn on a framework-owned webhook, and resumes once the token comes back. Interactive auth is always `principalType: "user"`, and the factory pins that for you.
+To run your own OAuth, use `defineInteractiveAuthorization` from `eve/connections`, which takes a three-method form and needs no Vercel Connect. eve mints a callback URL, parks (durably suspends) the turn on a framework-owned webhook, and resumes once the token comes back. Interactive auth is always `principalType: "user"`; `credentialOwner` applies only to getToken-only auth, and the factory pins the interactive value for you.
 
 ```ts title="agent/connections/linear.ts"
 import {

package/docs/getting-started.mdx

@@ -12,7 +12,7 @@ You need:
 - npm, which Node.js includes
 - A credential for the model your agent uses
 
-The default scaffolded model routes through the Vercel AI Gateway. Set `AI_GATEWAY_API_KEY`, or link a Vercel project to use `VERCEL_OIDC_TOKEN`. To use a model provider directly, install its AI SDK provider package and set the provider's API key.
+Connect a ChatGPT subscription, a Vercel account, or an AI Gateway, OpenAI, or Anthropic API key in the terminal UI. You do not need a Vercel project to start chatting.
 
 Choose a model, provider, and channel that meet your data-processing and compliance requirements.
 
@@ -24,7 +24,11 @@ Run `eve init` with a project name:
 npx eve@latest init my-agent
 ```
 
-The command creates the project, installs dependencies, and initializes Git. After scaffolding, eve offers to start the development server or, if a supported coding agent is installed, to open the project in the coding agent.
+The command creates the project, installs dependencies, initializes Git, and opens the terminal UI. eve reuses an available model connection or opens `/login`. Once connected, type your first message. Channel and integration setup is optional; use `/add` when you need it.
+
+In `/add`, search by name or capability, such as `iMessage` or `SMS`. The picker matches item names, addresses, titles, and descriptions. Select an item to install it and complete its required setup.
+
+During startup, the status line shows what eve is waiting for. If you choose a Vercel account, finish signing in in your browser and select a team when prompted. eve checks that team's AI Gateway access and applies the connection before returning to the composer. Changing only the account, team, or key does not rebuild your agent. Once connected, you can send your first message while the agent information refreshes in the background; no restart is required.
 
 To add eve to a project that already has a `package.json`, run this command from its root before you create any `agent/` files:
 
@@ -44,7 +48,7 @@ npx eve@latest init my-agent --model openai/gpt-5.6-terra --reasoning high
 
 ## Run the agent
 
-Choose **Start eve dev** after scaffolding, or run this from the project root:
+The terminal UI opens after interactive initialization. To return later, run this from the project root:
 
 ```bash
 npm run dev
@@ -156,7 +160,7 @@ Prefer the nested layout because it keeps application files separate from the au
 
 ### Debug file discovery
 
-Run `eve info` when eve does not discover a file. It lists the discovered surface and diagnostics so you can check the authored slot and root-versus-subagent boundary. eve also writes inspectable artifacts under `.eve/`; see [Observability](./guides/instrumentation) and the [CLI](./reference/cli) reference.
+Run `eve info` when eve does not discover a file. It lists the discovered surface and diagnostics so you can check the authored slot and root-versus-subagent boundary. eve also writes inspectable artifacts under `.eve/`; see [Instrumentation](./observability/instrumentation) and the [CLI](./reference/cli) reference.
 
 ## Install manually
 

package/docs/guides/deployment/self-hosting.md

@@ -84,5 +84,5 @@ eve dev https://your_agent.example.com
 Use these guides to secure and observe the deployed agent:
 
 - [Authentication](../auth-and-route-protection): configure the host’s route policy
-- [Observability](../instrumentation): export traces and diagnose runtime failures
+- [Instrumentation](../../observability/instrumentation): export traces and diagnose runtime failures
 - [Sandbox](../../sandbox): select and secure a sandbox backend

package/docs/guides/deployment/vercel.mdx

@@ -118,7 +118,7 @@ export default await withEve({
 });
 ```
 
-A Vercel project can use only one configuration source, so remove `vercel.json` when adopting `vercel.ts`. Keep `eve` in the root package dependencies so Vercel can import `eve/vercel` while evaluating the configuration. Pass `{ root: "/absolute/workspace/path" }` as the second argument only when `vercel.ts` is evaluated from somewhere other than the workspace root.
+A Vercel project can use only one configuration source, so remove `vercel.json` when adopting `vercel.ts`. Keep `eve` in the root package dependencies so Vercel can import `eve/vercel` while evaluating the configuration. `withEve` discovers the workspace containing its evaluation directory, including Vercel's temporary `.vercel` configuration directory. Pass `{ root: "/absolute/workspace/path" }` as the second argument only when you need to select a specific workspace root.
 
 An authored eve service routed at `/eve/v1` already uses the protocol path; callbacks remain at `/eve/v1/callback/*`. A named mount such as `/support` adds that mount before the protocol path, giving `/support/eve/v1/callback/*`.
 
@@ -158,12 +158,12 @@ Set `VERCEL_AUTOMATION_BYPASS_SECRET` locally before connecting if the deploymen
 
 Vercel detects eve and can add an **Agent Runs** tab under the project’s **Observability** view. Use it to browse sessions and inspect each conversation trace.
 
-The Agent Runs tab requires enablement for your Vercel team. Contact your Vercel representative if the tab doesn’t appear. For third-party tracing backends, configure [OpenTelemetry instrumentation](../instrumentation).
+The Agent Runs tab requires enablement for your Vercel team. Contact your Vercel representative if the tab doesn’t appear. For third-party tracing backends, configure [OpenTelemetry instrumentation](../../observability/instrumentation).
 
 ## Continue configuring production
 
 Use these guides to secure and observe the deployed agent:
 
 - [Authentication](../auth-and-route-protection): configure who can call the deployed agent
-- [Observability](../instrumentation): export traces and diagnose runtime failures
+- [Instrumentation](../../observability/instrumentation): export traces and diagnose runtime failures
 - [Sandbox](../../sandbox): configure resources, isolation, and network access

package/docs/guides/dev-tui.md

@@ -9,57 +9,82 @@ description: "Use eve locally or connect to a deployed agent from an interactive
 eve dev
 ```
 
+The footer shows the active model and connection separated by dots. Vercel account connections show the team slug once it resolves; the local server port is omitted.
+
 The transcript remains in your terminal scrollback after you exit. Run `/help` in the UI to see the commands available in the current session.
 
 ## Commands
 
-| Command       | Description                                                                                                                                                              |
-| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `/model`      | Configure the model and its provider. Pass a model ID to set it directly: `/model provider/model-id`.                                                                    |
-| `/add`        | Select and install channels, MCP connections, extensions, and observability integrations. Pass an item address to confirm and install it directly: `/add channel/slack`. |
-| `/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.                                                                                                               |
-| `/info`       | Show the resolved application, compiled artifacts, discovery diagnostics, and messaging routes.                                                                          |
-| `/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.                                                                                                                                                 |
-
-`/model`, `/add`, `/deploy`, `/info`, and `/traces` are available when `eve dev` runs locally. They are unavailable when the UI connects to a server with `--url`.
+| Command     | Description                                                                                                                                                  |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `/login`    | Connect a ChatGPT subscription, Vercel account, or provider API key.                                                                                         |
+| `/model`    | Choose the model and its settings. Pass a model ID to set it directly: `/model provider/model-id`.                                                           |
+| `/add`      | Select and install channels, MCP connections, extensions, and observability integrations. Pass an item address to install it directly: `/add channel/slack`. |
+| `/deploy`   | Deploy the agent to Vercel production. Installs the Vercel CLI, signs in, and links the directory if needed.                                                 |
+| `/info`     | Show the resolved application, compiled artifacts, discovery diagnostics, and messaging routes.                                                              |
+| `/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.                                                                                                                                     |
+
+`/login`, `/model`, `/add`, `/deploy`, `/info`, and `/traces` are available when `eve dev` runs locally. They are unavailable when the UI connects to a server with `--url`.
 
 ## Set up a new agent
 
-After `eve init`, the terminal UI guides you through **Model**, **Channels**, **Integrations**, and **Review** before the first chat prompt. The progress rail keeps the four steps visible throughout onboarding. Model setup can install or upgrade the Vercel CLI, open Vercel login, and resume project linking without leaving the flow.
+After interactive `eve init`, the TUI opens directly. eve keeps the project's selected connection. For a new connection, it checks explicit environment credentials, the saved machine default, and then the Vercel CLI's current team. Existing project OIDC connections remain supported. Automatic Vercel reuse validates account access without creating or linking a project.
 
-Model and Vercel changes take effect when you complete Model, then onboarding continues to Channels. Channel and integration selections remain drafts until you finish Review. You can move back and forth between Channels, Integrations, and Review; use `/model` after onboarding to change the committed model configuration.
+During startup, the composer stays visible while a progress indicator names the connection being checked and shows when eve is preparing your chat. Type a message and press `Enter` to queue it for when the agent is ready. A picker temporarily takes over input when a choice or API key is needed; your draft returns afterward. If setup is cancelled or fails, queued messages return to the draft.
 
-## Add an integration
+If no connection is ready, `/login` offers:
+
+1. Vercel Account
+2. Vercel AI Gateway API Key
+3. ChatGPT Subscription
+4. OpenAI API Key
+5. Anthropic API Key
+
+Vercel account login opens a browser. When multiple teams are available, `/login` shows a searchable team picker with the current project or CLI team highlighted so you can switch teams. A sole available team is selected automatically. Automatic startup reuses the selected connection without opening this picker. Account-token access to Gateway depends on availability for your account and team; if it is unavailable, choose an API key or another connection.
+
+Type to filter a menu, press `Enter` to select, or `Esc` to return to chat. Dismissing a setup menu adds no cancellation message to the transcript; completed work and failures still appear. Arrow navigation is also available. Cancelling login preserves your draft. If a connection fails, retry `/login`; eve does not silently switch providers.
+
+### Credentials and deployment
+
+eve saves API keys and eve-owned OAuth refresh credentials in the OS secret store through just-secrets. It saves the last successful login as the machine default and records the project's connection and team separately as nonsecret metadata in `.eve/provider.json`. Newly entered keys are never written into project files. A key explicitly selected through `/login` takes precedence over another key for that provider in your shell; a project connected through environment credentials continues to use its environment. Vercel CLI retains ownership of its credentials and refresh tokens.
 
-Bare `/add` opens the standalone planner on **Channels**. It does not include model configuration. The progress rail shows selection counts as you move between **Channels**, **Integrations**, and **Review**.
+Local discovery runs only in development. Deployments need explicitly provisioned `AI_GATEWAY_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or supported project OIDC credentials. ChatGPT subscription models are local-only. `/login` does not link a deployment or authenticate a remote server; `/deploy` handles Vercel CLI installation and account login when needed.
 
-Press `Space` or `Enter` to toggle the highlighted item. Press `Right Arrow` to preserve the current selections and continue, `Left Arrow` to preserve them and go back, or `Esc` to cancel. Installation requires `Enter` on **Install and set up** from Review. During installation, `Esc` cancels only the active item and continues with the remaining selections. The final summary reports installed, cancelled, and failed items separately.
+### Models and settings
 
-Pass an item address to `/add` to confirm and install that exact address without opening the planner:
+`/model` opens the model picker and settings. Each completed selection applies immediately and returns to chat; there is no final Done step. A successful login or model change takes effect on the next prompt.
+
+OpenAI, ChatGPT, and Gateway connections default to `gpt-5.6-luna-fast`; Anthropic defaults to `claude-sonnet-5`. An explicitly authored compatible model stays selected. If a new default is unavailable, eve offers the connection's available models. Dynamic or custom model expressions must be edited in `agent.ts`.
+
+## Add an integration
+
+`/add` opens one searchable catalog of channels, connections, extensions, and integrations. Type to filter and press `Enter` to install one item and run its required setup. The flow returns to chat afterward.
+
+Pass an item address to install it directly:
 
 ```text
 /add channel/slack
 /add extension/agent-browser
-/add linear
+/add channel/linear
 /add @acme/analytics
 ```
 
-The UI installs planner selections in order and offers deployment once after the batch when an installed item requires it.
+Required authorization or deployment setup still runs for the selected item. Press `Esc` to cancel setup; files already installed remain in the project.
 
 ## Work with the agent
 
 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.
 
-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. If a direct cancellation requested with `/cancel` or `Ctrl+C` does not settle, press `Ctrl+C` to stop waiting. The UI then returns to the prompt and asks you to press `Ctrl+C` again to exit. At an idle prompt, press `Ctrl+C` twice to exit.
+While a turn is running, `Enter` sends your message immediately as steering. Before assistant output begins, the runtime interrupts pending model generation and continues the same turn with your correction. Executing tools finish safely. After output begins, steering applies at the next workflow boundary and preserves streamed text.
+
+Slash commands wait until the turn ends, except `/cancel`, which cancels directly. If the session does not support steering, messages queue for the next turn. Press `Esc` or `Ctrl+C` to cancel a turn with no queued messages. With queued messages, these keys select the oldest message for steering, or for the next turn if steering is unavailable. If a direct cancellation requested with `/cancel` or `Ctrl+C` does not settle, press `Ctrl+C` to stop waiting. The UI then returns to the prompt and asks you to press `Ctrl+C` again to exit. At an idle prompt, press `Ctrl+C` twice to exit.
 
 | Key           | Action                                                                                                                  |
 | ------------- | ----------------------------------------------------------------------------------------------------------------------- |
@@ -77,7 +102,7 @@ By default, the UI shows `stderr` logs. Use `/loglevel <all|stderr|sandbox|none>
 
 Every `eve dev` process writes diagnostic logs to `.eve/logs/`, regardless of the display mode. Read them with [`eve logs`](../reference/cli#eve-logs).
 
-Use `/traces` to inspect traces recorded during local development. See [Instrumentation](instrumentation#local-traces) for trace capture and retention settings.
+Use `/traces` to inspect traces recorded during local development. See [Instrumentation](../observability/instrumentation#local-traces) for trace capture and retention settings.
 
 ## Display options
 
@@ -87,7 +112,7 @@ Use `eve dev` flags to control tool calls, reasoning, subagents, connection auth
 eve dev --tools full --reasoning collapsed --logs all
 ```
 
-Use `--host` and `--port` to bind the local server, or `--no-ui` to run without the terminal UI. See the [`eve dev` CLI reference](../reference/cli#eve-dev) for the complete option list, accepted values, and defaults.
+Use `--host` and `--port` to bind the local server, or `--no-ui` to run without the terminal UI. Set `EVE_TUI_RENDER_MARKDOWN=0` to show assistant and subagent responses without Markdown parsing or styling; `1` (the default) enables Markdown rendering. See the [`eve dev` CLI reference](../reference/cli#eve-dev) for the complete option list, accepted values, and defaults.
 
 ## Connect to a deployment
 
@@ -104,10 +129,12 @@ eve dev https://user:pass@your-app.example.com
 eve dev https://your-app.example.com -H 'Authorization: Bearer your_token_here'
 ```
 
-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`.
+Remote Vercel sessions reuse an existing authorized CLI session. They do not open an account login flow or modify the local project's Vercel link or `.env.local`.
+
+When Deployment Protection blocks startup, eve verifies the target project and asks before adding a Trusted Sources rule for development access to that deployment's environment. After approval, eve applies the rule and checks access again before returning to chat. Cancelling preserves your draft; restart `eve dev <url>` to try again. If you cannot change the project's policy, provide `VERCEL_AUTOMATION_BYPASS_SECRET` or ask a project administrator to configure access in Deployment Protection settings.
 
 ## What to read next
 
-- [Instrumentation](./instrumentation): traces, OpenTelemetry, and diagnostics.
+- [Instrumentation](../observability/instrumentation): traces, OpenTelemetry, and diagnostics.
 - [CLI](../reference/cli): commands and flags.
 - [Agent Client Protocol (ACP)](../protocols/acp): drive the same agent from ACP clients such as Zed instead of the TUI.

package/docs/guides/dynamic-capabilities.md

@@ -136,9 +136,9 @@ shadows the session selection for that turn, including when the turn handler
 returns `null`. If a resolver throws or returns an invalid definition, eve logs the
 failure and omits the subagent.
 
-The resolved set applies to local and remote direct delegation. Background subagents are not
-exposed inside the model-authored `Workflow` tool. eve
-also checks availability again before starting the child, so a stale or
+The resolved set applies to local and remote direct delegation. An authored workflow tool can
+also call a selected subagent through `ctx.agent`. A generated program can call it through the
+provided `workflow` tool. eve checks availability again before starting the child, so a stale or
 manually constructed call fails with `SUBAGENT_UNAVAILABLE`. Treat conditional
 availability as capability composition, not as the only authorization
 boundary: sensitive child tools still need their own authorization and
@@ -178,7 +178,7 @@ export default defineDynamic({
             description: `${account.label} (${account.accountId})`,
             instanceKey: account.accountId,
             auth: {
-              principalType: "user",
+              credentialOwner: "user",
               getToken: ({ principal }) => mintAccountToken(principal, account),
             },
           }),

package/docs/guides/frontend/overview.mdx

@@ -107,7 +107,9 @@ await agent.send([
 ]);
 ```
 
-Assistant text, reasoning, tool calls, and tool results stream into `data` as they arrive, and a new turn moves `status` from `ready` to `submitted` to `streaming` and back. Resuming an attached session uses `resuming` while eve performs bounded catch-up. Disable message and HITL submission in that state. A settled tail moves directly to `ready`; an in-flight tail moves to `streaming` before eve follows it. To replace an active turn with a follow-up, send the message with `turnPolicy: "steer"`. eve accepts the message through the durable session, cancels the active turn, and keeps the hook attached through the replacement turn:
+Assistant text, reasoning, tool calls, and tool results stream into `data` as they arrive, and a new turn moves `status` from `ready` to `submitted` to `streaming` and back. Resuming an attached session uses `resuming` while eve performs bounded catch-up. Disable message and HITL submission in that state. A settled tail moves directly to `ready`; an in-flight tail moves to `streaming` before eve follows it.
+
+To steer an active turn with a follow-up, send the message with `turnPolicy: "steer"`. Before answer output or local tool execution begins, eve interrupts pending model generation and continues the same turn with the correction. Executing tools finish and checkpoint their results first; after answer output starts, steering waits for the next committed workflow boundary. Reasoning and search progress do not count as answer output. The hook stays attached through completion:
 
 ```tsx
 await agent.send(message, { turnPolicy: "steer" });

package/docs/guides/hooks.md

@@ -50,7 +50,7 @@ export default githubChannel({
 
 A GitHub channel event handler cannot fire for a Slack-owned session, so platform-specific side effects do not depend on an early-return guard. On a built-in channel, an authored handler replaces that channel's default handler for the same event key. Check the channel page before overriding events that deliver replies, progress, errors, or human-input prompts.
 
-Use `ctx.channel.kind` inside a global hook only when the operation is otherwise agent-wide and conditional handling is intentional. For typed channel metadata in dynamic resolvers or instrumentation, import the channel definition and narrow with `isChannel`; see [Instrumentation](./instrumentation#runtime-context).
+Use `ctx.channel.kind` inside a global hook only when the operation is otherwise agent-wide and conditional handling is intentional. For typed channel metadata in dynamic resolvers or instrumentation, import the channel definition and narrow with `isChannel`; see [Add runtime context](../observability/instrumentation#add-runtime-context).
 
 ## Hook structure and context
 

package/docs/guides/instrumentation/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Observability",
+  "defaultOpen": false,
+  "pages": ["overview", "providers", "otel"]
+}