eve 0.52.2 → 0.52.3

package/docs/tutorial/ship-it.mdx

@@ -1,9 +1,9 @@
 ---
 title: "Ship It"
-description: "Part 9 of the Build an Agent tutorial. Put a web dashboard on the agent with useEveAgent, replace placeholderAuth, and deploy to Vercel."
+description: "Part 8 of the Build an Agent tutorial. Put a web dashboard on the agent with useEveAgent, replace placeholderAuth, and deploy to Vercel."
 ---
 
-The analytics assistant runs fine in the TUI. Now ship it for real, as a web dashboard your team logs into, behind actual auth, deployed on Vercel. There are three pieces to wire up. A React UI, the channel's auth, and the deploy itself.
+The analytics assistant runs in the TUI. Now add a web dashboard and deploy a private, single-user version on Vercel. This example protects the sample app with a username and password. It does not require another authentication service.
 
 ## Add the Web Chat app
 
@@ -24,121 +24,110 @@ const nextConfig: NextConfig = {};
 export default withEve(nextConfig);
 ```
 
-## A dashboard with `useEveAgent`
-
-The dashboard talks to the built-in eve HTTP channel (`agent/channels/eve.ts`). On the browser side, `useEveAgent` handles session creation, streaming, and HITL. The scaffold renders its chat from `app/_components/agent-chat.tsx`, mounted by `app/page.tsx`. That component is fuller than you need to start, so replace its contents with this minimal version:
-
-```tsx title="app/_components/agent-chat.tsx"
-"use client";
-
-import { useEveAgent } from "eve/react";
-
-export function AgentChat() {
-  const agent = useEveAgent();
-  const isBusy = agent.status === "submitted" || agent.status === "streaming";
-
-  return (
-    <form
-      onSubmit={(event) => {
-        event.preventDefault();
-        const data = new FormData(event.currentTarget);
-        const message = String(data.get("q") ?? "").trim();
-        if (message) void agent.send(message);
-      }}
-    >
-      {agent.data.messages.map((message) => (
-        <article key={message.id}>
-          <header>{message.role}</header>
-          {message.parts.map((part, index) =>
-            part.type === "text" ? <p key={index}>{part.text}</p> : null,
-          )}
-        </article>
-      ))}
-      <input name="q" disabled={isBusy} placeholder="Ask about the data…" />
-      <button type="submit" disabled={isBusy}>
-        Ask
-      </button>
-    </form>
-  );
-}
-```
-
-The generated `app/page.tsx` already imports and renders this `AgentChat` export, so no other wiring is needed:
+## Use the generated chat
 
-```tsx title="app/page.tsx"
-import { AgentChat } from "@/app/_components/agent-chat";
+Keep the generated `app/_components/agent-chat.tsx` and `agent-message.tsx` components. `app/page.tsx` already renders the chat, and `useEveAgent` handles session creation and streaming.
 
-export default function Page() {
-  return <AgentChat />;
-}
-```
+The generated UI displays tool results and errors, authorization links, approval buttons, and question forms. The spend approval from [Guard the spend](./guard-the-spend) needs those controls to resume a waiting turn. A component that renders only text messages leaves those interactions unavailable.
 
-`agent.data.messages` and `agent.status` cover most chat UIs. The generated Web Chat renders HITL prompts directly in the conversation: approvals get action controls, and `ask_question` gets a visible form with vertical choices, a text field, or both. The spend approval from [Step 8](./guard-the-spend) uses the same response path. For the full API, see [Frontend](../guides/frontend/overview).
+Run `npm run dev`, open the local web URL printed by the server, and ask for an unfiltered revenue query. Confirm that the approval appears and that approving it lets the query finish. You can customize the UI after this flow works; see [Frontend](../guides/frontend/overview).
 
 ## Replace `placeholderAuth`
 
-The scaffold's channel ships with `placeholderAuth()`, which fails closed. It rejects production traffic so an unauthenticated app can't go live by accident. Swap it for your app's real auth before you deploy.
+The scaffold's channel ships with `placeholderAuth()`, which rejects unauthenticated production requests. Replace it with a verifier that checks credentials on every request. Never return a fixed user without checking the request.
 
-Your auth lives in one module that turns a request into a user. Create `agent/lib/auth.ts` and wire your real provider (a cookie session, Auth.js, Clerk) in here. The stub below returns a fixed user so the page compiles and runs end to end:
+Create `agent/lib/auth.ts`. This uses eve's HTTP Basic verifier, which compares passwords in constant time. Missing environment variables, missing credentials, and wrong credentials all fail closed:
 
 ```ts title="agent/lib/auth.ts"
