eve 0.83.2 → 0.84.0

package/docs/guides/remote-agents.md

@@ -20,70 +20,81 @@ export default defineRemoteAgent({
 
 `defineRemoteAgent` accepts:
 
-| Parameter          | Type                                          | Required | Default           | Description                                                                                                                                              |
-| ------------------ | --------------------------------------------- | -------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `url`              | `string \| (() => string \| Promise<string>)` | Yes      | n/a               | Base URL of the remote eve deployment to call. A string is baked at compile time; a function is resolved at runtime (see [Runtime URLs](#runtime-urls)). |
-| `description`      | `string`                                      | Yes      | n/a               | Model-visible delegation description.                                                                                                                    |
-| `auth`             | `OutboundAuthFn`                              | No       | none              | Outbound auth hook from `eve/agents/auth`.                                                                                                               |
-| `forwardPrincipal` | `boolean`                                     | No       | `false`           | Forward the dispatching turn's session principal to the remote deployment (see [Forwarding the caller identity](#forwarding-the-caller-identity)).       |
-| `headers`          | `HeadersValue`                                | No       | none              | Static or lazily resolved request headers.                                                                                                               |
-| `path`             | `string`                                      | No       | `/eve/v1/session` | Route appended to `url` for the create-session request.                                                                                                  |
-| `tool`             | `boolean`                                     | No       | `true`            | Expose the remote agent as a tool to the parent model. Set `false` to allow only `ctx.agent()` calls from authored workflow tools.                       |
+| Parameter          | Type                    | Required | Default           | Description                                                                                                                                        |
+| ------------------ | ----------------------- | -------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `url`              | `string`                | Yes      | n/a               | Base URL of the remote eve deployment. Compute runtime URLs in a dynamic definition (see [Runtime URLs](#runtime-urls)).                           |
+| `description`      | `string`                | Yes      | n/a               | Model-visible delegation description.                                                                                                              |
+| `auth`             | `OutboundAuthFn`        | No       | none              | Outbound auth hook from `eve/agents/auth`.                                                                                                         |
+| `forwardPrincipal` | `boolean`               | No       | `false`           | Forward the dispatching turn's session principal to the remote deployment (see [Forwarding the caller identity](#forwarding-the-caller-identity)). |
+| `headers`          | `HeadersValue`          | No       | none              | Static or lazily resolved request headers.                                                                                                         |
+| `path`             | `string`                | No       | `/eve/v1/session` | Route appended to `url` for the create-session request.                                                                                            |
+| `tool`             | `boolean \| "deferred"` | No       | `true`            | Expose the remote agent as a tool to the parent model. Set `false` to allow only `ctx.agent()` calls from authored workflow tools.                 |
 
 ## Dynamic remote agents
 
 Wrap the file in `defineDynamic` when the target or its availability depends on
-the current session. Return `defineRemoteAgent(...)` to expose it and `null` to
-omit it:
+the current session. The function returns `defineRemoteAgent(...)` to expose it or `null` to omit it:
 
 ```ts title="agent/subagents/weather.ts"
 import { defineDynamic, defineRemoteAgent } from "eve";
 
-export default defineDynamic({
-  events: {
-    "session.started": (_event, ctx) =>
-      ctx.session.auth.current?.attributes.region === "us"
-        ? defineRemoteAgent({
-            description: "Answers weather questions for US customers.",
-            url: "https://us-weather-agent.example.com",
-          })
-        : null,
-  },
-});
+export default defineDynamic((ctx) =>
+  ctx.session.auth.current?.attributes.region === "us"
+    ? defineRemoteAgent({
+        description: "Answers weather questions for US customers.",
+        url: "https://us-weather-agent.example.com",
+      })
+    : null,
+);
 ```
 
-Dynamic remote subagents support `session.started` and `turn.started`. The
-returned definition may select different remote settings at either scope. eve
-resolves function-valued URLs when the event handler runs. Auth and headers
-remain lazy and resolve before each outbound request without entering durable
-workflow state.
+eve evaluates the function before each ordinary model call. `auth` and `headers` can close over
+its context or memo results. They resolve before each outbound request; credentials are not
+memo results and must not be stored in them.
 
-Author `auth` and `headers` directly in the `defineRemoteAgent({ ... })` object
-and keep their functions self-contained with module imports, module-level
-constants, or environment variables. They are rehydrated outside the event
-handler, so they cannot close over `_event`, `ctx`, or handler-local values. The
-build fails with an error that names the handler-local value when they do.
+```ts title="agent/subagents/finance.ts"
+import { defineDynamic, defineRemoteAgent } from "eve";
+import { mintFinanceToken } from "../lib/finance";
+
+export default defineDynamic((ctx) => {
+  const tenant = ctx.session.auth.current?.attributes.tenant;
+  return typeof tenant === "string"
+    ? defineRemoteAgent({
+        description: "Analyzes the tenant's financial data.",
+        url: "https://finance-agent.example.com",
+        auth: async () => ({
+          headers: { authorization: `Bearer ${await mintFinanceToken(tenant)}` },
+        }),
+      })
+    : null;
+});
+```
 
-eve compiles only `auth` and `headers` written directly in the
-`defineRemoteAgent({ ... })` object in the subagent file. When they arrive
-through a spread, a variable passed as the argument, or a definition built in
-another module, eve rejects the definition at runtime, logs the error, and runs
-the agent without that subagent.
+A child keeps the parent context and memo results used to select its remote configuration.
+Later messages, answers, cancellation, reset, and stream reads use that original selection when
+rebuilding transport credentials. Only saved memo results are available: a missing result or a
+changed child name or URL fails before credentials are sent. `ctx.messages()` is unavailable
+during this reconstruction, including when eve opens the child; keep conversation-based
+selection inside a memo. This does not change the per-message caller identity described in
+[Forwarding the caller identity](#forwarding-the-caller-identity). See
+[Dynamic capabilities](./dynamic-capabilities#dynamic-subagents) for the memo rules.
 
 ## Runtime URLs
 
-A string `url` is read at compile time and frozen into the build. When the target comes from a runtime env var — known only once the deployment runs — pass a function instead. eve calls it when it resolves the agent graph at runtime, so it can read `process.env`:
+A static `url` is read at compile time. When an environment variable supplies the URL only at runtime, compute it inside `defineDynamic`:
 
 ```ts title="agent/subagents/weather.ts"
-import { defineRemoteAgent } from "eve";
+import { defineDynamic, defineRemoteAgent } from "eve";
 
-export default defineRemoteAgent({
-  url: () => process.env.WEATHER_AGENT_URL ?? "https://weather-agent.example.com",
-  description: "Answers weather, temperature, forecast, wind, rain, and snow questions.",
-});
+export default defineDynamic(() =>
+  defineRemoteAgent({
+    url: process.env.WEATHER_AGENT_URL ?? "https://weather-agent.example.com",
+    description: "Answers weather, temperature, forecast, wind, rain, and snow questions.",
+  }),
+);
 ```
 
-The function may be async and must return a non-empty string. `auth` and `headers` are resolved at runtime the same way.
+`url` must be a non-empty string. `auth` and `headers` remain lazy callbacks resolved per request.
 
 ## Calling a remote agent
 
@@ -207,22 +218,77 @@ A remote subagent call runs a child session in the remote deployment as a task:
 2. The remote accepts the child and runs its turn while the task works.
 3. The callback delivers the child's reply, which becomes the task's result.
 
-The parent stream carries the same `task.started`, `agent.started`, and `task.settled` events as local delegation. For a remote child, `agent.started.data.remote.url` records the target.
+The callback URL must use `http` or `https` and reach the parent at a public address. The remote rejects a create-session request whose callback host is a private, link-local, or reserved IP address, and refuses to deliver a callback to a hostname that resolves to one. A refused delivery fails without retries. Loopback hosts such as `localhost` and `127.0.0.1` work only when the remote runs as a local development server (`eve dev` or `vercel dev`), so parents and remotes that reach each other over a private network can't exchange callbacks.
+
+The parent stream carries the same `task.started`, `child.opened`, and `call.settled` facts as local delegation. A remote child's deployment binding is private: only the parent's stream proxy reads it.
 
-Clients follow a remote child through the parent. [`session.agent(started).stream()`](./client/streaming#follow-a-subagent) reads the `agent.started` event's `streamPath`, a route on the parent deployment. The parent verifies that its session recorded the child for that tool call, resolves the remote agent's `auth` and `headers`, and relays the child's stream. A browser never calls the remote deployment or holds its credentials; it only needs access to the parent session.
+Clients follow a remote child through the parent. [`session.agent(opened).stream()`](./client/streaming#follow-a-subagent) reads the `child.opened` event's `stream` path, a route on the parent deployment. The parent verifies that its session recorded the child for that tool call, resolves the remote agent's `auth` and `headers`, and relays the child's stream. A browser never calls the remote deployment or holds its credentials; it only needs access to the parent session.
 
-Cancelling the parent turn or the agent task with `eve__task_cancel` also cancels the remote child's current turn. eve resolves the remote's `headers` and `auth` again for every cancellation attempt, so rotating credentials work the same way as they do for session creation. Cancellation always uses the standard eve cancel path on `url`, even when `path` customizes only the create-session endpoint. The remote child reports `turn.cancelled` → `session.waiting` on its own stream; an older or unreachable remote is logged but cannot turn the parent's cancellation into a failure.
+Cancelling the parent turn or the agent task with `eve__task_cancel` also cancels the remote child's current turn. eve resolves the remote's `headers` and `auth` again for every cancellation attempt, so rotating credentials work the same way as they do for session creation. Cancellation always uses the standard eve cancel path on `url`, even when `path` customizes only the create-session endpoint. The remote child reports `turn.settled` with `outcome: "cancelled"` on its own stream; an older or unreachable remote is logged but cannot turn the parent's cancellation into a failure.
 
 When the workflow run that opened a remote child finishes, eve sends an authenticated `POST /eve/v1/session/:childSessionId/reset` for it. An agent task's run finishes when the parent session ends. Reset retires the parked remote session and recursively cleans up its descendants. The request uses freshly resolved `headers` and `auth`; failures are logged so an unreachable remote cannot block parent finalization.
 
-The parent names its eve remote agent protocol version when it creates the child, and the remote answers with the version it serves. A remote also serves parents on protocol 1 (eve 0.66 through 0.68), including their approvals and sign-in requests, so upgrade remote agents before their callers; see [Upgrade remote agents before their callers](../tools/tasks-upgrade#upgrade-remote-agents-before-their-callers). A parent accepts a protocol-1 remote's results and failures, but that remote's approvals and sign-in requests don't reach the parent. Any other mismatch fails the call at start with an error naming both versions. A failed _start_ fails the call immediately. After a remote starts, a terminal failure callback fails the call with the remote's error. Terminal callback delivery runs as a durable step on the underlying workflow engine (see [Execution model & durability](../concepts/execution-model-and-durability)). A failed callback POST is rethrown rather than completing the call, so the engine retries it.
+The parent names its remote agent protocol version when it creates the child, and the remote
+answers with the version it serves. This release serves protocols 2 and 3. A protocol-3 parent
+accepts a protocol-2 remote's results and failures, but cannot follow its live stream. It relays that
+remote's approvals, questions, and sign-ins to the person it serves, as described below.
+A protocol-3 remote returns results and failures to callers on protocol 2, but cannot relay
+approvals, questions, or sign-ins to them: a turn that needs a person fails with upgrade guidance
+instead of waiting on an unreachable prompt. Unsupported versions, including protocol 1 from
+eve 0.66 through 0.68, fail at start with an error naming both versions.
+
+A receiver on an earlier supported protocol can reject a new caller's create request
+before admission. After an explicit `409 REMOTE_AGENT_PROTOCOL_MISMATCH` rejection,
+eve makes one request with that receiver's supported version and fresh credentials.
+It does not negotiate after an accepted response, an unreadable receipt, a rejection
+that names a session, or an unsupported version.
+
+A parent that negotiated protocol 2 relays that child's approvals, questions, and
+sign-ins like a protocol-3 child's. The person answers them in the parent's session,
+and their answers return in the form the child accepts. The child still decides who
+may answer: an answer it turns away, such as one from a responder its approval policy
+refuses, leaves the approval open. The child reports how its approvals and sign-ins
+settle. It doesn't report how a question or budget prompt settles, so the parent
+settles those once the child accepts the answer. Cancelling the parent's call withdraws
+what it mirrored.
+
+### Upgrading callers and remote agents
+
+Upgrade callers before the remote agents they call, or both together. A caller on this release
+relays a protocol-2 remote agent's approvals, questions, and sign-ins, but a remote agent on this
+release can't relay them to a protocol-2 caller.
+
+A remote child's callback goes to the parent's current production deployment, not to the
+deployment that started the call; the parent's own sessions stay on the deployment that started
+them. Every callback URL a parent gives a child names the protocol they agreed
+(`eveRemoteProtocol`), and the parent reads a child's callbacks by that protocol. A URL that names
+none comes from a parent run started before v27. When an earlier child's approval, question, or
+sign-in for such a run reaches an upgraded deployment, the deployment passes it to that run as is,
+so the run receives it as it did before the upgrade.
+
+### Retries and acknowledgements
+
+Each follow-up message and each set of answers a parent sends a protocol-3 child carries an
+`idempotencyKey` named by the parent's own durable step. When the child accepts a request but the
+parent doesn't hear back, the parent's retry is the same delivery: the child admits it once and
+returns the original receipt. Protocol-2 children don't accept the field, so the parent sends
+it only to protocol-3 children.
+
+A failed start fails the call immediately. After a remote starts, a terminal failure callback
+fails the call with the remote's error. Terminal callback delivery runs as a durable step on the
+underlying workflow engine (see [Execution model & durability](../concepts/execution-model-and-durability)).
+A failed callback POST is rethrown so the engine retries it. A parent's callback route answers
+`404` with `code: "CALLBACK_NOT_PENDING"` when nothing waits on the callback: the parent already
+took the result, for example from a delivery whose acknowledgement was lost, or stopped waiting for
+it. The child retries that answer for a few seconds, in case the parent hasn't yet registered the
+reply it sent the token for, then logs it and keeps its session, rather than failing it.
 
 If a remote accepts the create request but its response has an incompatible
 protocol or an unreadable body, the work may have completed. eve stops workflow
 retries and reports that uncertainty. A protocol mismatch includes the accepted
 remote session ID so you can inspect the outcome before sending another request.
-Upgrading the remote does not undo work that it already performed. A receiver's
-explicit protocol rejection remains a compatibility error.
+Upgrading the remote does not undo work that it already performed. An unsupported version, or a rejection of the single negotiated request,
+remains a compatibility error.
 
 ## What to read next
 

package/docs/guides/self-modification.md

@@ -5,7 +5,7 @@ description: "Ask your agent to update its own authored files during local devel
 
 When `eve dev` starts a local server, it mounts the bundled self-modification extension by default. Ask your agent to change its instructions, tools, skills, or other files under `agent/`; eve delegates the source work to the `self-modification__agent` subagent. Connecting to an existing server with `eve remote connect --url <url>` does not add the bundled extension to that server.
 
-The bundled extension is `eve/self-modification/local`. It is for local development and is not included in production builds. To let a deployed agent propose source changes, mount the separate [`eve/self-modification/remote`](#propose-changes-from-a-deployed-agent) extension.
+The bundled extension is `eve/extensions/self-modification/local`. It is for local development and is not included in production builds. To let a deployed agent propose source changes, mount the separate [`eve/extensions/self-modification/remote`](#propose-changes-from-a-deployed-agent) extension.
 
 ```bash
 eve dev
@@ -19,6 +19,10 @@ Add a tool that converts temperatures between Celsius and Fahrenheit.
 
 The self-modification subagent changes the authored files in your project. Review the diff and test the new behavior as you would for any other source change. `eve dev` reloads changes while you work.
 
+The subagent is offered only to sessions authenticated by [`localDev()`](./auth-and-route-protection#localdev) or by the Vercel development token the dev TUI sends for a linked project. Sessions authenticated as Slack users or by your own authenticators, including HTTP Basic operator credentials, do not see it. The local mount has no `authorize` override; edit the authored files directly when using those authenticators.
+
+A tunnel or reverse proxy running on the same machine can forward callers that `localDev()` accepts as the synthetic local developer. Those callers can use the editor. Before exposing `eve dev` through a tunnel, require authentication at the tunnel or proxy, or remove `localDev()` from the exposed channel's auth chain. Putting another authenticator before `localDev()` does not reject callers that it skips: they can still fall through to `localDev()`.
+
 ## Change the self-modification model
 
 The subagent uses your agent's model by default. To give it a different model or reasoning level, ask for it directly:
@@ -31,7 +35,7 @@ The first time, this creates `agent/extensions/self-modification/extension.ts` w
 
 ```ts
 // agent/extensions/self-modification/extension.ts
-import selfModification from "eve/self-modification/local";
+import selfModification from "eve/extensions/self-modification/local";
 
 export default selfModification({
   model: "openai/gpt-6-sol",
@@ -39,17 +43,17 @@ export default selfModification({
 });
 ```
 
-Mounts that import `eve/self-modification` still work; that specifier is an alias for `eve/self-modification/local`. Neither specifier accepts a `deployed` option. If your mount sets `deployed`, eve rejects it and asks you to move that configuration to an `eve/self-modification/remote` mount.
+The bare `eve/self-modification` entry is removed. Mount `eve/extensions/self-modification/local` for development or `eve/extensions/self-modification/remote` for deployed source changes. The local mount does not accept a `deployed` option. If your mount sets `deployed`, eve rejects it and asks you to move that configuration to an `eve/extensions/self-modification/remote` mount.
 
 ## Propose changes from a deployed agent
 
-`eve/self-modification/remote` is a separate extension for deployed agents. It adds a subagent that checks out your repository in a sandbox, edits the authored source, and opens a draft pull request against a target branch. It never changes the running deployment. Changes take effect only after you review, merge, and redeploy.
+`eve/extensions/self-modification/remote` is a separate extension for deployed agents. It adds a subagent that checks out your repository in a sandbox, edits the authored source, and opens a draft pull request against a target branch. It never changes the running deployment. Changes take effect only after you review, merge, and redeploy.
 
 Mount it under its own namespace so it does not replace the local extension:
 
 ```ts
 // agent/extensions/self-modification-remote/extension.ts
-import selfModification from "eve/self-modification/remote";
+import selfModification from "eve/extensions/self-modification/remote";
 
 export default selfModification({
   source: {
@@ -61,7 +65,7 @@ export default selfModification({
   target: { branch: "main" },
   credentials: { pat: true },
   authorize: ({ channel, principal }) =>
-    channel.kind === "http" && principal?.principalId === "release-bot",
+    channel.kind === "channel:eve" && principal?.principalId === "release-bot",
 });
 ```
 
@@ -74,7 +78,7 @@ export default selfModification({
 | `credentials`           | Required. An object with a `resolve({ capability, repository })` function that returns a GitHub token, or `{ pat: true }` to read `EVE_SELF_MODIFICATION_GITHUB_TOKEN` from the deployment environment. |
 | `model`, `reasoning`    | Optional model and reasoning level for the deployed subagent. It defaults to the parent agent's model.                                                                                                  |
 
-The deployed subagent is never offered during `eve dev`. It requires deploying on Vercel, where Vercel Sandbox provides the runtime credential transforms that keep the GitHub token out of the sandbox. Builds succeed on any host, but in a deployment outside Vercel the deployed subagent fails with an error that names this requirement when it opens its sandbox. Don't mount `eve/self-modification/remote` in self-hosted deployments. eve applies the GitHub token as a sandbox network credential only while it checks out or publishes, so commands in the sandbox cannot read it.
+The deployed subagent is never offered during `eve dev`. It requires deploying on Vercel, where Vercel Sandbox provides the runtime credential transforms that keep the GitHub token out of the sandbox. Builds succeed on any host, but in a deployment outside Vercel the deployed subagent fails with an error that names this requirement when it opens its sandbox. Don't mount `eve/extensions/self-modification/remote` in self-hosted deployments. eve applies the GitHub token as a sandbox network credential only while it checks out or publishes, so commands in the sandbox cannot read it.
 
 ## Run without self-modification
 

package/docs/instructions.mdx

@@ -40,7 +40,7 @@ export default defineInstructions({
 });
 ```
 
-`role` is either `"system"` or `"user"` and defaults to `"system"`. The legacy `{ markdown: string }` form still creates system-role instructions, but is deprecated; do not combine `markdown` with `content` or `role`. Blank content contributes no context.
+`role` is either `"system"` or `"user"` and defaults to `"system"`. The retired `{ markdown: string }` form is rejected; use `content`. Blank content contributes no context.
 
 A module-backed definition runs once at build time. eve stores its resolved content and role in the compiled manifest, so the definition is not a runtime entry.
 
@@ -74,13 +74,11 @@ Static instructions never run code at runtime. When you need typed executable be
 
 ## Dynamic instructions
 
-To resolve instructions from session context (auth, tenant, channel, or external data), wrap `defineInstructions` in `defineDynamic`. Instruction resolvers support `session.started` and `turn.started`, not `step.started`, and may return `null` to contribute nothing.
+To compute instructions from auth, tenant, channel, or external data, use `defineDynamic((ctx) => ...)` and return `defineInstructions(...)` or `null`. The function runs before each ordinary model call. Use `ctx.memo(key, fn)` for JSON observations that should stay fixed for a key.
 
-A dynamic system result applies at its lifecycle scope. A dynamic user result is appended to durable history at that boundary: session results before turn results, and both before the current delivery. Completed workflow steps are replay-safe, so parking, resuming, or replaying one does not append the message again.
+A dynamic system instruction applies while its function returns it, outside history. A dynamic user instruction joins durable history only when its content changes. Before a turn's first model call it joins ahead of the turn's input; mid-turn changes append at the current position. Returning `null` adds nothing and resets content tracking, so returning the earlier text later adds it again. Existing history is not removed. Content digests survive deployment changes, clear, and compaction.
 
-The `messages` snapshot passed to a `session.started` resolver includes static user instructions. A `turn.started` resolver additionally sees user instructions produced at `session.started`. Other dynamic capability resolvers keep their existing snapshots.
-
-See [Dynamic capabilities](./guides/dynamic-capabilities) for examples and failure behavior. For a `session.started` instruction that reads the earlier conversation into a replacement session, see [Recover a stranded session](./guides/deployment/self-hosting#recover-a-stranded-session).
+See [Dynamic capabilities](./guides/dynamic-capabilities) for examples and failure behavior. To give a session that replaced a [stranded session](./concepts/execution-model-and-durability#what-a-replacement-session-receives) the earlier conversation, read its stream with `sessions.attach()` and `transcriptOf()` in a user-role instruction that memoizes it by the predecessor's ID.
 
 ## History controls and prompt caching
 

package/docs/memory/custom-provider.md

@@ -78,11 +78,11 @@ prepended to its description.
 does not need; `fileMemory()`, for example, implements recall and tools but no
 capture.
 
-| Surface   | Handlers                                              | Responsibility                                           |
-| --------- | ----------------------------------------------------- | -------------------------------------------------------- |
-| `recall`  | `"turn.started"` (required), `"compaction.completed"` | Return messages to place in model context                |
-| `capture` | `"turn.completed"`, `"compaction.requested"`          | Observe settled history and write to the store           |
-| `tools`   | one function                                          | Return model-facing operations bound to the locked scope |
+| Surface   | Handlers                                     | Responsibility                                           |
+| --------- | -------------------------------------------- | -------------------------------------------------------- |
+| `recall`  | `"turn.started"` (required)                  | Return messages to place in model context                |
+| `capture` | `"turn.completed"`, `"compaction.requested"` | Observe settled history and write to the store           |
+| `tools`   | one function                                 | Return model-facing operations bound to the locked scope |
 
 ### Operation context
 
@@ -104,11 +104,12 @@ Phase-specific fields:
 - `turn.started` and `turn.completed` add `turn` with the turn `id`, `input`
   messages, and `sequence`.
 - `compaction.requested` adds `compaction.modelId` and
-  `compaction.usageInputTokens`; `turn` is `null` for standalone compaction.
-- `compaction.completed` adds `compaction.modelId`; `turn` may be `null`.
+  `compaction.usageInputTokens`, the input tokens that crossed the threshold or
+  `null` for a requested compaction. Its `turn` is the turn the compaction runs
+  in, or `null` for a compaction between turns.
 
-`tools()` receives a `MemoryToolsContext` with the same `memory` and `turn`
-fields plus the ordinary dynamic-resolve context.
+`tools()` receives a `MemoryToolsContext` with the same `memory` field, the
+session and channel, and an `abortSignal`.
 
 ### Recall results
 
@@ -124,14 +125,26 @@ return {
 };
 ```
 
-eve adds each message to model context as a user-role message attributed to the
-slot. Provider content is never promoted to system instructions.
+eve adds each message to the model calls as a user-role message attributed to
+the slot. Provider content is never promoted to system instructions.
 
-Use a stable `id` for replaceable facts. A later message with the same ID in
-the same slot, namespace, and scope supersedes the earlier one; identical
-content is a no-op. Messages without an ID accumulate, even when their content
-repeats. Omitting an earlier ID from a later result does not delete it; recall
-cannot retract, only supersede.
+What a turn recalls stays for the rest of the session: each turn's recall sits
+just before that turn's input in every later model call, so the prompt prefix
+stays cached. The `id` decides what a later recall
+does with it:
+
+| Message           | Effect                                                                                                                      |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `{ content, id }` | Replaces the message an earlier turn recalled with the same `id`. The same content changes nothing; the earlier copy stays. |
+| `{ content }`     | Adds a message. A later recall can't replace or remove it.                                                                  |
+
+A result of `null`, `undefined`, or `{ messages: [] }` adds nothing and keeps
+what earlier turns recalled. Give every message a stable `id` when the provider
+returns its current state each turn, as `fileMemory()` does: without one, each
+turn adds another copy. Retrieval that returns different records each turn
+accumulates them for the session, and they count toward every model call's
+context. The `id` also identifies the record in
+[instrumentation](../observability/instrumentation).
 
 ### Tools
 
@@ -141,54 +154,48 @@ only letters, digits, underscores, or dashes, and be at most 64 characters.
 Schemas, `approval`, `outputSchema`, and `toModelOutput` work as they do for
 authored tools.
 
-A tool closes over the locked scope for the current turn, so it cannot be
-redirected to another tenant or caller by the model. eve keeps each tool
-callback replayable after a process restart or redeployment. On replay, eve
-calls `tools()` again with the captured `memory`, `turn`, and session context.
-`messages` is the history the current process resolved the turn's tools with,
-so after a mid-turn restart it also includes the turn's earlier tool results.
+A tool closes over the locked scope, so it cannot be redirected to another
+tenant or caller by the model. Like recall, eve resolves the scope once per
+turn and principal and keeps it for that turn, so the tools and recall use the
+same scope. A new turn or principal resolves it again. A fresh process in the
+same turn, after a restart, calls `tools()` again with the kept scope rather
+than resolving it again.
 
 ## Lifecycle
 
-| Phase                  | Handler                           | `messages` contains                                        |
-| ---------------------- | --------------------------------- | ---------------------------------------------------------- |
-| `turn.started`         | `recall["turn.started"]`          | History before recall; the new delivery is in `turn.input` |
-| `turn.completed`       | `capture["turn.completed"]`       | Settled history after a successful turn                    |
-| `compaction.requested` | `capture["compaction.requested"]` | History before the checkpoint changes                      |
-| `compaction.completed` | `recall["compaction.completed"]`  | The checkpoint plus canonical recalled records             |
-
-At turn start, eve resolves and locks the scope for every active slot before any
-recall runs. All slots see the same pre-recall history, and eve commits their
-validated results atomically.
-
-During compaction, eve excludes recalled records from the summarizer, keeps the
-latest value for each keyed record plus every unkeyed record, and then calls
-`recall["compaction.completed"]` against the new checkpoint. This keeps
-provider content attributable and prevents a summary from turning it into
-ordinary conversation history. During a turn, eve places those recalled records
-before the turn's latest user message, as it does at turn start; between turns
-they follow the checkpoint. If raw superseded records exceed 512 entries or
-256 KiB, eve canonicalizes them without waiting for the normal token threshold;
-this changes session history only, not the provider's store.
-
-Calling `clear()` on a session removes its history, recalled records, locked
-scopes, and replay bookkeeping. It does not touch the provider's store; a later
-turn recalls the same data again.
+| Phase                  | Handler                           | `messages` contains                                                           |
+| ---------------------- | --------------------------------- | ----------------------------------------------------------------------------- |
+| `turn.started`         | `recall["turn.started"]`          | The conversation the turn's first model call reads, with the turn's new input |
+| `turn.completed`       | `capture["turn.completed"]`       | Settled history after a successful turn                                       |
+| `compaction.requested` | `capture["compaction.requested"]` | The history compaction is about to rewrite                                    |
+
+eve recalls before the first model call of each turn, and again when the
+session's principal changes. Recalled messages stay outside history, so
+compaction never summarizes them. When compaction summarizes a turn, that
+turn's recalled messages move to just after the summary.
+
+Before automatic or requested compaction rewrites history, eve calls
+`capture["compaction.requested"]` with the history it is about to rewrite, so a
+provider can keep detail the summary will lose. The summary waits for it.
+
+Calling `clear()` on a session removes its history and what earlier turns
+recalled. It does not touch the provider's store; the next turn recalls again.
+A new scope, such as another principal's, also starts over.
 
 ## Failure behavior
 
 - A throwing or invalid `recall["turn.started"]` fails the turn before the
-  model call. No slot's recall results are committed. If the turn's
+  model call, and the next model call recalls again. If the turn's
   `abortSignal` is already aborted, eve treats the error as cancellation and
   continues with any queued follow-up. An `AbortError` with an active
   signal still fails the turn.
-- A throwing `capture["compaction.requested"]` leaves history unchanged.
-- A throwing `recall["compaction.completed"]` fails an automatic turn. For
-  standalone compaction, eve logs the error and returns the session to waiting,
-  because the checkpoint has already been written.
-- An invalid or throwing `tools()` result is logged and omitted for that turn.
+- A throwing or invalid `tools()` result fails the turn before the model call,
+  like any other [dynamic tool](../guides/dynamic-capabilities#errors-and-recovery).
 - A throwing `capture["turn.completed"]` is logged after the response and does
   not rewrite the completed turn.
+- A throwing `capture["compaction.requested"]` fails the compaction before it
+  rewrites history, which stays as it was. Like a failed summary, a compaction
+  that fails during a turn fails the turn.
 
 ## Requirements
 
@@ -197,8 +204,8 @@ Providers must:
 - Partition every read and write by `memory.scope.key`. For semantic
   retrieval, include the key in the query itself, not as a filter after a
   global search.
-- Treat `operationId` as an idempotency key. eve may replay a handler with the
-  same ID; replaying a recall with a different result is an error.
+- Treat `operationId` as an idempotency key. eve may run a handler again with
+  the same ID, such as when an interrupted step retries.
 - Enforce their own size and retention policies. eve does not truncate or
   expire provider content.
 - Treat recalled content as user-controlled data.
@@ -216,7 +223,7 @@ provider:
 
 ## What to read next
 
-- [Memory overview](/docs/memory): slots, scope, namespace, and visibility.
+- [Memory overview](/docs/memory): slots, scope, and namespace.
 - [File memory](./file): the built-in provider as a reference implementation.
-- [Dynamic capabilities](../guides/dynamic-capabilities): the dynamic-tool lifecycle provider tools run through.
+- [Dynamic capabilities](../guides/dynamic-capabilities): how eve evaluates the dynamic tools provider tools run through.
 - [Default harness](../concepts/default-harness): compaction in the built-in loop.

package/docs/memory/file.md

@@ -5,7 +5,7 @@ description: "Configure the built-in fileMemory() provider: a bounded, model-mai
 
 `fileMemory()` from `eve/memory/file` is the memory provider built into eve.
 It keeps one small document per resolved scope, recalls that document before
-each turn and after compaction, and gives the model two tools to maintain it.
+each turn, and gives the model two tools to maintain it.
 Use it when a short list of durable facts and preferences is enough; use
 [another provider](/docs/memory#choose-a-provider) when you need semantic
 retrieval or automatic capture.

package/docs/memory/overview.mdx

@@ -59,8 +59,8 @@ eve and the provider split responsibilities along a fixed boundary:
 | --------------------------------------------------- | ------------------------------------- |
 | Slot names, derived from the file path              | Storage and indexing                  |
 | Namespace and scope resolution from trusted context | Retrieval, ranking, and formatting    |
-| When recall and capture run, including compaction   | What to extract and how to capture it |
-| Attribution and supersession of recalled messages   | Retention and deletion                |
+| When recall and capture run                         | What to extract and how to capture it |
+| Attribution of recalled messages                    | Retention and deletion                |
 | Qualifying provider tools as `<slot>__<tool>`       | Which model-facing tools to offer     |
 
 Because the boundary is fixed, a bounded text document, a hosted semantic
@@ -216,7 +216,6 @@ Each file exports one `defineMemory()` value with these fields:
 | `scope`       | Yes      | Who or what shares this slot's memory; see [Scope](#scope)                               |
 | `description` | No       | Prepended to every provider tool description to tell the model what belongs in this slot |
 | `namespace`   | No       | The application domain the scope lives in; see [Namespace](#namespace)                   |
-| `visibility`  | No       | What the model sees after the scope changes mid-session; see [Visibility](#visibility)   |
 
 Slots are independent. Two slots can use the same provider without merging
 their recalled context or tools, and the default namespace includes the slot
@@ -297,22 +296,15 @@ A custom namespace is complete; eve adds no suffix. Returning `null` disables
 the slot. Scope resolves first, so a disabled scope never calls the namespace
 resolver.
 
-## Visibility
+## When the scope changes
 
-`visibility` controls which previously recalled messages stay in model context
-after a slot's scope changes within one session. It does not change the scope
-passed to the provider.
-
-| Value               | After a scope change                                                |
-| ------------------- | ------------------------------------------------------------------- |
-| `"scope"` (default) | Hide recalled messages from the slot's earlier scope                |
-| `"session"`         | Keep earlier recalled messages visible within the current namespace |
-
-Use `"session"` only when every scope that can appear in the session belongs
-to one trusted audience. Namespace remains an isolation boundary in both modes,
-and visibility cannot remove information already included in an assistant
-response; applications that need hard isolation between participants must use
-separate sessions.
+What a turn recalls stays in model context for the rest of the session, and eve
+recalls again when the session's principal changes. When that gives the slot
+another scope, the slot starts over: messages recalled for the earlier scope
+leave model context.
+This cannot remove information already included in an assistant response;
+applications that need hard isolation between participants must use separate
+sessions.
 
 ## Tell the model how to use memory
 

package/docs/patterns/durable-cross-channel-notifications.md

@@ -21,14 +21,15 @@ import { notificationOutbox } from "../lib/notification-outbox";
 export default githubChannel({
   botName: process.env.GITHUB_APP_SLUG,
   events: {
-    async "turn.completed"(event, channel, ctx) {
+    async "turn.settled"(event, ctx) {
+      if (event.data.outcome !== "completed") return;
       await notificationOutbox.enqueue({
-        key: `github-review:${ctx.session.id}:${event.turnId}`,
+        key: `github-review:${ctx.session.id}:${event.data.turnId}`,
         destination: {
           channelId: process.env.SLACK_REVIEW_CHANNEL_ID!,
           provider: "slack",
         },
-        message: `PR review completed for ${channel.repository.fullName}.`,
+        message: `PR review completed for ${ctx.channel.repository.fullName}.`,
       });
     },
   },