eve 0.90.0 → 0.91.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (185) hide show
  1. package/CHANGELOG.md +34 -23
  2. package/dist/src/channel/auth/http-basic.js +1 -1
  3. package/dist/src/channel/channel-operations.d.ts +1 -1
  4. package/dist/src/channel/types.d.ts +2 -0
  5. package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
  6. package/dist/src/client/session.d.ts +1 -1
  7. package/dist/src/compiled/.vendor-stamp.json +1 -1
  8. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  9. package/dist/src/execution/proxied-deliver-step.js +1 -1
  10. package/dist/src/execution/sandbox/bash.js +2 -2
  11. package/dist/src/execution/session/active-turn.js +1 -1
  12. package/dist/src/execution/session/admission.d.ts +6 -0
  13. package/dist/src/execution/session/admission.js +1 -1
  14. package/dist/src/execution/session/delivery-facts.js +1 -1
  15. package/dist/src/execution/session/next-input.d.ts +2 -2
  16. package/dist/src/execution/session/next-input.js +1 -1
  17. package/dist/src/execution/session/program.js +1 -1
  18. package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
  19. package/dist/src/execution/session-inbox/inbox.js +1 -1
  20. package/dist/src/execution/session-inbox/protocol.js +1 -1
  21. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  22. package/dist/src/harness/compaction/engine.js +2 -2
  23. package/dist/src/harness/current-messages.js +1 -1
  24. package/dist/src/harness/emission.d.ts +3 -0
  25. package/dist/src/harness/emission.js +1 -1
  26. package/dist/src/harness/facts.d.ts +5 -2
  27. package/dist/src/harness/facts.js +1 -1
  28. package/dist/src/harness/model-call/call.d.ts +7 -1
  29. package/dist/src/harness/model-call/call.js +3 -1
  30. package/dist/src/harness/provider-tool-history.d.ts +8 -0
  31. package/dist/src/harness/provider-tool-history.js +1 -1
  32. package/dist/src/harness/session-machine/transitions.d.ts +3 -2
  33. package/dist/src/harness/step/after-model.js +1 -1
  34. package/dist/src/harness/step/context.js +1 -1
  35. package/dist/src/harness/step/intake.js +1 -1
  36. package/dist/src/harness/step/prompt.js +1 -1
  37. package/dist/src/harness/tool-history-repair.d.ts +2 -0
  38. package/dist/src/harness/tool-history-repair.js +1 -1
  39. package/dist/src/harness/tool-loop.js +1 -1
  40. package/dist/src/internal/application/stamped-package-version.js +1 -1
  41. package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
  42. package/dist/src/protocol/session-events/families/delivery.js +1 -1
  43. package/dist/src/protocol/session-projection/fold.js +1 -1
  44. package/dist/src/public/channels/discord/hitl.js +1 -1
  45. package/dist/src/public/channels/slack/hitl.d.ts +2 -1
  46. package/dist/src/public/channels/slack/hitl.js +3 -3
  47. package/dist/src/public/channels/slack/interaction-cards.js +1 -1
  48. package/dist/src/public/channels/slack/request-card-render.js +1 -1
  49. package/dist/src/public/channels/teams/hitl.js +1 -1
  50. package/dist/src/public/channels/teams/verify.js +1 -1
  51. package/dist/src/public/definitions/hook.d.ts +90 -7
  52. package/dist/src/public/definitions/hook.js +1 -1
  53. package/dist/src/public/hooks/index.d.ts +3 -2
  54. package/dist/src/reactions/continuation.d.ts +19 -0
  55. package/dist/src/reactions/continuation.js +1 -0
  56. package/dist/src/reactions/intents.d.ts +10 -4
  57. package/dist/src/reactions/intents.js +1 -1
  58. package/dist/src/reactions/kinds/hook.js +1 -1
  59. package/dist/src/reactions/runner.js +1 -1
  60. package/dist/src/reactions/state.d.ts +15 -2
  61. package/dist/src/reactions/state.js +1 -1
  62. package/dist/src/runtime/resolve-connection.js +1 -1
  63. package/dist/src/runtime/subagents/workflow.js +1 -1
  64. package/dist/src/setup/primitives/open-url.js +1 -1
  65. package/dist/src/setup/scaffold/create/project.js +1 -1
  66. package/dist/src/shared/value-delta.d.ts +5 -4
  67. package/dist/src/shared/value-delta.js +1 -1
  68. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  69. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  70. package/dist/src/tools/provided/web-fetch.js +1 -1
  71. package/docs/agent-config.md +199 -222
  72. package/docs/channels/chat-sdk.mdx +60 -64
  73. package/docs/channels/custom.mdx +264 -281
  74. package/docs/channels/discord.mdx +176 -123
  75. package/docs/channels/eve.mdx +136 -206
  76. package/docs/channels/github.mdx +24 -22
  77. package/docs/channels/linear.mdx +30 -30
  78. package/docs/channels/linq.mdx +25 -13
  79. package/docs/channels/mcp.mdx +154 -116
  80. package/docs/channels/overview.mdx +31 -32
  81. package/docs/channels/photon.mdx +32 -56
  82. package/docs/channels/slack.mdx +538 -375
  83. package/docs/channels/teams.mdx +40 -26
  84. package/docs/channels/telegram.mdx +13 -13
  85. package/docs/channels/twilio.mdx +11 -11
  86. package/docs/code-extension.mdx +40 -42
  87. package/docs/concepts/built-in-tools.md +89 -57
  88. package/docs/concepts/context-control.md +20 -20
  89. package/docs/concepts/default-harness.md +20 -36
  90. package/docs/concepts/execution-model-and-durability.mdx +96 -160
  91. package/docs/concepts/project-structure.mdx +21 -14
  92. package/docs/concepts/security-model.md +27 -27
  93. package/docs/concepts/sessions-runs-and-streaming.md +184 -198
  94. package/docs/concepts/state.md +7 -15
  95. package/docs/connections/mcp.mdx +109 -93
  96. package/docs/connections/openapi.mdx +57 -59
  97. package/docs/connections/overview.mdx +175 -170
  98. package/docs/evals/assertions.mdx +36 -29
  99. package/docs/evals/cases.mdx +38 -42
  100. package/docs/evals/judge.mdx +21 -29
  101. package/docs/evals/overview.mdx +42 -38
  102. package/docs/evals/reporters.mdx +54 -27
  103. package/docs/evals/running.mdx +15 -8
  104. package/docs/evals/targets.mdx +16 -19
  105. package/docs/evals/tool-stubs.mdx +111 -97
  106. package/docs/experimental/dynamic-schedules.mdx +118 -63
  107. package/docs/extensions.md +58 -65
  108. package/docs/getting-started.mdx +4 -6
  109. package/docs/guides/auth-and-route-protection.md +87 -70
  110. package/docs/guides/client/continuations.mdx +23 -26
  111. package/docs/guides/client/messages.mdx +47 -66
  112. package/docs/guides/client/output-schema.mdx +8 -8
  113. package/docs/guides/client/overview.mdx +45 -43
  114. package/docs/guides/client/streaming.mdx +62 -71
  115. package/docs/guides/decide.md +24 -79
  116. package/docs/guides/deployment/meta.json +1 -1
  117. package/docs/guides/deployment/overview.md +27 -18
  118. package/docs/guides/deployment/self-hosted-operations.md +99 -0
  119. package/docs/guides/deployment/self-hosting.md +63 -80
  120. package/docs/guides/deployment/vercel.mdx +31 -27
  121. package/docs/guides/deployment/workflow-worlds.md +100 -0
  122. package/docs/guides/dev-tui.md +48 -41
  123. package/docs/guides/dynamic-capabilities.md +49 -50
  124. package/docs/guides/frontend/nextjs.mdx +2 -2
  125. package/docs/guides/frontend/nuxt.mdx +11 -11
  126. package/docs/guides/frontend/overview.mdx +1 -1
  127. package/docs/guides/frontend/sveltekit.mdx +11 -11
  128. package/docs/guides/frontend/tanstack.mdx +16 -16
  129. package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
  130. package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
  131. package/docs/guides/frontend/use-eve-agent.mdx +25 -25
  132. package/docs/guides/hooks.md +152 -106
  133. package/docs/guides/instrumentation/agent-runs.mdx +26 -30
  134. package/docs/guides/instrumentation/instrumentation.mdx +49 -76
  135. package/docs/guides/instrumentation/meta.json +1 -1
  136. package/docs/guides/instrumentation/otel.mdx +113 -179
  137. package/docs/guides/remote-agents.md +125 -187
  138. package/docs/guides/self-modification.md +18 -18
  139. package/docs/guides/session-context.md +16 -16
  140. package/docs/install-integrations.mdx +26 -24
  141. package/docs/instructions.mdx +37 -42
  142. package/docs/memory/custom-provider.md +35 -41
  143. package/docs/memory/file.md +93 -76
  144. package/docs/memory/overview.mdx +145 -156
  145. package/docs/patterns/durable-cross-channel-notifications.md +15 -19
  146. package/docs/patterns/dynamic-scheduling.md +19 -23
  147. package/docs/patterns/multi-tenant-approvals.md +17 -22
  148. package/docs/patterns/multi-tenant-auth.md +43 -42
  149. package/docs/patterns/multi-tenant-memory.md +39 -36
  150. package/docs/patterns/voice-notes.md +3 -3
  151. package/docs/protocols/acp.md +13 -13
  152. package/docs/protocols/ucp.mdx +7 -7
  153. package/docs/reference/agent-files.md +6 -6
  154. package/docs/reference/cli.md +99 -98
  155. package/docs/reference/telemetry.md +1 -1
  156. package/docs/reference/typescript-api.md +52 -53
  157. package/docs/responsible-use.md +2 -2
  158. package/docs/sandbox/custom-providers.mdx +60 -56
  159. package/docs/sandbox/default.mdx +23 -24
  160. package/docs/sandbox/docker.mdx +16 -10
  161. package/docs/sandbox/index.mdx +93 -61
  162. package/docs/sandbox/just-bash.mdx +17 -11
  163. package/docs/sandbox/troubleshooting.mdx +29 -23
  164. package/docs/sandbox/vercel.mdx +45 -52
  165. package/docs/schedules.mdx +65 -54
  166. package/docs/skills.mdx +74 -49
  167. package/docs/subagents/index.mdx +97 -136
  168. package/docs/tools/human-in-the-loop.md +160 -90
  169. package/docs/tools/meta.json +1 -1
  170. package/docs/tools/overview.mdx +229 -237
  171. package/docs/tools/tasks.md +118 -117
  172. package/docs/tools/workflows.mdx +447 -543
  173. package/docs/tutorial/connect-a-warehouse.mdx +11 -13
  174. package/docs/tutorial/first-agent.mdx +14 -16
  175. package/docs/tutorial/guard-the-spend.mdx +6 -8
  176. package/docs/tutorial/how-it-runs.mdx +8 -8
  177. package/docs/tutorial/query-sample-data.mdx +8 -8
  178. package/docs/tutorial/remember-definitions.mdx +4 -4
  179. package/docs/tutorial/run-analysis.mdx +20 -22
  180. package/docs/tutorial/ship-it.mdx +19 -19
  181. package/docs/tutorial/team-playbooks.mdx +9 -9
  182. package/docs/use-cases.mdx +13 -11
  183. package/package.json +1 -1
  184. package/docs/guides/instrumentation/migration.md +0 -96
  185. package/docs/tools/tasks-upgrade.md +0 -218
