eve 0.58.1 → 0.59.0

package/docs/concepts/context-control.md

@@ -58,6 +58,10 @@ See [Dynamic capabilities](../guides/dynamic-capabilities) for the resolver API,
 
 ## Compaction and clear
 
+Before a model call, eve checks the projected history together with the effective system instructions and advertised tool schemas. The check runs after `step.started` resolves dynamic capabilities. When the provider reports input usage, eve adds estimates for new messages and growth in the instructions and tool catalog to that count; unchanged schemas are not counted again.
+
+Compaction reserves space for those instructions and tools while reducing conversation history. It cannot shrink the instructions or tool catalog themselves, so keep them within the selected model's context window.
+
 User-role instructions follow the normal history lifecycle. Compaction can summarize them, and clear removes them without rerunning their static definitions or dynamic resolvers. System-role instructions remain outside history and continue to apply after either operation.
 
 Recalled memory also uses user-role messages, but eve keeps their attribution

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

@@ -33,16 +33,31 @@ React, Vue, and Svelte apps reach for [`useEveAgent()`](../guides/frontend/overv
 
 ## Start a session
 
+Create and park a conversation session before its first turn by omitting `message`:
+
+```bash
+curl -X POST http://127.0.0.1:2000/eve/v1/session
+```
+
+eve starts the durable workflow, establishes its inbox, and waits for the first message before
+running session-scoped initialization or emitting `session.started`. The first message sent to the returned
+`sessionId` remains `turn_0`. Message-free creation supports conversation mode only and does not
+accept turn-scoped `clientContext`, `outputSchema`, callbacks, or activity observers.
+
+To create the session and start its first turn in one request, include the message:
+
 ```bash
 curl -X POST http://127.0.0.1:2000/eve/v1/session \
   -H 'content-type: application/json' \
   -d '{"message":"Summarize the latest forecast."}'
 ```
 
-eve responds with `202` and the durable `sessionId` in the JSON body and
+In both forms, eve responds with `202` and the durable `sessionId` in the JSON body and
 `x-eve-session-id` header as soon as Workflow accepts the run. The command inbox can still be
-starting at that point. An immediate follow-up can return `409 session_not_active`; wait for
-`session.waiting` before sending the next message.
+starting at that point. An immediate follow-up can return `409 session_not_ready`; retry that
+code with bounded backoff. The TypeScript client retries sends for up to 20 seconds and respects
+the caller's abort signal. Do not wait
+for `session.waiting` on a prewarmed session: initialization and its first events require a message.
 
 ## Stream a session
 

package/docs/evals/assertions.mdx

@@ -50,15 +50,15 @@ attached.messageIncludes("Sunny");
 
 ## Value assertions with `t.check`
 
-`t.check(value, assertion)` grades an explicit value against a builder from `eve/evals/expect`. The value can be `t.reply`, a turn's `.message`, parsed JSON, or any local you computed:
+`t.check(value, assertion)` grades an explicit value against a builder from `eve/evals/expect`. The value can be a turn’s `.message`, parsed JSON, or any local you computed:
 
 ```ts
 import { includes, equals, matches, satisfies, similarity } from "eve/evals/expect";
 
-t.check(t.reply, includes(/sunny/i)); // substring or RegExp (gate)
+t.check(turn.message, includes(/sunny/i)); // substring or RegExp (gate)
 t.check(parsed, equals({ city: "Brooklyn" })); // deep structural equality (gate)
 t.check(parsed, matches(WeatherSchema)); // Standard Schema, e.g. Zod (gate)
-t.check(t.reply, similarity("Sunny, 72F")); // fuzzy 0–1 Levenshtein (soft)
+t.check(turn.message, similarity("Sunny, 72F")); // fuzzy 0–1 Levenshtein (soft)
 t.check(
   latencyMs,
   satisfies((value) => value < 1_000, "latency under one second"),
@@ -114,7 +114,7 @@ const request = session.requireInputRequest({
 
 ## Run state and derived facts
 
-Beyond the raw `t.events` stream, the runner derives typed facts the assertions read: tool calls (name, input, output, lifecycle status), subagent calls, and HITL input requests. A turn that leaves the session open for a next message is the normal end state of a successful turn; parking on unanswered HITL input is tracked separately.
+Beyond the raw `session.events` stream, the runner derives typed facts the assertions read: tool calls (name, input, output, lifecycle status), subagent calls, and HITL input requests. A turn that leaves the session open for a next message is the normal end state of a successful turn; parking on unanswered HITL input is tracked separately.
 
 Typed event matching covers presence, absence, numeric or predicate counts, partial event data, and ordering:
 
@@ -166,8 +166,8 @@ The defaults are chosen so you rarely set severity. Run-level methods and `inclu
 
 ```ts
 t.calledTool("get_weather").soft(); // record the tool call as a metric, don't gate
-t.check(t.reply, similarity("Sunny")).label("forecast wording").atLeast(0.8);
-t.check(t.reply, includes("error")).soft(); // track without failing the build
+t.check(turn.message, similarity("Sunny")).label("forecast wording").atLeast(0.8);
+t.check(turn.message, includes("error")).soft(); // track without failing the build
 ```
 
 ## What to read next

package/docs/evals/cases.mdx

@@ -15,7 +15,7 @@ export default defineEvalConfig({});
 
 ## Single-turn evals
 
-The common case sends one turn and asserts on the reply. `t.send(input)` resolves once the turn settles, and `t.reply` is the last assistant message:
+The common case sends one turn and asserts on the reply. `t.send(input)` resolves once the turn settles, and the returned turn’s `.message` is the assistant reply:
 
 ```ts title="evals/weather/brooklyn-forecast.eval.ts"
 import { defineEval } from "eve/evals";
@@ -23,9 +23,9 @@ import { includes } from "eve/evals/expect";
 
 export default defineEval({
   async test(t) {
-    await t.send("What is the weather in Brooklyn?");
+    const turn = await t.send("What is the weather in Brooklyn?");
     t.succeeded();
-    t.check(t.reply, includes("Sunny"));
+    t.check(turn.message, includes("Sunny"));
   },
 });
 ```
@@ -60,7 +60,7 @@ evals/
 
 ## Multi-turn evals
 
-Drive several turns in sequence for branching, HITL approvals, structured output, attachments, or multiple sessions. Because assertions live in the function, an intermediate value is a local variable. Judge a draft before the next turn overwrites it, then keep going.
+Drive several turns in sequence for branching, HITL approvals, structured output, attachments, or multiple sessions. Because assertions live in the function, an intermediate value is a local variable. Keep each turn in a local variable and continue through its `.session`.
 
 ```ts title="evals/draft-then-send.eval.ts"
 import { defineEval } from "eve/evals";
@@ -72,7 +72,7 @@ export default defineEval({
     t.check(draft.message, includes("Best regards"));
     t.judge.autoevals.closedQA("professional tone", { on: draft.message }).atLeast(0.6);
 
-    await t.send("Now send it.");
+    await draft.session.send("Now send it.");
     t.calledTool("send_email");
   },
 });
@@ -88,7 +88,7 @@ export default defineEval({
   async test(t) {
     const first = await t.send("My favorite word is marigold.");
 
-    const second = await t.send("What is my favorite word?");
+    const second = await first.session.send("What is my favorite word?");
     await t.require(second.sessionId, equals(first.sessionId));
 
     t.succeeded();
@@ -96,7 +96,7 @@ export default defineEval({
 
     t.judge.autoevals
       .closedQA("The assistant remembers the user's favorite word across turns", {
-        on: t.transcript,
+        on: first.session.transcript,
       })
       .atLeast(0.8);
   },
@@ -105,21 +105,56 @@ export default defineEval({
 
 ## The drive API
 
-`t` drives the primary session; `t.newSession()` returns an independent `EveEvalSession` against the same target, whose events feed the same run-level assertions.
+Every `t.session()` or `t.send()` creates a new independent conversation. Continue an existing conversation through its session handle. Events from all sessions feed the same run-level assertions.
 
-- `t.send(message, options?)` sends a turn and waits for it to settle. It matches `ClientSession.send()` and resolves to a turn carrying `.message` and `.expectOk()`.
-- `t.start(message)` starts a text turn but returns as soon as the server accepts it. The returned live turn exposes `.sessionId`, `.waitForEvent(...)`, `.cancel()`, and `.result()` for coordinating with work that is still running.
-- `t.cancel()` requests cooperative cancellation of the primary session's active turn. Both `accepted` and `no_active_turn` are successful outcomes.
-- `t.sendFile(text, path, mediaType?)` attaches a local file as a data URL.
-- `t.requireInputRequest(filter?)` records a gate, requires exactly one pending request, and returns it. Filters match tool name, action input, prompt, display, and option ids.
-- `t.respond(responses, options?)` answers specific pending input requests and sends them as the next turn.
-- `t.respondAll(optionId)` answers every pending input request with the same option and sends the responses as the next turn.
-- `t.reply` is the last assistant message (or `null`); `t.sessionId` is the current session id; `t.events` is the full typed event stream captured so far.
-- `t.transcript` formats the primary session's observed user and assistant messages in turn order. Pass it as a judge's `on` value to grade the complete conversation. An independent session returned by `t.newSession()` exposes its own `session.transcript`.
+- `t.session(options?)` creates a session without starting a turn or consuming its stream. It resolves on `202 Accepted` with an `EveEvalSession` whose `.sessionId` and `.state` are available. Options accept per-request `headers` and `signal`; creation uses the eval timeout signal by default.
+- `t.send(message, options?)` creates a new session with its first message in one request and waits for the turn to settle. The returned turn carries `.session`, `.message`, and `.expectOk()`.
+- `session.send(message, options?)` sends a follow-up on that session and waits for it to settle.
+- `session.start(message, options?)` starts a text turn and returns as soon as the server accepts it. The live turn exposes `.session`, `.sessionId`, `.waitForEvent(...)`, `.cancel()`, and `.result()`.
+- `session.cancel()` requests cooperative cancellation of that session's active turn. Both `accepted` and `no_active_turn` are successful outcomes.
+- `session.sendFile(text, path, mediaType?)` attaches a local file as a data URL.
+- `session.requireInputRequest(filter?)` records a gate, requires exactly one pending request, and returns it. Filters match tool name, action input, prompt, display, and option ids.
+- `session.respond(responses, options?)` answers specific pending input requests and sends them as the next turn. `session.startRespond(...)` returns a live turn for the same operation.
+- `session.respondAll(optionId)` answers every pending input request with the same option and sends the responses as the next turn.
+- `session.events` contains the events captured for that session. `session.transcript` formats its observed user and assistant messages in turn order.
 
-The transcript uses `User:` and `Assistant:` labels separated by blank lines. It excludes reasoning, tool calls, tool results, and messages from other sessions. It updates after each turn settles, so read it after `await t.send(...)`, `await t.respond(...)`, or `await live.result()`.
+The transcript uses `User:` and `Assistant:` labels separated by blank lines. It excludes reasoning, tool calls, tool results, and messages from other sessions. It updates after each turn settles, so read it after `await session.send(...)`, `await session.respond(...)`, or `await live.result()`.
 
-Each `send` (and `respond`/`respondAll`) resolves to an immutable turn with `.message`, `.data`, `.events`, `.inputRequests`, `.toolCalls`, `.sessionId`, `.status`, and `.expectOk()`. Use `.sessionId` to relate turns or attach follow-up work to the session that produced a specific turn. `expectOk()` throws only when the turn ended failed; a session left open for a next message is the normal end state of a successful turn.
+Each `send` (and `respond`/`respondAll`) resolves to a turn with `.message`, `.data`, `.events`, `.inputRequests`, `.toolCalls`, `.session`, `.sessionId`, `.status`, and `.expectOk()`. Turn results retain their captured output and events; `.session` references the live conversation handle. `expectOk()` throws only when the turn ended failed; a session left open for a next message is the normal end state of a successful turn.
+
+## Prewarming a session
+
+Use `t.session()` to create a session before its first message:
+
+```ts title="evals/prewarm.eval.ts"
+import { defineEval } from "eve/evals";
+import { equals } from "eve/evals/expect";
+
+export default defineEval({
+  async test(t) {
+    const session = await t.session();
+    const turn = await session.send("Greet Alice briefly.");
+    await t.require(turn.sessionId, equals(session.sessionId));
+    turn.event("session.started", { count: 1 });
+    turn.event("turn.started", { count: 1, data: { turnId: "turn_0" } });
+    t.succeeded();
+  },
+});
+```
+
+Acceptance is not an initialization barrier. The first message runs session initialization;
+the TypeScript client handles bounded retries if the workflow inbox is still starting.
+Creation failures reject `t.session()` without returning a handle. Each call creates an
+independent session, including concurrent calls. Accepted sessions appear in eval results
+and participate in timeout cleanup even when no message was sent.
+
+## Migrating existing evals
+
+Replace `t.newSession()` and `t.prewarm()` with `const session = await t.session()`.
+Replace consecutive `t.send()` calls with `session.send()` calls, or continue the first
+returned turn through `turn.session.send()`. Read identity, cursor, events, and transcript
+from `session`; read replies from `turn.message`. Session operations such as `respond()`,
+`requireInputRequest()`, and `cancel()` also move from `t` to `session`.
 
 ## In-flight turns
 
@@ -130,7 +165,8 @@ import { defineEval } from "eve/evals";
 
 export default defineEval({
   async test(t) {
-    const live = await t.start("Run the long operation.");
+    const session = await t.session();
+    const live = await session.start("Run the long operation.");
 
     await live.waitForEvent("actions.requested", {
       data: {
@@ -152,7 +188,7 @@ export default defineEval({
 
 Use `expectOk()` only when the next operation depends on that intermediate turn succeeding. A final `t.succeeded()` already records a complete-run gate.
 
-To intentionally omit an eval for the current target, call `t.skip(reason)` before sending messages or recording assertions. Skipped evals are reported separately and do not affect the exit code.
+To intentionally omit an eval for the current target, call `t.skip(reason)` before creating sessions, sending messages, or recording assertions. Skipped evals are reported separately and do not affect the exit code.
 
 Events from every session are captured in the result and artifacts. `t.log(message)` records debug lines into the eval artifact; `--verbose` also streams them to stdout as evals run. `t.signal` is an `AbortSignal` that fires on timeout.
 
@@ -174,9 +210,9 @@ export default rows.map((row) =>
   defineEval({
     description: row.task,
     async test(t) {
-      await t.send(row.prompt);
+      const turn = await t.send(row.prompt);
       t.succeeded();
-      t.check(t.reply, equals(row.sql));
+      t.check(turn.message, equals(row.sql));
     },
   }),
 );

package/docs/evals/judge.mdx

@@ -19,7 +19,7 @@ export default defineEval({
 
 ## The graders
 
-The judges live under `t.judge.autoevals`. The namespace names the [Braintrust autoevals](https://github.com/braintrustdata/autoevals) grader family, so the factuality and closedQA semantics are autoevals', not eve-invented. Each grader scores `t.reply` by default and is soft by default (tracked, no gate):
+The judges live under `t.judge.autoevals`. The namespace names the [Braintrust autoevals](https://github.com/braintrustdata/autoevals) grader family, so the factuality and closedQA semantics are autoevals', not eve-invented. Each grader scores the most recently settled turn’s assistant message by default and is soft by default (tracked, no gate):
 
 | Grader                                   | Grades                                                                                 |
 | ---------------------------------------- | -------------------------------------------------------------------------------------- |
@@ -28,6 +28,8 @@ The judges live under `t.judge.autoevals`. The namespace names the [Braintrust a
 | `t.judge.autoevals.closedQA(criteria)`   | Whether the reply satisfies a free-form yes/no criterion (no expected answer to match) |
 | `t.judge.autoevals.sql(expected)`        | Semantic equivalence of two SQL statements                                             |
 
+Judges receive the latest message text from the session whose turn most recently settled as the input prompt. Approval responses and stream reads preserve that prompt. For multipart messages, including `session.sendFile()`, the prompt contains the text parts.
+
 A failed `closedQA` assertion prints the input and judge explanation:
 
 ```text
@@ -40,7 +42,7 @@ A failed `closedQA` assertion prints the input and judge explanation:
 
 The reference or criteria is the positional argument. An options object follows:
 
-- `on` is the value to grade, defaulting to `t.reply`. Pass an intermediate draft or parsed value to grade it instead.
+- `on` is the value to grade, defaulting to the most recently settled turn’s assistant message. Pass an intermediate draft or parsed value to grade it instead.
 - `model` and `modelOptions` are a per-call judge override (see below).
 
 ```ts
@@ -48,20 +50,20 @@ const draft = await t.send("Draft the welcome email.");
 t.judge.autoevals.closedQA("professional tone", { on: draft.message }).atLeast(0.6);
 ```
 
-For a multi-turn eval, pass `t.transcript` to grade the primary session's complete observed conversation instead of only its final reply:
+For a multi-turn eval, pass `session.transcript` to grade a session's complete observed conversation instead of only its final reply:
 
 ```ts
-await t.send("My favorite word is marigold. Remember it.");
-await t.send("What is my favorite word?");
+const { session } = await t.send("My favorite word is marigold. Remember it.");
+await session.send("What is my favorite word?");
 
 t.judge.autoevals
   .closedQA("The assistant remembers the user's favorite word across turns", {
-    on: t.transcript,
+    on: session.transcript,
   })
   .atLeast(0.8);
 ```
 
-`t.transcript` contains the session's user and assistant messages in turn order. It excludes reasoning, tool calls, and tool results. See [Multi-turn evals](./cases#multi-turn-evals) for the transcript format and independent sessions.
+`session.transcript` contains the session's user and assistant messages in turn order. It excludes reasoning, tool calls, and tool results. See [Multi-turn evals](./cases#multi-turn-evals) for the transcript format and independent sessions.
 
 ## Soft scoring and thresholds
 
@@ -91,7 +93,7 @@ The judge model is resolved once when the runner builds `t`. It is **never** the
 import { defineEvalConfig } from "eve/evals";
 
 export default defineEvalConfig({
-  judge: { model: "openai/gpt-5.4-mini" }, // the default judge for every eval in this tree
+  judge: { model: "openai/gpt-5.6-luna" }, // the default judge for every eval in this tree
 });
 ```
 

package/docs/evals/overview.mdx

@@ -32,10 +32,10 @@ import { includes } from "eve/evals/expect";
 export default defineEval({
   description: "Basic message and tool-usage coverage for the weather agent.",
   async test(t) {
-    await t.send("What is the weather in Brooklyn?");
+    const turn = await t.send("What is the weather in Brooklyn?");
     t.succeeded();
     t.calledTool("get_weather");
-    t.check(t.reply, includes("Sunny"));
+    t.check(turn.message, includes("Sunny"));
   },
 });
 ```
@@ -51,7 +51,7 @@ import { defineEvalConfig } from "eve/evals";
 import { Braintrust } from "eve/evals/reporters";
 
 export default defineEvalConfig({
-  judge: { model: "openai/gpt-5.4-mini" },
+  judge: { model: "openai/gpt-5.6-luna" },
   reporters: [Braintrust({ projectName: "my-agent" })],
 });
 ```
@@ -100,7 +100,7 @@ model: mockModel({
 
 `t` is both the driver and the assertion surface. There are no separate `input`, `run`, `checks`, or `scores` fields. You write ordinary control flow, sending turns and asserting inline.
 
-- **Drive** the agent: `t.send(...)`, `t.start(...)`, `t.cancel()`, `t.respond(...)`, `t.respondAll(...)`, `t.sendFile(...)`, `t.requireInputRequest(...)`, `t.newSession()`. Live turns returned by `start()` can wait for typed mid-turn events before cancellation or settlement. Read what came back with `t.reply` (the last assistant message), `t.transcript` (the primary session's user and assistant messages), `t.sessionId`, and `t.events`. See [Cases](./cases).
+- **Drive** the agent: `t.session()` creates an empty session; `t.send(...)` creates a session with its first message and returns a turn. Continue through `turn.session.send(...)`. Session handles also expose `start`, `cancel`, `respond`, `respondAll`, `sendFile`, and `requireInputRequest`. Read output from `turn.message`, and conversation state from `turn.session`. See [Cases](./cases).
 - **Assert** with three surfaces, covered next.
 
 ## Three assertion surfaces
@@ -108,8 +108,8 @@ model: mockModel({
 Each surface matches a genuinely different kind of judgment:
 
 - **Scoped methods** read the final whole run on `t`, snapshot one independent session when invoked there, or inspect one immutable `EveEvalTurn`. See [Assertions](./assertions).
-- **`t.check(value, assertion)`** grades an explicit value with a deterministic builder from `eve/evals/expect`, such as `t.check(t.reply, includes("sunny"))`. Grade `t.reply`, an intermediate draft, parsed JSON, or anything else. See [Assertions](./assertions).
-- **`t.judge.autoevals.*`** is the LLM-as-judge surface, like `t.judge.autoevals.closedQA("cites a source")`. It grades `t.reply` by default; pass `{ on: t.transcript }` to grade a multi-turn conversation. The judge uses the configured judge model, never the agent under test. See [Judge](./judge).
+- **`t.check(value, assertion)`** grades an explicit value with a deterministic builder from `eve/evals/expect`, such as `t.check(turn.message, includes("sunny"))`. Grade `turn.message`, an intermediate draft, parsed JSON, or anything else. See [Assertions](./assertions).
+- **`t.judge.autoevals.*`** is the LLM-as-judge surface, like `t.judge.autoevals.closedQA("cites a source")`. It grades the most recently settled turn’s assistant message by default; pass `{ on: turn.session.transcript }` to grade a multi-turn conversation. The judge uses the configured judge model, never the agent under test. See [Judge](./judge).
 
 ## Gate vs soft
 

package/docs/evals/reporters.mdx

@@ -18,7 +18,7 @@ import { defineEvalConfig } from "eve/evals";
 import { Braintrust } from "eve/evals/reporters";
 
 export default defineEvalConfig({
-  judge: { model: "openai/gpt-5.4-mini" },
+  judge: { model: "openai/gpt-5.6-luna" },
   reporters: [Braintrust({ projectName: "weather-agent" })],
 });
 ```

package/docs/evals/targets.mdx

@@ -29,6 +29,11 @@ export default defineEval({
 
 Sessions attached this way are full `EveEvalSession`s: you can keep driving them and assert directly on that session (`session.succeeded()`, `session.calledTool(...)`). Aggregate assertions on `t` continue to read the whole run, including every attached session.
 
+For session creation and message delivery, use the [drive API](./cases#the-drive-api).
+`t.session()` creates a session without a first message; call `session.send()` or `session.start()`
+on the returned handle to use it. `t.send()` creates a new session with its first message.
+These helpers handle the session protocol, retries, and event collection for the eval.
+
 ## Authentication
 
 Local targets send no auth: `eve eval` owns the dev server it boots. For a remote `--url`, eve gets the expected Vercel owner and project from `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` when both are set. Otherwise it reads `.vercel/project.json`. Eve then asks Vercel to resolve the exact HTTPS origin and sends ambient credentials only when the project IDs match. An arbitrary URL remains anonymous.

package/docs/guides/client/messages.mdx

@@ -36,11 +36,11 @@ console.log(result.status, result.message);
 
 When the stream includes `session.failed`, the turn returns `status: "failed"` rather than throwing. Transport and route errors throw `ClientError`.
 
-`session.send()` retries `409 session_not_active` three times when a durable run has been accepted
-but its command inbox is still starting. The retries wait 250 ms, 500 ms, and 1 second. Other
-errors, `session.respond()`, control methods, and raw HTTP requests do not use this retry. An unknown
-session still throws `ClientError` immediately, while a terminal session throws after the final
-attempt. The client never creates a replacement session.
+`session.send()` retries `409 session_not_ready` with bounded exponential backoff for up to 20
+seconds when a durable run has been accepted but its command inbox is still starting. The caller's
+abort signal cancels the wait. Other errors, `session.respond()`, control methods, and raw HTTP
+requests do not use this retry. An unknown
+or terminal session throws `ClientError` immediately with `session_not_active`. The client never creates a replacement session.
 
 ## Send a full turn payload
 

package/docs/guides/client/overview.mdx

@@ -113,7 +113,21 @@ Per-request headers override client-level values with the same name. For example
 
 ## Sessions
 
-For an ID-addressed session, create it explicitly with the first message:
+Create and park an ID-addressed conversation before its first turn when you can start session work
+while the user is still composing:
+
+```ts
+const { session } = await client.sessions.create();
+
+const response = await session.send("Summarize account A.");
+await response.result();
+```
+
+The create promise resolves when the server accepts the durable workflow. It does not open the
+event stream or wait for initialization; an early `session.send()` uses the
+same bounded startup retries as other follow-ups.
+
+To create the session and start its first turn in one request, include the message:
 
 ```ts
 const { session, response } = await client.sessions.create({ message: "Summarize account A." });

package/docs/guides/dynamic-capabilities.md

@@ -265,6 +265,12 @@ Write callback properties as inline function expressions, arrows, method shortha
 
 Closure values must be JSON-serializable. Plain objects, arrays, strings, finite numbers, booleans, and `null` are supported; `undefined` object properties are omitted. Functions, class instances, `Date`, `Map`, symbols, non-finite numbers, and cyclic values fail resolution with the tool name and callback phase instead of being serialized lossily.
 
+Dynamic tools preserve authored input and output validation, including Zod refinements and transformations. JSON Schema describes the tool to the model; the authored validator checks its input and output. eve transforms inline `inputSchema` and `outputSchema` expressions into schema factories and snapshots the JSON-serializable values they capture, just as it does for callbacks.
+
+Write schemas inline in `defineTool()`, or reference a stable module-level schema. A schema stored in a resolver-local variable is a non-serializable capture; inline its construction instead. Schema factories must be synchronous and deterministic for their captured values. Keep external reads in the resolver and capture the resulting JSON data. Imported functions and module-level values remain live code, so they must not hide per-session state.
+
+Schema factories use the same session, scope, resolver entry, and recovery rules as the tool's callbacks. A recovered factory receives its original captures, even if re-running the resolver produces different values. If a required factory is missing, validation fails explicitly; eve does not substitute its JSON Schema description.
+
 Call expressions such as `execute: makeExecutor()` are not transformed. Put the callback body directly in `defineTool()` inside an authored module; eve rejects a dynamic tool if a callback lacks durable metadata.
 
 ### Create dynamic tools in a package
@@ -298,6 +304,22 @@ export function createSearchTool(baseUrl: string) {
 
 Wrap every callback property with the helper. This includes labels, approval policies, `approvalKey`, `execute`, and `toModelOutput`.
 
+For live schemas created in a provider package, use `defineDurableSchema` from `eve/tools`. Put the schema's per-tool values in `closure` and construct the schema in `schema`. Plain JSON Schema objects need no helper.
+
+```ts
+import { defineDurableSchema } from "eve/tools";
+import { z } from "zod";
+
+export function amountSchema(limit: number) {
+  return defineDurableSchema({
+    closure: { limit },
+    schema: ({ limit }) => z.object({ amount: z.number().refine((amount) => amount <= limit) }),
+  });
+}
+```
+
+Pass the result as `inputSchema` or `outputSchema` in `defineTool()`. Rebuild existing extensions with the current `eve extension build` to generate schema factories. A live dynamic schema without a durable factory is rejected at resolution with instructions to inline its construction or use `defineDurableSchema`.
+
 `closure` is the callback's only durable snapshot. Store the identifiers and configuration needed to reproduce the call there. Reconstruct clients or look up live runtime state when the callback runs. The callback may call stable imported functions, but it must not capture runtime objects outside `closure`. Those values disappear on a cold start.
 
 eve-provided factories, including [memory provider tools](../memory), use the same durable callback mechanism.

package/docs/guides/evaluate.md

@@ -1,12 +1,13 @@
 ---
 title: Automatic Model Selection
-description: "Choose an agent model from the current request with an AI SDK evaluation model."
+description: "Choose agent models automatically or evaluate typed questions in your tools and application code."
 ---
 
 Use `autoModel` to choose an agent model from an allowlist before inference begins.
 It uses the [AI SDK evaluation API](https://ai-sdk.dev/docs/ai-sdk-core/evaluation),
 so the evaluator can be a Vercel AI Gateway model ID or an evaluation model from
-an installed provider.
+an installed provider. Use `evaluate` from the same entrypoint to ask typed
+questions in your own tools or application code.
 
 `eve/experimental/evaluate` is experimental. Its API can change between eve
 releases, and the AI SDK evaluation model specification can change in patch
@@ -37,7 +38,8 @@ does not add a TypeSafe credential or transport layer. During `eve dev`, a
 Gateway evaluator uses the same connection selected through `/login` as Gateway
 language models. A configured AI SDK default provider still owns string model
 resolution during development. The TUI footer displays `dynamic model` when the
-agent uses `autoModel`.
+agent uses `autoModel`, then adds the resolved model for the current turn, such as
+`dynamic model · openai/gpt-5.6-luna`.
 
 ## Use a provider directly
 
@@ -102,6 +104,54 @@ Supported reasoning values are `"provider-default"`, `"none"`, `"minimal"`,
 `"low"`, `"medium"`, `"high"`, and `"xhigh"`. An omitted value inherits the
 agent's reasoning setting.
 
+## Evaluate inside a tool
+
+Use `evaluate` to ask choice, score, or boolean questions about the state you pass to it.
+It defaults to `typesafe-ai/jev` and uses the same authentication as `autoModel`,
+including the Gateway connection selected through `/login` during `eve dev`.
+Pass `model` to use another evaluation model ID or a provider instance. A configured
+AI SDK default provider takes precedence over the local Gateway connection.
+
+```ts title="agent/tools/classify-request.ts"
+import { evaluate } from "eve/experimental/evaluate";
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description: "Choose the team that can help with a customer request.",
+  inputSchema: z.object({ request: z.string().min(1).max(8000) }),
+  async execute({ request }, ctx) {
+    const result = await evaluate({
+      state: { request },
+      questions: {
+        team: {
+          type: "choice",
+          instructions: "Select the team best suited to handle the request.",
+          criteria: {
+            billing: "Invoices, payments, and refunds",
+            support: "Product questions and troubleshooting",
+          },
+        },
+      },
+      abortSignal: ctx.abortSignal,
+    });
+    return { team: result.answers.team.choice };
+  },
+});
+```
+
+The choice above is typed as `"billing" | "support"`. Each question appears under
+its authored key in `result.answers`. Results also include token usage, warnings,
+provider metadata, and response metadata.
+
+`evaluate` accepts AI SDK evaluation options, including `maxRetries`, `headers`,
+and `providerOptions`. Pass an `abortSignal` to cancel the request. Input and
+answer validation, retries, and provider errors follow AI SDK semantics.
+
+You can also call `evaluate` outside a tool; it does not require an active eve
+session. Each call performs its own evaluation. `autoModel` uses this function
+and adds the per-turn routing behavior described below.
+
 ## Runtime behavior
 
 `autoModel` evaluates at the first `step.started` event, after the incoming prompt