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/channels/custom.mdx
CHANGED
|
@@ -3,19 +3,46 @@ title: "Custom Channels"
|
|
|
3
3
|
description: "Author custom HTTP and WebSocket channels with routes, events, metadata, continuation tokens, and file uploads."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
A custom channel connects your own HTTP or WebSocket endpoint to your agent. Each one is a file under `agent/channels/` that default-exports `defineChannel(...)` from `eve/channels`. Use one for an internal webhook, a WebSocket client, or a platform eve has no channel for. A custom channel can host a conversation or pass incoming events to another channel.
|
|
7
7
|
|
|
8
8
|
## File location and identity
|
|
9
9
|
|
|
10
|
-
Custom channels live in `agent/channels/` at the root agent or in an [extension](../extensions) mounted there. Local subagents
|
|
10
|
+
Custom channels live in `agent/channels/` at the root agent or in an [extension](../extensions) mounted there. Local subagents don't declare channels.
|
|
11
11
|
|
|
12
|
-
The
|
|
13
|
-
|
|
14
|
-
Hooks, instrumentation, and `delivery.admitted.data.source.channel` identify an authored channel as `channel:<name>`, including channels that only declare routes. Use `isChannel(ctx.channel, importedChannel)` from `eve/channels` to match a channel in a hook.
|
|
12
|
+
The file stem is the channel id, so `agent/channels/internal-webhook.ts` is addressed as `internal-webhook`. Hooks, instrumentation, and `delivery.admitted.data.source.channel` identify it as `channel:<name>`, including channels that only declare routes. Use `isChannel(ctx.channel, importedChannel)` from `eve/channels` to match a channel in a hook.
|
|
15
13
|
|
|
16
14
|
## Define a channel
|
|
17
15
|
|
|
18
|
-
|
|
16
|
+
Declare routes, and pass the platform's conversation ID to `from(...)` in each one. A message to a new ID starts a session; later messages to the same ID continue it:
|
|
17
|
+
|
|
18
|
+
```ts title="agent/channels/support.ts"
|
|
19
|
+
import { defineChannel, POST } from "eve/channels";
|
|
20
|
+
|
|
21
|
+
export default defineChannel({
|
|
22
|
+
routes: [
|
|
23
|
+
// required: one or more routes; the path is the app URL, with no channel prefix
|
|
24
|
+
POST("/threads/:threadId/messages", async (request, { from, params }) => {
|
|
25
|
+
const body = await request.json();
|
|
26
|
+
// from(address) names the conversation; the same address reaches the same session
|
|
27
|
+
const delivery = await from(params.threadId).send(body.message, { auth: null });
|
|
28
|
+
return Response.json(delivery, { status: 202 });
|
|
29
|
+
}),
|
|
30
|
+
],
|
|
31
|
+
});
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
A route's `path` is its app URL, without a channel-name prefix. The route above answers at `POST /threads/:threadId/messages`, not `/support/threads/:threadId/messages`. Give each route a unique method and path outside `/eve/v1/*`, which eve reserves.
|
|
35
|
+
|
|
36
|
+
Each route handler receives:
|
|
37
|
+
|
|
38
|
+
- `from(address)` binds `send`, `respond`, `cancel`, `compact`, `clear`, and `end` to an address: your channel's ID for one conversation, such as a thread ID. See [Continuation tokens](#continuation-tokens).
|
|
39
|
+
- `resolveSession(address)` returns the session that currently uses an address.
|
|
40
|
+
- `attachSession(sessionId)` returns a handle for one session ID, without a lookup.
|
|
41
|
+
- `to(channel, target).send(message, options)` hands work to another authored channel.
|
|
42
|
+
- `params`, `waitUntil`, and `requestIp` provide request metadata and lifetime control.
|
|
43
|
+
- `describe()`, `invokeTool()`, `listSkillFiles()`, and `readSkill()` describe the agent and run its tools without a conversation. See [Describe the agent and run tools directly](#describe-the-agent-and-run-tools-directly).
|
|
44
|
+
|
|
45
|
+
This fuller version adds commands, a stream route, and an event handler:
|
|
19
46
|
|
|
20
47
|
```ts title="agent/channels/support.ts"
|
|
21
48
|
import { defineChannel, GET, POST } from "eve/channels";
|
|
@@ -78,46 +105,40 @@ export default defineChannel({
|
|
|
78
105
|
});
|
|
79
106
|
```
|
|
80
107
|
|
|
81
|
-
|
|
108
|
+
Event handlers receive `(event, ctx)`. The event has `type`, `data`, and `scope` (the turn or call it belongs to). Handlers run after eve records the event, so they can't change it.
|
|
82
109
|
|
|
83
|
-
|
|
110
|
+
- `ctx.session.id` identifies the session.
|
|
111
|
+
- `ctx.position` locates the event on the stream, and `ctx.view` is a read-only snapshot of the session at that point.
|
|
112
|
+
- `ctx.channel` is the channel's own context. `ctx.channel.continuation.token` is the address that `from()`, `resolveSession()`, and `alias()` accept, without eve's prefixes. `alias()` adds another address.
|
|
84
113
|
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
114
|
+
One stream line can hold several events. Use `committed(line, ctx)` to update a status or card once per line instead of once per event. It runs after the line's event handlers, with `line.facts`, `line.position`, and the line's snapshot at `ctx.view`.
|
|
115
|
+
|
|
116
|
+
Handle `interaction.settled` to remove a question or approval you posted once it ends, whether it was answered, withdrawn, or interrupted. Match by `interactionId` and check its `outcome`.
|
|
117
|
+
|
|
118
|
+
### Describe the agent and run tools directly
|
|
119
|
+
|
|
120
|
+
A route handler can also describe the agent and run its tools without a conversation, as the [MCP channel](./mcp) does:
|
|
92
121
|
|
|
93
|
-
|
|
122
|
+
- `describe()` returns the agent's name and description, the tools a caller can run outside a turn, and the agent's skills. Tools carry their JSON schemas, skills carry `name` and `description`, and both are sorted by name.
|
|
123
|
+
- `invokeTool(name, input, { auth, key })` runs one of those tools as `auth` outside any conversation.
|
|
124
|
+
- `listSkillFiles(skill)` resolves to the skill's regular files, each with its `path` under the skill root and `size` in bytes, sorted by path. It rejects a skill the agent doesn't have.
|
|
125
|
+
- `readSkill(skill, path?)` resolves to one skill file's raw bytes as a `Uint8Array`; decode text yourself, for example with `new TextDecoder().decode(bytes)`. `path` is relative to the skill root, such as `references/api.md`; omit it to read `SKILL.md`. It rejects absolute paths, paths with `.`, `..`, or empty segments, files the skill doesn't list, and files over 512 KiB.
|
|
94
126
|
|
|
95
|
-
|
|
96
|
-
- `readSkill(skill, path?)` resolves to one skill file's raw bytes as a `Uint8Array`; decode text yourself, for example with `new TextDecoder().decode(bytes)`. `path` is relative to the skill root, such as `references/api.md`, and defaults to the skill's `SKILL.md`. It rejects absolute paths, paths with `.`, `..`, or empty segments, files the skill does not list, and files over 512 KiB.
|
|
127
|
+
`describe()` carries no skill file contents, paths, config, or inspection detail, so a channel can publish it to callers. It leaves out tools that need a turn: framework tools, workflow and provider tools, and tools without `execute`. It also leaves out tools and skills that dynamic resolvers or subagents add.
|
|
97
128
|
|
|
98
|
-
|
|
99
|
-
`scope`, and a context. `ctx.session.id` identifies the exact session, `ctx.position`
|
|
100
|
-
and `ctx.view` locate the fact on the stream and expose an opaque snapshot of its whole commit,
|
|
101
|
-
and `ctx.channel` is the channel's own context. `ctx.channel.continuation` exposes the
|
|
102
|
-
current address and `alias()` when this channel needs to add another address. Handlers
|
|
103
|
-
run after the line is written, so they observe facts and never shape them.
|
|
129
|
+
`invokeTool()` runs no model, turn, or workflow run. Authored state starts from its initial value and isn't kept. It returns one of these outcomes:
|
|
104
130
|
|
|
105
|
-
|
|
131
|
+
- `"completed"` with output.
|
|
132
|
+
- `"failed"` with an error, including for invalid input.
|
|
133
|
+
- `"rejected"` with a reason, including for approval or sign-in requirements, because a direct call can't pause for a person.
|
|
106
134
|
|
|
107
|
-
|
|
135
|
+
Omit `key` to give each call its own session and delete any sandbox the tool opens when the call ends. Pass a `key` of 1 to 512 characters to share a session ID and sandbox across calls from the same `auth` identity. Keyed calls need Vercel Sandbox, just-bash, or a custom provider that sets `toolSessions: true`. They also need an authenticated `auth`; a keyed call without one is `denied`. See [MCP tool sessions](./mcp#tool-sessions). When a trusted forwarder passes `auth` for someone else, pass the forwarder identity your route verified as `forwardedBy`. It's part of the session, so one user reached through two forwarders gets two sessions.
|
|
108
136
|
|
|
109
|
-
`
|
|
110
|
-
`from()`, `resolveSession()`, and `alias()`. Framework namespace prefixes are not
|
|
111
|
-
part of the authored channel API.
|
|
137
|
+
A direct call doesn't go through the AI SDK. AI SDK telemetry integrations registered with `registerTelemetry()` from `ai` in an `agent/instrumentation/*.ts` module receive `onToolExecutionStart` and `onToolExecutionEnd` only for conversation tool calls. eve traces a direct call itself, with an `execute_tool` span under the caller's trace. Instrumentation also receives `call.requested` and `call.settled`. Over MCP, the caller's trace comes from the request's `_meta` trace context (see [Trace context](./mcp#trace-context)).
|
|
112
138
|
|
|
113
139
|
## Channel operations and session handles
|
|
114
140
|
|
|
115
|
-
Channel operations
|
|
116
|
-
owns the address. `create()` and `send()` can create a session when the address is unowned.
|
|
117
|
-
Without an [idempotency key](#retried-deliveries), a new session's handle can
|
|
118
|
-
return before it claims the address. If another send wins the address, eve
|
|
119
|
-
forwards the message to that session. Call `resolveSession(address)` after
|
|
120
|
-
startup to get the winning session's handle.
|
|
141
|
+
Channel operations reach whichever session currently uses the address. `create()` and `send()` create a session when no session uses it. Without an [idempotency key](#retried-deliveries), a new session's handle can return before the session takes the address. If another send takes it first, eve forwards the message to that session. Call `resolveSession(address)` after startup to get the handle of the session that won.
|
|
121
142
|
|
|
122
143
|
```ts
|
|
123
144
|
const source = from(threadId);
|
|
@@ -133,21 +154,11 @@ await source.end({ reason: "Start over" });
|
|
|
133
154
|
const currentSession = await resolveSession(threadId);
|
|
134
155
|
```
|
|
135
156
|
|
|
136
|
-
When the session at an address is
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
produce one fresh session. A `respond()` call, or a `deliver()` that includes input responses,
|
|
142
|
-
carries answers a fresh session has no request for, so it throws `SessionStrandedError` and leaves
|
|
143
|
-
the stranded session in place.
|
|
144
|
-
|
|
145
|
-
`Session` from `eve/sessions` is fixed: every call targets exactly one durable ID. It never
|
|
146
|
-
creates, follows, or resolves a replacement. Shared `Delivery`, `DeliveryResult`, `SessionReader`,
|
|
147
|
-
stream/read options, and `SessionNotActiveError` also come from `eve/sessions`, not `eve/channels`.
|
|
148
|
-
Accepted commands return reusable deliveries: call `stream({ signal })` for events or
|
|
149
|
-
`result({ signal })` for a settled summary with its `outcome` and failure `error`. Aborting a read
|
|
150
|
-
does not cancel the command or other readers.
|
|
157
|
+
When another eve version built the session at an address, the session is [stranded](../guides/deployment/self-hosted-operations#recover-a-stranded-session). `send()` ends it and starts one fresh session, even for concurrent sends. The message becomes the fresh session's first turn, which can read recent text from the earlier conversation. A `respond()` call, or a `deliver()` with input responses, throws `SessionStrandedError` because a fresh session has no request to answer. The stranded session stays in place.
|
|
158
|
+
|
|
159
|
+
`Session` from `eve/sessions` is fixed to one session ID and never creates, follows, or finds a replacement. `Delivery`, `DeliveryResult`, `SessionReader`, stream and read options, and `SessionNotActiveError` also come from `eve/sessions`, not `eve/channels`.
|
|
160
|
+
|
|
161
|
+
Each accepted operation returns a `Delivery` receipt that you can read more than once. Call `stream({ signal })` for its events, or `result({ signal })` for a summary once it finishes, with its `outcome` and failure `error`. Aborting a read doesn't cancel the operation or other readers.
|
|
151
162
|
|
|
152
163
|
```ts
|
|
153
164
|
const session = attachSession(sessionId);
|
|
@@ -161,15 +172,9 @@ await session.end({ reason: "Retire this session" });
|
|
|
161
172
|
for await (const event of session.stream({ startIndex: 12 })) render(event);
|
|
162
173
|
```
|
|
163
174
|
|
|
164
|
-
A following `
|
|
165
|
-
or its recorded history has expired, so a route can answer with an error status before it sends any
|
|
166
|
-
bytes.
|
|
175
|
+
Attaching does no lookup; the first operation reports whether the ID is active. A following `stream()` rejects on its first read when the session doesn't exist or its history has expired. A route can read once before sending headers, as the example above does, to answer with an error status.
|
|
167
176
|
|
|
168
|
-
For a stranded session, `Session.send()`, `Session.respond()`, and a following
|
|
169
|
-
read through `Session.stream()` throw `SessionStrandedError` from `eve/channels` and deliver nothing.
|
|
170
|
-
`stream({ follow: false })` still reads the recorded history up to the current tail without
|
|
171
|
-
changing the session. `error.owner.eveVersion` names the eve release that built the session when it recorded one. Call
|
|
172
|
-
`end()` to retire the stranded session, then start a new one:
|
|
177
|
+
For a stranded session, `Session.send()`, `Session.respond()`, and a following `Session.stream()` throw `SessionStrandedError` from `eve/channels` and send nothing. `stream({ follow: false })` still reads the recorded history up to the current tail. `error.owner.eveVersion` names the eve release that built the session, when recorded. Call `end()` to retire the stranded session, then start a new one:
|
|
173
178
|
|
|
174
179
|
```ts
|
|
175
180
|
import { SessionStrandedError } from "eve/channels";
|
|
@@ -182,10 +187,7 @@ try {
|
|
|
182
187
|
}
|
|
183
188
|
```
|
|
184
189
|
|
|
185
|
-
`respond()` accepts exact response literals
|
|
186
|
-
been widened to `Answer[]`—for example, after decoding a platform
|
|
187
|
-
payload—validate them with eve's strict schema before delivery. The validated
|
|
188
|
-
type preserves that proof across channel wrappers:
|
|
190
|
+
`respond()` accepts exact response literals. Validate responses already widened to `Answer[]`, for example decoded from a platform payload, with `parseAnswers`; the validated type carries that proof across channel wrappers:
|
|
189
191
|
|
|
190
192
|
```ts
|
|
191
193
|
import { parseAnswers } from "eve/client";
|
|
@@ -194,13 +196,17 @@ const answers = parseAnswers(decodedResponses);
|
|
|
194
196
|
await source.respond(answers, { auth });
|
|
195
197
|
```
|
|
196
198
|
|
|
197
|
-
Message sends use the channel's `turnPolicy`, which defaults to `"steer"
|
|
199
|
+
Message sends use the channel's `turnPolicy`, which defaults to `"steer"`; see [Overlapping messages](./overview#overlapping-messages). A sent message can interrupt the model before your `deliver` hook runs. Filter events before `send(...)` when they should never interrupt the model.
|
|
200
|
+
|
|
201
|
+
Every `send()` and `respond()` passes its `state` option to the channel's `deliver(payload, channel)` hook as `payload.state`, including sends to an existing session. Use it for per-message values such as a message's author. The hook decides what to merge into `channel.state`; eve seeds `channel.state` from `state` only when `send()` creates the session.
|
|
198
202
|
|
|
199
|
-
|
|
203
|
+
The payload is `ChannelDelivery<TState>` from `eve/channels`: `message`, `answers`, `context`, `outputSchema`, and `state?: Partial<TState>`. The hook's return value decides what reaches the session:
|
|
200
204
|
|
|
201
|
-
|
|
205
|
+
- Return nothing to keep it unchanged.
|
|
206
|
+
- Return a replacement with `message`, `answers`, `context`, or `outputSchema` to change it. Other fields, including `state`, are not accepted; change saved state through `channel.state`.
|
|
207
|
+
- Return `{}` to ignore it.
|
|
202
208
|
|
|
203
|
-
The
|
|
209
|
+
The `state` you pass to `defineChannel(...)` is the starting value of every session's `channel.state`, and must be plain JSON-like data. eve restores any top-level field from it that a session's state is missing, so a field you add in a later deploy also appears in existing sessions, including in `context(state)` and event handlers. A field you `delete` comes back the same way; to clear one, set it to `null` or `undefined`. eve doesn't merge nested objects: a saved object replaces the starting object whole.
|
|
204
210
|
|
|
205
211
|
```ts
|
|
206
212
|
import { defineChannel } from "eve/channels";
|
|
@@ -217,7 +223,7 @@ export default defineChannel({
|
|
|
217
223
|
});
|
|
218
224
|
```
|
|
219
225
|
|
|
220
|
-
|
|
226
|
+
Set `turnPolicy: "queue"` on `defineChannel(...)` when messages should wait for the active turn to finish, or override one send:
|
|
221
227
|
|
|
222
228
|
```ts
|
|
223
229
|
export default defineChannel({
|
|
@@ -235,11 +241,23 @@ export default defineChannel({
|
|
|
235
241
|
});
|
|
236
242
|
```
|
|
237
243
|
|
|
238
|
-
The same override
|
|
244
|
+
The same override works on fixed `Session.send(...)` and cross-channel `to(...).send(...)`. `respond(...)` never joins a running turn; it sends only the answers it names. Use `cancel()` to stop work without a replacement message.
|
|
239
245
|
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
246
|
+
## Operation semantics
|
|
247
|
+
|
|
248
|
+
- `cancel` asks the running turn to stop. Confirm it with `turn.settled` and
|
|
249
|
+
`outcome: "cancelled"`; the session accepts another message afterward.
|
|
250
|
+
- `compact` summarizes model context without adding a user message. The stream
|
|
251
|
+
shows `context.started`, then `context.settled` with `kind: "compaction"`.
|
|
252
|
+
- `clear` cancels the running turn and every working task, then removes
|
|
253
|
+
model-message history in place. It keeps the system prompt, skills, tools,
|
|
254
|
+
state, limits, addresses, and session sandbox.
|
|
255
|
+
- `end` ends the current session for good. A later `send()` to the address creates
|
|
256
|
+
a new session; a fixed `Session` handle still points at the ended ID.
|
|
257
|
+
|
|
258
|
+
Control operations never create a session. Unknown or inactive targets throw
|
|
259
|
+
`SessionNotActiveError`. A cancel with nothing to stop ends with `outcome: "ignored"`. Authenticate and deduplicate command webhooks before
|
|
260
|
+
calling `end`, because a delayed duplicate can end a newer session at the same address.
|
|
243
261
|
|
|
244
262
|
## Retried deliveries
|
|
245
263
|
|
|
@@ -253,150 +271,93 @@ const session = await from(conversationId).send(message, {
|
|
|
253
271
|
});
|
|
254
272
|
```
|
|
255
273
|
|
|
256
|
-
Channel and fixed-session `send()` and `respond()`
|
|
257
|
-
as does the Chat SDK bridge. Keys must contain 1–256 characters and identify one
|
|
258
|
-
delivery. Prefix IDs with the provider or event type if they can overlap.
|
|
259
|
-
Reusing a retained key ignores the new input, even if the message changed.
|
|
274
|
+
Channel and fixed-session `send()` and `respond()` accept `idempotencyKey`, as does the Chat SDK bridge. A key has 1–256 characters and identifies one message or answer; prefix IDs with the provider or event type if they can overlap.
|
|
260
275
|
|
|
261
|
-
|
|
276
|
+
Reusing a remembered key ignores the new input, even if the message changed. It returns a new receipt whose result is `ignored`, and doesn't repeat the original reply. Use `result()` to read how a send ended. Each session remembers its last 1,024 keys. An older key runs again, and so does a key reused after the session ends or in another session. All replicas must use the same Workflow World.
|
|
262
277
|
|
|
263
|
-
Await `send()` before acknowledging a webhook when the provider allows it.
|
|
264
|
-
Acknowledging sooner can lose work. This does not make tool calls, outbound
|
|
265
|
-
posts, or work done before `send()` exactly once.
|
|
266
|
-
|
|
267
|
-
## Wrap an existing channel's routes
|
|
278
|
+
Await `send()` before acknowledging a webhook when the provider allows it, because acknowledging sooner can lose work. Keys don't make tool calls, outbound posts, or work done before `send()` exactly once.
|
|
268
279
|
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
The built-in Slack, Teams, and Telegram channels, and the Chat SDK bridge's `send`, hand every inbound message to `from(address).send(message, options)`. A route wrapper that replaces `send` on the source returned by `from(address)` therefore sees each inbound message, and a rejected delivery reaches the wrapper as an error:
|
|
272
|
-
|
|
273
|
-
```ts title="agent/channels/slack.ts"
|
|
274
|
-
import type { RouteHandlerArgs } from "eve/channels";
|
|
275
|
-
import { slackChannel, type SlackChannelState } from "eve/channels/slack";
|
|
276
|
-
|
|
277
|
-
const slack = slackChannel();
|
|
278
|
-
|
|
279
|
-
function reportFailedDeliveries(
|
|
280
|
-
args: RouteHandlerArgs<SlackChannelState>,
|
|
281
|
-
): RouteHandlerArgs<SlackChannelState> {
|
|
282
|
-
return {
|
|
283
|
-
...args,
|
|
284
|
-
from(address) {
|
|
285
|
-
const source = args.from(address);
|
|
286
|
-
return {
|
|
287
|
-
...source,
|
|
288
|
-
async send(message, options) {
|
|
289
|
-
try {
|
|
290
|
-
return await source.send(message, options);
|
|
291
|
-
} catch (error) {
|
|
292
|
-
console.error("Slack delivery failed", { address, error });
|
|
293
|
-
throw error;
|
|
294
|
-
}
|
|
295
|
-
},
|
|
296
|
-
};
|
|
297
|
-
},
|
|
298
|
-
};
|
|
299
|
-
}
|
|
280
|
+
## File uploads
|
|
300
281
|
|
|
301
|
-
|
|
302
|
-
...slack,
|
|
303
|
-
routes: slack.routes.map((route) =>
|
|
304
|
-
route.transport === "websocket"
|
|
305
|
-
? route
|
|
306
|
-
: {
|
|
307
|
-
...route,
|
|
308
|
-
handler: (request: Request, args: RouteHandlerArgs<SlackChannelState>) =>
|
|
309
|
-
route.handler(request, reportFailedDeliveries(args)),
|
|
310
|
-
},
|
|
311
|
-
),
|
|
312
|
-
};
|
|
282
|
+
`from(address).send()` and `Session.send()` accept `MessageContent`: a string, or an array mixing text and file parts:
|
|
313
283
|
|
|
314
|
-
|
|
284
|
+
```ts
|
|
285
|
+
await from(continuationToken).send(
|
|
286
|
+
[
|
|
287
|
+
{ type: "text", text: body.message },
|
|
288
|
+
{ type: "file", data: imageBytes, mediaType: "image/png" },
|
|
289
|
+
],
|
|
290
|
+
{ auth },
|
|
291
|
+
);
|
|
315
292
|
```
|
|
316
293
|
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
## Operation semantics
|
|
320
|
-
|
|
321
|
-
- `cancel` cooperatively stops the active turn. Confirm it with `turn.settled` and
|
|
322
|
-
`outcome: "cancelled"`; the session accepts another message afterward.
|
|
323
|
-
- `compact` summarizes model context without adding a synthetic user message. It
|
|
324
|
-
is a context change: `context.started`, then `context.settled` with
|
|
325
|
-
`kind: "compaction"`.
|
|
326
|
-
- `clear` removes model-message history in place. It preserves the system prompt,
|
|
327
|
-
skills, tools, durable state, limits, address ownership, and session sandbox.
|
|
328
|
-
- `end` terminally retires the current session. A later address `send()` creates
|
|
329
|
-
a fresh session; a fixed `Session` handle remains pinned to the retired ID.
|
|
330
|
-
|
|
331
|
-
Control operations never create a session. Unknown or inactive targets throw
|
|
332
|
-
`SessionNotActiveError`; an accepted no-op cancellation settles with `outcome: "ignored"`. Authenticate and deduplicate command webhooks before
|
|
333
|
-
calling `end`, because a delayed duplicate can retire a newer address owner.
|
|
334
|
-
|
|
335
|
-
## CORS
|
|
336
|
-
|
|
337
|
-
Custom HTTP channels leave CORS untouched unless you opt in. Pass `cors: true`
|
|
338
|
-
for permissive browser access with preflight handling, or pass a serializable
|
|
339
|
-
CORS options object to narrow origins, methods, and headers:
|
|
294
|
+
For files behind authenticated URLs, as on Slack, put a `URL` object in the file part's `data` and declare `fetchFile` on the channel config:
|
|
340
295
|
|
|
341
296
|
```ts
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
allowHeaders: ["authorization", "content-type"],
|
|
297
|
+
defineChannel({
|
|
298
|
+
fetchFile(url) {
|
|
299
|
+
if (!url.startsWith("https://files.slack.com/")) return null;
|
|
300
|
+
return fetch(url, { headers: { authorization: `Bearer ${token}` } })
|
|
301
|
+
.then((r) => r.arrayBuffer())
|
|
302
|
+
.then((b) => ({ bytes: Buffer.from(b) }));
|
|
349
303
|
},
|
|
350
|
-
|
|
304
|
+
|
|
305
|
+
routes: [
|
|
306
|
+
POST("/webhook", async (req, { from }) => {
|
|
307
|
+
await from(continuationToken).send(
|
|
308
|
+
[
|
|
309
|
+
{ type: "text", text: message.text },
|
|
310
|
+
...message.attachments.map((a) => ({
|
|
311
|
+
type: "file" as const,
|
|
312
|
+
data: new URL(a.url),
|
|
313
|
+
mediaType: a.mediaType,
|
|
314
|
+
})),
|
|
315
|
+
],
|
|
316
|
+
{
|
|
317
|
+
auth,
|
|
318
|
+
state,
|
|
319
|
+
},
|
|
320
|
+
);
|
|
321
|
+
}),
|
|
322
|
+
],
|
|
351
323
|
});
|
|
352
324
|
```
|
|
353
325
|
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
Use `WS()` when a custom channel needs a WebSocket endpoint. The route handler runs once per upgrade request and returns lifecycle hooks for that connection:
|
|
326
|
+
If `fetchFile` throws, eve replaces that attachment with a model-visible note and continues the turn. To tell the model why, throw `attachmentError` from `eve/channels`:
|
|
357
327
|
|
|
358
328
|
```ts
|
|
359
|
-
import {
|
|
329
|
+
import { attachmentError } from "eve/channels";
|
|
360
330
|
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
],
|
|
369
|
-
});
|
|
331
|
+
async function fetchUpload(url: string) {
|
|
332
|
+
const response = await fetch(url, { headers: { authorization: `Bearer ${token}` } });
|
|
333
|
+
if (response.status === 413) {
|
|
334
|
+
throw attachmentError("The file is over 100 MB. Ask for a smaller file.");
|
|
335
|
+
}
|
|
336
|
+
return Buffer.from(await response.arrayBuffer());
|
|
337
|
+
}
|
|
370
338
|
```
|
|
371
339
|
|
|
372
|
-
`
|
|
373
|
-
`params`, `waitUntil`, and `requestIp` arguments as HTTP route handlers. The
|
|
374
|
-
returned hooks are eve-owned structural types compatible with Nitro/H3 websocket
|
|
375
|
-
routing, including `upgrade`, `open`, `message`, `close`, and `error`.
|
|
376
|
-
|
|
377
|
-
### Node upgrade server escape hatch
|
|
340
|
+
The model then reads `Attachment report.pdf could not be retrieved: The file is over 100 MB. Ask for a smaller file.` The message reaches the model as written. Keep it to details the person can act on, such as a size limit or a missing permission. Never include URLs, tokens, or upstream response text. Pass the original error as `attachmentError(message, { cause })` to keep it in operator logs. Any other thrown error becomes a generic note, with the original in operator logs.
|
|
378
341
|
|
|
379
|
-
|
|
342
|
+
`fetchFile` receives the URL as a string (its `href`), so the example matches with `url.startsWith(...)`. A string with a URL scheme in `data`, such as `https://...` or `myapp-file:abc`, works the same as a `URL` object. The second argument carries the channel's `state` and the attachment's `session`, so a resolver can check a file against the caller in `session.auth`.
|
|
380
343
|
|
|
381
|
-
|
|
382
|
-
import { defineChannel, WS, createWebSocketUpgradeServer } from "eve/channels";
|
|
344
|
+
Return bytes to save the file to the sandbox. Return `null` for a URL your channel doesn't resolve, and eve downloads a public `https:` URL itself. eve's downloads have these limits:
|
|
383
345
|
|
|
384
|
-
|
|
346
|
+
- 25 MB by default, with a 30-second timeout.
|
|
347
|
+
- No private or reserved addresses.
|
|
348
|
+
- At most 10 URLs per message, fetched one at a time.
|
|
385
349
|
|
|
386
|
-
|
|
350
|
+
Any other URL, or a failed download, reaches the model as a note. The model provider never fetches an attachment, so a link that expires or needs credentials can't fail later model calls.
|
|
387
351
|
|
|
388
|
-
|
|
389
|
-
routes: [WS("/vendor/ws", bridge.route)],
|
|
390
|
-
});
|
|
391
|
-
```
|
|
352
|
+
Set `uploadPolicy` on `defineChannel` to cap what eve saves for the channel, for example `uploadPolicy: { maxBytes: 10 * 1024 * 1024, allowedMediaTypes: ["image/*", "application/pdf"] }`. eve checks every saved file, including its own downloads, by its actual bytes and detected media type. A violating file reaches the model as a note. Omit `uploadPolicy` to rely on your `fetchFile` checks, with eve's own downloads capped at 25 MB.
|
|
392
353
|
|
|
393
|
-
|
|
354
|
+
See [Inbound attachments](../sandbox#inbound-attachments) for the shared storage, size, and provider-input behavior.
|
|
394
355
|
|
|
395
356
|
## Cross-channel hand-off
|
|
396
357
|
|
|
397
|
-
|
|
358
|
+
A cross-channel hand-off starts or resumes a conversation on another channel from a route handler with `ctx.to(channel, target).send(message, { auth })`. The agent runs and replies on the destination channel. The source channel starts no session and returns only its HTTP response.
|
|
398
359
|
|
|
399
|
-
This webhook filters incoming events and asks the agent to investigate in Slack. Import the destination channel's default export; `verifyAndParseEvent` is
|
|
360
|
+
This webhook filters incoming events and asks the agent to investigate in Slack. Import the destination channel's default export; `verifyAndParseEvent` is your own helper.
|
|
400
361
|
|
|
401
362
|
```ts title="agent/channels/intake.ts"
|
|
402
363
|
import { defineChannel, POST } from "eve/channels";
|
|
@@ -436,15 +397,19 @@ Before sending:
|
|
|
436
397
|
- Filter out events that should not reach the agent.
|
|
437
398
|
- Pass the provider's stable event ID as `idempotencyKey`, so a redelivered webhook doesn't deliver the message twice. See [Retried deliveries](#retried-deliveries) for the limits.
|
|
438
399
|
|
|
439
|
-
The supplied `auth` identifies who started the session,
|
|
400
|
+
The supplied `auth` identifies who started the session, and tools and event handlers read it as `session.auth.initiator`.
|
|
401
|
+
|
|
402
|
+
The destination's `receive` hook defines the target fields and how they map to a session; see [Slack proactive sessions](./slack#proactive-sessions) for Slack's. To let people continue the conversation, configure the destination's inbound handlers to accept follow-ups.
|
|
440
403
|
|
|
441
|
-
|
|
404
|
+
`send` takes the same options as `from(address).send()` and `Session.send()`: `auth`, `context`, `history`, `idempotencyKey`, `outputSchema`, `title`, and `turnPolicy`. The destination's `receive` hook gets them with the message and target, and every built-in channel passes them on to the session.
|
|
442
405
|
|
|
443
|
-
|
|
406
|
+
The destination session dedupes keys from every sender. Prefix each key with its source, such as `pagerduty:${event.id}`, so keys stay unique across senders. Two senders that pick the same key reach the same session, and the second message is `ignored`. A Slack target with only a `channelId` uses the key to choose the session, so a retry reaches the same session.
|
|
407
|
+
|
|
408
|
+
A key still dedupes only within that session's remembered keys. A retry after the key is dropped runs another turn. A retry after the session ends starts a new session, which on Slack is a new thread. Work a `receive` hook does before sending also repeats on retry. Examples are posting an `initialMessage` (Slack, Teams, Discord, GitHub, and Telegram) and creating a Linear Agent Session for an `issueId` or `commentId` target.
|
|
444
409
|
|
|
445
410
|
### Write a receive hook
|
|
446
411
|
|
|
447
|
-
A custom channel's `receive` hook maps the target to an address. Pass the
|
|
412
|
+
A custom channel's `receive` hook maps the target to an address. Pass the rest of the input to `from(address).send()`, so the session gets every option the sender set:
|
|
448
413
|
|
|
449
414
|
```ts
|
|
450
415
|
async receive({ message, target, ...send }, { from }) {
|
|
@@ -456,9 +421,64 @@ Route handlers, [handler-form schedules](../schedules#handler-form-run), and [to
|
|
|
456
421
|
|
|
457
422
|
For notifications that don't need an agent turn, use the platform's API instead. See [Durable cross-channel notifications](../patterns/durable-cross-channel-notifications) when those posts also need retries.
|
|
458
423
|
|
|
424
|
+
## CORS
|
|
425
|
+
|
|
426
|
+
Custom HTTP channels send no CORS headers by default. Pass `cors: true` for permissive browser access with preflight handling, or a serializable options object to narrow origins, methods, and headers:
|
|
427
|
+
|
|
428
|
+
```ts
|
|
429
|
+
import { defineChannel, POST } from "eve/channels";
|
|
430
|
+
|
|
431
|
+
export default defineChannel({
|
|
432
|
+
cors: {
|
|
433
|
+
origin: ["https://app.example.com"],
|
|
434
|
+
methods: ["POST"],
|
|
435
|
+
allowHeaders: ["authorization", "content-type"],
|
|
436
|
+
},
|
|
437
|
+
routes: [POST("/message", async () => new Response("ok"))],
|
|
438
|
+
});
|
|
439
|
+
```
|
|
440
|
+
|
|
441
|
+
## WebSocket routes
|
|
442
|
+
|
|
443
|
+
`WS()` declares a WebSocket route. Its handler runs once per upgrade request and returns the hooks for that connection:
|
|
444
|
+
|
|
445
|
+
```ts
|
|
446
|
+
import { defineChannel, WS } from "eve/channels";
|
|
447
|
+
|
|
448
|
+
export default defineChannel({
|
|
449
|
+
routes: [
|
|
450
|
+
WS("/voice/ws", async (_req, { from }) => ({
|
|
451
|
+
async message(_peer, message) {
|
|
452
|
+
await from("voice-demo").send(message.text(), { auth: null });
|
|
453
|
+
},
|
|
454
|
+
})),
|
|
455
|
+
],
|
|
456
|
+
});
|
|
457
|
+
```
|
|
458
|
+
|
|
459
|
+
`WS()` handlers receive the same `from`, `to`, `attachSession`, `params`, `waitUntil`, and `requestIp` arguments as HTTP route handlers. The returned hooks, `upgrade`, `open`, `message`, `close`, and `error`, are compatible with Nitro/H3 websocket routing.
|
|
460
|
+
|
|
461
|
+
### Node upgrade server escape hatch
|
|
462
|
+
|
|
463
|
+
Use `createWebSocketUpgradeServer()` only when a third-party SDK or framework expects to bind to a Node `http.Server` with `server.on("upgrade", ...)`. Otherwise, use the `WS()` lifecycle hooks.
|
|
464
|
+
|
|
465
|
+
```ts
|
|
466
|
+
import { defineChannel, WS, createWebSocketUpgradeServer } from "eve/channels";
|
|
467
|
+
|
|
468
|
+
const bridge = createWebSocketUpgradeServer();
|
|
469
|
+
|
|
470
|
+
thirdPartySdk.attach(bridge.server);
|
|
471
|
+
|
|
472
|
+
export default defineChannel({
|
|
473
|
+
routes: [WS("/vendor/ws", bridge.route)],
|
|
474
|
+
});
|
|
475
|
+
```
|
|
476
|
+
|
|
477
|
+
The bridge server doesn't listen on its own port. It receives only upgrade events that matched the eve route, and only on hosts where Nitro exposes the raw Node upgrade request, socket, and head.
|
|
478
|
+
|
|
459
479
|
## Channel metadata
|
|
460
480
|
|
|
461
|
-
|
|
481
|
+
Channel metadata is the part of a channel's state that instrumentation and dynamic tools, skills, and instructions can read in their `select`. Define a `metadata(state)` function that returns it:
|
|
462
482
|
|
|
463
483
|
```ts
|
|
464
484
|
import { defineChannel, POST } from "eve/channels";
|
|
@@ -496,13 +516,11 @@ export default defineChannel({
|
|
|
496
516
|
});
|
|
497
517
|
```
|
|
498
518
|
|
|
499
|
-
|
|
519
|
+
eve recomputes the metadata when channel event handlers change state. A dynamic tool's or skill's `select` reads it as `ctx.channel.metadata` and narrows it with `isChannel`. See [Dynamic capabilities](../guides/dynamic-capabilities) for the full consumption pattern.
|
|
500
520
|
|
|
501
521
|
### Conversation audience
|
|
502
522
|
|
|
503
|
-
|
|
504
|
-
whether instrumentation may capture conversation content. The hook runs after
|
|
505
|
-
route authentication and before the session is created:
|
|
523
|
+
`audience(input)` sets the session's audience, which controls whether traces may capture conversation content. It runs after route authentication and before the session is created:
|
|
506
524
|
|
|
507
525
|
```ts
|
|
508
526
|
import { defineChannel, POST } from "eve/channels";
|
|
@@ -518,15 +536,15 @@ export default defineChannel({
|
|
|
518
536
|
});
|
|
519
537
|
```
|
|
520
538
|
|
|
521
|
-
The input contains the channel's `state`, `caller`, `channel`, and `environment`.
|
|
539
|
+
The input, typed `AudienceContext<TState>`, contains the channel's `state`, `caller`, `channel`, and `environment`. An authenticated caller (`caller.type === "principal"`) omits `principalId`, `issuer`, and `subject`. Its `attributes` come from route auth and can still identify the person.
|
|
522
540
|
|
|
523
|
-
|
|
541
|
+
Return `"public"`, `"private"`, or `"unknown"`. Return `"unknown"` when the channel can't tell; traces treat it as non-public. A missing, throwing, asynchronous, or malformed `audience` function also falls back to `"unknown"`. An `audience` field returned from `metadata()` sets nothing.
|
|
524
542
|
|
|
525
|
-
|
|
543
|
+
The audience is fixed when the session is created, so turns from a different caller don't change it. A local subagent inherits its parent's audience, and eve forwards the parent's custom channel metadata separately.
|
|
526
544
|
|
|
527
545
|
## Continuation tokens
|
|
528
546
|
|
|
529
|
-
|
|
547
|
+
A continuation token is the address that each channel operation accepts: your channel's ID for one conversation. Each token belongs to its channel, so tokens from different channels never collide.
|
|
530
548
|
|
|
531
549
|
```ts
|
|
532
550
|
import { slackContinuationToken } from "eve/channels/slack";
|
|
@@ -536,7 +554,7 @@ slackContinuationToken({ channelId: "C0123ABC", threadTs: "1800000000.001234" })
|
|
|
536
554
|
twilioContinuationToken({ from: "+15551234567", to: "+15557654321" }); // "+15551234567:+15557654321"
|
|
537
555
|
```
|
|
538
556
|
|
|
539
|
-
|
|
557
|
+
Each built-in channel exports a token builder from its `eve/channels/<platform>` entry. Pass the token to that channel's `from(...)` helper. A token is a routing address, not a credential, and doesn't replace authorization.
|
|
540
558
|
|
|
541
559
|
| Builder | Address fields |
|
|
542
560
|
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
@@ -549,22 +567,11 @@ Built-in channels export token builders from their own `eve/channels/<platform>`
|
|
|
549
567
|
| `telegramContinuationToken` | `chatId`, optional `messageThreadId` and `conversationId` |
|
|
550
568
|
| `linearContinuationToken` | `agentSessionId` |
|
|
551
569
|
|
|
552
|
-
|
|
553
|
-
Tokens are routing addresses, not credentials or substitutes for authorization.
|
|
554
|
-
|
|
555
|
-
Custom channels write their own function that joins the identity fields. The framework derives nothing for you; the channel owns its token format.
|
|
556
|
-
|
|
557
|
-
When another identity should address a session, add it with `channel.continuation?.alias(rawToken)`. The runtime preserves the current channel namespace and exposes the new token as `channel.continuation.token` for later handlers.
|
|
570
|
+
A custom channel owns its token format; write a function that joins the platform's identity fields.
|
|
558
571
|
|
|
559
|
-
|
|
572
|
+
To let another identity address a session, call `channel.continuation?.alias(rawToken)`. The new token belongs to the same channel and becomes `channel.continuation.token` for later handlers. Earlier addresses still reach the same session and accept the same payloads. `end` ends the session and frees all its addresses for later `send()` calls. `cancel` stops only the running turn and keeps the session, history, and addresses.
|
|
560
573
|
|
|
561
|
-
The `context(state, channel)` config option builds the per-step
|
|
562
|
-
in event handlers. Its second argument is `ChannelContext` from `eve/channels`: live
|
|
563
|
-
`session.id` and `session.auth` information, plus channel-owned `continuation` routing. It does
|
|
564
|
-
not expose session commands or put aliasing on session information. Close over
|
|
565
|
-
`channel.continuation` for late-bound callbacks, or call `ctx.channel.continuation?.alias(token)`
|
|
566
|
-
from an event handler. eve adds `ChannelContinuationOps` to the returned context and writes
|
|
567
|
-
state mutations back to adapter state.
|
|
574
|
+
The `context(state, channel)` config option builds the per-step `ctx.channel` that event handlers read. Its second argument is `ChannelContext` from `eve/channels`: the current `session.id` and `session.auth`, plus `continuation`, without session commands. Keep a reference to `channel.continuation` for callbacks that run later, or call `ctx.channel.continuation?.alias(token)` from an event handler. eve adds `ChannelContinuationOps` to the returned context and saves changes you make to `state`.
|
|
568
575
|
|
|
569
576
|
```ts
|
|
570
577
|
import { defineChannel } from "eve/channels";
|
|
@@ -591,83 +598,61 @@ defineChannel<{ ref: string | null }>({
|
|
|
591
598
|
});
|
|
592
599
|
```
|
|
593
600
|
|
|
594
|
-
|
|
601
|
+
The new address joins the session at the next workflow boundary. If another active session already uses the token, the session that called `alias()` fails instead of taking it over. Every address stays active until the session ends. Sessions with continuation addresses stay on their current deployment.
|
|
595
602
|
|
|
596
|
-
Tokens must be nonempty. A session supports up to 256 addresses, including its stable inbox; repeating an existing alias
|
|
603
|
+
Tokens must be nonempty. A session supports up to 256 addresses, including its stable inbox; repeating an existing alias doesn't use another address.
|
|
597
604
|
|
|
598
|
-
##
|
|
605
|
+
## Wrap an existing channel's routes
|
|
599
606
|
|
|
600
|
-
|
|
601
|
-
text and file parts), while `Session.send()` accepts `MessageContent` directly. To
|
|
602
|
-
include file attachments, pass an array mixing text and file parts:
|
|
607
|
+
Spread a channel value into a new object with replaced `routes`. The copy keeps the channel's adapter, events, and build metadata, such as the Slack app manifest, so `{ ...channel, routes }` compiles and runs like the original.
|
|
603
608
|
|
|
604
|
-
|
|
605
|
-
await from(continuationToken).send(
|
|
606
|
-
[
|
|
607
|
-
{ type: "text", text: body.message },
|
|
608
|
-
{ type: "file", data: imageBytes, mediaType: "image/png" },
|
|
609
|
-
],
|
|
610
|
-
{ auth },
|
|
611
|
-
);
|
|
612
|
-
```
|
|
609
|
+
The built-in Slack, Teams, and Telegram channels, and the Chat SDK bridge's `send`, hand every inbound message to `from(address).send(message, options)`. A wrapper that replaces `send` on the source from `from(address)` sees each inbound message, and a rejected delivery reaches it as an error:
|
|
613
610
|
|
|
614
|
-
|
|
611
|
+
```ts title="agent/channels/slack.ts"
|
|
612
|
+
import type { RouteHandlerArgs } from "eve/channels";
|
|
613
|
+
import { slackChannel, type SlackChannelState } from "eve/channels/slack";
|
|
615
614
|
|
|
616
|
-
|
|
617
|
-
defineChannel({
|
|
618
|
-
fetchFile(url) {
|
|
619
|
-
if (!url.startsWith("https://files.slack.com/")) return null;
|
|
620
|
-
return fetch(url, { headers: { authorization: `Bearer ${token}` } })
|
|
621
|
-
.then((r) => r.arrayBuffer())
|
|
622
|
-
.then((b) => ({ bytes: Buffer.from(b) }));
|
|
623
|
-
},
|
|
615
|
+
const slack = slackChannel();
|
|
624
616
|
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
617
|
+
function reportFailedDeliveries(
|
|
618
|
+
args: RouteHandlerArgs<SlackChannelState>,
|
|
619
|
+
): RouteHandlerArgs<SlackChannelState> {
|
|
620
|
+
return {
|
|
621
|
+
...args,
|
|
622
|
+
from(address) {
|
|
623
|
+
const source = args.from(address);
|
|
624
|
+
return {
|
|
625
|
+
...source,
|
|
626
|
+
async send(message, options) {
|
|
627
|
+
try {
|
|
628
|
+
return await source.send(message, options);
|
|
629
|
+
} catch (error) {
|
|
630
|
+
console.error("Slack delivery failed", { address, error });
|
|
631
|
+
throw error;
|
|
632
|
+
}
|
|
639
633
|
},
|
|
640
|
-
|
|
641
|
-
}
|
|
642
|
-
|
|
643
|
-
});
|
|
644
|
-
```
|
|
645
|
-
|
|
646
|
-
If `fetchFile` throws, eve replaces that attachment with a model-visible note and continues the turn. To tell the model why, throw `attachmentError` from `eve/channels`:
|
|
647
|
-
|
|
648
|
-
```ts
|
|
649
|
-
import { attachmentError } from "eve/channels";
|
|
650
|
-
|
|
651
|
-
async function fetchUpload(url: string) {
|
|
652
|
-
const response = await fetch(url, { headers: { authorization: `Bearer ${token}` } });
|
|
653
|
-
if (response.status === 413) {
|
|
654
|
-
throw attachmentError("The file is over 100 MB. Ask for a smaller file.");
|
|
655
|
-
}
|
|
656
|
-
return Buffer.from(await response.arrayBuffer());
|
|
634
|
+
};
|
|
635
|
+
},
|
|
636
|
+
};
|
|
657
637
|
}
|
|
658
|
-
```
|
|
659
|
-
|
|
660
|
-
The model then reads `Attachment report.pdf could not be retrieved: The file is over 100 MB. Ask for a smaller file.` The message reaches the model as written, so keep it to details the person can act on, such as a size limit or a missing permission, and never include URLs, tokens, or upstream response text. Pass the original error as `attachmentError(message, { cause })` to keep it in operator logs. Any other error that `fetchFile` throws becomes a generic note, and eve keeps the original error in operator logs.
|
|
661
|
-
|
|
662
|
-
`fetchFile` receives the channel's `state` and the `session` the attachment arrived in as its second argument, so a resolver can check a file against the session's caller in `session.auth`.
|
|
663
638
|
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
639
|
+
const channel: typeof slack = {
|
|
640
|
+
...slack,
|
|
641
|
+
routes: slack.routes.map((route) =>
|
|
642
|
+
route.transport === "websocket"
|
|
643
|
+
? route
|
|
644
|
+
: {
|
|
645
|
+
...route,
|
|
646
|
+
handler: (request: Request, args: RouteHandlerArgs<SlackChannelState>) =>
|
|
647
|
+
route.handler(request, reportFailedDeliveries(args)),
|
|
648
|
+
},
|
|
649
|
+
),
|
|
650
|
+
};
|
|
667
651
|
|
|
668
|
-
|
|
652
|
+
export default channel;
|
|
653
|
+
```
|
|
669
654
|
|
|
670
|
-
|
|
655
|
+
Keep each route's `method` and `path` unless you mean to move the endpoint.
|
|
671
656
|
|
|
672
657
|
## What to read next
|
|
673
658
|
|