-export interface AppUser {
-  id: string;
-  team: string;
-}
-
-// Replace with your real session/provider lookup.
-export async function authenticate(_request: Request): Promise<AppUser | null> {
-  return { id: "demo-user", team: "growth" };
-}
+import { verifyHttpBasic, withAuthChallenges } from "eve/channels/auth";
+
+export const appAuth = withAuthChallenges(
+  (request: Request) => {
+    const username = process.env.ANALYTICS_USERNAME;
+    const password = process.env.ANALYTICS_PASSWORD;
+    if (!username || !password) return null;
+
+    if (request.headers.has("origin") && request.headers.get("sec-fetch-site") !== "same-origin")
+      return null;
+
+    const result = verifyHttpBasic(request.headers.get("authorization"), { username, password });
+    if (!result.ok) return null;
+
+    return {
+      ...result.sessionAuth,
+      attributes: { team: "growth" },
+      issuer: "analytics-tutorial",
+    };
+  },
+  [{ scheme: "Basic", parameters: { realm: "analytics", charset: "UTF-8" } }],
+);
 ```
 
-Now point the channel at it. Replace the contents of `agent/channels/eve.ts`, which Step 7 left with a dev-only `devTeam` entry and `placeholderAuth()`. List your app auth first, ahead of the catch-all helpers, so any entry that doesn't recognize the caller falls through to the next one:
+Replace `agent/channels/eve.ts`, removing the earlier `devTeam` entry. The eve channel checks `appAuth` for session creation, messages, controls, and streams. The remaining helpers preserve authenticated Vercel CLI access and local development:
 
 ```ts title="agent/channels/eve.ts"
 import { eveChannel } from "eve/channels/eve";
-import { localDev, vercelOidc, type AuthFn } from "eve/channels/auth";
-import { authenticate } from "../lib/auth";
-
-const appAuth: AuthFn<Request> = async (request) => {
-  const user = await authenticate(request); // your cookie/session/provider
-  if (!user) return null;
-  return {
-    attributes: { team: user.team }, // the claim Step 7's playbook reads
-    principalType: "user",
-    principalId: user.id,
-    authenticator: "app",
-    issuer: "analytics-dashboard",
-  };
-};
+import { localDev, vercelOidc } from "eve/channels/auth";
+import { appAuth } from "../lib/auth";
 
 export default eveChannel({
   auth: [appAuth, vercelOidc(), localDev()],
 });
 ```
 
-That `team` attribute is exactly what the dynamic playbook in [Step 7](./team-playbooks) reads from `ctx.session.auth`. Identity is set in this one place and flows out to every capability from there.
+The verified username becomes the user principal. The `growth` team selects the sample playbook from [Team playbooks](./team-playbooks). Keep these credentials private to one person. A shared password does not give each person a separate identity or isolated sessions. For a multi-user app, use a real session provider and enforce [session ownership](../guides/auth-and-route-protection#what-reaches-ctxsessionauth).
+
+Add `proxy.ts` at the project root so opening the dashboard triggers the browser's native username/password prompt. It protects the generated UI routes; eve API routes keep their channel auth, so an OIDC-authenticated CLI request does not encounter a browser-only gate:
+
+```ts title="proxy.ts"
+import { routeAuth } from "eve/channels/auth";
+import { NextResponse } from "next/server";
+import { appAuth } from "./agent/lib/auth";
+
+export async function proxy(request: Request) {
+  if (process.env.NODE_ENV === "development") return NextResponse.next();
+  const result = await routeAuth(request, appAuth);
+  return result instanceof Response ? result : NextResponse.next();
+}
+
+export const config = { matcher: ["/", "/s/:path*"] };
+```
+
+After login, the browser sends the credentials on same-origin requests from the generated chat. When a browser sends an `Origin` header, the Basic verifier also requires [`Sec-Fetch-Site: same-origin`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Sec-Fetch-Site). Keep the auth module server-side: never put the password in a React component, a `NEXT_PUBLIC_` variable, or a client-side `useEveAgent` option. Use HTTPS for deployed HTTP Basic authentication.
 
 ## Deploy to Vercel
 
+From `analytics-assistant/`, link a Vercel project and add a username and a long, unique password. These commands prompt for values without putting the password in shell history:
+
 ```bash