@@ -3,7 +3,7 @@ title: "Hooks"
3
3
  description: "Subscribe to runtime stream events from agent/hooks/."
4
4
  ---
5
5
 
6
- Hooks are eve's authored extension points for the runtime event stream. A hook subscribes to stream events and runs side effects after each event is durably recorded, such as audit logging, metrics and alerting, or persisting every session and message to your own database for analytics. Reach for one to observe what the agent does without writing a tool, a context provider (a value made available across a step), or a channel adapter handler (a handler defined on a channel's adapter; see [Channels](../channels/overview)).
6
+ A hook runs your code after the agent records an event on its session stream, such as a session starting or a turn ending. Each hook is a file under `agent/hooks/`. Use hooks for audit logs, metrics and alerts, or copying sessions and messages to your own database. A hook sees events from every channel; to handle one channel's events, see [Scope side effects to a channel](#scope-side-effects-to-a-channel).
7
7
 
8
8
  ## Define a hook
9
9
 
@@ -23,64 +23,25 @@ export default defineHook({
23
23
  });
24
24
  ```
25
25
 
26
- The slug is the path-relative basename. `agent/hooks/audit.ts` becomes `"audit"`, and `agent/hooks/auth/load-profile.ts` becomes `"auth/load-profile"`.
26
+ The hook's name is its path without the extension: `agent/hooks/audit.ts` is `"audit"`, and `agent/hooks/auth/load-profile.ts` is `"auth/load-profile"`. `defineHook`, `HookDefinition`, and `HookContext` come from `eve/hooks`.
27
27
 
28
- `defineHook`, `HookDefinition`, and `HookContext` live on `eve/hooks`.
28
+ The `events` map keys each handler by event type, and `*` matches every event. Any event in [Sessions, runs and streaming](../concepts/sessions-runs-and-streaming) works, such as `session.started`, `turn.settled`, `content.completed`, and `call.settled`. Progress events (`content.delta`, `call.input`, and `call.progress`) reach only handlers keyed on their exact type, never `*`.
29
29
 
30
- A hook file declares stream-event subscribers under the `events` map, keyed by fact type, with `*` matching every fact. Subscribe to any fact in the v27 catalog documented in [Sessions, runs and streaming](../concepts/sessions-runs-and-streaming), such as `session.started`, `turn.settled`, `content.completed`, and `call.settled`. Progress records (`content.delta`, `call.input`, `call.progress`) reach only handlers keyed on their type, never `*`. Handlers can call external services and cancel the running turn. They cannot inject model context. To contribute runtime model messages, use `defineDynamic` and `defineInstructions` in `agent/instructions/`.
31
-
32
- ## Scope side effects to a channel
33
-
34
- A hook under `agent/hooks/` observes matching events from every channel on the root agent. `defineHook` has no channel filter. Use a channel's `events` configuration when a handler assumes a specific platform or should run only for sessions owned by that channel:
35
-
36
- ```ts title="agent/channels/github.ts"
37
- import { githubChannel } from "eve/channels/github";
38
-
39
- export default githubChannel({
40
- events: {
41
- async "turn.settled"(event, ctx) {
42
- console.info("GitHub turn settled", {
43
- outcome: event.data.outcome,
44
- repository: ctx.channel.repository.fullName,
45
- sessionId: ctx.session.id,
46
- turnId: event.data.turnId,
47
- });
48
- },
49
- },
50
- });
51
- ```
52
-
53
- A GitHub channel event handler cannot fire for a Slack-owned session, so platform-specific side effects do not depend on an early-return guard. On a built-in channel, an authored handler replaces that channel's default handler for the same event key. Check the channel page before overriding events that deliver replies, progress, errors, or human-input prompts. The [Slack channel](/docs/channels/slack#customize-rendering) takes renderers instead: a renderer's handler keeps Slack's default by calling `next()` and replaces it by skipping `next`.
54
-
55
- Use `ctx.channel.kind` inside a global hook only when the operation is otherwise agent-wide and conditional handling is intentional. For a channel with event handlers, such as `githubChannel`, `slackChannel`, and the other built-ins, the kind is the path-derived identity. `agent/channels/github.ts` reports `channel:github`, so `ctx.channel.kind === "github"` never matches. Import the channel definition and compare it with `isChannel` from `eve/channels`:
56
-
57
- ```ts title="agent/hooks/github-only.ts"
58
- import { isChannel } from "eve/channels";
59
- import { defineHook } from "eve/hooks";
60
-
61
- import github from "../channels/github";
62
-
63
- export default defineHook({
64
- events: {
65
- async "turn.started"(_event, ctx) {
66
- if (!isChannel(ctx.channel, github)) return;
67
- // GitHub-owned turns only.
68
- },
69
- },
70
- });
71
- ```
72
-
73
- Route-only channels use the same path-derived identity, even when they have no event handlers. Use `isChannel` with the authored channel definition rather than checking for the former `"http"` kind.
74
-
75
- For typed channel metadata in dynamic resolvers or instrumentation, narrow with `isChannel` the same way; see [OpenTelemetry runtime context](../observability/otel#add-runtime-context).
30
+ Handlers can call external services, cancel the running turn, and [continue a finished turn](#continue-a-turn-from-a-hook) with a new message. They can't add text to the model's context. To add model context at runtime, use `defineDynamic` and `defineInstructions` in `agent/instructions/`.
76
31
 
77
32
  ## Hook structure and context
78
33
 
79
- Every handler receives the same `HookContext`, including the shared session
80
- helpers documented in [Session context](./session-context):
34
+ Every handler receives a `HookContext`, which includes the shared [session context](./session-context) helpers. `HookContext<K>` is keyed by the handler's event key. Only `turn.settled` and `*` handlers get `continue`, so type a helper that calls it as `HookContext<"turn.settled">`:
81
35
 
82
36
  ```ts
