eve 0.89.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 +39 -9
- package/dist/src/channel/adapter.d.ts +12 -3
- package/dist/src/channel/adapter.js +1 -1
- package/dist/src/channel/auth/definitions.d.ts +7 -20
- package/dist/src/channel/auth/definitions.js +1 -1
- package/dist/src/channel/auth/http-basic.js +1 -1
- package/dist/src/channel/auth/jwt-ecdsa.js +1 -1
- package/dist/src/channel/auth/jwt-hmac.js +1 -1
- package/dist/src/channel/auth/oidc.js +1 -1
- package/dist/src/channel/auth/result.d.ts +2 -3
- package/dist/src/channel/auth/result.js +1 -1
- package/dist/src/channel/channel-address.d.ts +1 -1
- package/dist/src/channel/channel-address.js +1 -1
- package/dist/src/channel/channel-operations.d.ts +1 -1
- package/dist/src/channel/schedule.js +1 -1
- package/dist/src/channel/types.d.ts +2 -0
- package/dist/src/chunks/{use-eve-agent-Bbl4H5aA.js → use-eve-agent-Bwloorf8.js} +77 -63
- package/dist/src/chunks/{use-eve-agent-CNpxgKEH.js → use-eve-agent-XCB0-tLX.js} +77 -63
- package/dist/src/cli/dev/environment.js +1 -1
- package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
- package/dist/src/cli/dev/tui/remote-connection-probe.js +1 -1
- package/dist/src/cli/dev/tui/remote-connection-types.d.ts +1 -0
- package/dist/src/cli/dev/tui/runner.js +2 -2
- package/dist/src/cli/dev/tui/status-line.d.ts +2 -2
- package/dist/src/cli/dev/tui/status-line.js +1 -1
- package/dist/src/client/agent-info-schema.d.ts +341 -326
- package/dist/src/client/agent-info-schema.js +1 -1
- package/dist/src/client/agent-info-types.d.ts +13 -10
- package/dist/src/client/client-error.d.ts +1 -1
- package/dist/src/client/client.d.ts +5 -3
- package/dist/src/client/client.js +1 -1
- package/dist/src/client/session.d.ts +1 -1
- package/dist/src/compiled/.vendor-stamp.json +1 -1
- package/dist/src/evals/target.js +1 -1
- package/dist/src/eve-channel/auth.d.ts +19 -0
- package/dist/src/eve-channel/auth.js +1 -0
- package/dist/src/eve-channel/index.d.ts +1 -0
- package/dist/src/eve-channel/index.js +1 -1
- package/dist/src/eve-channel/types.d.ts +23 -4
- package/dist/src/execution/catalog/connection-entry.js +1 -1
- package/dist/src/execution/coordination-dispatch-shared.js +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/internal/authored-module-graph.js +1 -1
- package/dist/src/internal/nitro/routes/agent-info/build-agent-info-response.d.ts +2 -2
- package/dist/src/protocol/routes.d.ts +7 -1
- package/dist/src/protocol/routes.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/github/githubChannel.js +1 -1
- package/dist/src/public/channels/github/state.d.ts +7 -0
- package/dist/src/public/channels/github/state.js +1 -1
- package/dist/src/public/channels/mcp.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/channels/telegram/telegramChannel.js +1 -1
- package/dist/src/public/connections/index.d.ts +1 -1
- package/dist/src/public/definitions/channel.js +1 -1
- package/dist/src/public/definitions/connections/tool-call.d.ts +2 -2
- 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/frame.js +1 -1
- 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/channels/registry.d.ts +2 -2
- package/dist/src/runtime/channels/registry.js +1 -1
- package/dist/src/runtime/connections/approval-scope.d.ts +9 -0
- package/dist/src/runtime/connections/approval-scope.js +1 -0
- package/dist/src/runtime/connections/mcp-client.d.ts +1 -1
- package/dist/src/runtime/connections/mcp-client.js +1 -1
- package/dist/src/runtime/connections/provided-arguments.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/agent-info-access.d.ts +5 -0
- package/dist/src/shared/agent-info-access.js +1 -0
- package/dist/src/shared/connection-types.d.ts +21 -4
- package/dist/src/shared/value-delta.d.ts +5 -4
- package/dist/src/shared/value-delta.js +1 -1
- package/dist/src/svelte/index.js +1 -1
- package/dist/src/svelte/use-eve-agent.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/dist/src/vue/index.js +1 -1
- package/dist/src/vue/use-eve-agent.js +1 -1
- package/docs/agent-config.md +199 -222
- package/docs/channels/chat-sdk.mdx +60 -64
- package/docs/channels/custom.mdx +265 -280
- package/docs/channels/discord.mdx +176 -123
- package/docs/channels/eve.mdx +136 -204
- 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 -194
- 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 +205 -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 +17 -18
- 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 +100 -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 +47 -41
- 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/prepare-for-1-0.md +23 -1
- 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
package/docs/guides/hooks.md
CHANGED
|
@@ -3,7 +3,7 @@ title: "Hooks"
|
|
|
3
3
|
description: "Subscribe to runtime stream events from agent/hooks/."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
|
|
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
|
|
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
|
-
`
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
99
|
-
|
|
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
|
|
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`
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
203
|
+
The event's other handlers still run. Then eve cancels the turn as [`session.cancel()`](./client/streaming) does:
|
|
253
204
|
|
|
254
|
-
|
|
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
|
-
|
|
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
|
-
|
|
211
|
+
Rules for `ctx.cancel()`:
|
|
259
212
|
|
|
260
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
271
|
-
|
|
|
272
|
-
|
|
|
273
|
-
|
|
|
274
|
-
|
|
|
275
|
-
|
|
|
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
|
-
|
|
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
|
-
|
|
15
|
-
in the project's **Observability** view. The tab
|
|
16
|
-
Vercel team
|
|
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.
|
|
26
|
-
|
|
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,
|
|
36
|
+
requests, set its rate to 100% instead of adding a later rule.
|
|
38
37
|
|
|
39
|
-
Tracing starts
|
|
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
|
|
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
|
-
|
|
46
|
-
for each
|
|
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`.
|
|
54
|
-
|
|
55
|
-
`/.well-known/eve/v1/schedules/consumer`.
|
|
56
|
-
incomplete. The workflow prefix also
|
|
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
|
|
70
|
-
|
|
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
|
-
|
|
84
|
-
`{
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
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
|
-
|
|
94
|
-
|
|
95
|
-
|
|
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
|
|
111
|
-
Runs
|
|
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`.
|