eve 0.76.0 → 0.76.2

package/docs/guides/frontend/tanstack.mdx

@@ -0,0 +1,201 @@
+---
+title: "TanStack Start"
+description: "Run an eve agent and a TanStack Start app as one project with the eveTanStack Vite plugin."
+---
+
+`eve/tanstack` runs a TanStack Start frontend and an eve agent as one project instead of two services. The `eveTanStack()` Vite plugin puts both on one dev server and one Vercel deploy, and [`useEveAgent`](./overview) from `eve/react` finds the mounted routes on its own. There's no CORS to configure and no URL env vars to keep in sync.
+
+## Prerequisites
+
+- The `eve` package installed in your project (`npm install eve@latest`).
+- An existing eve agent directory. If you don't have one, start from [Getting started](../../getting-started).
+- A TanStack Start app using React, with the [Nitro Vite plugin](https://tanstack.com/start/latest/docs/framework/react/guide/hosting#nitro) (`nitro` installed and `nitro()` registered). TanStack Start deploys to Vercel through Nitro, and the plugin attaches eve to it.
+
+## Add the generated Web Chat app
+
+Run the Web Chat installer and choose **TanStack Start** when it asks which framework to use:
+
+```bash
+eve add channel/web
+```
+
+In automation, answer the framework and hosting questions up front. Without a `web-framework` answer, non-interactive installs use Next.js:
+
+```bash
+eve add channel/web --non-interactive \
+  --answer 'web-framework="tanstack"' \
+  --answer 'web-hosting="vercel"'
+```
+
+The installer creates a TanStack Start app under `apps/web/` and adds the `dev:web` and `build:web` scripts. It asks how to deploy it:
+
+- **Vercel services** (recommended) deploys Web Chat and the agent as separate services. Run both locally with `pnpm dev:all`; you don't need to link a Vercel project to do that.
+- **TanStack Start** hosts the agent in the TanStack Start app through `eveTanStack()`. Run it with `pnpm dev:web`. The app lives in `apps/web/` while its dependencies are in the project root `package.json`, so a Vercel deploy from the project root doesn't build it. Choose **Vercel services** to deploy Web Chat on Vercel.
+
+Rerun `eve add channel/web --skip-install` with the other choice to switch modes; the installer removes the `vercel.ts` and scripts it wrote for the previous one. When `apps/web/` already contains a Web Chat app, the installer keeps that app's framework and stops if you answer a different one. To switch between Next.js and TanStack Start, remove `apps/web/` first.
+
+Sign in with Vercel setup is available only for the Next.js Web Chat app, so the TanStack Start installer doesn't ask about authentication.
+
+The chat has the same URL-addressed durable sessions as the [Next.js Web Chat](./nextjs#use-the-generated-web-chat-routes): `/`, `/s`, and `/s/$sessionId`. Before accepting production browser traffic, replace the generated placeholder authorization policy. See [Authenticate browser requests](./overview#authenticate-browser-requests).
+
+The installer doesn't support selecting a workspace agent for single-app hosting: a workspace agent always deploys as a separate Vercel service. If you already have a TanStack Start app, skip the installer and follow the steps below.
+
+## Register the Vite plugin
+
+Add `eveTanStack()` to `vite.config.ts` next to `nitro()`:
+
+```ts title="vite.config.ts"
+import { tanstackStart } from "@tanstack/react-start/plugin/vite";
+import viteReact from "@vitejs/plugin-react";
+import { eveTanStack } from "eve/tanstack";
+import { nitro } from "nitro/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [eveTanStack(), tanstackStart(), viteReact(), nitro()],
+});
+```
+
+The plugin looks for an `agent/` folder in the TanStack Start project root. Pass `eveRoot` when the agent lives elsewhere:
+
+```ts
+export default defineConfig({
+  plugins: [
+    eveTanStack({
+      eveRoot: "../my-agent",
+    }),
+    tanstackStart(),
+    viteReact(),
+    nitro(),
+  ],
+});
+```
+
+Without `nitro()` registered, Vite fails at startup with an error naming the missing plugin instead of serving a project whose eve routes would return 404.
+
+### `eveTanStack` options
+
+All fields are optional.
+
+| Option               | Type     | Default                     | Purpose                                                                                                                     |
+| -------------------- | -------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `eveRoot`            | `string` | TanStack Start project root | eve project root, relative to the TanStack Start project root unless absolute.                                              |
+| `eveBuildCommand`    | `string` | generated                   | Build command for the generated eve Vercel service.                                                                         |
+| `devServerTimeoutMs` | `number` | `180000`                    | Maximum time to wait for the eve development server to start, including when another TanStack Start process is starting it. |
+
+For slow cold starts, increase the development timeout:
+
+```ts
+export default defineConfig({
+  plugins: [
+    eveTanStack({
+      devServerTimeoutMs: 300_000,
+    }),
+    tanstackStart(),
+    viteReact(),
+    nitro(),
+  ],
+});
+```
+
+## Call the hook
+
+With the plugin in `vite.config.ts`, components call [`useEveAgent`](./overview) from `eve/react` and don't pass a host:
+
+```tsx title="src/routes/index.tsx"
+import { createFileRoute } from "@tanstack/react-router";
+import { useEveAgent } from "eve/react";
+import { useState } from "react";
+
+export const Route = createFileRoute("/")({
+  component: Chat,
+});
+
+function Chat() {
+  const agent = useEveAgent();
+  const [draft, setDraft] = useState("");
+  const isBusy = agent.status === "submitted" || agent.status === "streaming";
+  const isInputDisabled = isBusy || agent.status === "resuming";
+
+  return (
+    <form
+      onSubmit={(event) => {
+        event.preventDefault();
+        const text = draft.trim();
+        if (text.length === 0 || isInputDisabled) return;
+        setDraft("");
+        void agent.send(text);
+      }}
+    >
+      {agent.data.messages.map((message) => (
+        <article key={message.id}>
+          <header>{message.role}</header>
+          {message.parts.map((part, index) =>
+            part.type === "text" ? <p key={part.id ?? index}>{part.text}</p> : null,
+          )}
+        </article>
+      ))}
+      <input
+        disabled={isInputDisabled}
+        onChange={(event) => setDraft(event.currentTarget.value)}
+        value={draft}
+      />
+      <button disabled={isInputDisabled} type="submit">
+        Send
+      </button>
+    </form>
+  );
+}
+```
+
+The browser still needs a production authentication policy. See [Authenticate browser requests](./overview#authenticate-browser-requests) for the default fail-closed behavior and channel configuration.
+
+eve ships hook bindings for React, Vue, and Svelte. A TanStack Start app that uses Solid can still mount the agent with this plugin and call it through the [Client SDK](../client/overview).
+
+## Dev vs deploy topology
+
+- **Local dev.** `npm run dev` boots the eve dev server next to TanStack Start and Nitro proxies `/eve/v1/**` to it, so the browser only ever hits the TanStack Start origin. The plugin uses the server named by `EVE_BASE_URL` when that variable is set, then a healthy shared eve dev server already running for the app, and otherwise starts one. A server the plugin starts stops when the Vite dev server closes (Vite 8.3 or later; earlier versions stop it when the process exits). Any tool that loads `vite.config.ts` in serve mode starts or reuses this server, including test runners such as Vitest. Keep `eveTanStack()` out of a separate test config if you don't want that.
+- **Vercel.** The TanStack Start app and the eve runtime deploy as a single project. On Vercel builds the plugin adds Build Output [`services`](https://vercel.com/docs/services) for eve and a `routes` entry that sends `/eve/v1/**` to that service before filesystem routing and before any routes you declare in `nitro({ vercel: { config } })`; the TanStack Start app remains the default app. No `vercel.json` is required. By default the generated service runs the installed eve binary from the TanStack Start app's dependencies, so the agent directory does not need its own `package.json`. When the agent needs its own build step, set `eveBuildCommand`:
+
+  ```ts
+  export default defineConfig({
+    plugins: [
+      eveTanStack({
+        eveBuildCommand: "npm run build:eve",
+      }),
+      tanstackStart(),
+      viteReact(),
+      nitro(),
+    ],
+  });
+  ```
+
+- **Other hosts.** `vite preview` and a self-hosted `node .output/server/index.mjs` don't mount the eve routes. Run the eve service on its own origin and pass `host` directly to `useEveAgent`:
+
+  ```ts
+  const agent = useEveAgent({
+    host: "https://agent.example.com",
+  });
+  ```
+
+  `eve build` and `vite build` (with Nitro's default Node.js preset) both write `.output/`. When the agent lives in the TanStack Start project root, build and serve eve from a separate directory (set `eveRoot` to it) so the two outputs do not overwrite each other. See [Self-host eve](../deployment/self-hosting) for running the eve service.
+
+## Managing vercel.json yourself
+
+When `vercel.json` declares [`services`](https://vercel.com/docs/services), the plugin generates nothing and your configuration owns routing. It must include the eve service (`framework: "eve"`) and a rewrite that exposes the eve transport, or the build fails:
+
+```json title="vercel.json"
+{
+  "services": {
+    "web": { "root": ".", "framework": "tanstack-start" },
+    "eve": { "root": "agent", "framework": "eve", "buildCommand": "eve build" }
+  },
+  "rewrites": [{ "source": "/eve/v1/(.*)", "destination": { "service": "eve" } }]
+}
+```
+
+## What to read next
+
+- [Frontend overview](./overview): the `useEveAgent` API
+- [Auth & route protection](../auth-and-route-protection)
+- [Deployment](../deployment/overview)

package/docs/guides/session-context.md

@@ -46,6 +46,7 @@ Public fields include:
 - `auth.current`: the caller for the active inbound turn.
 - `auth.initiator`: the caller that started the session.
 - `parent`: the parent call, session, root session, and turn for a child subagent session.
+- `predecessor`: present when eve started this session in place of a [stranded session](../concepts/execution-model-and-durability#stranded-sessions). Its `sessionId` names the session this one replaced. Read the earlier conversation with `sessions.attach(predecessor.sessionId)` from `eve/server`. See [What a replacement session receives](../concepts/execution-model-and-durability#what-a-replacement-session-receives).
 
 Unprotected agents expose `auth.current` and `auth.initiator` as `null`. Top-level schedule sessions use the framework app principal (`principalId: "eve:app"`, `principalType: "runtime"`). See [Authentication](./auth-and-route-protection#what-reaches-ctxsessionauth) for how inbound identity becomes session auth.
 

package/docs/install-integrations.mdx

@@ -19,7 +19,7 @@ eve add memory/file
 
 If an item is not found, `eve add` searches the available catalogs and prints close matches without installing anything.
 
-Web Chat installs a shared Next.js application at `apps/web` for either a standalone agent or a selected member of an agent workspace. Choose **Vercel services** (recommended) to deploy Web Chat and agents as separate services, or **Next.js** to serve Web Chat and route agent requests through one Next.js app. Vercel services run locally without a linked Vercel project; link one when you are ready to deploy. Existing authored Next.js or Vercel configuration is preserved, and eve stops with manual composition guidance instead of overwriting it. See [Project Structure](./concepts/project-structure) for browser-app placement and [Next.js](./guides/frontend/nextjs) for Next.js-owned integration.
+Web Chat installs a shared Next.js or TanStack Start application at `apps/web` for either a standalone agent or a selected member of an agent workspace. The installer asks which framework to use (`web-framework`), then how to deploy it; non-interactive runs use Next.js unless you answer `web-framework="tanstack"`. Choose **Vercel services** (recommended) to deploy Web Chat and agents as separate services, or the framework (**Next.js** or **TanStack Start**) to serve Web Chat and route agent requests through one app. Vercel services run locally without a linked Vercel project; link one when you are ready to deploy. Existing authored Next.js or Vercel configuration is preserved, and eve stops with manual composition guidance instead of overwriting it. See [Project Structure](./concepts/project-structure) for browser-app placement, and [Next.js](./guides/frontend/nextjs) or [TanStack Start](./guides/frontend/tanstack) for framework-owned integration.
 
 If you do not know an item name yet, run `eve add` without an argument. Its help output shows how to search the registry with `eve registry search <query>`.
 

package/docs/instructions.mdx

@@ -80,7 +80,7 @@ A dynamic system result applies at its lifecycle scope. A dynamic user result is
 
 The `messages` snapshot passed to a `session.started` resolver includes static user instructions. A `turn.started` resolver additionally sees user instructions produced at `session.started`. Other dynamic capability resolvers keep their existing snapshots.
 
-See [Dynamic capabilities](./guides/dynamic-capabilities) for examples and failure behavior.
+See [Dynamic capabilities](./guides/dynamic-capabilities) for examples and failure behavior. To give a session that replaced a [stranded session](./concepts/execution-model-and-durability#what-a-replacement-session-receives) the earlier conversation, read its stream with `sessions.attach()` and `transcriptReducer()` in a `session.started` user-role instruction.
 
 ## History controls and prompt caching
 

package/docs/reference/typescript-api.md

@@ -152,7 +152,7 @@ Tool definitions accept `availableInSubagents: false` to restrict the tool to to
 | `eve/evals/reporters`                                                             | `Braintrust`, `JUnit`, `EvalReporter`                                                                                          |
 | `eve/evals/loaders`                                                               | `loadJson`, `loadYaml`                                                                                                         |
 | `eve/react`, `eve/vue`, `eve/svelte`                                              | `useEveAgent`                                                                                                                  |
-| `eve/next`, `eve/nuxt`, `eve/sveltekit`                                           | framework bundler plugins                                                                                                      |
+| `eve/next`, `eve/nuxt`, `eve/sveltekit`, `eve/tanstack`                           | framework bundler plugins                                                                                                      |
 | [`eve/client`](../guides/client/overview)                                         | `Client`, `ClientSession`, health and agent-info schemas, response errors                                                      |
 | [`eve/server`](../concepts/sessions-runs-and-streaming#read-a-session-in-process) | `sessions`, for reading session streams in process                                                                             |
 

package/docs/tools/human-in-the-loop.md

@@ -219,6 +219,8 @@ Approvals and questions share one protocol:
 3. The run parks durably, for as long as it takes. The turn stays open: the stream emits `turn.waiting`, and after the answer the turn resumes under the same `turnId`. That `turn.waiting` carries `on: "input"`, since a person must act.
 4. The client answers with `inputResponses` (structured, keyed by `requestId`) or a normal follow-up `message`. A follow-up whose text matches an option ID, option label, or numeric option index resolves automatically, including approval options such as `approve` and `cancel`.
 
+To tell the model why a call was denied, send `text` with the `cancel` response, for example `{ requestId, optionId: "cancel", text: "Only the three-pack." }`. The model receives the note quoted in the denial result, marked as written by the person who denied the call, who may not be the user. The note is also visible to anyone who can read the session stream, in `input.resolved`.
+
 For `ctx.ask()` questions from tools and prompts proxied from subagents, a follow-up message answers the first open request, as described in [Several requests at once](#several-requests-at-once). The message must match an option, or the question must allow free text. Otherwise the message follows the session's `turnPolicy`. A steering message, the default, aborts the `ctx.abortSignal` of each `execute` workflow tool call the turn waits on, so a question such a call asked, such as `ask_question`'s, is withdrawn and resolves as `cancelled`. The model reads the message once those calls settle.
 
 Each request includes a `kind` discriminator: `tool-approval`, `question`, or

package/docs/tutorial/ship-it.mdx

@@ -7,7 +7,7 @@ The analytics assistant runs in the TUI. Now add a web dashboard and deploy a pr
 
 ## Add the Web Chat app
 
-Step 1 scaffolded the agent without a web frontend. Add one now with `eve add channel/web`, run from the `analytics-assistant/` directory:
+Step 1 scaffolded the agent without a web frontend. Add one now with `eve add channel/web`, run from the `analytics-assistant/` directory, and choose **Next.js** when it asks which framework to use:
 
 ```bash
 npx eve add channel/web

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve",
-  "version": "0.76.0",
+  "version": "0.76.2",
   "private": false,
   "description": "Filesystem-first framework for durable backend AI agents that run anywhere.",
   "keywords": [
@@ -16,6 +16,7 @@
     "observability",
     "react",
     "serverless",
+    "tanstack",
     "tools",
     "vercel",
     "workflow"
@@ -102,6 +103,11 @@
       "import": "./dist/src/public/sveltekit/index.js",
       "default": "./dist/src/public/sveltekit/index.js"
     },
+    "./tanstack": {
+      "types": "./dist/src/public/tanstack/index.d.ts",
+      "import": "./dist/src/public/tanstack/index.js",
+      "default": "./dist/src/public/tanstack/index.js"
+    },
     "./tools/approval": {
       "types": "./dist/src/public/tools/approval/index.d.ts",
       "import": "./dist/src/public/tools/approval/index.js",