-vercel deploy
+npx vercel@latest link
+npx vercel@latest env add ANALYTICS_USERNAME preview
+npx vercel@latest env add ANALYTICS_PASSWORD preview
 ```
 
-On Vercel, the web app stays public and the eve runtime sits behind it on the same origin, with the sandbox running on Vercel Sandbox. You can smoke-test the deployment without leaving the CLI:
+Before deploying, configure the model credential your agent uses in the project's Preview environment; local `.env` values are not uploaded by deployment. If you used a local ChatGPT subscription, switch `agent/agent.ts` to an AI Gateway model and configure `AI_GATEWAY_API_KEY` for that model. Subscription credentials stay on your laptop. See [Deployment](../guides/deployment/overview) for model and runtime configuration.
+
+```bash
+npx vercel@latest deploy
+```
+
+Open the HTTPS preview URL and enter the configured username and password. Create a session and ask a sample-data question. In a private browser window, cancel the login prompt and verify the dashboard is denied. A `POST /eve/v1/session` request without credentials must also return `401`.
+
+The authenticated web app and eve runtime share the same origin, and the sandbox runs on Vercel Sandbox. You can also smoke-test the deployment through the authenticated CLI:
 
 ```bash
 npx eve dev https://your-analytics-app.vercel.app
 ```
 
-That's the full assistant, deployed and authed. It queries the warehouse, runs analysis in a sandbox, charts the results, remembers your team's definitions, loads the right playbook per team, and asks before it spends.
+For a production deployment, add the username, password, and model credential to the Production environment too, then run `npx vercel@latest deploy --prod`. Missing Basic credentials keep browser access closed.
+
+The private assistant queries the sample data, runs analysis in a sandbox, charts the results, remembers definitions, loads the Growth playbook, and asks before an expensive query.
 
 ## What you learned
 
-Across the nine steps you built and shipped one agent, and along the way you used:
+Across the eight steps you built and shipped one agent, and along the way you used:
 
 - **Tools** to give the model typed actions (`run_sql`, `chart_series`, `define_metric`).
-- **Connections** to reach a warehouse over an OAuth MCP, with per-user tokens eve resolves for you.
 - **The sandbox** to compute and chart beyond SQL in an isolated `/workspace`.
 - **State** (`defineState`) to remember the team's glossary across turns.
 - **Dynamic skills** (`defineDynamic`) to load the right team playbook per caller.
@@ -148,6 +137,7 @@ Across the nine steps you built and shipped one agent, and along the way you use
 
 ## Next steps
 
+- [Connect a warehouse](./connect-a-warehouse) when you have a data service to use in place of the sample dataset.
 - [MCP connections](../connections/mcp) for tool allowlists and per-connection approval.
 - [Sandbox](../sandbox) for backends, lifecycle, and network policy.
 - [Dynamic capabilities](../guides/dynamic-capabilities) for schema-derived dynamic tools, a read-only analyst subagent, and model-authored report workflows on this same example.

package/docs/tutorial/team-playbooks.mdx

@@ -1,9 +1,9 @@
 ---
 title: "Team Playbooks"
-description: "Part 7 of the Build an Agent tutorial. Load the caller's team playbook with a dynamic skill keyed on the principal."
+description: "Part 6 of the Build an Agent tutorial. Load the caller's team playbook with a dynamic skill keyed on the principal."
 ---
 
-The glossary from [Step 6](./remember-definitions) is per-session. But your teams have standing analysis conventions for the analytics assistant (Growth runs cohort retention a particular way, Finance has its own revenue-recognition rules), and those shouldn't bleed across tenants. Load the right team's playbook for whoever is asking.
+The glossary from [Step 5](./remember-definitions) is per-session. But your teams have standing analysis conventions for the analytics assistant (Growth groups revenue by date, Finance reconciles customer totals), and those shouldn't bleed across tenants. Load the right team's playbook for whoever is asking.
 
 A skill is an on-demand procedure. The model pulls it in with `load_skill` only when a turn needs it. Make it dynamic and the skill gets decided at runtime instead of baked in. A `defineDynamic` resolver reads the session and returns a `defineSkill` (or nothing). Here you key that decision on the caller's identity in `ctx.session.auth`.
 
@@ -18,14 +18,14 @@ const PLAYBOOKS: Record<string, { title: string; markdown: string }> = {
   growth: {
     title: "Growth analysis playbook",
     markdown:
-      "When analyzing retention, use weekly cohorts anchored on signup week, " +
-      "report curves not point estimates, and exclude trial accounts.",
+      "When analyzing sample orders, group revenue by order date, report dollars, " +
+      "and compare customers by plan.",
   },
   finance: {
     title: "Finance analysis playbook",
     markdown:
-      "Report revenue net of refunds and recognized over the subscription term. " +
-      "Always reconcile against the close-of-month snapshot.",
+      "Reconcile total order revenue against the daily and customer totals. " +
+      "Report dollars and label this as gross order revenue; the dataset has no refunds.",
   },
 };
 
@@ -52,14 +52,14 @@ export default defineDynamic({
 
 ## See it route
 
-The team comes from authenticated claims, which the auth layer stamps on in [Step 9](./ship-it). Until then `ctx.session.auth.current` has no `team`, so the resolver returns `null` and no playbook loads. To verify routing now, stamp a team in local dev. Add a dev-only entry to `agent/channels/eve.ts` ahead of `localDev()`, and remove it before Step 9 wires real auth:
+The team comes from authenticated claims, which the auth layer stamps on in [Step 8](./ship-it). Until then `ctx.session.auth.current` has no `team`, so the resolver returns `null` and no playbook loads. To verify routing now, stamp a team in local dev. Add a dev-only entry to `agent/channels/eve.ts` ahead of `localDev()`, and remove it before Step 8 wires real auth:
 
 ```ts title="agent/channels/eve.ts"
 import { eveChannel } from "eve/channels/eve";
 import { localDev, placeholderAuth, vercelOidc, type AuthFn } from "eve/channels/auth";
 
