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
@@ -4,18 +4,16 @@ description: "Pause a run for a person — gate a tool on approval or have the a
4
4
  url: /human-in-the-loop
5
5
  ---
6
6
 
7
- Human-in-the-loop (HITL) is any point where the agent durably pauses and waits for a person. Two things trigger it, and both ride the same pause-and-resume protocol:
7
+ Human-in-the-loop (HITL) is any point where the agent pauses and waits for a person. Two things cause a pause:
8
8
 
9
- - **Approvals** — a tool policy allows, denies, or pauses a call for a person to review. The agent decides to call the tool; the policy decides whether it runs automatically or needs a human decision.
10
- - **Questions** — the agent itself asks the user a clarifying question or a choice mid-turn, and parks until they answer.
9
+ - **Approvals**: a tool's `approval` policy allows, denies, or holds a call for a person to review.
10
+ - **Questions**: the agent asks the user a clarifying question or a choice in the middle of a turn.
11
11
 
12
- Both keep the turn open, and the stream reports `turn.paused` awaiting the person. The run waits durably, for as long as it takes — seconds or days — and picks back up exactly where it left off once the answer arrives. Channels render the request for you.
12
+ The turn stays open and the stream reports `turn.paused`. The wait survives process restarts, so it can last seconds or days. When the answer arrives, the run continues where it stopped.
13
13
 
14
14
  ## Approvals
15
15
 
16
- Approval is a property of a [tool](/docs/tools) that gates it before it runs. This includes [workflow tools](/docs/tools/workflows): a call waiting for approval does not start its workflow, and a call denied by a policy or person never runs. Other calls from the same model response that do not require approval can proceed while it waits.
17
-
18
- The policy can decide automatically or pause for a person. Set `approval` with the helpers from `eve/tools/approval`:
16
+ Set `approval` on a [tool](/docs/tools), including a [workflow tool](/docs/tools/workflows), to check each call before it runs. Use the helpers from `eve/tools/approval`:
19
17
 
20
18
  ```ts title="agent/tools/refund_charge.ts"
21
19
  import { defineTool } from "eve/tools";
@@ -39,17 +37,25 @@ export default defineTool({
39
37
  | `always()` | Require approval before every call. |
40
38
  | `auto()` | Ask a decision model whether to run the exact call or require user approval. |
41
39
 
42
- By default, omitted `approval` behaves like `never()`, so tool calls may execute without human approval. Require human approval or other safeguards for sensitive, irreversible, regulated, financial, healthcare, employment, housing, legal, safety-impacting, user-impacting, or external side-effecting actions.
40
+ Rules:
41
+
42
+ - A call that waits for approval hasn't started, and a denied call never runs.
43
+ - Other calls from the same model response that need no approval run while it waits.
44
+ - Omitted `approval` behaves like `never()`, so tool calls run without human approval by default. Require human approval or other safeguards for sensitive, irreversible, regulated, financial, healthcare, employment, housing, legal, safety-impacting, user-impacting, or external side-effecting actions.
45
+ - Approval doesn't make a charge or email happen exactly once. Give non-idempotent side effects their own idempotency keys.
46
+ - Approval is consent only. The approved call, its policy recheck, and the rest of the turn run with the requesting user's identity, connections, and credentials, never the approver's. See [Act as the approver](#act-as-the-approver).
47
+
48
+ ### Let a decision model review calls
43
49
 
44
- `auto()` uses an [AI SDK decision model](/docs/guides/decide) to classify each call as `clear` or `caution`. It defaults to `typesafe-ai/jev`, TypeSafe AI's [Jev decision model](https://vercel.com/i/what-is-jev). Like `decide`, a model string uses Vercel AI Gateway unless the application configures a global AI SDK default provider:
50
+ `auto()` sends each call to an [AI SDK decision model](/docs/guides/decide), which classifies it as `clear` or `caution`. A `clear` call runs. A `caution`, a failed review, or incomplete input requires user approval. The tool name and input go to the decision model's provider.
51
+
52
+ Omit `model` to use `typesafe-ai/jev`, TypeSafe AI's [Jev decision model](https://vercel.com/i/what-is-jev). As with `decide`, a model string uses Vercel AI Gateway unless the application configures a global AI SDK default provider:
45
53
 
46
54
  ```ts
47
55
  approval: auto({ model: "typesafe-ai/jev" });
48
56
  ```
49
57
 
50
- The decision model reviews the tool name and input for dangerous effects. A caution, failed review, or incomplete input requires user approval. The tool input is sent to the decision model's provider.
51
-
52
- Override the classifier text for application-specific policy:
58
+ Override the classifier text for an application-specific policy:
53
59
 
54
60
  ```ts