83
- interface HookContext extends SessionContext {
37
+ type HookContext<K extends HookEventKey = HookEventKey> = HookBaseContext &
38
+ (K extends "turn.settled" | "*" ? HookContinue : {});
39
+
40
+ interface HookContinue {
41
+ continue(message: MessageContent, options?: HookContinueOptions): HookContinueResult;
42
+ }
43
+
44
+ interface HookBaseContext extends SessionContext {
84
45
  readonly agent: { readonly name: string; readonly nodeId?: string };
85
46
  readonly channel: { readonly kind?: string; readonly continuationToken?: string };
86
47
  /** Where the event sits on the stream: its line, and its index in that line. */
@@ -95,8 +56,15 @@ interface HookContext extends SessionContext {
95
56
  }
96
57
  ```
97
58
 
98
- That means a hook can access the current sandbox and release its backing
99
- compute at an application-defined boundary:
59
+ - `ctx.turn` is the latest turn, including one that ended, or `null` before the first turn.
60
+ - `ctx.now` is the time eve recorded the event.
61
+ - `ctx.memo(key, fn)` follows the [dynamic-value memo rules](./dynamic-capabilities#memo-rules).
62
+ - `ctx.view` is a read-only snapshot of the session, taken with the event. Read what changed from the event and where things stand from the view. On `call.settled`, `call(ctx.view, event.data.callId)` from `eve/events` returns the call's name, kind, input, output, and state.
63
+ - Hooks don't receive the assembled conversation history.
64
+
65
+ For `task.started`, `task.ended`, and `child.opened`, `ctx.session.id` is the session that started the task or opened the child session, even when the event arrives between turns. These hooks can call `ctx.getSandbox()` on that session, and their state and sandbox changes carry into its next turn.
66
+
67
+ A hook can stop the session's sandbox at a point you choose:
100
68
 
101
69
  ```ts title="agent/hooks/stop-after-turn.ts"
102
70
  import { defineHook } from "eve/hooks";
@@ -111,30 +79,11 @@ export default defineHook({
111
79
  });
112
80
  ```
113
81
 
114
- Every built-in backend stops its underlying compute while preserving the
115
- durable session and filesystem for the next callback. On Vercel, the current
116
- handle can also automatically resume on later I/O. A hook failure, including a
117
- failed stop, follows the normal
118
- [hook failure behavior](#what-happens-when-a-hook-throws).
119
-
120
- `ctx.turn` is the latest turn, including a settled one, or `null` before the first turn. `ctx.now` is the commit time. `ctx.memo(key, fn)` follows the [dynamic-value memo rules](./dynamic-capabilities#memo-rules). Hooks do not receive assembled conversation history.
121
-
122
- `ctx.view` is the session's state as of the event's whole commit, folded by the same code as
123
- `eve/events`. Read what changed from the event, and where things stand from the view: for
124
- example, `call(ctx.view, event.data.callId)` from `eve/events` on a `call.settled` returns its
125
- name, kind, input, output, and state. The view has no public tables; queries return immutable
126
- observations. A retained snapshot stays unchanged after later events.
127
-
128
- For `task.started`, `task.ended`, and `child.opened`, `ctx.session.id`
129
- identifies the session that started the task or opened the subagent session.
130
- Typed handlers and `*` handlers receive this context even when the event
131
- arrives between turns. These hooks can use `ctx.getSandbox()` against that
132
- session. Session state and sandbox changes they make are kept for the
133
- session's next turn. `child.opened` appears when the child session opens.
82
+ Every built-in sandbox backend stops the compute but keeps the session and its filesystem. On Vercel, the sandbox starts again on its next use. A failed stop follows the normal [hook failure behavior](#what-happens-when-a-hook-throws).
134
83
 
135
84
  ### Narrowing tool results
136
85
 
137
- `toolResultFrom` narrows a settled call to a specific authored tool or connection (MCP or OpenAPI) and returns typed output. Pass it the observation from `call(ctx.view, callId)`, which carries the call's name, kind, state, and output. Import it from `eve/tools`:
86
+ `toolResultFrom` from `eve/tools` checks whether a finished call came from a specific authored tool or MCP or OpenAPI connection, and returns its typed output. Pass it the result of `call(ctx.view, callId)`:
138
87
 
139
88
  ```ts
140
89
  import { defineHook } from "eve/hooks";
@@ -164,9 +113,13 @@ export default defineHook({
164
113
  });
165
114
  ```
166
115
 
167
- Returns `undefined` when the call doesn't match, or when it didn't complete. For authored tools the return includes `{ output, toolName, callId }` with `output` typed as the tool's `TOutput`. For connections it includes `{ output, toolName, connectionToolName, callId }` with `output` as `unknown`.
116
+ | Call | `toolResultFrom` returns |
117
+ | ------------------------------- | ------------------------------------------------------------------------------ |
118
+ | Doesn't match, or didn't finish | `undefined` |
119
+ | Authored tool | `{ output, toolName, callId }`, with `output` typed as the tool's `TOutput` |
120
+ | Connection | `{ output, toolName, connectionToolName, callId }`, with `output` as `unknown` |
168
121
 
169
- This works for a mounted extension's tools too — import the tool from the extension's `./tools` export and pass it. `toolResultFrom` matches the namespaced call (`crm__search`) because it keys off the tool definition, not the name:
122
+ `toolResultFrom` matches by tool definition, not name, so it also works for tools from a mounted extension. Import the tool from the extension's `./tools` export:
170
123
 
171
124
  ```ts
172
125
  import { search } from "@acme/crm/tools";
@@ -176,11 +129,11 @@ import { call } from "eve/events";
176
129
  const crmSearch = toolResultFrom(call(ctx.view, event.data.callId), search); // typed; matches crm__search
177
130
  ```
178
131
 
179
- When one definition is mounted under more than one tool name, for example when a subagent re-exports an extension tool, `toolResultFrom` matches calls from every mounted name.
132
+ When one definition is mounted under several names, such as when a subagent re-exports an extension tool, `toolResultFrom` matches all of them.
180
133
 
181
134
  ### Persist events to your own database
182
135
 
183
- Every event a hook receives has its stream position as `ctx.position`. A position never changes, so `(session, line, index)` makes a natural primary key for an events table:
136
+ `ctx.position` is the event's place on the stream. A position never changes, so `(session, line, index)` works as a primary key for an events table:
184
137
 
185
138
  ```ts title="agent/hooks/persist.ts"
186
139
  import { defineHook } from "eve/hooks";
@@ -199,34 +152,32 @@ export default defineHook({
199
152
  });
200
153
  ```
201
154
 
202
- A consumer that re-reads the stream gets the same positions, so the key above deduplicates ingestion. If a step is interrupted after publishing but before checkpointing, its retry does not run hooks again for what it already published. New recovery facts run their hooks normally. Some handlers may already have run while others never ran; this is not an exactly-once effect guarantee.
155
+ Reading the stream again yields the same positions, so the key removes duplicates. After an interruption, eve doesn't run hooks again for events it already published. Some handlers for an event may have run and others not, so effects are not exactly-once.
203
156
 
204
- Pass `ctx.occurrence.idempotencyKey` to services that support idempotency. It identifies this handler's fact position. For one effect per turn or call, use that resource's identity instead, such as `turnId` or `callId`. Effects such as one alert per session still need author-managed durable state. `ctx.memo` caches observations, not effect receipts; its records can be discarded on deployment changes.
157
+ Pass `ctx.occurrence.idempotencyKey`, which identifies this handler's run for this event, to services that support idempotency. For one effect per turn or call, key on `turnId` or `callId` instead. An effect such as one alert per session needs state you store yourself. `ctx.memo` caches lookups, not records of effects, and a deployment change can discard it.
205
158
 
206
159
  See [Positions](../concepts/sessions-runs-and-streaming#positions) for the full contract.
207
160
 
208
161
  ## Execution order
209
162
 
210
- Each committed line is published in this order:
211
-
212
- 1. Write. The line is written to the durable stream.
213
- 2. Channel delivery. The channel adapter handler runs for each fact.
214
- 3. Hooks. Stream-event hooks fire (typed handlers first, then the `*` wildcard). Return values are ignored.
215
- 4. Cancellation requests queued by `ctx.cancel()` take effect after the handlers return.
163
+ eve handles each recorded line of the stream in this order:
216
164
 
217
- Before an ordinary model call, dynamic functions compute the model and capabilities from the latest committed session. They do not subscribe to events.
165
+ 1. Write. The line is saved to the session stream.
166
+ 2. Channel. The channel's handler runs for each event.
167
+ 3. Hooks. Typed handlers run first, then `*` handlers. Return values are ignored.
168
+ 4. Cancellation. A cancel requested with `ctx.cancel()` takes effect after the handlers return.
218
169
 
219
- Hooks always run after the line is durably recorded, so if a hook throws, the stream stays consistent.
170
+ Hooks run after the line is saved, so a hook that throws can't corrupt the stream. [Dynamic functions](./dynamic-capabilities) don't subscribe to events; they run before each model call.
220
171
 
221
172
  ## What happens when a hook throws
222
173
 
223
- An unhandled error fails the running turn before its next model call or as it would settle. Between turns there is no active turn to fail, so eve logs the error without changing an earlier outcome. Catch errors from optional audit or metrics work if the turn should continue. To stop without a failure, call [`ctx.cancel(reason?)`](#cancel-the-running-turn-from-a-hook).
174
+ An unhandled error fails the running turn before its next model call, or when the turn would end. Between turns, eve only logs the error. Catch errors from optional audit or metrics work if the turn should continue. To stop without a failure, call [`ctx.cancel(reason?)`](#cancel-the-running-turn-from-a-hook).
224
175
 
225
- A hook failure does not trigger a retry. State changes and external side effects made before the exception are not rolled back. If a side effect needs retries or compensation, handle that inside the hook. Runtime failures outside the authored handler, such as failures setting up context or persisting state, still propagate. If a published fact outlives its step's checkpoint, the step's retry does not run the hook again.
176
+ eve doesn't retry a failed hook or undo the state changes and side effects it made before the error. Handle retries or compensation inside the hook. Runtime failures outside the handler, such as context setup or saving state, still propagate.
226
177
 
227
178
  ## Cancel the running turn from a hook
228
179
 
229
- Call `ctx.cancel(reason?)` when a hook finds that the turn cannot proceed. For example, a `turn.started` hook that cannot load the caller's credentials can stop the turn before the model runs, instead of letting every tool call fail:
180
+ Call `ctx.cancel(reason?)` when a hook finds that the turn can't continue. For example, a `turn.started` hook that can't load the caller's credentials can stop the turn before the model runs:
230
181
 
231
182
  ```ts title="agent/hooks/require-credentials.ts"
232
183
  import { defineHook } from "eve/hooks";
@@ -249,32 +200,127 @@ export default defineHook({
249
200
  });
250
201
  ```
251
202
 
252
- The remaining subscribers for the event still run. Then eve cancels the turn the same way [`session.cancel()`](./client/streaming) does: in-flight model and tool work is aborted, delegated child turns are cancelled, and the turn settles with `outcome: "cancelled"` and `cause: { hook }` naming the hook. No failure is recorded. A cancel from `turn.started` or `model.requested` takes effect before that model call. In a conversation, the next message starts a new turn. A delegated task reports the cancellation to its caller.
203
+ The event's other handlers still run. Then eve cancels the turn as [`session.cancel()`](./client/streaming) does:
253
204
 
254
- A plain-text message that answers a pending question, such as one from `ask_question`, is recorded as `delivery.consumed` before eve delivers it. Only the turn's own principal can answer by text; anyone else's text waits and runs as its own turn. Like a follow-up message, the answer updates the claims on `ctx.session.auth.current` for that event's hooks and the rest of the turn. Calling `ctx.cancel()` from that event's hook cancels the turn instead: the question settles as `interrupted`, and the waiting tool call never receives the text.
205
+ - eve stops model and tool work in progress.
206
+ - eve cancels child turns the turn delegated to.
207
+ - The turn ends with `outcome: "cancelled"` and `cause: { hook }` naming the hook, and eve records no failure.
255
208
 
256
- The same goes for the `call.progress` a workflow tool reports while the turn waits on it: `ctx.cancel()` from its hook cancels the turn, and the run's result never reaches the model.
209
+ A cancel from `turn.started` or `model.requested` takes effect before that model call. In a conversation, the next message starts a new turn. A delegated task reports the cancellation to its caller.
257
210
 
258
- `ctx.cancel()` returns `void` rather than a promise. The turn stops after the hook returns, so there is nothing to await. Call it before the handler's promise settles: a call from work the handler did not await throws. A cancel counts only if the handler returns: a handler that calls `ctx.cancel()` and then throws fails the turn instead.
211
+ Rules for `ctx.cancel()`:
259
212
 
260
- `ctx.cancel()` targets the turn being processed, including while its input is being admitted. Calls between turns without an incoming turn do nothing. Repeated requests cancel that turn only once; they never cancel a later turn. Hook-side `ctx.compact` and `ctx.once` are not available. Client and channel session compaction APIs are unchanged.
213
+ - It returns `void`, because the turn stops after the hook returns.
214
+ - Call it before the handler's promise resolves. A call from work the handler didn't await throws.
215
+ - A handler that calls `ctx.cancel()` and then throws fails the turn instead.
216
+ - It targets the current turn, including while eve still accepts the turn's input. Between turns with no incoming turn, it does nothing.
217
+ - Repeated calls cancel that turn once and never a later turn.
218
+ - `ctx.compact` and `ctx.once` aren't available in hooks.
219
+
220
+ A plain-text answer to a pending question, such as one from `ask_question`, is recorded as `delivery.consumed` before the question receives it. Only the turn's own sender can answer by text; anyone else's text waits and runs as its own turn. The answer updates the claims on `ctx.session.auth.current` for that event's hooks and the rest of the turn, as a follow-up message does. Calling `ctx.cancel()` from that event's hook cancels the turn: the question ends as `interrupted`, and the waiting tool call never gets the text. In the same way, `ctx.cancel()` from a hook for a workflow tool's `call.progress` cancels the turn, and the run's result never reaches the model.
221
+
222
+ ## Scope side effects to a channel
223
+
224
+ A hook under `agent/hooks/` sees matching events from every channel on the root agent. To run a handler only for sessions from one channel, put it in that channel's `events` configuration:
225
+
226
+ ```ts title="agent/channels/github.ts"
227
+ import { githubChannel } from "eve/channels/github";
228
+
229
+ export default githubChannel({
230
+ events: {
231
+ async "turn.settled"(event, ctx) {
232
+ console.info("GitHub turn settled", {
233
+ outcome: event.data.outcome,
234
+ repository: ctx.channel.repository.fullName,
235
+ sessionId: ctx.session.id,
236
+ turnId: event.data.turnId,
237
+ });
238
+ },
239
+ },
240
+ });
241
+ ```
242
+
243
+ On a built-in channel, your handler replaces the channel's default handler for the same event key. Check the channel page before you override events that send replies, progress, errors, or prompts for human input. The [Slack channel](/docs/channels/slack#customize-rendering) takes renderers instead: a renderer keeps Slack's default by calling `next()` and replaces it by skipping `next`.
244
+
245
+ To check the channel inside a global hook, use `isChannel` from `eve/channels`, not `ctx.channel.kind`. The kind comes from the file path: `agent/channels/github.ts` reports `channel:github`, so `ctx.channel.kind === "github"` never matches. `isChannel` works for every channel, including route-only channels without event handlers:
246
+
247
+ ```ts title="agent/hooks/github-only.ts"
248
+ import { isChannel } from "eve/channels";
249
+ import { defineHook } from "eve/hooks";
250
+
251
+ import github from "../channels/github";
252
+
253
+ export default defineHook({
254
+ events: {
255
+ async "turn.started"(_event, ctx) {
256
+ if (!isChannel(ctx.channel, github)) return;
257
+ // GitHub-owned turns only.
258
+ },
259
+ },
260
+ });
261
+ ```
262
+
263
+ Use `isChannel` the same way to get typed channel metadata in dynamic functions or instrumentation; see [OpenTelemetry runtime context](../observability/otel#add-runtime-context).
264
+
265
+ ## Continue a turn from a hook
266
+
267
+ Call `ctx.continue(message, options?)` from a `turn.settled` handler to start the session's next turn. This hook keeps the agent working until the tests pass, for at most ten more turns:
268
+
269
+ ```ts title="agent/hooks/until-green.ts"
270
+ import { defineState } from "eve/context";
271
+ import { defineHook } from "eve/hooks";
272
+
273
+ const attempts = defineState("until-green.attempts", () => 0);
274
+
275
+ export default defineHook({
276
+ events: {
277
+ async "turn.settled"(event, ctx) {
278
+ if (event.data.outcome !== "completed") return;
279
+ const sandbox = await ctx.getSandbox();
280
+ const test = await sandbox.run({ command: "pnpm test --reporter=dot" });
281
+ if (test.exitCode === 0 || attempts.get() >= 10) {
282
+ attempts.update(() => 0);
283
+ return;
284
+ }
285
+ attempts.update((n) => n + 1);
286
+ ctx.continue(
287
+ `Tests still fail. Fix them without editing test files.\n\n${test.stdout.slice(-2000)}`,
288
+ );
289
+ },
290
+ },
291
+ });
292
+ ```
293
+
294
+ Only `turn.settled` and `*` handlers receive `ctx.continue`. The message is [`MessageContent`](./client/messages), and `options` takes `context` and `auth`, as `session.send()` does. Without `auth`, the continuation names no sender and the turn runs as the session's current identity.
295
+
296
+ The continuation waits until the session is idle, then starts an ordinary turn. It's dropped if anything else starts a turn first, such as a person's message, or if the session is cancelled, cleared, or ended, so a person can always stop a loop. Its `delivery.admitted` records `source: { channel, hook }`, and a note in the turn's history tells the model no person wrote it. Like other hook effects, a continuation is lost if the step that settled the turn is interrupted before it's saved. Bound loops yourself, as the example does.
297
+
298
+ A turn can be continued when it completed, or when the same hook cancelled it, so a hook can `ctx.cancel()` the agent mid-turn and continue with a correction. When several hooks continue the same turn, their messages share the next turn.
299
+
300
+ `ctx.continue()` returns `{ queued: true }`, or `{ queued: false, reason }` when it can't continue the turn: `not-completed`, `already-queued`, `auth-conflict` (another hook's continuation acts for a different sender), or `not-settled` (a `*` handler on another event).
261
301
 
262
302
  ## Subagent isolation
263
303
 
264
- Subagents may carry their own `agent/hooks/` directory. Subagent hooks fire only inside the subagent scope. Parent-agent hooks do not fire for subagent turns, and subagent hooks see only the subagent's own context.
304
+ A subagent can have its own `agent/hooks/` directory. Its hooks run only for the subagent's turns and see only its context. Parent hooks don't run for subagent turns.
305
+
306
+ A subagent's approvals, questions, and sign-ins appear on the parent stream as the parent's own `interaction.opened` events. Parent hooks see them with the parent's session, agent, and channel context. In a relayed request:
307
+
308
+ - `subject` names the parent call that waits on it.
309
+ - `origin` names the child session and request, and `origin.call` names the child's call.
265
310
 
266
- A subagent's approvals, questions, and sign-ins are also relayed to the parent stream, as the parent's own `interaction.opened` facts. Parent hooks observe them after the stream write, with the parent's session, agent, and channel context. A relayed interaction's `subject` names the parent call that waits on it, and its `origin` names the child session and request that asked, with `origin.call` naming the child's call. When the parent's turn is paused on that child, the relayed request pauses it on the person too. The child's settlement is relayed as the parent's `interaction.settled`.
311
+ While the parent's turn waits on that child, the relayed request makes it wait for the person too. When the child's request ends, the parent stream records `interaction.settled`.
267
312
 
268
313
  ## Hook vs tool vs provider
269
314
 
270
- | Need | Use |
271
- | ------------------------------------------------- | ---------------------------------------------- |
272
- | Observe runtime events (audit, metrics, alerting) | `events.<type>` (or a channel adapter handler) |
273
- | Provide structured input to the model on demand | a tool |
274
- | Make a value available across the entire step | a context provider |
275
- | Subscribe to platform-specific events | a channel adapter handler |
315
+ | Need | Use |
316
+ | ----------------------------------------------- | ---------------------------------------------- |
317
+ | Watch runtime events (audit, metrics, alerting) | `events.<type>` (or a channel handler) |
318
+ | Start the next turn after one finishes | `ctx.continue()` from `events["turn.settled"]` |
319
+ | Give the model structured input on demand | a tool |
320
+ | Add model context at runtime | `defineDynamic` with `defineInstructions` |
321
+ | Subscribe to platform-specific events | a channel handler |
276
322
 
277
- Stream-event hooks and channel adapter event handlers are structurally identical. Choose the channel adapter handler when you are authoring adapter-specific behavior, and choose `events.*` when you are authoring agent-level behavior that should fire across every channel. Both fire when both are registered.
323
+ Hooks and channel event handlers have the same shape. When both handle an event, both run.
278
324
 
279
325
  ## What to read next
280
326
 
@@ -11,9 +11,9 @@ url: "/observability/agent-runs"
11
11
  plans.
12
12
  </Callout>
13
13
 
14
- Use Vercel Agent Runs to browse eve sessions and inspect conversation traces
15
- in the project's **Observability** view. The tab requires enablement for your
16
- Vercel team; contact your Vercel representative if it does not appear.
14
+ Vercel Agent Runs lets you browse eve sessions and inspect conversation traces
15
+ in the project's **Observability** view. The tab must be enabled for your
16
+ Vercel team. If it doesn't appear, contact your Vercel representative.
17
17
 
18
18
  Agent Runs usage is billed at
19
19
  [Always-on Tracing rates](https://vercel.com/docs/tracing/always-on-tracing#usage-and-pricing)
@@ -22,9 +22,8 @@ during beta. All plans include 30-day Agent Runs retention during beta.
22
22
  ## Enable tracing on Vercel
23
23
 
24
24
  When `eve deploy` creates a new Vercel project, it configures 100% trace
25
- sampling for all environments. Existing Vercel projects need a sampling rule
26
- configured to collect traces. To enable tracing for an existing project, select
27
- your team and project, then open
25
+ sampling for all environments. An existing project needs a sampling rule before
26
+ it collects traces. Select your team and project, then open
28
27
  [**Settings → Tracing**](https://vercel.com/d?to=%2F%5Bteam%5D%2F%5Bproject%5D%2Fsettings%2Ftracing&title=Go+to+Tracing+settings):
29
28
 
30
29
  1. Select **Add Sampling Rule**.
@@ -34,26 +33,26 @@ your team and project, then open
34
33
  5. Select **Save**.
35
34
 
36
35
  Vercel applies the first matching rule. If an existing rule matches these
37
- requests, update it to use a 100% rate; a later rule will not override it.
36
+ requests, set its rate to 100% instead of adding a later rule.
38
37
 
39
- Tracing starts as soon as you save the rule. You can also manage sampling
38
+ Tracing starts when you save the rule. You can also manage sampling
40
39
  rules with [`vercel traces config`](https://vercel.com/docs/cli/traces#manage-trace-sampling-rules).
41
- The CLI accepts rates from 1 to 100%; add a 0% rule from the dashboard.
40
+ The CLI accepts rates from 1 to 100%. Add a 0% rule from the dashboard.
42
41
 
43
42
  ## Trace selected paths
44
43
 
45
- If you prefer path-scoped sampling, replace the all-path rule with 100% rules
46
- for each required **Request Path Prefix**. For a single agent at the default
44
+ To sample only some paths, replace the all-path rule with a 100% rule
45
+ for each **Request Path Prefix** you need. For a single agent at the default
47
46
  mount, start with:
48
47
 
49
48
  - `/eve/v1`: eve's HTTP API and default channel endpoints.
50
49
  - `/.well-known/workflow`: workflow execution and webhooks.
51
50
 
52
51
  For named agents, use their deployed prefixes, such as `/eve/support/v1`,
53
- instead of `/eve/v1`. Include custom channel routes and, for Vercel-backed
54
- schedule collections,
55
- `/.well-known/eve/v1/schedules/consumer`. Missing paths can leave traces
56
- incomplete. The workflow prefix also includes non-eve workflows in the same
52
+ instead of `/eve/v1`. Also include custom channel routes. For
53
+ [dynamic schedules](/docs/experimental/dynamic-schedules) on Vercel, include
54
+ `/.well-known/eve/v1/schedules/consumer`. A missing path can leave traces
55
+ incomplete. The workflow prefix also samples non-eve workflows in the same
57
56
  project.
58
57
 
59
58
  ## Configure Agent Runs
@@ -66,8 +65,8 @@ default-export `agentRuns(...)` from that file, or default-export
66
65
  ## Filter Agent Runs exports
67
66
 
68
67
  `agentRuns()` accepts one `exportPolicy` object or an array applied in order.
69
- Each policy filters spans and attributes before the Agent Runs destination
70
- receives them:
68
+ Each policy filters spans and attributes before Agent Runs receives them.
69
+ The return values match [Filter a destination](./otel#filter-a-destination):
71
70
 
72
71
  ```ts title="agent/instrumentation/agent-runs.ts"
73
72
  import { agentRuns } from "eve/instrumentation/otel";
@@ -80,19 +79,17 @@ export default agentRuns({
80
79
  });
81
80
  ```
82
81
 
83
- Return `{ emit: true }` from `span` to retain a span unchanged, or
84
- `{ emit: false }` to omit it from Agent Runs. To retain the span while redacting
85
- content, return `{ redact: true }` with `inputs: true`, `outputs: true`, or
86
- both. A redaction decision implies emission and requires at least one
87
- direction. A throwing `span` callback drops the span from Agent Runs. Return
88
- `{ emit: true }`, `{ emit: false }`, or `{ replace: true, value }` from
89
- `attribute` to retain, remove, or change one attribute.
82
+ From `span`, return `{ emit: true }` to keep a span, `{ emit: false }` to omit
83
+ it, or `{ redact: true }` with `inputs: true`, `outputs: true`, or both to keep
84
+ it without that content. A throwing `span` callback drops the span from Agent
85
+ Runs. From `attribute`, return `{ emit: true }`, `{ emit: false }`, or
86
+ `{ replace: true, value }` to keep, remove, or change one attribute.
90
87
 
91
88
  ## Redact content
92
89
 
93
- The `exportPolicy` can further narrow what Agent Runs receives after the
94
- process-wide `otel({ tracePolicy })` has admitted a trace. For example, keep
95
- spans while redacting inputs and outputs unless the session is public:
90
+ `exportPolicy` can only narrow what the process-wide `otel({ tracePolicy })`
91
+ already allows. This policy keeps spans but redacts inputs and outputs unless
92
+ the session is public:
96
93
 
97
94
  ```ts title="agent/instrumentation/agent-runs.ts"
98
95
  import { agentRuns } from "eve/instrumentation/otel";
@@ -107,11 +104,10 @@ export default agentRuns({
107
104
 
108
105
  Input redaction removes eve's known prompt, instruction, document, and
109
106
  tool-argument attributes. Output redaction removes response, reasoning,
110
- tool-result, exception, and status attributes. Redaction narrows only Agent
111
- Runs; it does not mutate spans sent to another destination.
107
+ tool-result, exception, and status attributes. Redaction applies only to Agent
108
+ Runs, not to spans sent to other destinations.
112
109
 
113
110
  ## What to read next
114
111
 
115
112
  - [OpenTelemetry](./otel): configure process-wide settings and third-party destinations.
116
113
  - [Vercel deployment](/docs/guides/deployment/vercel): deploy an eve agent and inspect its runtime.
117
- - [Migrate instrumentation](/docs/observability/instrumentation-migration): replace `agent/instrumentation.ts`.