eve 0.52.2 → 0.52.4

package/docs/tutorial/run-analysis.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Run Analysis"
-description: "Part 5 of the Build an Agent tutorial. Seed the warehouse schema into the sandbox workspace, then compute and chart beyond SQL."
+description: "Part 4 of the Build an Agent tutorial. Seed the sample database schema into the sandbox workspace, then compute and chart beyond SQL."
 ---
 
 SQL tells the analytics assistant the numbers, but a cohort curve, a forecast, or a chart needs real computation. That's what the sandbox is for. It's an isolated bash environment with a `/workspace` filesystem, and every agent gets exactly one.
@@ -9,7 +9,7 @@ This takes two pieces. First seed reference files the model can read, then compu
 
 ## Seed the schema into the workspace
 
-Mount the warehouse schema into the sandbox so the model isn't guessing at table shapes. Seeding uses the folder sandbox layout, where anything under `agent/sandbox/workspace/` lands in the live `/workspace` cwd at session bootstrap.
+Mount the sample database schema into the sandbox so the model isn't guessing at table shapes. Seeding uses the folder sandbox layout, where anything under `agent/sandbox/workspace/` lands in the live `/workspace` cwd at session bootstrap.
 
 ```text
 agent/sandbox/
@@ -21,65 +21,202 @@ agent/sandbox/
 ```sql
 -- agent/sandbox/workspace/schema.sql
 -- Reference only: table shapes the analyst can read before writing queries.
-CREATE TABLE orders     (id INT, customer_id INT, amount_cents INT, created_at DATE);
-CREATE TABLE customers  (id INT, name TEXT, plan TEXT, signed_up_at DATE);
+CREATE TABLE orders     (id INTEGER, customer_id INTEGER, amount_cents INTEGER, created_at TEXT);
+CREATE TABLE customers  (id INTEGER, name TEXT, plan TEXT);
 ```
 
-Top-level workspace entries get advertised to the model automatically, so it knows `schema.sql` is there to read. No `agent/sandbox/sandbox.ts` required. A `workspace/` folder keeps the default sandbox and seeds your files into it.
+Top-level workspace entries get advertised to the model automatically, so it knows `schema.sql` is there to read. A `workspace/` folder seeds your files without requiring a sandbox definition. Add one next to install the chart dependencies.
+
+## Install the chart dependencies
+
+Python needs a sandbox that runs real binaries. For local development, start a Docker-compatible daemon and run `docker info` to verify it is reachable before restarting `npm run dev`. eve also supports [microsandbox](../sandbox#microsandbox) on compatible hosts. The `just-bash` fallback cannot run Python or install packages; installing Python on your laptop does not add it to the sandbox. You can [continue to the next chapter](./remember-definitions) if you do not want to set up a local container or VM yet.
+
+The default eve images for Docker, microsandbox, and Vercel Sandbox include Python, but not matplotlib. Add this definition alongside `workspace/` to install matplotlib in a virtual environment. It uses the same environment for installation and chart execution, without changing the system Python:
+
+```ts title="agent/sandbox/sandbox.ts"
+import { defineSandbox } from "eve/sandbox";
+
+export default defineSandbox({
+  async bootstrap({ use }) {
+    const sandbox = await use();
+    const commands = [
+      "sudo apt-get update && sudo apt-get install -y python3 python3-venv",
+      "python3 -m venv /workspace/.venv",
+      "/workspace/.venv/bin/python -m pip install matplotlib==3.10.8",
+      "/workspace/.venv/bin/python -c \"import matplotlib.pyplot; print('Chart dependencies ready')\"",
+    ];
+    for (const command of commands) {
+      const result = await sandbox.run({ command });
+      if (result.exitCode !== 0) {
+        throw new Error(
+          `Chart setup failed (exit ${result.exitCode}): ${result.stderr || result.stdout}`,
+        );
+      }
+    }
+  },
+});
+```
+
+Bootstrap runs when eve builds the sandbox template, and sessions inherit the installed environment. The first build needs network access to Ubuntu package repositories and PyPI. Keep the default network policy while following this example; a custom `deny-all` or allow-list policy must permit these downloads during bootstrap. The same definition uses Vercel Sandbox after deployment to Vercel.
+
+Restart `npm run dev` after adding the definition. Before asking for a chart, send this message in the TUI:
+
+```text
+Run /workspace/.venv/bin/python -c "import matplotlib; print(matplotlib.__version__)" in the sandbox.
+```
+
+The command should print `3.10.8`. If setup fails, check the dev server's sandbox logs for the failing command. Resolve the package download or backend error before continuing.
 
 ## Compute and chart in the sandbox
 
 The built-in `bash`, `read_file`, and `write_file` tools already target the sandbox. When you write your own analysis steps, grab a live handle with `ctx.getSandbox()`:
 
 ```ts title="agent/tools/chart_series.ts"