55
61
  approval: auto({
@@ -62,11 +68,11 @@ approval: auto({
62
68
  });
63
69
  ```
64
70
 
65
- Dynamic tools rebuild their policies when evaluated. Use [`ctx.memo()`](/docs/guides/dynamic-capabilities) to keep external JSON observations used to configure a policy.
71
+ A dynamic tool rebuilds its policy each time eve evaluates the tool. To keep external data that configures a policy, save it with [`ctx.memo()`](/docs/guides/dynamic-capabilities).
66
72
 
67
- Each pending approval needs its own answer. A `once()` approval applies to later calls, not other already-open prompts.
73
+ ### Customize the approval prompt
68
74
 
69
- Use the object form of `approval` to replace the default `Approve <tool label>?` text with a tool-specific summary. The `prompt` callback receives the validated `input`, final `toolName`, and `callId`:
75
+ Use the object form of `approval` to replace the default `Approve <tool label>?` text. The `prompt` callback receives the validated `input`, final `toolName`, and `callId`:
70
76
 
71
77
  ```ts title="agent/tools/refund_charge.ts"
72
78
  import { defineTool } from "eve/tools";
@@ -86,9 +92,13 @@ export default defineTool({
86
92
  });
87
93
  ```
88
94
 
89
- Channels render this prompt in their approval UI. Slack also includes the complete tool input in a collapsed **Tool input** block so an approver can inspect the original structured value.
95
+ Channels show this prompt in their approval UI. Slack also shows the complete tool input in a collapsed **Tool input** block.
90
96
 
91
- When the decision depends on the input, pass your own policy instead of a helper. It receives the same session context as tool execution, plus `{ toolName, toolInput, callId, abortSignal }` (connection tools also get `toolAnnotations`), and returns an AI SDK 7 approval status synchronously or as a promise. Use `abortSignal` for asynchronous policy work so cancellation stops it with the turn. Use `ctx.session.auth.current` to guard by the caller of the current turn and `ctx.session.auth.initiator` to guard by the caller that created the session. Return `"user-approval"` to pause for a person or `"not-applicable"` to continue without a prompt. `toolInput` can be undefined, so guard the access. This policy denies cross-tenant calls, then requires approval only when an amount crosses a threshold:
97
+ ### Write your own policy
98
+
99
+ When the decision depends on the input, pass a function. It receives `session`, the same as `ctx.session` in `execute`, plus `{ toolName, toolInput, callId, abortSignal }`. Connection tools also get `toolAnnotations`.
100
+
101
+ This policy denies cross-tenant calls, then requires approval only above an amount:
92
102
 
93
103
  ```ts
94
104
  approval: ({ session, toolInput }) => {
@@ -100,23 +110,52 @@ approval: ({ session, toolInput }) => {
100
110
  },
101
111
  ```
102
112
 
103
- A boolean is a supported shorthand, returned synchronously or as a promise: `true` means `"user-approval"` and `false` means `"not-applicable"`.
113
+ The policy returns an `ApprovalStatus`, directly or as a promise:
114
+
115
+ | Return | Result |
116
+ | ----------------------------- | ------------------------------------------ |
117
+ | `"user-approval"` or `true` | Pause for a person. |
118
+ | `"not-applicable"` or `false` | Continue without a prompt. |
119
+ | `"approved"` | Run the call without a person. |
120
+ | `"denied"` | Deny the call without a person. |
121
+ | `{ type: "denied", reason }` | Deny the call and give the model `reason`. |
122
+
123
+ When you write a policy:
124
+
125
+ - Pass `abortSignal` to asynchronous work, so the work stops with the turn.
126
+ - Check `session.auth.current` for the caller of the current turn, or `session.auth.initiator` for the caller that started the session.
127
+ - Handle a `toolInput` of `undefined`.
104
128
 
105
- Policies can also return `"approved"` or `"denied"` to decide automatically. Use `{ type: "denied", reason }` when the model should receive a reason for denying the call. A denied call never starts: it settles `call.settled` with `outcome: "rejected"`, `cause: { policy: "approval" }`, and a `TOOL_EXECUTION_DENIED` output, whether the policy denies it as the model calls it or when an approved call is checked again. A tool that runs and throws settles `failed`. An explicit `"approved"` result records `clearedBy: { policy: "approval" }` on `call.started`. A call cleared by a remembered `once()` approval records the same `{ policy: "approval" }`; a call approved by a person records `{ interactionId }`. Calls that need no approval omit `clearedBy`. The `Approval`, `ApprovalConfiguration`, `ApprovalContext`, `ApprovalPolicy`, and `ApprovalStatus` types are exported from `eve/tools/approval`.
129
+ A denied call never starts, including when the policy denies an approved call on its recheck. Its `call.settled` event has `outcome: "rejected"`, `cause: { policy: "approval" }`, and a `TOOL_EXECUTION_DENIED` output. A tool that runs and throws ends with `outcome: "failed"` instead.
106
130
 
107
- Approval is not an exactly-once guarantee for a charge or email. Give non-idempotent side effects their own idempotency keys.
131
+ The `call.started` event records what let the call run in `clearedBy`:
132
+
133
+ | Cleared by | `clearedBy` |
134
+ | -------------------------------------------- | ------------------------ |
135
+ | A policy returning `"approved"` | `{ policy: "approval" }` |
136
+ | A remembered `once()` approval | `{ policy: "approval" }` |
137
+ | A person | `{ interactionId }` |
138
+ | Nothing, because the call needed no approval | omitted |
139
+
140
+ The `Approval`, `ApprovalConfiguration`, `ApprovalContext`, `ApprovalPolicy`, and `ApprovalStatus` types are exported from `eve/tools/approval`.
108
141
 
109
142
  ### Remember approval for a tool
110
143
 
111
- `once()` remembers the latest decision people gave its prompts for the resolved tool name, across turns and context clears, until the session ends. A remembered approval covers later calls to that tool regardless of their input; it does not clear a different tool. A later denial of a `once()` prompt for the tool replaces it, so the next call asks again. When one delivery answers several of those prompts, a denial among its answers stands. Approving a prompt asked by `always()` or by a policy that does not return `once()`'s decision remembers nothing, and so does a wrapping policy that calls `once()` but returns a different status. Existing pending prompts still need their own answers.
144
+ `once()` remembers the latest answer to its prompts for the tool's final name, across turns and context clears, until the session ends. A remembered approval covers later calls to that tool, whatever their input.
145
+
146
+ - A later denial of a `once()` prompt replaces the approval, so the next call asks again.
147
+ - When one message answers several of those prompts, a denial among the answers wins.
148
+ - A `once()` approval covers later calls, not other approvals already waiting. Each waiting approval needs its own answer.
112
149
 
113
- A remembered approval is consent, not authorization. Authorize the current caller on every call. Use `always()` or an input-dependent policy when different tenants, environments, or other inputs need separate approval decisions. When wrapping `once()` in another policy, forward the policy context and return its status object unchanged.
150
+ eve remembers only prompts that `once()`'s own status asked for. It remembers nothing for an `always()` prompt, or for a wrapping policy that calls `once()` but returns a different status. When you wrap `once()`, pass the policy context through and return its status object unchanged.
151
+
152
+ A remembered approval is consent, not authorization. Authorize the current caller on every call. Use `always()` or an input-dependent policy when different tenants, environments, or other inputs need separate approval decisions.
114
153
 
115
154
  ### Authorizing approval responses
116
155
 
117
156
  By default, only the person whose turn requested a call can approve or cancel it.
118
157
 
119
- Define an approval response policy to change who may settle a call, for example, to specify a set of designated approvers who must approve a certain tool. A tool with a `response` policy replaces the default entirely, so return `{ status: "allowed" }` to let any responder through:
158
+ Define a `response` policy to change who can answer, such as a list of designated approvers. The policy replaces the default entirely, so return `{ status: "allowed" }` to accept any responder:
120
159
 
121
160
  ```ts title="agent/tools/refund_charge.ts"
122
161
  import { defineTool } from "eve/tools";
@@ -147,14 +186,14 @@ export default defineTool({
147
186
 
148
187
  The `response` policy receives:
149
188
 
150
- - `request`: the stable `interactionId`, `callId`, `toolName`, and typed `toolInput` for the call being approved, plus `principal`: the authenticated principal whose turn requested the call, or `null` when that caller was unauthenticated or anonymous. eve captures `request.principal` when the approval is requested, so it stays the same while other people continue the session.
151
- - `response`: the submitted `decision`, `"approve"` or `"deny"`, plus `principal`: the authenticated principal that submitted it, including its `principalId`, `principalType`, `authenticator`, and `attributes`. Your route or channel supplies this identity. The policy runs for both decisions, so a responder it rejects can neither approve nor deny the call.
152
- - `session`: read-only session identity and lineage: `id`, `initiator`, `parent`, and `turn`.
153
- - `auth`: narrow `getToken(provider, options?)` and `requireAuth(provider, options?)` capabilities bound to the responder. Use these when authorization depends on a provider identity or permission; an interactive provider flow parks durably and then retries the policy.
189
+ - `request`: the call's `interactionId`, `callId`, `toolName`, and typed `toolInput`. `request.principal` is the signed-in user whose turn requested the call, or `null` for an unauthenticated or anonymous caller. It is fixed when the approval opens, even if other people continue the session.
190
+ - `response`: the submitted `decision` (`"approve"` or `"deny"`) and the responder's `principal` from your route or channel. `principal` has `principalId`, `principalType`, `authenticator`, and `attributes`.
191
+ - `session`: read-only `id`, `initiator`, `parent`, and `turn`.
192
+ - `auth`: `getToken(provider, options?)` and `requireAuth(provider, options?)` for the responder, for checks that depend on a provider identity or permission. If the responder must sign in, eve waits for sign-in and then runs the policy again.
154
193
 
155
- Return `{ status: "allowed" }` to accept the decision. Return `{ status: "rejected", reason }` to leave the shared request pending so another eligible responder can settle it. When a policy only cares who approves, return `{ status: "allowed" }` for `deny` so anyone can still dismiss the request.
194
+ The policy runs for both decisions, so a rejected responder can neither approve nor deny. `{ status: "rejected", reason }` keeps the request open for another eligible responder. When a policy only checks who approves, allow every `deny`, so anyone can dismiss the request.
156
195
 
157
- `session.initiator` is the person who started the session, and `request.principal` is the person who asked for this call. In a shared thread they can differ. Compare the full identity of `response.principal` with `request.principal` to let only the requester settle the call:
196
+ In a shared thread, `session.initiator`, who started the session, can differ from `request.principal`, who asked for this call. To let only the requester answer, compare every identity field of the two:
158
197
 
159
198
  ```ts title="agent/tools/publish_release.ts"
160
199
  import { defineTool } from "eve/tools";
@@ -188,11 +227,48 @@ export default defineTool({
188
227
  });
189
228
  ```
190
229
 
191
- When the policy refuses a response, its `response.settled` reports `outcome: "refused"` and the approval stays open for another answer. Submitting an answer does not approve the call on its own: wait for `interaction.settled` to confirm the decision.
230
+ When the policy refuses an answer, `response.settled` reports `outcome: "refused"` and the approval stays open. Submitting an answer doesn't finish the call by itself, so wait for `interaction.settled` to confirm a decision.
231
+
232
+ #### Act as the approver
233
+
234
+ A `defineTool` tool can act for the approver explicitly. While an approved `defineTool` call runs, `ctx.approval.responder` is the approver, and `ctx.session.auth.current` stays the requester. `ctx.approval.responder.getToken(provider)` returns the approver's token for an inline provider. `ctx.approval` is absent in workflow tools and for calls that needed no approval.
235
+
236
+ `ctx.approval.responder.getToken(provider)` never starts a sign-in. When the approver has no token, it throws a `ConnectionAuthorizationFailedError` with `reason: "approver_authorization_required"`.
237
+
238
+ A connection's `headers` and `toolCall.providedArguments` callbacks receive the same `ctx.approval.responder` while an approved connection call runs. See [Send the approver to the server](/docs/connections#send-the-approver-to-the-server).
239
+
240
+ ```ts
241
+ export default defineTool({
242
+ description: "Grant the requester access to a repository.",
243
+ inputSchema: z.object({ repo: z.string() }),
244
+ approval: {
245
+ request: always(),
246
+ response: ({ response }) =>
247
+ itAdmins.includes(response.principal.principalId)
248
+ ? { status: "allowed" }
249
+ : { status: "rejected" },
250
+ },
251
+ async execute({ repo }, ctx) {
252
+ const admin = await ctx.approval?.responder.getToken(github);
253
+ if (admin === undefined) throw new Error("An IT admin must approve this grant.");
254
+ return await grantAccess(repo, ctx.session.auth.current, admin.token);
255
+ },
256
+ });
257
+ ```
258
+
259
+ Traces record both people:
260
+
261
+ | Span | Attributes | Names |
262
+ | -------- | -------------------------------------------------------------- | -------------------------------- |
263
+ | Turn | `agent.principal.current.*` | The requester |
264
+ | Approval | `agent.approval.responder.type`, `agent.approval.responder.id` | The person who answered |
265
+ | Tool | `agent.tool.approver.type`, `agent.tool.approver.id` | The approver of an approved call |
266
+
267
+ The ids are recorded only when the trace policy records both inputs and outputs, and the conversation is public or runs in development. Otherwise, only the type is recorded.
192
268
 
193
269
  ### Skipping approval for schedule-dispatched turns
194
270
 
195
- `session.auth.current` identifies the caller of this turn. Markdown schedules use the app principal (`authenticator: "app"`, `principalId: "eve:app"`, `principalType: "runtime"`) automatically. A `run` schedule must pass its `appAuth` to `send(...)` for the child session to use that principal. Match all three fields to skip approval for automated turns while still prompting when a person calls the same tool:
271
+ Markdown schedules run as the app: `authenticator: "app"`, `principalId: "eve:app"`, and `principalType: "runtime"`. A `run` schedule must pass its `appAuth` to `send(...)` for the child session to run as the app. To skip approval for scheduled turns but still ask a person, match all three fields on `session.auth.current`:
196
272
 
197
273
  ```ts title="agent/tools/refund_charge.ts"
198
274
  import { defineTool } from "eve/tools";
@@ -215,18 +291,11 @@ export default defineTool({
215
291
  });
216
292
  ```
217
293
 
218
- `session` in `approval` has the same shape as `ctx.session` in `execute`: `id`, `auth`, `turn`, and an optional `parent`. If a person later resumes a schedule-started session, `session.auth.current` becomes that person while `session.auth.initiator` remains the app principal. Inspect `initiator` only when the policy should apply to the whole session. Skipping approval on scheduled turns means any non-idempotent side effect will re-fire if a step replays, so pair this pattern with idempotency keys or `once()` where needed.
294
+ If a person later continues a schedule-started session, `session.auth.current` becomes that person. `session.auth.initiator` stays the app, so check `initiator` only when the policy should cover the whole session. Pair this pattern with idempotency keys or `once()`, because a non-idempotent side effect runs again if a step replays.
219
295
 
220
296
  ## Questions
221
297
 
222
- The `ask_question` tool lets the model pause and ask the user one question, rather than guessing. The model calls it with `{ question, options? }`:
223
-
224
- - `question`: the question to put to the user, with the context needed to answer it.
225
- - `options`: two or three mutually exclusive choices, each with a `label` and a one-sentence `description`. Channels render these as buttons or a select menu. Omit `options` for an open-ended question.
226
-
227
- The user can always type their own answer instead of picking an option, so the model never needs an "Other" option. The tool returns `{ status: "answered", answer }` with the chosen option's label or the user's words, `{ interrupted: true }` when a new message arrived that did not answer the question, or `{ status: "unavailable" }` when the session cannot request input.
228
-
229
- `ask_question` is an [opt-in framework tool](/docs/concepts/built-in-tools#ask_question). Add it with `eve add tool/ask_question`, which creates this file:
298
+ The opt-in `ask_question` tool lets the model pause and ask the user one question instead of guessing. Add it with `eve add tool/ask_question`, which creates this file:
230
299
 
231
300
  ```ts title="agent/tools/ask_question.ts"
232
301
  import { askQuestion } from "eve/tools/ask_question";
@@ -234,82 +303,83 @@ import { askQuestion } from "eve/tools/ask_question";
234
303
  export default askQuestion;
235
304
  ```
236
305
 
237
- `ask_question` is an ordinary [workflow tool](/docs/tools/workflows) built on `ctx.ask()`. Write your own workflow tool with `ctx.ask()` when you need a different schema or want to act on the answer in the same call. Without any asking tool, the model asks in its reply text and the user's next message carries the answer.
306
+ The model calls `ask_question` with `{ question, options? }`:
307
+
308
+ - `question`: the question for the user, with the context needed to answer it.
309
+ - `options`: two or three mutually exclusive choices, each with a `label` and a one-sentence `description`. Channels show these as buttons or a select menu. Omit `options` for an open-ended question.
310
+
311
+ The user can always type their own answer, so the model never needs an "Other" option. The tool returns:
312
+
313
+ | Result | When |
314
+ | -------------------------------- | --------------------------------------------------------- |
315
+ | `{ status: "answered", answer }` | The user picked an option (its label) or typed an answer. |
316
+ | `{ interrupted: true }` | A new message arrived that didn't answer the question. |
317
+ | `{ status: "unavailable" }` | The session can't request input. |
318
+
319
+ Without any asking tool, the model asks in its reply text, and the user's next message carries the answer.
238
320
 
239
- In a custom workflow tool, an answered `ctx.ask()` returns the authenticated responder's `id`, `type`, and optional `issuer` when that identity is available. It does not include channel attributes. `ctx.session.auth.current` remains the run's auth snapshot; use the response's `responder` to identify who answered.
321
+ `ask_question` is an ordinary [workflow tool](/docs/tools/workflows) built on `ctx.ask()`. Write your own with `ctx.ask()` when you need a different schema or want to act on the answer in the same call.
322
+
323
+ An answered `ctx.ask()` returns `responder`, when available: the signed-in responder's `id`, `type`, and optional `issuer`, without channel attributes. Use `responder`, not `ctx.session.auth.current`, to identify who answered.
324
+
325
+ ## Answering from a client or channel
326
+
327
+ Every [channel](/docs/channels/overview) turns requests into native UI and sends the user's choice back as the answer. Slack, for example, shows approvals as buttons and questions as select menus.
328
+
329
+ In your own frontend, use `openInteractions(view)` and `respond([{ interactionId, optionId }])` on the same session. A request stays `open` until its `interaction.settled` event, and you can answer while other work runs. See [Building a frontend](/docs/guides/frontend/overview#human-in-the-loop-prompts).
240
330
 
241
331
  ## How pause and resume works
242
332
 
243
- Approvals and questions share one protocol:
333
+ Approvals and questions pause and resume the same way:
244
334
 
245
335
  1. A tool call needs approval, or a workflow tool such as `ask_question` calls `ctx.ask()`.
246
- 2. eve emits an `interaction.opened` fact for each pending request.
247
- 3. The run parks durably, for as long as it takes. The turn stays open: the stream emits `turn.paused` awaiting those interactions, and after the answer the turn runs on under the same `turnId`.
248
- 4. The client answers with `answers` (structured, each naming its `interactionId`) or a normal follow-up `message`. A follow-up whose text matches an option ID, option label, or numeric option index resolves automatically, including approval options such as `approve` and `deny`.
336
+ 2. eve emits an `interaction.opened` event for each waiting request.
337
+ 3. The stream emits `turn.paused` for those requests. After the answer, the turn continues with the same `turnId`.
338
+ 4. The client answers with `answers`, each naming its `interactionId`, or with a follow-up `message`. A message whose text matches an option ID, option label, or option number answers automatically. This includes approval options such as `approve` and `deny`.
249
339
 
250
- To tell the model why a call was denied, send `text` with the `deny` response, for example `{ interactionId, optionId: "deny", text: "Only the three-pack." }`. The model receives the note quoted in the denial result, marked as written by the person who denied the call, who may not be the user. The note is also visible to anyone who can read the session stream, in the `response.submitted` and `interaction.settled` facts.
340
+ To tell the model why you denied a call, send `text` with the `deny` answer: `{ interactionId, optionId: "deny", text: "Only the three-pack." }`. The model gets the note quoted in the denial result, attributed to the person who denied the call. That person may not be the user. Anyone who can read the session stream sees the note in `response.submitted` and `interaction.settled`.
251
341
 
252
- For `ctx.ask()` questions from tools and prompts proxied from subagents, a follow-up message answers the first open request, as described in [Several requests at once](#several-requests-at-once). The message must match an option, or the question must allow free text. Otherwise the message follows the session's `turnPolicy`. A steering message, the default, aborts the `ctx.abortSignal` of each `execute` workflow tool call the turn waits on, so a question such a call asked, such as `ask_question`'s, is withdrawn: its interaction settles `withdrawn`. The model reads the message once those calls settle.
342
+ Cancelling the turn ends its approvals as `interrupted`. The call doesn't run, and a later answer approves nothing.
253
343
 
254
- On the stream, each interaction's `request.kind` is `approval`, `question`, `budget`, or `sign-in`,
255
- and its `subject` names the call, task, or turn it is about. Clients read the same interaction as an
256
- `Interaction`, with the same nested `request.kind`; use it to choose behavior and presentation, and keep a
257
- default branch, since a later release can add a kind. `interactionId` identifies the interaction to
258
- answer, and `call.callId`, when present, identifies the call it is about; neither encodes the
259
- interaction's semantics.
344
+ ### Follow-up messages
260
345
 
261
- The run picks back up exactly where it parked. Because the pause is durable, nothing is held in memory while it waits — the process can restart and the parked turn survives.
346
+ For `ctx.ask()` questions and prompts passed up from subagents, a follow-up message can answer the first open request; see [Several requests at once](#several-requests-at-once). The message answers when it matches an option or the question allows free text. Otherwise, the message follows the session's `turnPolicy`.
262
347
 
263
- When a subagent requests input, its parent session relays it as its own `interaction.opened`, with `origin` naming the child session and request, and `origin.call` naming the child's call. Answering through that parent session routes the response directly to the blocked child without invoking the parent model.
348
+ A steering message, the default, aborts the `ctx.abortSignal` of each `execute` workflow tool call that the turn waits on. A question from such a call, such as `ask_question`'s, ends as `withdrawn`. The model reads the message after those calls finish.
264
349
 
265
- A message from the parent agent to a subagent never answers the subagent's tool approval or session-limit request, even when its text matches an option such as `approve` or `continue`. Only a person's structured answer, routed through the parent session, settles these requests. The subagent still receives the parent's message as an ordinary message. It steers the turn past a pending approval, whose interaction settles `withdrawn`, and waits behind a session-limit request until a person answers it.
350
+ For approvals, a follow-up message that matches no option steers the turn, even with `turnPolicy: "queue"`, because the turn can't end until the person acts:
266
351
 
267
- Approval is consent only. An approved tool call runs with the requesting user's identity, connections, and credentials, including its policy recheck. The approver's access is never lent to the call. Subsequent tool calls in the turn also stay with the original owner.
352
+ - eve withdraws every unanswered approval. The request ends as `withdrawn`, its call ends as `rejected` without running, and the model reads the message next.
353
+ - Approvals that already have an answer use that answer, so approved calls still run.
354
+ - A message from anyone other than the person the turn serves waits until the turn ends.
268
355
 
269
- For auditing, traces record both people: the turn span's `agent.principal.current.*` attributes name the requester, and the approval span's `agent.approval.responder.type` and `agent.approval.responder.id` name who approved or denied the call. An approved call's tool span also records its approver as `agent.tool.approver.type` and `agent.tool.approver.id`, since the tool can act on the approver's behalf. All of these ids follow one rule: they are recorded only when the trace policy records both inputs and outputs and the conversation is public or running in development. Otherwise only the type is recorded.
356
+ ### Request kinds
270
357
 
271
- A `defineTool` tool can still act on the approver's behalf when it chooses to. While an approved `defineTool` call runs, `ctx.approval.responder` is the principal who approved it, and `ctx.approval.responder.getToken(provider)` resolves that person's token for an inline provider, as `ctx.getToken(provider)` does for the requester. `ctx.session.auth.current` stays the requester. `ctx.approval` is absent for calls that needed no approval, and workflow tools don't receive it. `ctx.approval.responder.getToken(provider)` never starts a sign-in: when the approver has no token, it throws a `ConnectionAuthorizationFailedError` with `reason: "approver_authorization_required"`. A connection's `headers` and `toolCall.providedArguments` callbacks receive the same `ctx.approval.responder` while an approved connection call runs; see [Send the approver to the server](/docs/connections#send-the-approver-to-the-server).
358
+ On the stream, each request's `request.kind` is `approval`, `question`, `budget`, or `sign-in`. Its `subject` names the call, task, or turn that the request is about. Clients read the same `request.kind` on an `Interaction` to choose behavior and display. Keep a default branch, because a later release can add a kind.
272
359
 
273
- ```ts
274
- export default defineTool({
275
- description: "Grant the requester access to a repository.",
276
- inputSchema: z.object({ repo: z.string() }),
277
- approval: {
278
- request: always(),
279
- response: ({ response }) =>
280
- itAdmins.includes(response.principal.principalId)
281
- ? { status: "allowed" }
282
- : { status: "rejected" },
283
- },
284
- async execute({ repo }, ctx) {
285
- const admin = await ctx.approval?.responder.getToken(github);
286
- if (admin === undefined) throw new Error("An IT admin must approve this grant.");
287
- return await grantAccess(repo, ctx.session.auth.current, admin.token);
288
- },
289
- });
290
- ```
360
+ `interactionId` identifies the request to answer, and `call.callId`, when present, identifies its call. Neither ID encodes what the request means.
291
361
 
292
- For approval requests, a follow-up message that doesn't match an option steers the turn instead of answering it. eve withdraws every approval nobody has answered: each interaction settles `withdrawn`, its call settles `rejected` without running, and the model reads the message next. This happens even when the message is sent with `turnPolicy: "queue"`, because a turn held on a person can't end until they act. Approvals that already have an answer settle on it, so calls the person already approved still run. A message from someone other than the person the turn serves waits until the turn ends. Cancelling the turn interrupts its approval: the call doesn't run, the interaction settles `interrupted`, and a later answer to it approves nothing.
362
+ ### Requests from subagents
293
363
 
294
- ### Several requests at once
295
-
296
- A turn can wait on more than one request, such as two `ctx.ask()` questions a workflow tool asks with `Promise.all`, or approvals for two tool calls the model made in one step. A follow-up message answers only the first open request: a [runtime limit](/docs/agent-config#runtime-limits) continuation prompt if one is open, and otherwise the request eve asked for first, in the order of its `interaction.opened` facts.
364
+ When a subagent asks for input, its parent session passes the request on as its own `interaction.opened` event. `origin` names the child session and request, and `origin.call` names the child's call. Answer through the parent session. The answer goes straight to the waiting child, without calling the parent model.
297
365
 
298
- The message answers that request when it matches one of its options, or when the request accepts free text. Otherwise the message is not an answer and follows the rules above. To answer several requests by text, send one message per request.
366
+ A message from the parent agent never answers a subagent's tool approval or session-limit request, even when its text matches an option. Only a person's structured answer, sent through the parent session, answers these requests. The subagent receives the parent's message as an ordinary message:
299
367
 
300
- An approval for a tool call made in the same step as a workflow tool call, such as `ask_question`, is not requested until the workflow tool call finishes, because the approved call can't run before then. The person answers the question first, then sees the approval.
368
+ - The message steers the turn past a waiting approval, which ends as `withdrawn`.
369
+ - The message waits behind a session-limit request until a person answers that request.
301
370
 
302
- Channels that show only text show one request at a time, in this order, and post the next once the current one is answered, so a reply answers the request the person sees. Twilio, GitHub, Linear, and Chat SDK channels work this way. Chat SDK can't tell whether an adapter shows buttons, so every Chat SDK channel shows requests one at a time, including Linq, Photon, and adapters with buttons. Native channels with buttons, such as Slack, show every open request so a person can press any of them, and a typed reply still answers the first. A Slack app that sets `onInputResponse` or `approvalChannel` takes answers only through its controls; see [Restrict who can invoke the agent](/docs/channels/slack#restrict-who-can-invoke-the-agent).
371
+ ### Several requests at once
303
372
 
304
- See [Sessions, runs & streaming](/docs/concepts/sessions-runs-and-streaming) for the full event and resume contract that this builds on.
373
+ A turn can wait on more than one request. Examples are two `ctx.ask()` questions from `Promise.all` in a workflow tool, or approvals for two tool calls from one step. A follow-up message answers only the first open request:
305
374
 
306
- ## Answering from a client or channel
375
+ 1. A [runtime limit](/docs/agent-config#runtime-limits) continuation prompt, if one is open.
376
+ 2. Otherwise, the oldest request, in the order of its `interaction.opened` events.
307
377
 
308
- Channels turn requests into native UI: the Slack adapter renders approvals as buttons and questions as select menus, and writes the user's choice back as the answer. You get this for free on every [channel](/docs/channels/overview).
378
+ The message answers that request when it matches one of its options or the request accepts free text. Otherwise, it follows the rules in [Follow-up messages](#follow-up-messages). To answer several requests by text, send one message per request.
309
379
 
310
- In your own frontend, use `openInteractions(view)` and `respond([{ interactionId, optionId }])` on the same session. See [Building a frontend](/docs/guides/frontend/overview#human-in-the-loop-prompts).
380
+ When one step calls both a workflow tool, such as `ask_question`, and an approval-gated tool, the question comes first. eve asks for the approval after the workflow tool call finishes.
311
381
 
312
- You can answer while other work runs. An interaction stays `open` until `interaction.settled`; the frontend example shows how to query pending prompts.
382
+ Text-only channels show one request at a time, in this order, so a reply answers the request the person sees. These are Twilio, GitHub, Linear, and all Chat SDK channels. Chat SDK can't tell whether an adapter shows buttons, so this includes Linq, Photon, and adapters with buttons. Native channels with buttons, such as Slack, show every open request, and a typed reply still answers the first. A Slack app that sets `onAnswers` or `approvalChannel` accepts answers only through its controls; see [Restrict who can invoke the agent](/docs/channels/slack#restrict-who-can-invoke-the-agent).
313
383
 
314
384
  ## What to read next
315
385
 
@@ -1,5 +1,5 @@
1
1
  {
2
2
  "title": "Tools",
3
3
  "defaultOpen": false,
4
- "pages": ["overview", "human-in-the-loop", "workflows", "tasks", "tasks-upgrade"]
4
+ "pages": ["overview", "human-in-the-loop", "workflows", "tasks"]
5
5
  }