eve 0.81.1 → 0.83.0

package/docs/agent-config.md

@@ -3,7 +3,7 @@ title: "Agent Configuration"
 description: "Configure an eve agent's model, reasoning effort, compaction, limits, and runtime behavior in agent.ts."
 ---
 
-An eve app has one root agent assembled from the files under `agent/`. Its optional `agent.ts` calls `defineAgent` (from `eve`) when you need to configure the model or other runtime behavior. Declared [subagents](./subagents) have their own `agent.ts` and capabilities; this page covers the configuration shared by root agents and subagents.
+An eve app's root agent uses files under `agent/` by default; a [flat layout](./reference/agent-files#flat-layout) places them directly in the app root instead. Its optional `agent.ts` calls `defineAgent` (from `eve`) when you need to configure the model or other runtime behavior. Declared [subagents](./subagents) have their own `agent.ts` and capabilities; this page covers the configuration shared by root agents and subagents.
 
 ## Set the model
 
@@ -137,7 +137,7 @@ export default defineAgent({
   starting points on Ollama.
 - **Usage.** `includeUsage: true` lets token usage reach eve's
   [session limits](#runtime-limits). Local models report no cost, so
-  `maxTokenCostUsdPerSession` does not apply.
+  `costUsd` stays unset in a `sessionUsage` check.
 - **Other servers.** Change `baseURL`, for example to
   `http://localhost:1234/v1` for LM Studio. Pass `apiKey` for a remote
   OpenAI-compatible server that requires one.
@@ -262,45 +262,88 @@ See [Default harness](./concepts/default-harness#compaction) for how the loop ap
 
 ## Runtime limits
 
-Use `limits` for framework-owned runtime caps. Session usage limits stop the
-current durable session from starting another model call after accumulated
-provider-reported tokens or model token cost reaches a configured limit:
+Use `limits` for framework-owned runtime caps. `sessionUsage` decides when the
+current durable session must stop starting model calls. It receives the
+session's usage and returns `true` when the limit is reached:
 
 ```ts title="agent/agent.ts"
 export default defineAgent({
   model: "anthropic/claude-opus-5.5",
   limits: {
-    maxInputTokensPerSession: 200_000,
-    maxOutputTokensPerSession: 20_000,
-    maxTokenCostUsdPerSession: 1.5,
+    sessionUsage: ({ window }) =>
+      window.inputTokens - window.cacheReadTokens >= 200_000 ||
+      window.outputTokens >= 20_000 ||
+      (window.costUsd ?? 0) >= 1.5,
     sessionTimeoutMs: 7 * 24 * 60 * 60 * 1_000,
   },
 });
 ```
 
-`sessionTimeoutMs` sets the lifetime for every session, including delegated
-sessions. It defaults to 30 days and starts at creation. Each successful
-deployment handoff or legacy-session import restarts the original configured
-duration. Process restarts, ordinary messages, compaction handoffs, and failed
-or skipped handoffs keep the existing deadline. At the deadline, eve lets an active turn settle,
-then emits `session.completed` and releases every continuation address; the next
-qualifying channel message starts fresh. Set it to `false` to disable the
-timeout. Session expiration follows [run-data retention](#run-data-retention);
-a zero-retention session loses its stored payloads when it ends.
-
-Input tokens, output tokens, and model token cost are checked independently.
-The model call that crosses a limit is allowed to finish because exact usage
-arrives after the call completes. Before the next model call, eve pauses the
-turn (`turn.waiting`) and sends a deterministic continuation prompt with two options:
-**Continue** grants a fresh window of each configured size and resumes the same
-turn, and **Stop**
-cancels the in-flight turn through the standard cancellation path
-(`turn.cancelled` → `session.waiting`) — a user decision, not an error. The session stays resumable; because it is
-still over budget after Stop, the next message raises a new prompt. Declining a
+`sessionTimeoutMs` sets how long a session may sit idle before eve completes it,
+for every session, including delegated sessions. It defaults to 30 days. The
+idle window starts at creation and restarts each time a turn settles, including
+turns that answer a message, clear or compact the context, or end in
+cancellation. A session never expires while a turn is open, including a turn
+held open while its [tasks](./tools/tasks) work or while it waits for a person
+to answer; the window restarts when that turn settles. Process restarts do not
+change the window. When the window elapses, eve emits `session.completed` and
+releases every continuation address; the next qualifying channel message starts
+fresh. To carry an earlier conversation into the fresh session, pass it as
+[prior history](./channels/eve#start-from-prior-history). Set it to `false` to
+disable the timeout. Session expiration follows
+[run-data retention](#run-data-retention); a zero-retention session loses its
+stored payloads when it ends.
+
+`sessionUsage` gets two usage records with `inputTokens`, `outputTokens`,
+`cacheReadTokens`, `cacheWriteTokens`, and `costUsd`: `total` is everything
+the session has spent, and `window` is what it spent since the last approved
+continuation. `inputTokens` includes cache reads and writes. Subtract
+`cacheReadTokens` to count only new input; cache reads are the history a
+provider replays from its prompt cache on every step. `costUsd` is the model
+token cost in US dollars that AI Gateway reports with each step, not tool or
+infrastructure spend; it is unset when no step reported a cost.
+
+When `sessionUsage` is omitted, the limit is `40_000_000` new input tokens per
+window:
+
+```ts
+({ window }) => window.inputTokens - window.cacheReadTokens >= 40_000_000;
+```
+
+`sessionUsage` can raise its threshold after each approval. This limit asks
+at 20,000 new input tokens, then at 40,000, 80,000, and so on:
+
+```ts title="agent/agent.ts"
+export default defineAgent({
+  model: "anthropic/claude-opus-5.5",
+  limits: {
+    sessionUsage: ({ total, window }) => {
+      const used = total.inputTokens - total.cacheReadTokens;
+      // Usage when the last continuation was approved; 0 before the first.
+      const approvedAt = used - (window.inputTokens - window.cacheReadTokens);
+      // Double past it, so each approval allows twice the usage before the next prompt.
+      let next = 20_000;
+      while (next <= approvedAt) next *= 2;
+      return used >= next;
+    },
+  },
+});
+```
+
+Set `sessionUsage: () => false` to leave sessions uncapped; `sessionUsage:
+false` is not accepted. eve calls `sessionUsage` before each model call once
+the window has usage. The model call that crosses a limit is allowed to finish
+because exact usage arrives after the call completes. Before the next model
+call, eve pauses the turn (`turn.waiting`) and sends a deterministic
+continuation prompt with two options: **Continue** starts a new window and
+resumes the same turn, and **Stop** cancels the in-flight turn through the
+standard cancellation path (`turn.cancelled` → `session.waiting`). Stop is a
+user decision, not an error. The session stays resumable; because it is still
+over budget after Stop, the next message raises a new prompt. Declining a
 delegated child's prompt cancels the root turn, which cascades to the whole
-delegation tree — the delegating parent never receives an error result it
-could retry against a fresh quota share. A reply that answers neither option
-is queued while the existing prompt stays pending; eve does not raise another
+delegation tree, so the delegating parent never receives an error result it
+could retry. A reply that answers neither option is queued while the existing
+prompt stays pending; eve does not raise another
 copy or start another turn. The reply is received (`message.received`) and
 processed in the held turn once the budget is granted.
 
@@ -312,44 +355,22 @@ turn or duplicate the prompt.
 
 Sessions that cannot request input from a human, such as markdown schedules and
 delegated runs without input proxying, skip the prompt and fail the next model
-call with `SESSION_TOKEN_LIMIT_REACHED` for token budgets or
-`SESSION_TOKEN_COST_LIMIT_REACHED` for model token cost. A delegated task with
-no inherited quota also fails instead of raising a continuation prompt that
-could only grant another zero-value window.
-
-When `maxInputTokensPerSession` is omitted, root sessions apply a default
-input budget of `40_000_000` provider-reported input tokens.
-`maxOutputTokensPerSession` and `maxTokenCostUsdPerSession` are unset by
-default. `maxTokenCostUsdPerSession` is a US-dollar limit on model token cost,
-not tool or infrastructure spend. It uses the cost reported with each model
-step; AI Gateway supplies this value, while model steps without reported cost
-do not add to the limit. Set any usage limit to `false` to uncap that axis.
-
-Delegated subagent sessions have no fixed default. Each child receives a share
-of the delegating parent's remaining quota when it starts: the remainder in
-the current budget window split evenly across the agent tasks that one model
-step starts. A session that a workflow tool opens with `ctx.agent` receives
-the share of the model step that called the tool, or the whole remainder when
-that step starts no agent tasks; eve does not divide that share among several
-sessions one call opens. A child keeps its grant for its whole session,
-including turns that later calls with `taskId` start. Remote agent tasks count
-toward the split but receive no grant: they run under their own deployment's
-limits.
-
-A child's usage, including what the child's own subagents spent, counts
-against the parent's quota. An agent task's usage counts with each reply it
+call with `SESSION_USAGE_LIMIT_REACHED`. Its details carry the `total` and
+`window` usage the check saw.
+
+Each subagent session checks its own usage against its own `sessionUsage`, or
+the root agent's when it authors none. A dynamic subagent can't select
+`sessionUsage` at runtime and always uses the root agent's. Remote agents run
+under their own deployment's limits.
+
+A child's usage, including what the child's own subagents spent, also counts
+in the parent's usage. An agent task's usage counts with each reply it
 sends. A turn it doesn't reply to, such as one a cancel stopped, counts with
 the next reply, or when the turn ends if no call waits for a reply. Sessions
 that any other `serve` workflow tool opens with `ctx.agent` count the same
 way; those of an `execute` or `task` tool count when the tool finishes. Remote
-agents' reported usage counts the same way. Later children draw from what
-remains, and the parent's own limit and continuation prompt include delegated
-spend. Token-cost budgets follow the same rules, including splitting the
-remaining US-dollar budget and adding child cost back to the parent. Approving
-a continuation opens a fresh parent window for later child grants without
-erasing lifetime usage. An authored child limit applies only when it is
-tighter than the parent's grant; an uncapped parent delegates uncapped
-children.
+agents' reported usage counts the same way, cost included. Approving a
+continuation starts a new window without erasing `total`.
 
 Some delegated usage doesn't count against the parent: a `ctx.agent` turn
 still running when its workflow tool finishes or is cancelled; the `ctx.agent`
@@ -496,7 +517,7 @@ keeps the data. Confirm support with your World provider. See
 | -------------- | ------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `reasoning`    | `AgentReasoningDefinition`            | provider default | Provider-agnostic reasoning effort forwarded to the agent's turn model calls.                                                                                                                                                                                                                                                        |
 | `modelOptions` | `AgentModelOptionsDefinition`         | none             | Provider option overrides forwarded to the model call, and [`promptCache`](#prompt-caching) settings.                                                                                                                                                                                                                                |
-| `limits`       | `AgentLimitsDefinition`               | field-specific   | Framework-owned runtime limits. Sessions complete after 30 days by default; usage-limit defaults and inheritance are described above. Set a limit to `false` to disable it.                                                                                                                                                          |
+| `limits`       | `AgentLimitsDefinition`               | field-specific   | Framework-owned runtime limits. Sessions complete after 30 idle days by default; usage-limit defaults and inheritance are described above. Set a limit to `false` to disable it.                                                                                                                                                     |
 | `experimental` | `AgentExperimentalDefinition`         | unset            | Unstable opt-ins. `workflow.world` selects the Workflow world package on the root agent; `workflow.modelCallsPerStep` batches sequential model calls into a wider replay unit; `workflow.retention` controls how long the durable runtime keeps run data.                                                                            |
 | `build`        | `{ externalDependencies?: string[] }` | none             | Hosted-build packaging controls. `externalDependencies` keeps listed packages external while eve compiles authored modules such as tools and channels, and traces those packages into the hosted output.                                                                                                                             |
 | `tool`         | `boolean \| "deferred"`               | `true`           | Exposes this agent to its parent model as a tool. `"deferred"` keeps it out of the model's tool list; the model finds it with `eve__search` and calls it with `eve__tool`. On the root agent, controls the built-in `agent` tool. A subagent with `tool: false` remains callable from authored workflow tools through `ctx.agent()`. |

package/docs/channels/chat-sdk.mdx

@@ -53,6 +53,11 @@ export default channel;
 
 `adapters` is a map of adapter name to adapter instance; each entry mounts its own webhook (see below). `state` takes any Chat SDK state adapter: `createMemoryState()` is fine for local development, but use a durable adapter (Redis, Upstash, etc.) in production so thread subscriptions and inbound deduplication survive restarts. `send` accepts a plain string or an AI SDK `UserContent` array, and must be called from inside a Chat SDK handler — it dispatches the turn on the webhook that is currently running.
 
+Pass `idempotencyKey: message.id` to `send` to prevent duplicate agent input
+within the session's [recent-key window](./custom#retried-deliveries). Chat SDK's
+separate duplicate check can mark a message as seen before eve accepts it, so
+a shared state adapter alone does not guarantee delivery.
+
 Deploy once the channel file is in place:
 
 ```bash
@@ -104,7 +109,7 @@ bot.onNewMention(async (thread, message) => {
 });
 ```
 
-`options` accepts `thread` and `adapterName`, plus the channel send options `auth`, `context`, `outputSchema`, `title`, `callback`, and `turnPolicy`. `title` sets the eve session's display title without changing the model message; `auth` attaches an authenticated principal to the turn. `auth` defaults to `null`.
+`options` accepts `thread` and `adapterName`, plus the channel send options `auth`, `context`, `outputSchema`, `title`, `callback`, `turnPolicy`, and `idempotencyKey`. `title` sets the eve session's display title without changing the model message; `auth` attaches an authenticated principal to the turn. `auth` defaults to `null`.
 
 To answer pending input requests from a handler you render yourself, call `respond(inputResponses, { thread, auth?, context? })`. Like a channel's `respond()`, it never creates a session. This example answers a custom button whose `value` carries the eve request id:
 

package/docs/channels/custom.mdx

@@ -68,7 +68,7 @@ Each route receives these operation surfaces:
 - `to(channel, target).send(message, options)` hands work to another authored channel.
 - `params`, `waitUntil`, and `requestIp` provide request metadata and lifetime control.
 - `describe()` returns the agent's name, description, the compiled tools a caller can run outside a turn, with their JSON schemas, and the compiled skills, each with its `name` and `description`, sorted by name. It reads the compiled manifest only, never a skill file, and carries no other paths, config, or inspection detail, so a channel can publish it to its callers. Tools that need a turn (framework tools, workflow and provider tools, tools without `execute`) and tools and skills added by dynamic resolvers or subagents are left out.
-- `invokeTool(name, input, { auth, key })` runs one of those tools as `auth`, outside any conversation: no model, turn, or workflow run. Authored state starts from its initial value and is not kept. Without `key`, each call gets its own session, and a sandbox the tool opens is deleted when the call ends. With `key` (1 to 512 characters), calls from the same `auth` principal with the same key share a session id and a sandbox, which is kept between calls; this needs Vercel Sandbox or just-bash, and an authenticated `auth` (a keyed call from the anonymous principal is `denied`); see [MCP tool sessions](./mcp#tool-sessions). When a trusted forwarder asserted `auth`, pass the principal your route verified as `forwardedBy`: it is part of the session, so one user reached through two forwarders gets two sessions. It resolves to `completed` with the tool's output, or to `invalid-input`, `denied`, `failed`, `approval-required` when the tool's approval policy asks a person (the tool did not run), or `authorization-required` with the connections the tool needs a sign-in to.
+- `invokeTool(name, input, { auth, key })` runs one of those tools as `auth`, outside any conversation: no model, turn, or workflow run. Authored state starts from its initial value and is not kept. Without `key`, each call gets its own session, and a sandbox the tool opens is deleted when the call ends. With `key` (1 to 512 characters), calls from the same `auth` principal with the same key share a session id and a sandbox, which is kept between calls; this needs Vercel Sandbox, just-bash, or a custom provider that sets `toolSessions: true`, and an authenticated `auth` (a keyed call from the anonymous principal is `denied`); see [MCP tool sessions](./mcp#tool-sessions). When a trusted forwarder asserted `auth`, pass the principal your route verified as `forwardedBy`: it is part of the session, so one user reached through two forwarders gets two sessions. It resolves to `completed` with the tool's output, or to `invalid-input`, `denied`, `failed`, `approval-required` when the tool's approval policy asks a person (the tool did not run), or `authorization-required` with the connections the tool needs a sign-in to.
 
   A direct call doesn't go through the AI SDK, so AI SDK telemetry integrations never see it. Conversation tool calls do: an integration that an `agent/instrumentation/*.ts` module registers with `registerTelemetry()` from `ai` receives `onToolExecutionStart` and `onToolExecutionEnd` for each of them. A direct call is traced by eve itself instead. It gets an `execute_tool` span under the caller's trace and emits `tool.call.started` and `tool.call.completed` to instrumentation. Over MCP, the caller's trace comes from the request's `_meta` trace context (see [Trace context](./mcp#trace-context)).
 
@@ -104,11 +104,11 @@ part of the authored channel API.
 ## Channel operations and session handles
 
 Channel operations are dynamic: every call targets whichever session currently
-owns the address. Only `send()` can create a session when the address is unowned.
-Cold-start sends return their accepted candidate without waiting for address
-ownership. If simultaneous sends race, eve forwards the losing candidate's
-message to the winner; resolve the address after startup when you need a fixed
-handle to the canonical owner.
+owns the address. `create()` and `send()` can create a session when the address is unowned.
+Without an [idempotency key](#retried-deliveries), a new session's handle can
+return before it claims the address. If another send wins the address, eve
+forwards the message to that session. Call `resolveSession(address)` after
+startup to get the winning session's handle.
 
 ```ts
 const source = from(threadId);
@@ -124,10 +124,10 @@ const currentSession = await resolveSession(threadId);
 ```
 
 When the session at an address is
-[stranded](../concepts/execution-model-and-durability#stranded-sessions) because another eve version
+[stranded](../guides/deployment/self-hosting#recover-a-stranded-session) because another eve version
 built it, `send()` ends that session and starts a fresh one. The message becomes the fresh
 session's first turn, and the fresh session can read recent text from the earlier conversation;
-see [What a replacement session receives](../concepts/execution-model-and-durability#what-a-replacement-session-receives). Concurrent sends to the same stranded address still
+see [Recover a stranded session](../guides/deployment/self-hosting#recover-a-stranded-session). Concurrent sends to the same stranded address still
 produce one fresh session. A `respond()` call, or a `deliver()` that includes input responses,
 carries answers a fresh session has no request for, so it throws `SessionStrandedError` and leaves
 the stranded session in place.
@@ -206,6 +206,38 @@ Attaching does no lookup. The first operation reports whether the ID is active.
 Call `resolveSession(address)` only when you explicitly need to snapshot an
 address's current owner as a fixed handle.
 
+## Retried deliveries
+
+After verifying a webhook, pass its stable event ID as `idempotencyKey`. Reuse the key
+when retrying a failed or timed-out send:
+
+```ts
+const session = await from(conversationId).send(message, {
+  auth,
+  idempotencyKey: providerEventId,
+});
+```
+
+Channel and fixed-session `send()` and `respond()` calls accept this option,
+as does the Chat SDK bridge. Keys must contain 1–256 characters and identify one
+delivery. Prefix IDs with the provider or event type if they can overlap.
+Reusing a retained key ignores the new input, even if the message changed.
+
+Each session remembers its last 1,024 distinct keys. Retries do not extend
+retention and can run again after eviction. Aliases share this window; replay
+and owner handoffs preserve it. Other sessions have separate windows, including
+those created after reset, expiration, or replacement. Replicas must share the
+same durable Workflow World.
+
+A known duplicate does not interrupt generation, call `deliver`, or start a
+turn. A keyed send that creates a session waits up to 30 seconds for the winning
+session's handle. Sends to existing sessions return after eve stores the
+delivery, without waiting for a turn or reporting whether it was a duplicate.
+
+Await `send()` before acknowledging a webhook when the provider allows it.
+Acknowledging sooner can lose work. This does not make tool calls, outbound
+posts, or work done before `send()` exactly once.
+
 ## Wrap an existing channel's routes
 
 A channel value can be spread into a new object with replaced `routes`. eve keeps the channel's adapter, events, and build metadata (such as the Slack app manifest) on the spread copy, so `{ ...channel, routes }` compiles and runs like the original.
@@ -374,7 +406,7 @@ Before sending:
 
 - Verify the provider's signature and validate the payload, including size limits. Derive `event.source` from the verified sender, not an untrusted payload field.
 - Filter out events that should not reach the agent.
-- Deduplicate retried events in your application if duplicates would cause unwanted sessions or posts. `send(...)` does not deduplicate them.
+- Deduplicate retries in your application unless the destination's `receive` hook passes a [delivery key](#retried-deliveries) to `from(address).send()`.
 
 The supplied `auth` identifies who started the session, available to tools and event handlers as `session.auth.initiator`.