+import { randomUUID } from "node:crypto";
 import { defineTool } from "eve/tools";
 import { z } from "zod";
 
 export default defineTool({
   description:
     "Plot a time series to a PNG in the workspace. Pass {date, value} points; " +
-    "returns the chart path.",
+    "returns the chart path and PNG data for the client to save.",
   inputSchema: z.object({
-    title: z.string(),
-    points: z.array(z.object({ date: z.string(), value: z.number() })),
+    title: z.string().min(1).max(120),
+    points: z
+      .array(z.object({ date: z.string().max(40), value: z.number() }))
+      .min(1)
+      .max(366),
   }),
   async execute({ title, points }, ctx) {
     const sandbox = await ctx.getSandbox();
+    const directory = `analysis/${randomUUID()}`;
     await sandbox.writeTextFile({
-      path: "analysis/series.json",
+      path: `${directory}/series.json`,
       content: JSON.stringify({ title, points }),
     });
     await sandbox.writeTextFile({
-      path: "analysis/plot.py",
+      path: `${directory}/plot.py`,
       content: [
         "import json, matplotlib",
         "matplotlib.use('Agg')",
         "import matplotlib.pyplot as plt",
         "d = json.load(open('series.json'))",
+        "plt.figure(figsize=(8, 4), dpi=100)",
         "plt.plot([p['date'] for p in d['points']], [p['value'] for p in d['points']])",
         "plt.title(d['title']); plt.savefig('chart.png')",
       ].join("\n"),
     });
-    const root = sandbox.resolvePath("analysis");
-    await sandbox.run({ command: `cd ${JSON.stringify(root)} && python plot.py` });
-    return { chart: `${root}/chart.png` };
+    const root = sandbox.resolvePath(directory);
+    const result = await sandbox.run({
+      command: `cd ${JSON.stringify(root)} && /workspace/.venv/bin/python plot.py`,
+    });
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `Chart generation failed (exit ${result.exitCode}): ${result.stderr || result.stdout}`,
+      );
+    }
+    const chart = `${root}/chart.png`;
+    const png = await sandbox.readBinaryFile({ path: chart });
+    if (!png || png.byteLength === 0) {
+      throw new Error("The chart command did not produce a PNG.");
+    }
+    if (png.byteLength > 1024 * 1024) {
+      throw new Error("The chart exceeds the 1 MiB download limit. Plot fewer points.");
+    }
+    return { chart, pngBase64: Buffer.from(png).toString("base64") };
+  },
+  toModelOutput({ chart }) {
+    return {
+      type: "text",
+      value: `Created ${chart}. The PNG is available in the tool result for the client to save.`,
+    };
   },
 });
 ```
 
-This tool shells out to `python` with matplotlib, which the sandbox base image does not preinstall. Install the runtime in sandbox bootstrap (or bake it into a custom image) so `python plot.py` resolves. See [Sandbox](../sandbox) for where bootstrap runs.
+The tool uses the Python environment installed in bootstrap. `matplotlib.use('Agg')` selects a renderer that writes PNGs without a desktop display.
 
-Now ask for something past plain SQL. If you skipped Step 4, this still works against the Step 3 sample dataset:
+`sandbox.run()` returns an exit code even when the command fails. Check `exitCode` before returning a chart path. Throwing an error gives the model the failed command's output, including a missing Python executable or matplotlib import, so it can report the failure instead of claiming a chart exists.
+
+Ask for a chart using the sample data from Step 3:
 
 ```text
