eve 0.90.0 → 0.91.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +34 -23
- package/dist/src/channel/auth/http-basic.js +1 -1
- package/dist/src/channel/channel-operations.d.ts +1 -1
- package/dist/src/channel/types.d.ts +2 -0
- package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
- package/dist/src/client/session.d.ts +1 -1
- package/dist/src/compiled/.vendor-stamp.json +1 -1
- package/dist/src/execution/dynamic-workflow/tool.js +1 -1
- package/dist/src/execution/proxied-deliver-step.js +1 -1
- package/dist/src/execution/sandbox/bash.js +2 -2
- package/dist/src/execution/session/active-turn.js +1 -1
- package/dist/src/execution/session/admission.d.ts +6 -0
- package/dist/src/execution/session/admission.js +1 -1
- package/dist/src/execution/session/delivery-facts.js +1 -1
- package/dist/src/execution/session/next-input.d.ts +2 -2
- package/dist/src/execution/session/next-input.js +1 -1
- package/dist/src/execution/session/program.js +1 -1
- package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
- package/dist/src/execution/session-inbox/inbox.js +1 -1
- package/dist/src/execution/session-inbox/protocol.js +1 -1
- package/dist/src/execution/tools/agent-router-workflow.js +1 -1
- package/dist/src/harness/compaction/engine.js +2 -2
- package/dist/src/harness/current-messages.js +1 -1
- package/dist/src/harness/emission.d.ts +3 -0
- package/dist/src/harness/emission.js +1 -1
- package/dist/src/harness/facts.d.ts +5 -2
- package/dist/src/harness/facts.js +1 -1
- package/dist/src/harness/model-call/call.d.ts +7 -1
- package/dist/src/harness/model-call/call.js +3 -1
- package/dist/src/harness/provider-tool-history.d.ts +8 -0
- package/dist/src/harness/provider-tool-history.js +1 -1
- package/dist/src/harness/session-machine/transitions.d.ts +3 -2
- package/dist/src/harness/step/after-model.js +1 -1
- package/dist/src/harness/step/context.js +1 -1
- package/dist/src/harness/step/intake.js +1 -1
- package/dist/src/harness/step/prompt.js +1 -1
- package/dist/src/harness/tool-history-repair.d.ts +2 -0
- package/dist/src/harness/tool-history-repair.js +1 -1
- package/dist/src/harness/tool-loop.js +1 -1
- package/dist/src/internal/application/stamped-package-version.js +1 -1
- package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
- package/dist/src/protocol/session-events/families/delivery.js +1 -1
- package/dist/src/protocol/session-projection/fold.js +1 -1
- package/dist/src/public/channels/discord/hitl.js +1 -1
- package/dist/src/public/channels/slack/hitl.d.ts +2 -1
- package/dist/src/public/channels/slack/hitl.js +3 -3
- package/dist/src/public/channels/slack/interaction-cards.js +1 -1
- package/dist/src/public/channels/slack/request-card-render.js +1 -1
- package/dist/src/public/channels/teams/hitl.js +1 -1
- package/dist/src/public/channels/teams/verify.js +1 -1
- package/dist/src/public/definitions/hook.d.ts +90 -7
- package/dist/src/public/definitions/hook.js +1 -1
- package/dist/src/public/hooks/index.d.ts +3 -2
- package/dist/src/reactions/continuation.d.ts +19 -0
- package/dist/src/reactions/continuation.js +1 -0
- package/dist/src/reactions/intents.d.ts +10 -4
- package/dist/src/reactions/intents.js +1 -1
- package/dist/src/reactions/kinds/hook.js +1 -1
- package/dist/src/reactions/runner.js +1 -1
- package/dist/src/reactions/state.d.ts +15 -2
- package/dist/src/reactions/state.js +1 -1
- package/dist/src/runtime/resolve-connection.js +1 -1
- package/dist/src/runtime/subagents/workflow.js +1 -1
- package/dist/src/setup/primitives/open-url.js +1 -1
- package/dist/src/setup/scaffold/create/project.js +1 -1
- package/dist/src/shared/value-delta.d.ts +5 -4
- package/dist/src/shared/value-delta.js +1 -1
- package/dist/src/tools/provided/ask-question-workflow.js +1 -1
- package/dist/src/tools/provided/sleep-workflow.js +1 -1
- package/dist/src/tools/provided/web-fetch.js +1 -1
- package/docs/agent-config.md +199 -222
- package/docs/channels/chat-sdk.mdx +60 -64
- package/docs/channels/custom.mdx +264 -281
- package/docs/channels/discord.mdx +176 -123
- package/docs/channels/eve.mdx +136 -206
- package/docs/channels/github.mdx +24 -22
- package/docs/channels/linear.mdx +30 -30
- package/docs/channels/linq.mdx +25 -13
- package/docs/channels/mcp.mdx +154 -116
- package/docs/channels/overview.mdx +31 -32
- package/docs/channels/photon.mdx +32 -56
- package/docs/channels/slack.mdx +538 -375
- package/docs/channels/teams.mdx +40 -26
- package/docs/channels/telegram.mdx +13 -13
- package/docs/channels/twilio.mdx +11 -11
- package/docs/code-extension.mdx +40 -42
- package/docs/concepts/built-in-tools.md +89 -57
- package/docs/concepts/context-control.md +20 -20
- package/docs/concepts/default-harness.md +20 -36
- package/docs/concepts/execution-model-and-durability.mdx +96 -160
- package/docs/concepts/project-structure.mdx +21 -14
- package/docs/concepts/security-model.md +27 -27
- package/docs/concepts/sessions-runs-and-streaming.md +184 -198
- package/docs/concepts/state.md +7 -15
- package/docs/connections/mcp.mdx +109 -93
- package/docs/connections/openapi.mdx +57 -59
- package/docs/connections/overview.mdx +175 -170
- package/docs/evals/assertions.mdx +36 -29
- package/docs/evals/cases.mdx +38 -42
- package/docs/evals/judge.mdx +21 -29
- package/docs/evals/overview.mdx +42 -38
- package/docs/evals/reporters.mdx +54 -27
- package/docs/evals/running.mdx +15 -8
- package/docs/evals/targets.mdx +16 -19
- package/docs/evals/tool-stubs.mdx +111 -97
- package/docs/experimental/dynamic-schedules.mdx +118 -63
- package/docs/extensions.md +58 -65
- package/docs/getting-started.mdx +4 -6
- package/docs/guides/auth-and-route-protection.md +87 -70
- package/docs/guides/client/continuations.mdx +23 -26
- package/docs/guides/client/messages.mdx +47 -66
- package/docs/guides/client/output-schema.mdx +8 -8
- package/docs/guides/client/overview.mdx +45 -43
- package/docs/guides/client/streaming.mdx +62 -71
- package/docs/guides/decide.md +24 -79
- package/docs/guides/deployment/meta.json +1 -1
- package/docs/guides/deployment/overview.md +27 -18
- package/docs/guides/deployment/self-hosted-operations.md +99 -0
- package/docs/guides/deployment/self-hosting.md +63 -80
- package/docs/guides/deployment/vercel.mdx +31 -27
- package/docs/guides/deployment/workflow-worlds.md +100 -0
- package/docs/guides/dev-tui.md +48 -41
- package/docs/guides/dynamic-capabilities.md +49 -50
- package/docs/guides/frontend/nextjs.mdx +2 -2
- package/docs/guides/frontend/nuxt.mdx +11 -11
- package/docs/guides/frontend/overview.mdx +1 -1
- package/docs/guides/frontend/sveltekit.mdx +11 -11
- package/docs/guides/frontend/tanstack.mdx +16 -16
- package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
- package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
- package/docs/guides/frontend/use-eve-agent.mdx +25 -25
- package/docs/guides/hooks.md +152 -106
- package/docs/guides/instrumentation/agent-runs.mdx +26 -30
- package/docs/guides/instrumentation/instrumentation.mdx +49 -76
- package/docs/guides/instrumentation/meta.json +1 -1
- package/docs/guides/instrumentation/otel.mdx +113 -179
- package/docs/guides/remote-agents.md +125 -187
- package/docs/guides/self-modification.md +18 -18
- package/docs/guides/session-context.md +16 -16
- package/docs/install-integrations.mdx +26 -24
- package/docs/instructions.mdx +37 -42
- package/docs/memory/custom-provider.md +35 -41
- package/docs/memory/file.md +93 -76
- package/docs/memory/overview.mdx +145 -156
- package/docs/patterns/durable-cross-channel-notifications.md +15 -19
- package/docs/patterns/dynamic-scheduling.md +19 -23
- package/docs/patterns/multi-tenant-approvals.md +17 -22
- package/docs/patterns/multi-tenant-auth.md +43 -42
- package/docs/patterns/multi-tenant-memory.md +39 -36
- package/docs/patterns/voice-notes.md +3 -3
- package/docs/protocols/acp.md +13 -13
- package/docs/protocols/ucp.mdx +7 -7
- package/docs/reference/agent-files.md +6 -6
- package/docs/reference/cli.md +99 -98
- package/docs/reference/telemetry.md +1 -1
- package/docs/reference/typescript-api.md +52 -53
- package/docs/responsible-use.md +2 -2
- package/docs/sandbox/custom-providers.mdx +60 -56
- package/docs/sandbox/default.mdx +23 -24
- package/docs/sandbox/docker.mdx +16 -10
- package/docs/sandbox/index.mdx +93 -61
- package/docs/sandbox/just-bash.mdx +17 -11
- package/docs/sandbox/troubleshooting.mdx +29 -23
- package/docs/sandbox/vercel.mdx +45 -52
- package/docs/schedules.mdx +65 -54
- package/docs/skills.mdx +74 -49
- package/docs/subagents/index.mdx +97 -136
- package/docs/tools/human-in-the-loop.md +160 -90
- package/docs/tools/meta.json +1 -1
- package/docs/tools/overview.mdx +229 -237
- package/docs/tools/tasks.md +118 -117
- package/docs/tools/workflows.mdx +447 -543
- package/docs/tutorial/connect-a-warehouse.mdx +11 -13
- package/docs/tutorial/first-agent.mdx +14 -16
- package/docs/tutorial/guard-the-spend.mdx +6 -8
- package/docs/tutorial/how-it-runs.mdx +8 -8
- package/docs/tutorial/query-sample-data.mdx +8 -8
- package/docs/tutorial/remember-definitions.mdx +4 -4
- package/docs/tutorial/run-analysis.mdx +20 -22
- package/docs/tutorial/ship-it.mdx +19 -19
- package/docs/tutorial/team-playbooks.mdx +9 -9
- package/docs/use-cases.mdx +13 -11
- package/package.json +1 -1
- package/docs/guides/instrumentation/migration.md +0 -96
- package/docs/tools/tasks-upgrade.md +0 -218
|
@@ -3,9 +3,9 @@ title: "Chat SDK"
|
|
|
3
3
|
description: "Bridge any Vercel Chat SDK adapter — Slack, Discord, Telegram, WhatsApp, email, and more — to your agent through one channel, using your own credentials and state store."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
The Chat SDK channel connects your agent to any [Vercel Chat SDK](https://chat-sdk.dev) adapter
|
|
6
|
+
The Chat SDK channel connects your agent to any [Vercel Chat SDK](https://chat-sdk.dev) adapter, such as `@chat-adapter/slack` or `@resend/chat-sdk-adapter`. It lives in a file under `agent/channels/`, such as `agent/channels/resend.ts`. You register handlers for the messages you care about, and call `send` to hand each one to eve. Use it for a surface without a built-in eve channel, or to manage credentials and state with Chat SDK instead of [Vercel Connect](../guides/auth-and-route-protection).
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
The adapter handles provider auth, webhook verification, and posting messages, and you supply its state store. eve handles sessions, streaming, typing indicators, and human-in-the-loop prompts. Built-in channels such as [Slack](./slack) have their own APIs and take credentials from Vercel Connect or environment variables.
|
|
9
9
|
|
|
10
10
|
## Install
|
|
11
11
|
|
|
@@ -15,11 +15,11 @@ Add eve, the Chat SDK core (`chat`), an adapter, and a state adapter. The exampl
|
|
|
15
15
|
npm install eve@latest chat @resend/chat-sdk-adapter @chat-adapter/state-memory
|
|
16
16
|
```
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
Any Chat SDK adapter works, such as `@chat-adapter/slack`, `@chat-adapter/discord`, or `@chat-adapter/telegram`.
|
|
19
19
|
|
|
20
20
|
## Add the channel
|
|
21
21
|
|
|
22
|
-
`chatSdkChannel` returns `{ bot, channel, send }`. Register Chat SDK handlers on `bot`, call `send` from those handlers to start or resume an eve session
|
|
22
|
+
`chatSdkChannel` returns `{ bot, channel, send }`. Register Chat SDK handlers on `bot`, and call `send` from those handlers to start or resume an eve session. Export `channel` as the module default:
|
|
23
23
|
|
|
24
24
|
```ts title="agent/channels/resend.ts"
|
|
25
25
|
import { createMemoryState } from "@chat-adapter/state-memory";
|
|
@@ -29,13 +29,16 @@ import { chatSdkChannel } from "eve/channels/chat-sdk";
|
|
|
29
29
|
|
|
30
30
|
export const { bot, channel, send } = chatSdkChannel({
|
|
31
31
|
userName: "Resend Bot",
|
|
32
|
+
// One webhook per adapter, at /eve/v1/<name>.
|
|
32
33
|
adapters: {
|
|
33
34
|
resend: createResendAdapter({
|
|
34
35
|
fromAddress: "hello@example.com",
|
|
35
36
|
fromName: "Resend Bot",
|
|
36
37
|
}),
|
|
37
38
|
},
|
|
39
|
+
// In-memory state is for local development only.
|
|
38
40
|
state: createMemoryState(),
|
|
41
|
+
// Email can't edit a sent message, so post each reply once.
|
|
39
42
|
streaming: false,
|
|
40
43
|
});
|
|
41
44
|
|
|
@@ -51,67 +54,56 @@ bot.onSubscribedMessage(async (thread: Thread, message: Message) => {
|
|
|
51
54
|
export default channel;
|
|
52
55
|
```
|
|
53
56
|
|
|
54
|
-
|
|
57
|
+
- `state` takes any Chat SDK state adapter. In production, use a persistent adapter such as Redis or Upstash, so thread subscriptions and duplicate checks survive restarts.
|
|
58
|
+
- `send` accepts a string or an array of message parts. Call it inside a Chat SDK handler, because it starts the turn on the running webhook.
|
|
59
|
+
- Pass `idempotencyKey: message.id` to `send` so a retried message reaches the agent once within the session's [recent-key window](./custom#retried-deliveries). Chat SDK can mark a message as seen before eve accepts it, so a shared state adapter alone doesn't guarantee the agent gets it.
|
|
55
60
|
|
|
56
|
-
|
|
57
|
-
within the session's [recent-key window](./custom#retried-deliveries). Chat SDK's
|
|
58
|
-
separate duplicate check can mark a message as seen before eve accepts it, so
|
|
59
|
-
a shared state adapter alone does not guarantee delivery.
|
|
60
|
-
|
|
61
|
-
Deploy once the channel file is in place:
|
|
61
|
+
Deploy to Vercel production, linking the project if needed:
|
|
62
62
|
|
|
63
63
|
```bash
|
|
64
64
|
eve deploy
|
|
65
65
|
```
|
|
66
66
|
|
|
67
|
-
`eve deploy` links the project if needed and deploys to Vercel production.
|
|
68
|
-
|
|
69
67
|
## Configure the webhook route
|
|
70
68
|
|
|
71
|
-
Each adapter
|
|
69
|
+
Each adapter serves `GET` and `POST` at `/eve/v1/{adapterName}`, so the `resend` adapter above is at `/eve/v1/resend`. Point your provider's webhook, such as the Resend inbound address or the Slack Event Subscriptions URL, at that path. The adapter handles each method. For example, X sends its verification challenge with `GET` and events with `POST`.
|
|
72
70
|
|
|
73
|
-
|
|
71
|
+
Set `route` to change the base path for every adapter, or `routes` to pin one adapter's path:
|
|
74
72
|
|
|
75
73
|
```ts
|
|
76
74
|
export const { bot, channel, send } = chatSdkChannel({
|
|
77
75
|
userName: "Resend Bot",
|
|
78
76
|
adapters: { resend: createResendAdapter({ fromAddress: "hello@example.com" }) },
|
|
79
77
|
state: createMemoryState(),
|
|
80
|
-
route: "/webhooks", // resend
|
|
78
|
+
route: "/webhooks", // resend mounts at /webhooks/resend
|
|
81
79
|
routes: { resend: "/webhooks/inbound-email" }, // …or pin it exactly
|
|
82
80
|
});
|
|
83
81
|
```
|
|
84
82
|
|
|
85
|
-
Use `routes` when a provider requires a fixed URL or
|
|
86
|
-
|
|
87
|
-
## Audience
|
|
88
|
-
|
|
89
|
-
Workspace-visible threads are `public`. DMs and private or external threads
|
|
90
|
-
are `private`; threads without a known visibility are `unknown`. The audience
|
|
91
|
-
controls observability content capture, not access to the thread. See
|
|
92
|
-
[Audience](./overview#audience) for the shared channel model.
|
|
83
|
+
Use `routes` when a provider requires a fixed URL, or to keep an existing endpoint without changing the provider's settings.
|
|
93
84
|
|
|
94
85
|
## How the channel handles messages
|
|
95
86
|
|
|
96
87
|
### Dispatch
|
|
97
88
|
|
|
98
|
-
|
|
89
|
+
A turn starts when a handler you register on `bot` calls `send`:
|
|
99
90
|
|
|
100
|
-
- `bot.onNewMention(thread, message)` fires on a
|
|
101
|
-
- `bot.onSubscribedMessage(thread, message)` fires on
|
|
102
|
-
- `bot.onAction`, `bot.onReaction`, and `bot.onSlashCommand`
|
|
91
|
+
- `bot.onNewMention(thread, message)` fires on a new `@mention`, or a new inbound thread on surfaces like email. Call `thread.subscribe()` so later replies in the thread keep reaching the agent.
|
|
92
|
+
- `bot.onSubscribedMessage(thread, message)` fires on later messages in a subscribed thread.
|
|
93
|
+
- `bot.onAction`, `bot.onReaction`, and `bot.onSlashCommand` fire for adapters that emit them.
|
|
103
94
|
|
|
104
|
-
`send(message, options)` starts or resumes the eve session. The `thread` you pass
|
|
95
|
+
`send(message, options)` starts or resumes the eve session. The `thread` you pass picks the session, so replies land on that thread:
|
|
105
96
|
|
|
106
97
|
```ts
|
|
107
98
|
bot.onNewMention(async (thread, message) => {
|
|
99
|
+
// `title` sets the session's display title without changing the model message.
|
|
108
100
|
await send(message.text, { thread, title: "Support request" });
|
|
109
101
|
});
|
|
110
102
|
```
|
|
111
103
|
|
|
112
|
-
`options` accepts `thread` and `adapterName`, plus the channel send options `auth`, `context`, `outputSchema`, `title`, `callback`, `turnPolicy`, and `idempotencyKey`. `
|
|
104
|
+
`options` accepts `thread` and `adapterName`, plus the channel send options `auth`, `context`, `outputSchema`, `title`, `callback`, `turnPolicy`, and `idempotencyKey`. `auth` names who the turn runs as. Omit it for `null`, an anonymous turn.
|
|
113
105
|
|
|
114
|
-
To answer
|
|
106
|
+
To answer open approvals and questions from controls you render yourself, call `respond(answers, { thread, auth?, context? })`. It never creates a session. This example answers a custom button whose `value` carries the request's `interactionId`:
|
|
115
107
|
|
|
116
108
|
```ts
|
|
117
109
|
export const { bot, channel, send, respond } = chatSdkChannel({/* ... */});
|
|
@@ -124,9 +116,9 @@ bot.onAction("approve_deploy", async (event) => {
|
|
|
124
116
|
|
|
125
117
|
### Steering
|
|
126
118
|
|
|
127
|
-
|
|
119
|
+
By default, a message that arrives while the agent is answering joins the running turn (`turnPolicy: "steer"`). The turn keeps its ID and completed tool work. [Message delivery and steering](../concepts/execution-model-and-durability#message-delivery-and-steering) says when it applies. With no active turn, the message starts one.
|
|
128
120
|
|
|
129
|
-
Set `turnPolicy: "queue"`
|
|
121
|
+
Set `turnPolicy: "queue"` to let the active turn finish first:
|
|
130
122
|
|
|
131
123
|
```ts
|
|
132
124
|
bot.onSubscribedMessage(async (thread, message) => {
|
|
@@ -137,34 +129,21 @@ bot.onSubscribedMessage(async (thread, message) => {
|
|
|
137
129
|
});
|
|
138
130
|
```
|
|
139
131
|
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
This policy controls overlapping eve turns. Chat SDK's separate `concurrency` option controls overlapping webhook handlers; use `concurrency: "concurrent"` when each inbound message should reach the steering path immediately.
|
|
132
|
+
Set the policy on `chatSdkChannel({ turnPolicy })` or per `send(...)`. `turnPolicy` governs overlapping eve turns, and Chat SDK's `concurrency` option governs overlapping webhook handlers. Use `concurrency: "concurrent"` so each new message reaches the running turn at once.
|
|
143
133
|
|
|
144
134
|
### Delivery
|
|
145
135
|
|
|
146
|
-
The default handlers post the agent's reply
|
|
136
|
+
The default handlers post the agent's reply to the thread as markdown (`{ markdown: … }`), so adapters render rich text and email HTML.
|
|
147
137
|
|
|
148
|
-
|
|
138
|
+
By default the channel streams. It posts a message and edits it as text arrives (`content.delta`), at most once per `streamingEditIntervalMs`. A last edit adds the full text if needed, and the channel never posts the streamed reply again. If the final edit fails, the channel logs the error and posts a short notice with the error id. On the next message, it tells the model that the user hasn't seen its reply.
|
|
149
139
|
|
|
150
|
-
|
|
140
|
+
Set `streaming: false` for surfaces that send one message per turn or can't edit messages, such as email and WhatsApp. The reply then posts once, when the turn completes.
|
|
151
141
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
```ts
|
|
155
|
-
chatSdkChannel({
|
|
156
|
-
userName: "Resend Bot",
|
|
157
|
-
adapters: { resend: createResendAdapter({ fromAddress: "hello@example.com" }) },
|
|
158
|
-
state: createMemoryState(),
|
|
159
|
-
streaming: false,
|
|
160
|
-
});
|
|
161
|
-
```
|
|
162
|
-
|
|
163
|
-
Typing indicators post automatically where the adapter supports them: `Working…` on `turn.started`, and on `call.requested`, each call's [label](/docs/tools#label-tool-activity) or a readable form of its name. They leave out the model's own `eve__task_wait` and `eve__task_cancel` calls.
|
|
142
|
+
Where the adapter supports typing indicators, the channel shows `Working…` when a turn starts. On each tool call, it shows the call's [label](/docs/tools#label-tool-activity) or readable name, except for `eve__task_wait` and `eve__task_cancel`.
|
|
164
143
|
|
|
165
144
|
### Optional capabilities degrade gracefully
|
|
166
145
|
|
|
167
|
-
|
|
146
|
+
When an adapter's `startTyping` throws a `NotImplementedError`, or an error with code `NOT_IMPLEMENTED`, the channel skips typing indicators. An unsupported `editMessage` turns off streaming edits for the rest of the session, so later replies post once at the end. A reply that already has a streamed message still gets the final edit attempt, and a failure is reported as above. Use the same check in custom `events` with `isNotImplemented`:
|
|
168
147
|
|
|
169
148
|
```ts
|
|
170
149
|
import { isNotImplemented } from "eve/channels/chat-sdk";
|
|
@@ -190,7 +169,12 @@ chatSdkChannel({
|
|
|
190
169
|
|
|
191
170
|
### Human-in-the-loop (HITL)
|
|
192
171
|
|
|
193
|
-
|
|
172
|
+
Approvals and questions render as a Chat SDK `Card` with buttons, and the channel wires `bot.onAction` to `respond`, so clicks resume the session. Adapters that can't render cards, such as Photon iMessage, get text with numbered options:
|
|
173
|
+
|
|
174
|
+
- A reply sent through `send` with an option's number or label answers the request. For example, `1` or `approve` runs an approval-gated tool, and `2` or `cancel` stops it.
|
|
175
|
+
- If the question allows a custom answer or has no options, any other text is the answer.
|
|
176
|
+
|
|
177
|
+
Set `inputActionPrefix` if your app already uses the default `eve_input:` prefix. Set `resolveInputAuth` to keep user or tenant auth when a click resumes the session:
|
|
194
178
|
|
|
195
179
|
```ts
|
|
196
180
|
chatSdkChannel({
|
|
@@ -208,13 +192,13 @@ chatSdkChannel({
|
|
|
208
192
|
|
|
209
193
|
### Sign-ins
|
|
210
194
|
|
|
211
|
-
When a tool needs a connection the person hasn't authorized, eve shows a sign-in prompt with the connection's link, code, or instructions. In a direct message
|
|
195
|
+
When a tool needs a connection the person hasn't authorized, eve shows a sign-in prompt with the connection's link, code, or instructions. In a direct message, eve posts the prompt in the thread and edits it once the sign-in completes.
|
|
212
196
|
|
|
213
|
-
|
|
197
|
+
Elsewhere, the prompt is a credential, so eve sends it only to the person signing in. It uses an ephemeral message where the adapter supports one, and otherwise a direct message. The thread gets a status without the link, which eve edits once the sign-in completes.
|
|
214
198
|
|
|
215
|
-
|
|
199
|
+
eve finds that person by matching the turn's `auth` user to the author of the message you passed to `send`. Private sign-ins need both of these:
|
|
216
200
|
|
|
217
|
-
- per-person `auth` on each `send`, so
|
|
201
|
+
- per-person `auth` on each `send`, so each `auth` names one person; and
|
|
218
202
|
- the handler's `Thread` object as `thread`, rather than a thread id string, so eve sees who wrote the message.
|
|
219
203
|
|
|
220
204
|
```ts
|
|
@@ -231,11 +215,11 @@ bot.onSubscribedMessage(async (thread, message) => {
|
|
|
231
215
|
});
|
|
232
216
|
```
|
|
233
217
|
|
|
234
|
-
Without both, including with the default `auth: null`, the thread only
|
|
218
|
+
Without both, including with the default `auth: null`, the thread gets only a notice to continue in a direct message, and the prompt isn't shown anywhere. The same happens when several people share one `auth`, such as tenant auth, or when the adapter has neither ephemerals nor `openDM`.
|
|
235
219
|
|
|
236
220
|
### Proactive sessions
|
|
237
221
|
|
|
238
|
-
|
|
222
|
+
To start a session without an incoming webhook, call `to(channel, target).send(message, { auth })` from a schedule `run` handler, or `ctx.to(channel, target).send(message, { auth })` from another channel. The target is a serialized Chat SDK thread, or `{ threadId, adapterName }` when you have only a provider-native thread id:
|
|
239
223
|
|
|
240
224
|
```ts
|
|
241
225
|
await to(channel, { adapterName: "resend", threadId: "resend:user@example.com" }).send(
|
|
@@ -246,7 +230,7 @@ await to(channel, { adapterName: "resend", threadId: "resend:user@example.com" }
|
|
|
246
230
|
|
|
247
231
|
### Attachments
|
|
248
232
|
|
|
249
|
-
|
|
233
|
+
To forward a Chat SDK message's attachments, convert it with `messageContentOf`. It returns `message.text` when there are no attachments. Otherwise it returns message parts: the text, plus one part per attachment:
|
|
250
234
|
|
|
251
235
|
```ts
|
|
252
236
|
import { messageContentOf } from "eve/channels/chat-sdk";
|
|
@@ -256,11 +240,22 @@ bot.onNewMention(async (thread, message) => {
|
|
|
256
240
|
});
|
|
257
241
|
```
|
|
258
242
|
|
|
259
|
-
When the adapter
|
|
243
|
+
When the adapter sets `fetchData`, as the Slack, Google Chat, WhatsApp, and Twilio adapters do, eve downloads the attachment when the turn runs. It uses the adapter's credentials and `rehydrateAttachment`, and passes the file bytes, because the model provider can't open platform URLs that need credentials. An attachment with only a URL is downloaded when the URL is public `https:`.
|
|
244
|
+
|
|
245
|
+
Every other attachment reaches the agent as a short note, so the agent still knows a file was sent. This covers:
|
|
246
|
+
|
|
247
|
+
- an attachment from an adapter without `rehydrateAttachment`;
|
|
248
|
+
- a non-public URL or a failed download;
|
|
249
|
+
- a file over 25 MB; and
|
|
250
|
+
- an attachment with neither a download nor a URL.
|
|
260
251
|
|
|
261
252
|
Audio attachments, such as voice notes, reach the model as a file label, not as sound. To answer them, give the agent a transcription tool; see [Voice notes](../patterns/voice-notes).
|
|
262
253
|
|
|
263
|
-
See [File uploads](./custom#file-uploads) for how eve
|
|
254
|
+
See [File uploads](./custom#file-uploads) for how eve prepares remote file URLs before the model call.
|
|
255
|
+
|
|
256
|
+
## Audience
|
|
257
|
+
|
|
258
|
+
Workspace-visible threads are `public`, DMs and private or external threads are `private`, and threads of unknown visibility are `unknown`. The audience controls which message content observability records, not who can access the thread. See [Audience](./overview#audience).
|
|
264
259
|
|
|
265
260
|
## Configuration reference
|
|
266
261
|
|
|
@@ -270,7 +265,7 @@ See [File uploads](./custom#file-uploads) for how eve stages remote file URLs be
|
|
|
270
265
|
| `state` | — | Chat SDK state adapter for subscriptions, locks, and dedupe. |
|
|
271
266
|
| `userName` | — | Display name for the bot (a standard Chat SDK `ChatConfig` field). |
|
|
272
267
|
| `route` | `/eve/v1` | Base path for generated adapter webhooks (`{route}/{adapter}`). |
|
|
273
|
-
| `routes` | — | Per-adapter path overrides for fixed or
|
|
268
|
+
| `routes` | — | Per-adapter path overrides for fixed or existing webhook URLs. |
|
|
274
269
|
| `streaming` | `true` | Post-then-edit streaming. Set `false` for one-message-per-turn surfaces. |
|
|
275
270
|
| `streamingEditIntervalMs` | `1000` | Minimum interval between streaming edits. |
|
|
276
271
|
| `events` | built-in | Per-event handlers. A supplied handler replaces that built-in default. |
|
|
@@ -282,6 +277,7 @@ Any other Chat SDK `ChatConfig` field (for example `concurrency`) is accepted an
|
|
|
282
277
|
|
|
283
278
|
## What to read next
|
|
284
279
|
|
|
285
|
-
- [Channels overview](./overview):
|
|
280
|
+
- [Channels overview](./overview): what every channel shares, and every built-in channel
|
|
281
|
+
- [Slack](./slack), [Discord](./discord), and [Telegram](./telegram): built-in channels with platform-specific APIs
|
|
286
282
|
- [Custom channels](./custom): build a channel for any surface with `defineChannel`
|
|
287
283
|
- [Auth & route protection](../guides/auth-and-route-protection): authenticating inbound traffic
|