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.
- package/CHANGELOG.md +34 -23
- package/dist/src/channel/auth/http-basic.js +1 -1
- package/dist/src/channel/channel-operations.d.ts +1 -1
- package/dist/src/channel/types.d.ts +2 -0
- package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
- package/dist/src/client/session.d.ts +1 -1
- package/dist/src/compiled/.vendor-stamp.json +1 -1
- package/dist/src/execution/dynamic-workflow/tool.js +1 -1
- package/dist/src/execution/proxied-deliver-step.js +1 -1
- package/dist/src/execution/sandbox/bash.js +2 -2
- package/dist/src/execution/session/active-turn.js +1 -1
- package/dist/src/execution/session/admission.d.ts +6 -0
- package/dist/src/execution/session/admission.js +1 -1
- package/dist/src/execution/session/delivery-facts.js +1 -1
- package/dist/src/execution/session/next-input.d.ts +2 -2
- package/dist/src/execution/session/next-input.js +1 -1
- package/dist/src/execution/session/program.js +1 -1
- package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
- package/dist/src/execution/session-inbox/inbox.js +1 -1
- package/dist/src/execution/session-inbox/protocol.js +1 -1
- package/dist/src/execution/tools/agent-router-workflow.js +1 -1
- package/dist/src/harness/compaction/engine.js +2 -2
- package/dist/src/harness/current-messages.js +1 -1
- package/dist/src/harness/emission.d.ts +3 -0
- package/dist/src/harness/emission.js +1 -1
- package/dist/src/harness/facts.d.ts +5 -2
- package/dist/src/harness/facts.js +1 -1
- package/dist/src/harness/model-call/call.d.ts +7 -1
- package/dist/src/harness/model-call/call.js +3 -1
- package/dist/src/harness/provider-tool-history.d.ts +8 -0
- package/dist/src/harness/provider-tool-history.js +1 -1
- package/dist/src/harness/session-machine/transitions.d.ts +3 -2
- package/dist/src/harness/step/after-model.js +1 -1
- package/dist/src/harness/step/context.js +1 -1
- package/dist/src/harness/step/intake.js +1 -1
- package/dist/src/harness/step/prompt.js +1 -1
- package/dist/src/harness/tool-history-repair.d.ts +2 -0
- package/dist/src/harness/tool-history-repair.js +1 -1
- package/dist/src/harness/tool-loop.js +1 -1
- package/dist/src/internal/application/stamped-package-version.js +1 -1
- package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
- package/dist/src/protocol/session-events/families/delivery.js +1 -1
- package/dist/src/protocol/session-projection/fold.js +1 -1
- package/dist/src/public/channels/discord/hitl.js +1 -1
- package/dist/src/public/channels/slack/hitl.d.ts +2 -1
- package/dist/src/public/channels/slack/hitl.js +3 -3
- package/dist/src/public/channels/slack/interaction-cards.js +1 -1
- package/dist/src/public/channels/slack/request-card-render.js +1 -1
- package/dist/src/public/channels/teams/hitl.js +1 -1
- package/dist/src/public/channels/teams/verify.js +1 -1
- package/dist/src/public/definitions/hook.d.ts +90 -7
- package/dist/src/public/definitions/hook.js +1 -1
- package/dist/src/public/hooks/index.d.ts +3 -2
- package/dist/src/reactions/continuation.d.ts +19 -0
- package/dist/src/reactions/continuation.js +1 -0
- package/dist/src/reactions/intents.d.ts +10 -4
- package/dist/src/reactions/intents.js +1 -1
- package/dist/src/reactions/kinds/hook.js +1 -1
- package/dist/src/reactions/runner.js +1 -1
- package/dist/src/reactions/state.d.ts +15 -2
- package/dist/src/reactions/state.js +1 -1
- package/dist/src/runtime/resolve-connection.js +1 -1
- package/dist/src/runtime/subagents/workflow.js +1 -1
- package/dist/src/setup/primitives/open-url.js +1 -1
- package/dist/src/setup/scaffold/create/project.js +1 -1
- package/dist/src/shared/value-delta.d.ts +5 -4
- package/dist/src/shared/value-delta.js +1 -1
- package/dist/src/tools/provided/ask-question-workflow.js +1 -1
- package/dist/src/tools/provided/sleep-workflow.js +1 -1
- package/dist/src/tools/provided/web-fetch.js +1 -1
- package/docs/agent-config.md +199 -222
- package/docs/channels/chat-sdk.mdx +60 -64
- package/docs/channels/custom.mdx +264 -281
- package/docs/channels/discord.mdx +176 -123
- package/docs/channels/eve.mdx +136 -206
- package/docs/channels/github.mdx +24 -22
- package/docs/channels/linear.mdx +30 -30
- package/docs/channels/linq.mdx +25 -13
- package/docs/channels/mcp.mdx +154 -116
- package/docs/channels/overview.mdx +31 -32
- package/docs/channels/photon.mdx +32 -56
- package/docs/channels/slack.mdx +538 -375
- package/docs/channels/teams.mdx +40 -26
- package/docs/channels/telegram.mdx +13 -13
- package/docs/channels/twilio.mdx +11 -11
- package/docs/code-extension.mdx +40 -42
- package/docs/concepts/built-in-tools.md +89 -57
- package/docs/concepts/context-control.md +20 -20
- package/docs/concepts/default-harness.md +20 -36
- package/docs/concepts/execution-model-and-durability.mdx +96 -160
- package/docs/concepts/project-structure.mdx +21 -14
- package/docs/concepts/security-model.md +27 -27
- package/docs/concepts/sessions-runs-and-streaming.md +184 -198
- package/docs/concepts/state.md +7 -15
- package/docs/connections/mcp.mdx +109 -93
- package/docs/connections/openapi.mdx +57 -59
- package/docs/connections/overview.mdx +175 -170
- package/docs/evals/assertions.mdx +36 -29
- package/docs/evals/cases.mdx +38 -42
- package/docs/evals/judge.mdx +21 -29
- package/docs/evals/overview.mdx +42 -38
- package/docs/evals/reporters.mdx +54 -27
- package/docs/evals/running.mdx +15 -8
- package/docs/evals/targets.mdx +16 -19
- package/docs/evals/tool-stubs.mdx +111 -97
- package/docs/experimental/dynamic-schedules.mdx +118 -63
- package/docs/extensions.md +58 -65
- package/docs/getting-started.mdx +4 -6
- package/docs/guides/auth-and-route-protection.md +87 -70
- package/docs/guides/client/continuations.mdx +23 -26
- package/docs/guides/client/messages.mdx +47 -66
- package/docs/guides/client/output-schema.mdx +8 -8
- package/docs/guides/client/overview.mdx +45 -43
- package/docs/guides/client/streaming.mdx +62 -71
- package/docs/guides/decide.md +24 -79
- package/docs/guides/deployment/meta.json +1 -1
- package/docs/guides/deployment/overview.md +27 -18
- package/docs/guides/deployment/self-hosted-operations.md +99 -0
- package/docs/guides/deployment/self-hosting.md +63 -80
- package/docs/guides/deployment/vercel.mdx +31 -27
- package/docs/guides/deployment/workflow-worlds.md +100 -0
- package/docs/guides/dev-tui.md +48 -41
- package/docs/guides/dynamic-capabilities.md +49 -50
- package/docs/guides/frontend/nextjs.mdx +2 -2
- package/docs/guides/frontend/nuxt.mdx +11 -11
- package/docs/guides/frontend/overview.mdx +1 -1
- package/docs/guides/frontend/sveltekit.mdx +11 -11
- package/docs/guides/frontend/tanstack.mdx +16 -16
- package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
- package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
- package/docs/guides/frontend/use-eve-agent.mdx +25 -25
- package/docs/guides/hooks.md +152 -106
- package/docs/guides/instrumentation/agent-runs.mdx +26 -30
- package/docs/guides/instrumentation/instrumentation.mdx +49 -76
- package/docs/guides/instrumentation/meta.json +1 -1
- package/docs/guides/instrumentation/otel.mdx +113 -179
- package/docs/guides/remote-agents.md +125 -187
- package/docs/guides/self-modification.md +18 -18
- package/docs/guides/session-context.md +16 -16
- package/docs/install-integrations.mdx +26 -24
- package/docs/instructions.mdx +37 -42
- package/docs/memory/custom-provider.md +35 -41
- package/docs/memory/file.md +93 -76
- package/docs/memory/overview.mdx +145 -156
- package/docs/patterns/durable-cross-channel-notifications.md +15 -19
- package/docs/patterns/dynamic-scheduling.md +19 -23
- package/docs/patterns/multi-tenant-approvals.md +17 -22
- package/docs/patterns/multi-tenant-auth.md +43 -42
- package/docs/patterns/multi-tenant-memory.md +39 -36
- package/docs/patterns/voice-notes.md +3 -3
- package/docs/protocols/acp.md +13 -13
- package/docs/protocols/ucp.mdx +7 -7
- package/docs/reference/agent-files.md +6 -6
- package/docs/reference/cli.md +99 -98
- package/docs/reference/telemetry.md +1 -1
- package/docs/reference/typescript-api.md +52 -53
- package/docs/responsible-use.md +2 -2
- package/docs/sandbox/custom-providers.mdx +60 -56
- package/docs/sandbox/default.mdx +23 -24
- package/docs/sandbox/docker.mdx +16 -10
- package/docs/sandbox/index.mdx +93 -61
- package/docs/sandbox/just-bash.mdx +17 -11
- package/docs/sandbox/troubleshooting.mdx +29 -23
- package/docs/sandbox/vercel.mdx +45 -52
- package/docs/schedules.mdx +65 -54
- package/docs/skills.mdx +74 -49
- package/docs/subagents/index.mdx +97 -136
- package/docs/tools/human-in-the-loop.md +160 -90
- package/docs/tools/meta.json +1 -1
- package/docs/tools/overview.mdx +229 -237
- package/docs/tools/tasks.md +118 -117
- package/docs/tools/workflows.mdx +447 -543
- package/docs/tutorial/connect-a-warehouse.mdx +11 -13
- package/docs/tutorial/first-agent.mdx +14 -16
- package/docs/tutorial/guard-the-spend.mdx +6 -8
- package/docs/tutorial/how-it-runs.mdx +8 -8
- package/docs/tutorial/query-sample-data.mdx +8 -8
- package/docs/tutorial/remember-definitions.mdx +4 -4
- package/docs/tutorial/run-analysis.mdx +20 -22
- package/docs/tutorial/ship-it.mdx +19 -19
- package/docs/tutorial/team-playbooks.mdx +9 -9
- package/docs/use-cases.mdx +13 -11
- package/package.json +1 -1
- package/docs/guides/instrumentation/migration.md +0 -96
- 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
|
|
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
|
|
10
|
-
- **Questions
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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()`
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
73
|
+
### Customize the approval prompt
|
|
68
74
|
|
|
69
|
-
Use the object form of `approval` to replace the default `Approve <tool label>?` text
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
151
|
-
- `response`: the submitted `decision
|
|
152
|
-
- `session`: read-only
|
|
153
|
-
- `auth`:
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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`
|
|
247
|
-
3. The
|
|
248
|
-
4. The client answers with `answers
|
|
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
|
|
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
|
-
|
|
342
|
+
Cancelling the turn ends its approvals as `interrupted`. The call doesn't run, and a later answer approves nothing.
|
|
253
343
|
|
|
254
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
356
|
+
### Request kinds
|
|
270
357
|
|
|
271
|
-
|
|
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
|
-
|
|
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
|
-
|
|
362
|
+
### Requests from subagents
|
|
293
363
|
|
|
294
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
371
|
+
### Several requests at once
|
|
303
372
|
|
|
304
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
package/docs/tools/meta.json
CHANGED