-Plot total order revenue per customer.
+Plot daily order revenue in dollars for May 2026.
+```
+
+The model queries `run_sql` for daily totals, divides `amount_cents` by 100, and passes date/value points to `chart_series`. The sample data has four dates with revenue of $42, $15, $99, and $8. The chart uses the same data you queried in Step 3.
+
+## Save the chart to your computer
+
+A sandbox path is not a download URL or a file on your laptop. `readBinaryFile` copies the generated PNG out of the sandbox into the tool result, where your client can use it. `toModelOutput` sends the model only a short description, so the image's base64 data does not fill its context. The TUI shows tool results as text; it does not save or preview this PNG automatically.
+
+Create this script in your project root. It asks for a chart through the same local HTTP API as the TUI, then saves the successful tool result as `chart.png` in the directory where you run the script:
+
+```ts title="save-chart.ts"
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { Client } from "eve/client";
+import { z } from "zod";
+
+const host = process.argv[2];
+if (!host) throw new Error("Usage: node save-chart.ts <dev-server-url>");
+
+const client = new Client({ host });
+const { response } = await client.sessions.create({
+  message: "Use run_sql and chart_series to plot daily order revenue in May 2026.",
+});
+const turn = await response.result();
+if (turn.status === "failed") throw new Error("The agent turn failed. Check the dev server logs.");
+if (turn.inputRequests.length > 0) {
+  const prompts = turn.inputRequests.map((request) => request.prompt).join("\n");
+  throw new Error(
+    `Session ${turn.sessionId} needs your input before it can create the chart:\n${prompts}`,
+  );
+}
+
+const chartOutput = z.object({ pngBase64: z.string().min(1).max(1_398_104) });
+let saved = false;
+for (const event of turn.events) {
+  if (event.type !== "action.result") continue;
+  const result = event.data.result;
+  if (result.kind !== "tool-result" || result.toolName !== "chart_series" || result.isError)
+    continue;
+
+  const { pngBase64 } = chartOutput.parse(result.output);
+  const png = Buffer.from(pngBase64, "base64");
+  if (
+    png.byteLength > 1024 * 1024 ||
+    !png.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))
+  ) {
+    throw new Error("The tool result is not a PNG within the 1 MiB download limit.");
+  }
+  await writeFile("chart.png", png);
+  saved = true;
+}
+if (!saved) {
+  console.error(turn.message ?? "The agent returned no explanation.");
+  throw new Error("No chart was returned. Check the agent's response above and sandbox setup.");
+}
+console.log(`Saved ${resolve("chart.png")}`);
+```
+
+Keep `npm run dev` running. In a second terminal, run the script with the actual URL printed by the dev server; for example:
+
+```bash
+node save-chart.ts http://localhost:2000
 ```
 
-The model queries for the numbers (the warehouse from Step 4, or the sample dataset if you skipped it), checks `schema.sql` to get the grain right, then calls `chart_series` to render the PNG in `/workspace`.
+Open the saved `chart.png` in your image viewer. This creates a separate session from your TUI conversation and overwrites an existing `chart.png`. A failed tool call or a turn without a chart fails the script instead of claiming a file was saved.
+
+This step does not require approvals. If you return after adding the approval gate in [Guard the spend](./guard-the-spend), the script reports any pending request with its session ID. [Respond through the client](../guides/client/messages#answer-human-input-requests) before collecting that session's chart result.
+
+The same client can save a chart from a hosted agent: pass the deployment URL and configure [client authentication](../guides/client/overview#authentication) for that deployment. The file is saved on the computer running the script. In a web UI, consume the same `action.result` output to build an image preview or download control. Returning bytes from a tool does not add that UI automatically.
+
+This example caps charts at 1 MiB because tool outputs are persisted with session events. For larger files, copy the bytes to your application's file storage and return an authorized download URL instead. Sandbox files themselves are not permanent artifact storage.
 
 ## Secrets stay out of the sandbox
 
-The sandbox has no `process.env` and no access to your app's secrets. Your warehouse token lives in the app runtime, and firewall brokering is the only path it takes to the warehouse host. It never enters the sandbox process.
+The sandbox has no `process.env` and no access to your app's secrets. The `run_sql` tool and sample database run in your app. You pass only the query results to the chart tool; the sandbox does not need database credentials.
 
 The local backend runs the sandbox on your laptop during `eve dev`; on Vercel it runs on Vercel Sandbox. Lifecycle, backends, and network policy are in [Sandbox](../sandbox).
 

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.4",
   "private": false,
   "description": "Filesystem-first framework for durable backend AI agents that run anywhere.",
   "keywords": [
@@ -290,6 +290,11 @@
       "import": "./dist/src/public/context/index.js",
       "default": "./dist/src/public/context/index.js"
     },
+    "./internal/workflow-step-execution": {
+      "types": "./dist/src/execution/tools/workflow/step-execution.d.ts",
+      "import": "./dist/src/execution/tools/workflow/step-execution.js",
+      "default": "./dist/src/execution/tools/workflow/step-execution.js"
+    },
     "./internal/programmatic-source-loader": {
       "types": "./dist/src/internal/programmatic-source-loader.d.ts",
       "import": "./dist/src/internal/programmatic-source-loader.js",
@@ -420,6 +425,12 @@
       "types": "./dist/src/setup/index.d.ts",
       "import": "./dist/src/setup/index.js",
       "default": "./dist/src/setup/index.js"
+    },
+    "./self-modification/config": {
+      "eve-source": "./src/self-modification/config.ts",
+      "types": "./dist/src/self-modification/config.d.ts",
+      "import": "./dist/src/self-modification/config.js",
+      "default": "./dist/src/self-modification/config.js"
     }
   },
   "publishConfig": {
@@ -478,6 +489,7 @@
     "chat": "4.34.0",
     "chokidar": "5.0.0",
     "commander": "14.0.3",
+    "dd-trace": "6.13.0",
     "emulate": "0.6.0",
     "env-runner": "0.1.16",
     "eventsource-parser": "3.1.0",
@@ -507,6 +519,7 @@
     "@opentelemetry/api": "^1.0.0",
     "ai": "^7.0.82",
     "braintrust": "^3.0.0",
+    "dd-trace": "^6.13.0",
     "just-bash": "^3.1.0",
     "microsandbox": "^0.5.0"
   },
@@ -517,6 +530,9 @@
     "braintrust": {
       "optional": true
     },
+    "dd-trace": {
+      "optional": true
+    },
     "just-bash": {
       "optional": true
     },

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 {};