-// Dev-only: stamp a team so Step 7's playbook resolver has something to read.
-// Remove before Step 9.
+// Dev-only: stamp a team so Step 6's playbook resolver has something to read.
+// Remove before Step 8.
 const devTeam: AuthFn<Request> = () =>
   process.env.NODE_ENV === "production"
     ? null
@@ -75,7 +75,7 @@ export default eveChannel({
 });
 ```
 
-Restart with `npm run dev` and ask "what's our 8-week retention?" The model sees the Growth playbook fits, calls `load_skill`, and applies the Growth conventions to that turn (weekly cohorts, no trial accounts). Switch `team` to `"finance"`, restart, and the same question routes to Finance's playbook instead.
+Restart with `npm run dev` and ask "Summarize May 2026 revenue using our team's playbook." The model calls `load_skill`, queries the sample data, and applies Growth's daily and plan groupings. Switch `team` to `"finance"`, restart, and start a new session before asking again. The resolver runs at `session.started`, so changing the team does not replace the playbook in an existing session. The same question in the new session uses Finance's reconciliation rules.
 
 Because the team comes from authenticated claims, not from the message, one tenant can't borrow another's playbook through the message content.
 

package/package.json

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

package/dist/src/execution/activity-text.js

@@ -1 +0,0 @@
-const MAX_ACTIVITY_TEXT_LENGTH=500;function normalizeActivityText(e){return e.replace(/\p{Cc}/gu,` `).replace(/\s+/g,` `).trim().slice(0,500)}export{MAX_ACTIVITY_TEXT_LENGTH,normalizeActivityText};

package/dist/src/internal/workflow-bundle/authored-workflow-modules.d.ts

@@ -1,9 +0,0 @@
-export interface AuthoredWorkflowModules {
-    readonly directiveModules: readonly string[];
-    readonly workflowModules: readonly string[];
-}
-/**
- * Scans the whole application root, as the SDK's bundler integrations do, so a
- * step helper can live wherever the tool imports it from.
- */
-export declare function discoverAuthoredWorkflowModules(appRoot: string): Promise<AuthoredWorkflowModules>;

package/dist/src/internal/workflow-bundle/authored-workflow-modules.js

@@ -1 +0,0 @@
-import{prepareAuthoredWorkflowDirectives}from"./authored-workflow-directives.js";import{isWorkflowSourceFile}from"./builder-support.js";import{isAuthoredApplicationModule,isAuthoredApplicationRoot}from"./workflow-builders.js";import{readFile,readdir}from"node:fs/promises";import{join}from"node:path";import{isGeneratedWorkflowFile}from"#compiled/@workflow/builders/index.js";const IGNORED_DIRECTORIES=new Set([`.cache`,`.eve`,`.git`,`.next`,`.nitro`,`.nuxt`,`.output`,`.pnpm-store`,`.svelte-kit`,`.swc`,`.turbo`,`.vercel`,`.workflow-data`,`.workflow-vitest`,`.yarn`,`coverage`,`dist`,`node_modules`]);function isIgnoredDirectory(e){return IGNORED_DIRECTORIES.has(e)||e.startsWith(`.output.`)}async function discoverAuthoredWorkflowModules(e){let t=[],n=[];if(!isAuthoredApplicationRoot(e))return{directiveModules:t,workflowModules:n};let r=await collectSourceFiles(e);for(let i of r.sort()){if(!isAuthoredApplicationModule(i,e)||isGeneratedWorkflowFile(i))continue;let r=await readFile(i,`utf8`);if(!r.includes(`use workflow`)&&!r.includes(`use step`))continue;let a=await prepareAuthoredWorkflowDirectives({filePath:i,source:r});a.hasDirectives&&(t.push(i),a.hasWorkflowDirective&&n.push(i))}return{directiveModules:t,workflowModules:n}}async function collectSourceFiles(e){let t=[];async function visit(e){let n;try{n=await readdir(e,{withFileTypes:!0})}catch(e){if(e instanceof Error&&`code`in e&&e.code===`ENOENT`)return;throw e}for(let r of n){let n=join(e,r.name);if(r.isDirectory()){isIgnoredDirectory(r.name)||await visit(n);continue}r.isFile()&&isWorkflowSourceFile(r.name)&&t.push(n)}}return await visit(e),t}export{discoverAuthoredWorkflowModules};

package/dist/src/public/models/openai/chatgpt/codex-app-server.d.ts

@@ -1,40 +0,0 @@
-import { type ChildProcessWithoutNullStreams } from "node:child_process";
-export interface CodexAuthStatus {
-    readonly authMethod?: string;
-    readonly authToken?: string;
-    readonly requiresOpenaiAuth?: boolean;
-}
-export interface CodexAppServer {
-    getAuthStatus(input: {
-        readonly refreshToken: boolean;
-    }): Promise<CodexAuthStatus>;
-    restart?(): void;
-}
-export interface CodexAppServerProcess {
-    readonly stderr: ChildProcessWithoutNullStreams["stderr"];
-    readonly stdin: ChildProcessWithoutNullStreams["stdin"];
-    readonly stdout: ChildProcessWithoutNullStreams["stdout"];
-    kill(): boolean;
-    once(event: "error", listener: (error: Error) => void): this;
-    once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;
-    unref(): void;
-}
-type SpawnCodexAppServer = (command: string, args: readonly string[], options: {
-    readonly env?: NodeJS.ProcessEnv;
-    stdio: ["pipe", "pipe", "pipe"];
-}) => CodexAppServerProcess;
-export interface CodexAppServerOptions {
-    readonly command?: string;
-    readonly env?: NodeJS.ProcessEnv;
-    readonly spawnProcess?: SpawnCodexAppServer;
-}
-/** Minimal authenticated subset of Codex's JSONL app-server protocol. */
-export declare class CodexAppServerClient implements CodexAppServer {
-    #private;
-    constructor(options?: CodexAppServerOptions);
-    getAuthStatus(input: {
-        readonly refreshToken: boolean;
-    }): Promise<CodexAuthStatus>;
-    restart(): void;
-}
-export {};

package/dist/src/public/models/openai/chatgpt/codex-app-server.js

@@ -1 +0,0 @@
-import{spawn}from"node:child_process";import{isObject}from"#shared/guards.js";import{createInterface}from"node:readline";var CodexAppServerClient=class{#e;#t;#n;#r;constructor(e={}){this.#e=e.command??`codex`,this.#t=e.env,this.#n=e.spawnProcess??spawnCodexAppServer}async getAuthStatus(e){let t=await this.#i();try{return await t.getAuthStatus(e)}catch(e){throw t.exited&&(this.#r=void 0),e}}restart(){let e=this.#r;this.#r=void 0,e?.then(e=>e.close()).catch(()=>void 0)}#i(){return this.#r===void 0&&(this.#r=CodexAppServerConnection.start({command:this.#e,env:this.#t,spawnProcess:this.#n}).catch(e=>{throw this.#r=void 0,e})),this.#r}},CodexAppServerConnection=class CodexAppServerConnection{#e;#t;#n=new Map;#r=1;#i=!1;#a;constructor(e){this.#e=e,e.unref(),unrefStream(e.stdin),unrefStream(e.stdout),unrefStream(e.stderr),e.stderr.resume(),this.#t=createInterface({input:e.stdout}),this.#t.on(`line`,e=>this.#l(e)),e.once(`error`,e=>this.#u(e)),e.once(`exit`,(e,t)=>{let n=t===null?`code ${e??`unknown`}`:`signal ${t}`;this.#u(Error(`Codex app-server exited with ${n}.`))})}get exited(){return this.#i}close(){this.#e.kill(),this.#u(Error(`Codex app-server connection was restarted.`))}static async start(e){let t;try{t=e.spawnProcess(e.command,[`app-server`,`--stdio`],{env:e.env,stdio:[`pipe`,`pipe`,`pipe`]})}catch(e){throw codexUnavailableError(e)}let n=new CodexAppServerConnection(t);try{return await n.#o(`initialize`,{capabilities:null,clientInfo:{name:`eve`,title:`eve`,version:`0.35.0`}}),n.#s(`initialized`,{}),n}catch(e){throw t.kill(),e}}async getAuthStatus(e){let t=await this.#o(`getAuthStatus`,{includeToken:!0,refreshToken:e.refreshToken});if(!isObject(t))throw Error(`Codex app-server returned an invalid authentication response.`);return{...typeof t.authMethod==`string`&&{authMethod:t.authMethod},...typeof t.authToken==`string`&&{authToken:t.authToken},...typeof t.requiresOpenaiAuth==`boolean`&&{requiresOpenaiAuth:t.requiresOpenaiAuth}}}#o(e,t){if(this.#i)return Promise.reject(this.#a??Error(`Codex app-server is not running.`));let n=this.#r++,r=new Promise((e,t)=>{this.#n.set(n,{reject:t,resolve:e})});return this.#c({id:n,method:e,params:t}),r}#s(e,t){this.#c({method:e,params:t})}#c(e){this.#e.stdin.write(`${JSON.stringify(e)}\n`)}#l(e){let t;try{t=JSON.parse(e)}catch{return}if(typeof t.id!=`number`)return;let n=this.#n.get(t.id);if(n!==void 0){if(this.#n.delete(t.id),t.error!==void 0){n.reject(Error(t.error.message??`Codex app-server request failed (${t.error.code}).`));return}n.resolve(t.result)}}#u(e){if(!this.#i){this.#i=!0,this.#a=codexUnavailableError(e),this.#t.close();for(let e of this.#n.values())e.reject(this.#a);this.#n.clear()}}};function spawnCodexAppServer(e,t,n){return spawn(e,[...t],n)}function unrefStream(e){`unref`in e&&typeof e.unref==`function`&&e.unref()}function codexUnavailableError(e){if(e instanceof Error&&`code`in e&&e.code===`ENOENT`)return Error("ChatGPT subscription authentication requires the Codex CLI. Install or upgrade `codex`, then run `codex login`.");let t=e instanceof Error?e.message:String(e);return Error(`Codex app-server is unavailable: ${t}`)}export{CodexAppServerClient};