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
|
@@ -9,46 +9,45 @@ A channel connects a platform to your agent. For conversations, it:
|
|
|
9
9
|
- Maps each platform conversation to an eve session.
|
|
10
10
|
- Decides how, where, and whether to deliver replies.
|
|
11
11
|
|
|
12
|
-
A channel can also receive events and pass them to another channel
|
|
12
|
+
A channel can also receive events and pass them to another channel without starting a conversation of its own.
|
|
13
13
|
|
|
14
|
-
eve ships a base HTTP channel
|
|
14
|
+
eve ships a base HTTP channel and first-class platform channels, and you can author your own. Browse them in the [Integrations](/integrations) gallery with the Channels filter.
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
Every channel runs the same agent, so tools and instructions need no channel-specific logic.
|
|
17
17
|
|
|
18
18
|
## Choose where the conversation lives
|
|
19
19
|
|
|
20
|
-
The agent doesn't have to reply where an event arrived. A webhook, for example, can start a conversation in a team chat without
|
|
20
|
+
The agent doesn't have to reply where an event arrived. A webhook, for example, can start a conversation in a team chat without replying to the webhook's source.
|
|
21
21
|
|
|
22
22
|
Use a [cross-channel hand-off](./custom#cross-channel-hand-off) when the conversation belongs elsewhere. The destination channel handles the session, replies, and follow-up messages. To post a notification without running the agent, use the platform's API instead.
|
|
23
23
|
|
|
24
24
|
## Audience
|
|
25
25
|
|
|
26
|
-
When a channel creates a session, it
|
|
27
|
-
`public`, `private`, or `unknown`. The audience controls trace content capture,
|
|
28
|
-
not who may call the channel. Each channel uses the visibility information it
|
|
29
|
-
has; `unknown` is the safe default when it cannot classify a conversation.
|
|
26
|
+
When a channel creates a session, it sets the session's audience: `public`, `private`, or `unknown`. The audience controls what traces capture, not who may call the channel. Each channel decides from what it knows about the conversation, and falls back to `unknown`.
|
|
30
27
|
|
|
31
|
-
Route auth
|
|
32
|
-
route protection](../guides/auth-and-route-protection) for principal types and
|
|
33
|
-
authorization. See the [default eve HTTP channel](./eve#audience) for its
|
|
34
|
-
mapping, or [custom channels](./custom#conversation-audience) to classify your
|
|
35
|
-
own.
|
|
28
|
+
Route auth decides who may call the channel and identifies the caller. See [Auth & route protection](../guides/auth-and-route-protection) for caller types and authorization. See the [default eve HTTP channel](./eve#audience) for its mapping, or [custom channels](./custom#conversation-audience) to classify your own.
|
|
36
29
|
|
|
37
30
|
## Sign-ins
|
|
38
31
|
|
|
39
|
-
When a tool needs a connection the person hasn't authorized, the built-in channels show a sign-in. Its link or code is a credential: whoever completes it connects their account. So it appears only where the person signing in
|
|
32
|
+
When a tool needs a connection the person hasn't authorized, the built-in channels show a sign-in. Its link or code is a credential: whoever completes it connects their account. So it appears only where the person signing in reads it alone:
|
|
40
33
|
|
|
41
34
|
- In a conversation that's theirs (a direct message, a private chat, an SMS thread), eve posts the sign-in there.
|
|
42
|
-
- In a group, eve sends
|
|
43
|
-
-
|
|
35
|
+
- In a group, eve posts a status without the link and sends the sign-in privately where the platform can. Slack and Chat SDK adapters use ephemeral messages; Telegram sends it once the requester presses **Authorize**.
|
|
36
|
+
- Teams channels and Discord servers and group DMs can't send privately. There, the status asks the person to continue in a direct message with the agent.
|
|
37
|
+
- On GitHub, where every comment is public, the status says the person who asked must sign in.
|
|
38
|
+
- When the sign-in ends, eve edits the status where it can, or posts how it ended. Once the person connects, it shows the turn resuming.
|
|
44
39
|
|
|
45
|
-
Linear uses its native sign-in prompt. A sign-in an approval's responder needs appears with that approval's prompt
|
|
40
|
+
Linear uses its native sign-in prompt. A sign-in that an approval's responder needs appears with that approval's prompt.
|
|
46
41
|
|
|
47
42
|
## Overlapping messages
|
|
48
43
|
|
|
49
|
-
Channels default to `turnPolicy: "steer"
|
|
44
|
+
Channels default to `turnPolicy: "steer"`, which adds a new message to the running turn. The turn ID stays the same.
|
|
50
45
|
|
|
51
|
-
|
|
46
|
+
- Before assistant answer output or local tool execution begins, the message interrupts pending model generation and the turn continues with the correction.
|
|
47
|
+
- Executing tools finish and keep their results before steering reaches the next model call.
|
|
48
|
+
- After answer output starts, steering waits until the current model step finishes.
|
|
49
|
+
|
|
50
|
+
Reasoning and search progress don't count as answer output. Interrupted provider-managed search may run again; completed local tools are preserved.
|
|
52
51
|
|
|
53
52
|
Set `turnPolicy: "queue"` on any built-in or custom channel when each turn must finish before the next message starts:
|
|
54
53
|
|
|
@@ -61,17 +60,17 @@ export default defineChannel({
|
|
|
61
60
|
});
|
|
62
61
|
```
|
|
63
62
|
|
|
64
|
-
Adjacent queued messages
|
|
63
|
+
Adjacent queued messages combine into one turn only when their full auth contexts match, including identity, issuer, authenticator, and authorization attributes. Their attachments and context stay in payload order. A different auth context ends the batch, and eve doesn't regroup messages across intervening senders. Anonymous messages stay separate. Turns still share the session's conversation history.
|
|
65
64
|
|
|
66
|
-
`from(address).send(...)`, fixed `Session.send(...)`, cross-channel sends, and Chat SDK bridge sends
|
|
65
|
+
`from(address).send(...)`, fixed `Session.send(...)`, cross-channel sends, and Chat SDK bridge sends accept a per-send `turnPolicy` override. A send with only `answers` answers its pending request without joining the turn. Use `cancel()` to stop without a replacement.
|
|
67
66
|
|
|
68
|
-
Events rejected before `send(...)`, such as invalid signatures or filtered mentions, never reach the active turn. A
|
|
67
|
+
Events rejected before `send(...)`, such as invalid signatures or filtered mentions, never reach the active turn. A message already sent to the session can interrupt the model before the channel's `deliver` hook runs. If that hook ignores the message, eve resumes the original request with its original auth, source, and channel state.
|
|
69
68
|
|
|
70
|
-
Each channel has its own provider terms, data flow, auth model, and user-consent expectations. Before
|
|
69
|
+
Each channel has its own provider terms, data flow, auth model, and user-consent expectations. Before you send non-public, sensitive, regulated, or production data through a channel, confirm that it fits your use case. Check the provider, your configured scopes, signature checks, route auth, and how replies are posted.
|
|
71
70
|
|
|
72
71
|
## Where channels live
|
|
73
72
|
|
|
74
|
-
Channel files live under `agent/channels/` in the root agent or come from an [extension](../extensions) mounted there. The file stem is the channel id: `agent/channels/intake.ts` is addressed as `intake`. An extension mount prefixes its
|
|
73
|
+
Channel files live under `agent/channels/` in the root agent or come from an [extension](../extensions) mounted there. The file stem is the channel id: `agent/channels/intake.ts` is addressed as `intake`. An extension mount prefixes its channel IDs but not their route paths. Local subagents don't declare channels.
|
|
75
74
|
|
|
76
75
|
```text
|
|
77
76
|
agent/
|
|
@@ -82,11 +81,11 @@ agent/
|
|
|
82
81
|
intake.ts
|
|
83
82
|
```
|
|
84
83
|
|
|
85
|
-
Install a channel from the registry with `eve add channel/<name>`, such as `eve add channel/slack` or `eve add channel/web
|
|
84
|
+
Install a channel from the registry with `eve add channel/<name>`, such as `eve add channel/slack` or `eve add channel/web`, or author the file by hand.
|
|
86
85
|
|
|
87
86
|
## The eve HTTP channel (default)
|
|
88
87
|
|
|
89
|
-
The eve channel is the
|
|
88
|
+
The eve channel is the default HTTP session API that the terminal UI, [`useEveAgent`](../guides/frontend/overview), and `curl` call. It serves the health, agent info, callback, task input, and session routes, which you replace together. eve supplies it when no `agent/channels/eve.ts` exists. Author that file to replace it, most often to change route auth. See [HTTP channel](./eve) for routes, auth, replacement, and disablement.
|
|
90
89
|
|
|
91
90
|
## Custom channels
|
|
92
91
|
|
|
@@ -94,9 +93,9 @@ Build a channel with `defineChannel` from `eve/channels` when you need your own
|
|
|
94
93
|
|
|
95
94
|
## Relationship to the Chat SDK
|
|
96
95
|
|
|
97
|
-
eve uses the [Chat SDK's card-builder components](https://chat-sdk.dev/docs/api/cards) (Cards, Buttons, Actions, etc.)
|
|
96
|
+
eve uses the [Chat SDK's card-builder components](https://chat-sdk.dev/docs/api/cards) (Cards, Buttons, Actions, etc.) to compose rich Slack messages. Cards you build with the [Slack channel](./slack) are converted to Slack Block Kit at post time.
|
|
98
97
|
|
|
99
|
-
eve's first-class channels
|
|
98
|
+
eve's first-class channels handle webhooks, verification, event parsing, and threads themselves. The optional [Chat SDK channel](./chat-sdk) instead accepts a Chat SDK adapter and exposes its `Chat` and `Thread` primitives. Use `slackChannel` for eve's Slack integration, `defineChannel(...)` for an eve-native custom channel, or `chatSdkChannel` when you want a Chat SDK adapter and runtime.
|
|
100
99
|
|
|
101
100
|
## Which channel?
|
|
102
101
|
|
|
@@ -104,7 +103,7 @@ eve's first-class channels use eve-owned runtimes for webhook handling, verifica
|
|
|
104
103
|
| ------------------------------------------- | ---------------------------------------------------------- |
|
|
105
104
|
| A web app / browser chat UI | eve channel + [`useEveAgent`](../guides/frontend/overview) |
|
|
106
105
|
| Local tooling, SDK clients, `curl` | [eve HTTP channel](./eve) (default) |
|
|
107
|
-
| MCP clients
|
|
106
|
+
| MCP clients handing off long-running work | [MCP](./mcp) |
|
|
108
107
|
| Slack mentions, DMs, buttons | [Slack](./slack) |
|
|
109
108
|
| iMessage and SMS | [Linq](./linq) |
|
|
110
109
|
| iMessage | [Photon](./photon) |
|
|
@@ -119,15 +118,15 @@ eve's first-class channels use eve-owned runtimes for webhook handling, verifica
|
|
|
119
118
|
|
|
120
119
|
## Disclaimer
|
|
121
120
|
|
|
122
|
-
As the deployer,
|
|
121
|
+
As the deployer, you are responsible for ensuring your agent complies with applicable laws.
|
|
123
122
|
|
|
124
|
-
Where an eve agent communicates with people,
|
|
123
|
+
Where an eve agent communicates with people, the law may require you to disclose that they are interacting with an automated AI system. eve doesn't add this disclosure; configure it in your instructions or channel responses. See [Responsible use](../responsible-use) for the full deployer responsibilities.
|
|
125
124
|
|
|
126
125
|
## What to read next
|
|
127
126
|
|
|
128
127
|
- [eve HTTP channel](./eve): the default session API behind the TUI, SDK clients, and browser UIs
|
|
129
128
|
- [Slack](./slack): the most common platform channel, end to end
|
|
130
|
-
- [MCP](./mcp):
|
|
129
|
+
- [MCP](./mcp): let MCP clients hand long-running work to the agent
|
|
131
130
|
- [Linq](./linq), [Photon](./photon), [Discord](./discord), [Teams](./teams), [Telegram](./telegram), [Twilio](./twilio), [GitHub](./github), and [Linear](./linear): the other first-class platform channels
|
|
132
131
|
- [Chat SDK adapters](./chat-sdk): reach services eve has no first-class channel for
|
|
133
132
|
- [Custom channels](./custom): build a channel for any surface with `defineChannel`
|
package/docs/channels/photon.mdx
CHANGED
|
@@ -3,14 +3,9 @@ title: Photon
|
|
|
3
3
|
description: Connect an eve agent to iMessage through Photon.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
The Photon channel connects your agent to iMessage through a Photon project and `agent/channels/photon.ts`.
|
|
7
7
|
|
|
8
|
-
Run `eve add channel/photon-imessage` to create or use a Photon project and register
|
|
9
|
-
your phone number. It then asks whether to configure Vercel Connect or portable
|
|
10
|
-
credentials. With Vercel Connect, eve signs you in and creates or links a Vercel
|
|
11
|
-
project when needed, then creates the connector and configures Photon’s webhook
|
|
12
|
-
through Connect. The channel resolves credentials lazily when
|
|
13
|
-
the adapter first initializes:
|
|
8
|
+
Run `eve add channel/photon-imessage` to create or use a Photon project and register your phone number, then choose Vercel Connect or portable credentials. With Vercel Connect, eve signs you in, creates or links a Vercel project, creates the connector, and configures Photon's webhook through Connect:
|
|
14
9
|
|
|
15
10
|
```ts title="agent/channels/photon.ts"
|
|
16
11
|
import { connectPhotonCredentials } from "@vercel/connect/eve";
|
|
@@ -21,29 +16,15 @@ export default photonIMessageChannel({
|
|
|
21
16
|
});
|
|
22
17
|
```
|
|
23
18
|
|
|
24
|
-
The
|
|
25
|
-
webhooks with Vercel OIDC from the same project and environment by default, derives user auth from each
|
|
26
|
-
message author, marks accepted messages as read, and continues the same eve
|
|
27
|
-
session for every message in an iMessage conversation. A new accepted message
|
|
28
|
-
steers the active turn. Steering can interrupt pending model generation before
|
|
29
|
-
answer output or local tool execution begins. Executing tools finish first;
|
|
30
|
-
after answer output starts, steering waits for the next committed workflow
|
|
31
|
-
boundary. See [Overlapping messages](./overview#overlapping-messages).
|
|
19
|
+
The channel resolves credentials on first use. It receives webhooks at `/eve/v1/photon` and, by default, verifies them with Vercel OIDC from the same project and environment. It builds auth from the person who sent each message, marks accepted messages as read, and keeps one eve session per iMessage conversation.
|
|
32
20
|
|
|
33
|
-
Set `turnPolicy: "queue"`
|
|
21
|
+
A message that arrives during a turn joins that turn, so the agent can take the correction into account. Set `turnPolicy: "queue"` to let every reply finish before the next message starts. See [Overlapping messages](./overview#overlapping-messages) for when a new message can interrupt the model.
|
|
34
22
|
|
|
35
|
-
Photon
|
|
36
|
-
Replicas that share a durable Workflow World ignore retries while the ID remains
|
|
37
|
-
in the session's recent-key window.
|
|
23
|
+
When Photon retries a webhook, eve accepts the message once, even across replicas that share a Workflow World. See [retried deliveries](./custom#retried-deliveries).
|
|
38
24
|
|
|
39
|
-
Images and other files people send reach the agent as file parts.
|
|
40
|
-
webhook lists each file without its bytes, so eve downloads it from Photon by
|
|
41
|
-
its attachment id with the project's credentials. The webhook omits the id
|
|
42
|
-
for voice notes, so eve refetches those messages from Photon to get it. A
|
|
43
|
-
failed download, a file over 25 MB, or a file eve can't find an id for reaches
|
|
44
|
-
the agent as a short note.
|
|
25
|
+
Images and other files people send reach the agent as file parts. A failed download, a file over 25 MB, or a file without an attachment id reaches the agent as a short note instead.
|
|
45
26
|
|
|
46
|
-
Customize inbound
|
|
27
|
+
Customize inbound handling with `onMessage`. Return `null` to ignore a message, or return `title` alongside `auth` to set the run title when the message starts a run:
|
|
47
28
|
|
|
48
29
|
```ts
|
|
49
30
|
export default photonIMessageChannel({
|
|
@@ -58,18 +39,13 @@ export default photonIMessageChannel({
|
|
|
58
39
|
});
|
|
59
40
|
```
|
|
60
41
|
|
|
61
|
-
Set `route` to
|
|
62
|
-
trusted-forwarder verifier. `eve/channels/photon` exports the `PhotonIMessageWebhookVerifier`,
|
|
63
|
-
`PhotonIMessageChannelCredentials`, and `PhotonProjectCredentials` types for these options.
|
|
42
|
+
Set `route` to change the webhook path, or `webhookVerifier` to use a different trusted-forwarder verifier. `eve/channels/photon` exports the `PhotonIMessageWebhookVerifier`, `PhotonIMessageChannelCredentials`, and `PhotonProjectCredentials` types for these options.
|
|
64
43
|
|
|
65
44
|
## Tapbacks
|
|
66
45
|
|
|
67
|
-
`IMESSAGE_TAPBACKS` from `eve/channels/photon` lists the built-in tapback names.
|
|
68
|
-
Use it to populate a picker or validate a named reaction. Tapback APIs can also
|
|
69
|
-
accept a single emoji; the list does not enumerate those.
|
|
46
|
+
`IMESSAGE_TAPBACKS` from `eve/channels/photon` lists the built-in tapback names. Use it to populate a picker or validate a named reaction. Tapback APIs also accept a single emoji, which the list does not include.
|
|
70
47
|
|
|
71
|
-
eve ignores tapbacks people send unless you pass `onTapback`. It receives the
|
|
72
|
-
tapback and returns the same result as `onMessage`, or `null` to ignore it:
|
|
48
|
+
eve ignores tapbacks people send unless you pass `onTapback`. It receives the tapback and returns the same result as `onMessage`, or `null` to ignore it:
|
|
73
49
|
|
|
74
50
|
```ts title="agent/channels/photon.ts"
|
|
75
51
|
import { connectPhotonCredentials } from "@vercel/connect/eve";
|
|
@@ -84,17 +60,18 @@ export default photonIMessageChannel({
|
|
|
84
60
|
});
|
|
85
61
|
```
|
|
86
62
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
tapback
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
and the person. An accepted tapback starts or steers a turn like any other
|
|
94
|
-
message, following `turnPolicy`. The agent's own tapbacks never reach `onTapback`. `onTapback` runs instead of `onMessage` for tapbacks, so repeat any sender checks from `onMessage` there.
|
|
63
|
+
| Field | Value |
|
|
64
|
+
| ------------------- | ---------------------------------------------------------------------------------------------- |
|
|
65
|
+
| `tapback.tapback` | `love`, `like`, `dislike`, `laugh`, `emphasize`, `question`, or the emoji for an emoji tapback |
|
|
66
|
+
| `tapback.messageId` | The message the tapback is on |
|
|
67
|
+
| `tapback.author` | The person who sent it |
|
|
68
|
+
| `tapback.added` | Always `true`, because Photon reports only added tapbacks |
|
|
95
69
|
|
|
96
|
-
|
|
97
|
-
|
|
70
|
+
The agent reads an accepted tapback as iMessage's text form, such as `Tapback: Loved “See you at 7”`. The quoted text appears when Photon can return the original message. An accepted tapback starts or steers a turn like any other message, following `turnPolicy`.
|
|
71
|
+
|
|
72
|
+
`onTapback` runs instead of `onMessage` for tapbacks, so repeat any sender checks from `onMessage` there. The agent's own tapbacks never reach it.
|
|
73
|
+
|
|
74
|
+
To let the agent send tapbacks, export the channel's tapback tool from a file in `agent/tools/`. The file name becomes the tool name:
|
|
98
75
|
|
|
99
76
|
```ts title="agent/tools/tapback.ts"
|
|
100
77
|
import photon from "../channels/photon";
|
|
@@ -102,11 +79,13 @@ import photon from "../channels/photon";
|
|
|
102
79
|
export default photon.tapbackTool();
|
|
103
80
|
```
|
|
104
81
|
|
|
105
|
-
The model calls it with a standard tapback, such as `{ "tapback": "love" }`, or any single emoji, such as `{ "tapback": "🎉" }
|
|
82
|
+
The model calls it with a standard tapback, such as `{ "tapback": "love" }`, or any single emoji, such as `{ "tapback": "🎉" }`. eve reacts to the latest message someone sent in the conversation. A standard tapback's own emoji, such as `👍`, sends that tapback.
|
|
83
|
+
|
|
84
|
+
The model can send a tapback alongside a reply; to let a tapback be the whole answer, also add [`no_reply`](../concepts/built-in-tools#no_reply). Subagents don't receive the tool. In a session from another channel, such as web chat, or before anyone has sent a message, the call returns an error to the model.
|
|
106
85
|
|
|
107
86
|
### Answer approvals with a tapback
|
|
108
87
|
|
|
109
|
-
Return `answer` from `onTapback` to answer the
|
|
88
|
+
Return `answer` from `onTapback` to answer the approval or question in the message the tapback is on. A [tool approval](/docs/human-in-the-loop#approvals) offers the options `approve` and `deny`, so a like or dislike on the approval prompt can approve or deny it:
|
|
110
89
|
|
|
111
90
|
```ts title="agent/channels/photon.ts"
|
|
112
91
|
import { connectPhotonCredentials } from "@vercel/connect/eve";
|
|
@@ -124,22 +103,21 @@ export default photonIMessageChannel({
|
|
|
124
103
|
});
|
|
125
104
|
```
|
|
126
105
|
|
|
127
|
-
`answer`
|
|
106
|
+
`answer` answers only the request posted in that message, and only while that request is still open and offers that option. A tapback on any other message, or on an answered prompt, reaches the agent as an ordinary tapback, such as `Tapback: Liked “Got it”`. The approval's response policy still decides whether the sender may answer. For a [question](/docs/human-in-the-loop#questions), return one of its option ids.
|
|
107
|
+
|
|
108
|
+
Return `message` to replace the text the agent receives for a tapback. Don't set `message` to an option's id, label, or number, because eve reads that text like a typed reply. A typed reply answers the first waiting approval, no matter which message the tapback is on.
|
|
128
109
|
|
|
129
110
|
## Other hosts
|
|
130
111
|
|
|
131
|
-
|
|
132
|
-
`eve add channel/photon-imessage`. eve scaffolds the channel and writes
|
|
133
|
-
`IMESSAGE_PROJECT_ID` and `IMESSAGE_PROJECT_SECRET` to `.env.local`.
|
|
112
|
+
On a host without Vercel Connect, choose **Use portable credentials** during `eve add channel/photon-imessage`. eve scaffolds the channel and writes `IMESSAGE_PROJECT_ID` and `IMESSAGE_PROJECT_SECRET` to `.env.local`.
|
|
134
113
|
|
|
135
114
|
After deploying the agent:
|
|
136
115
|
|
|
137
116
|
1. Create a Photon webhook for your public `https://…/eve/v1/photon` URL.
|
|
138
117
|
2. Copy its signing secret into `IMESSAGE_WEBHOOK_SECRET`.
|
|
139
|
-
3. Set `IMESSAGE_PROJECT_ID`, `IMESSAGE_PROJECT_SECRET`, and
|
|
140
|
-
`IMESSAGE_WEBHOOK_SECRET` in the host’s encrypted environment variables.
|
|
118
|
+
3. Set `IMESSAGE_PROJECT_ID`, `IMESSAGE_PROJECT_SECRET`, and `IMESSAGE_WEBHOOK_SECRET` in the host’s encrypted environment variables.
|
|
141
119
|
|
|
142
|
-
To configure the channel by hand,
|
|
120
|
+
To configure the channel by hand, resolve credentials from the environment:
|
|
143
121
|
|
|
144
122
|
```ts title="agent/channels/photon.ts"
|
|
145
123
|
import { photonIMessageChannel } from "eve/channels/photon";
|
|
@@ -155,6 +133,4 @@ export default photonIMessageChannel({
|
|
|
155
133
|
});
|
|
156
134
|
```
|
|
157
135
|
|
|
158
|
-
For direct Photon webhooks, pass `webhookSecret` or set
|
|
159
|
-
`IMESSAGE_WEBHOOK_SECRET`; the signing secret takes precedence over the default
|
|
160
|
-
OIDC verifier.
|
|
136
|
+
For direct Photon webhooks, pass `webhookSecret` or set `IMESSAGE_WEBHOOK_SECRET`. The signing secret takes precedence over the default OIDC verifier.
|