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.
Files changed (247) hide show
  1. package/CHANGELOG.md +39 -9
  2. package/dist/src/channel/adapter.d.ts +12 -3
  3. package/dist/src/channel/adapter.js +1 -1
  4. package/dist/src/channel/auth/definitions.d.ts +7 -20
  5. package/dist/src/channel/auth/definitions.js +1 -1
  6. package/dist/src/channel/auth/http-basic.js +1 -1
  7. package/dist/src/channel/auth/jwt-ecdsa.js +1 -1
  8. package/dist/src/channel/auth/jwt-hmac.js +1 -1
  9. package/dist/src/channel/auth/oidc.js +1 -1
  10. package/dist/src/channel/auth/result.d.ts +2 -3
  11. package/dist/src/channel/auth/result.js +1 -1
  12. package/dist/src/channel/channel-address.d.ts +1 -1
  13. package/dist/src/channel/channel-address.js +1 -1
  14. package/dist/src/channel/channel-operations.d.ts +1 -1
  15. package/dist/src/channel/schedule.js +1 -1
  16. package/dist/src/channel/types.d.ts +2 -0
  17. package/dist/src/chunks/{use-eve-agent-Bbl4H5aA.js → use-eve-agent-Bwloorf8.js} +77 -63
  18. package/dist/src/chunks/{use-eve-agent-CNpxgKEH.js → use-eve-agent-XCB0-tLX.js} +77 -63
  19. package/dist/src/cli/dev/environment.js +1 -1
  20. package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
  21. package/dist/src/cli/dev/tui/remote-connection-probe.js +1 -1
  22. package/dist/src/cli/dev/tui/remote-connection-types.d.ts +1 -0
  23. package/dist/src/cli/dev/tui/runner.js +2 -2
  24. package/dist/src/cli/dev/tui/status-line.d.ts +2 -2
  25. package/dist/src/cli/dev/tui/status-line.js +1 -1
  26. package/dist/src/client/agent-info-schema.d.ts +341 -326
  27. package/dist/src/client/agent-info-schema.js +1 -1
  28. package/dist/src/client/agent-info-types.d.ts +13 -10
  29. package/dist/src/client/client-error.d.ts +1 -1
  30. package/dist/src/client/client.d.ts +5 -3
  31. package/dist/src/client/client.js +1 -1
  32. package/dist/src/client/session.d.ts +1 -1
  33. package/dist/src/compiled/.vendor-stamp.json +1 -1
  34. package/dist/src/evals/target.js +1 -1
  35. package/dist/src/eve-channel/auth.d.ts +19 -0
  36. package/dist/src/eve-channel/auth.js +1 -0
  37. package/dist/src/eve-channel/index.d.ts +1 -0
  38. package/dist/src/eve-channel/index.js +1 -1
  39. package/dist/src/eve-channel/types.d.ts +23 -4
  40. package/dist/src/execution/catalog/connection-entry.js +1 -1
  41. package/dist/src/execution/coordination-dispatch-shared.js +1 -1
  42. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  43. package/dist/src/execution/proxied-deliver-step.js +1 -1
  44. package/dist/src/execution/sandbox/bash.js +2 -2
  45. package/dist/src/execution/session/active-turn.js +1 -1
  46. package/dist/src/execution/session/admission.d.ts +6 -0
  47. package/dist/src/execution/session/admission.js +1 -1
  48. package/dist/src/execution/session/delivery-facts.js +1 -1
  49. package/dist/src/execution/session/next-input.d.ts +2 -2
  50. package/dist/src/execution/session/next-input.js +1 -1
  51. package/dist/src/execution/session/program.js +1 -1
  52. package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
  53. package/dist/src/execution/session-inbox/inbox.js +1 -1
  54. package/dist/src/execution/session-inbox/protocol.js +1 -1
  55. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  56. package/dist/src/harness/compaction/engine.js +2 -2
  57. package/dist/src/harness/current-messages.js +1 -1
  58. package/dist/src/harness/emission.d.ts +3 -0
  59. package/dist/src/harness/emission.js +1 -1
  60. package/dist/src/harness/facts.d.ts +5 -2
  61. package/dist/src/harness/facts.js +1 -1
  62. package/dist/src/harness/model-call/call.d.ts +7 -1
  63. package/dist/src/harness/model-call/call.js +3 -1
  64. package/dist/src/harness/provider-tool-history.d.ts +8 -0
  65. package/dist/src/harness/provider-tool-history.js +1 -1
  66. package/dist/src/harness/session-machine/transitions.d.ts +3 -2
  67. package/dist/src/harness/step/after-model.js +1 -1
  68. package/dist/src/harness/step/context.js +1 -1
  69. package/dist/src/harness/step/intake.js +1 -1
  70. package/dist/src/harness/step/prompt.js +1 -1
  71. package/dist/src/harness/tool-history-repair.d.ts +2 -0
  72. package/dist/src/harness/tool-history-repair.js +1 -1
  73. package/dist/src/harness/tool-loop.js +1 -1
  74. package/dist/src/internal/application/stamped-package-version.js +1 -1
  75. package/dist/src/internal/authored-module-graph.js +1 -1
  76. package/dist/src/internal/nitro/routes/agent-info/build-agent-info-response.d.ts +2 -2
  77. package/dist/src/protocol/routes.d.ts +7 -1
  78. package/dist/src/protocol/routes.js +1 -1
  79. package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
  80. package/dist/src/protocol/session-events/families/delivery.js +1 -1
  81. package/dist/src/protocol/session-projection/fold.js +1 -1
  82. package/dist/src/public/channels/discord/hitl.js +1 -1
  83. package/dist/src/public/channels/github/githubChannel.js +1 -1
  84. package/dist/src/public/channels/github/state.d.ts +7 -0
  85. package/dist/src/public/channels/github/state.js +1 -1
  86. package/dist/src/public/channels/mcp.js +1 -1
  87. package/dist/src/public/channels/slack/hitl.d.ts +2 -1
  88. package/dist/src/public/channels/slack/hitl.js +3 -3
  89. package/dist/src/public/channels/slack/interaction-cards.js +1 -1
  90. package/dist/src/public/channels/slack/request-card-render.js +1 -1
  91. package/dist/src/public/channels/teams/hitl.js +1 -1
  92. package/dist/src/public/channels/teams/verify.js +1 -1
  93. package/dist/src/public/channels/telegram/telegramChannel.js +1 -1
  94. package/dist/src/public/connections/index.d.ts +1 -1
  95. package/dist/src/public/definitions/channel.js +1 -1
  96. package/dist/src/public/definitions/connections/tool-call.d.ts +2 -2
  97. package/dist/src/public/definitions/hook.d.ts +90 -7
  98. package/dist/src/public/definitions/hook.js +1 -1
  99. package/dist/src/public/hooks/index.d.ts +3 -2
  100. package/dist/src/reactions/continuation.d.ts +19 -0
  101. package/dist/src/reactions/continuation.js +1 -0
  102. package/dist/src/reactions/frame.js +1 -1
  103. package/dist/src/reactions/intents.d.ts +10 -4
  104. package/dist/src/reactions/intents.js +1 -1
  105. package/dist/src/reactions/kinds/hook.js +1 -1
  106. package/dist/src/reactions/runner.js +1 -1
  107. package/dist/src/reactions/state.d.ts +15 -2
  108. package/dist/src/reactions/state.js +1 -1
  109. package/dist/src/runtime/channels/registry.d.ts +2 -2
  110. package/dist/src/runtime/channels/registry.js +1 -1
  111. package/dist/src/runtime/connections/approval-scope.d.ts +9 -0
  112. package/dist/src/runtime/connections/approval-scope.js +1 -0
  113. package/dist/src/runtime/connections/mcp-client.d.ts +1 -1
  114. package/dist/src/runtime/connections/mcp-client.js +1 -1
  115. package/dist/src/runtime/connections/provided-arguments.js +1 -1
  116. package/dist/src/runtime/resolve-connection.js +1 -1
  117. package/dist/src/runtime/subagents/workflow.js +1 -1
  118. package/dist/src/setup/primitives/open-url.js +1 -1
  119. package/dist/src/setup/scaffold/create/project.js +1 -1
  120. package/dist/src/shared/agent-info-access.d.ts +5 -0
  121. package/dist/src/shared/agent-info-access.js +1 -0
  122. package/dist/src/shared/connection-types.d.ts +21 -4
  123. package/dist/src/shared/value-delta.d.ts +5 -4
  124. package/dist/src/shared/value-delta.js +1 -1
  125. package/dist/src/svelte/index.js +1 -1
  126. package/dist/src/svelte/use-eve-agent.js +1 -1
  127. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  128. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  129. package/dist/src/tools/provided/web-fetch.js +1 -1
  130. package/dist/src/vue/index.js +1 -1
  131. package/dist/src/vue/use-eve-agent.js +1 -1
  132. package/docs/agent-config.md +199 -222
  133. package/docs/channels/chat-sdk.mdx +60 -64
  134. package/docs/channels/custom.mdx +265 -280
  135. package/docs/channels/discord.mdx +176 -123
  136. package/docs/channels/eve.mdx +136 -204
  137. package/docs/channels/github.mdx +24 -22
  138. package/docs/channels/linear.mdx +30 -30
  139. package/docs/channels/linq.mdx +25 -13
  140. package/docs/channels/mcp.mdx +154 -116
  141. package/docs/channels/overview.mdx +31 -32
  142. package/docs/channels/photon.mdx +32 -56
  143. package/docs/channels/slack.mdx +538 -375
  144. package/docs/channels/teams.mdx +40 -26
  145. package/docs/channels/telegram.mdx +13 -13
  146. package/docs/channels/twilio.mdx +11 -11
  147. package/docs/code-extension.mdx +40 -42
  148. package/docs/concepts/built-in-tools.md +89 -57
  149. package/docs/concepts/context-control.md +20 -20
  150. package/docs/concepts/default-harness.md +20 -36
  151. package/docs/concepts/execution-model-and-durability.mdx +96 -160
  152. package/docs/concepts/project-structure.mdx +21 -14
  153. package/docs/concepts/security-model.md +27 -27
  154. package/docs/concepts/sessions-runs-and-streaming.md +184 -194
  155. package/docs/concepts/state.md +7 -15
  156. package/docs/connections/mcp.mdx +109 -93
  157. package/docs/connections/openapi.mdx +57 -59
  158. package/docs/connections/overview.mdx +205 -170
  159. package/docs/evals/assertions.mdx +36 -29
  160. package/docs/evals/cases.mdx +38 -42
  161. package/docs/evals/judge.mdx +21 -29
  162. package/docs/evals/overview.mdx +42 -38
  163. package/docs/evals/reporters.mdx +54 -27
  164. package/docs/evals/running.mdx +15 -8
  165. package/docs/evals/targets.mdx +17 -18
  166. package/docs/evals/tool-stubs.mdx +111 -97
  167. package/docs/experimental/dynamic-schedules.mdx +118 -63
  168. package/docs/extensions.md +58 -65
  169. package/docs/getting-started.mdx +4 -6
  170. package/docs/guides/auth-and-route-protection.md +100 -70
  171. package/docs/guides/client/continuations.mdx +23 -26
  172. package/docs/guides/client/messages.mdx +47 -66
  173. package/docs/guides/client/output-schema.mdx +8 -8
  174. package/docs/guides/client/overview.mdx +47 -41
  175. package/docs/guides/client/streaming.mdx +62 -71
  176. package/docs/guides/decide.md +24 -79
  177. package/docs/guides/deployment/meta.json +1 -1
  178. package/docs/guides/deployment/overview.md +27 -18
  179. package/docs/guides/deployment/self-hosted-operations.md +99 -0
  180. package/docs/guides/deployment/self-hosting.md +63 -80
  181. package/docs/guides/deployment/vercel.mdx +31 -27
  182. package/docs/guides/deployment/workflow-worlds.md +100 -0
  183. package/docs/guides/dev-tui.md +48 -41
  184. package/docs/guides/dynamic-capabilities.md +49 -50
  185. package/docs/guides/frontend/nextjs.mdx +2 -2
  186. package/docs/guides/frontend/nuxt.mdx +11 -11
  187. package/docs/guides/frontend/overview.mdx +1 -1
  188. package/docs/guides/frontend/sveltekit.mdx +11 -11
  189. package/docs/guides/frontend/tanstack.mdx +16 -16
  190. package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
  191. package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
  192. package/docs/guides/frontend/use-eve-agent.mdx +25 -25
  193. package/docs/guides/hooks.md +152 -106
  194. package/docs/guides/instrumentation/agent-runs.mdx +26 -30
  195. package/docs/guides/instrumentation/instrumentation.mdx +49 -76
  196. package/docs/guides/instrumentation/meta.json +1 -1
  197. package/docs/guides/instrumentation/otel.mdx +113 -179
  198. package/docs/guides/prepare-for-1-0.md +23 -1
  199. package/docs/guides/remote-agents.md +125 -187
  200. package/docs/guides/self-modification.md +18 -18
  201. package/docs/guides/session-context.md +16 -16
  202. package/docs/install-integrations.mdx +26 -24
  203. package/docs/instructions.mdx +37 -42
  204. package/docs/memory/custom-provider.md +35 -41
  205. package/docs/memory/file.md +93 -76
  206. package/docs/memory/overview.mdx +145 -156
  207. package/docs/patterns/durable-cross-channel-notifications.md +15 -19
  208. package/docs/patterns/dynamic-scheduling.md +19 -23
  209. package/docs/patterns/multi-tenant-approvals.md +17 -22
  210. package/docs/patterns/multi-tenant-auth.md +43 -42
  211. package/docs/patterns/multi-tenant-memory.md +39 -36
  212. package/docs/patterns/voice-notes.md +3 -3
  213. package/docs/protocols/acp.md +13 -13
  214. package/docs/protocols/ucp.mdx +7 -7
  215. package/docs/reference/agent-files.md +6 -6
  216. package/docs/reference/cli.md +99 -98
  217. package/docs/reference/telemetry.md +1 -1
  218. package/docs/reference/typescript-api.md +52 -53
  219. package/docs/responsible-use.md +2 -2
  220. package/docs/sandbox/custom-providers.mdx +60 -56
  221. package/docs/sandbox/default.mdx +23 -24
  222. package/docs/sandbox/docker.mdx +16 -10
  223. package/docs/sandbox/index.mdx +93 -61
  224. package/docs/sandbox/just-bash.mdx +17 -11
  225. package/docs/sandbox/troubleshooting.mdx +29 -23
  226. package/docs/sandbox/vercel.mdx +45 -52
  227. package/docs/schedules.mdx +65 -54
  228. package/docs/skills.mdx +74 -49
  229. package/docs/subagents/index.mdx +97 -136
  230. package/docs/tools/human-in-the-loop.md +160 -90
  231. package/docs/tools/meta.json +1 -1
  232. package/docs/tools/overview.mdx +229 -237
  233. package/docs/tools/tasks.md +118 -117
  234. package/docs/tools/workflows.mdx +447 -543
  235. package/docs/tutorial/connect-a-warehouse.mdx +11 -13
  236. package/docs/tutorial/first-agent.mdx +14 -16
  237. package/docs/tutorial/guard-the-spend.mdx +6 -8
  238. package/docs/tutorial/how-it-runs.mdx +8 -8
  239. package/docs/tutorial/query-sample-data.mdx +8 -8
  240. package/docs/tutorial/remember-definitions.mdx +4 -4
  241. package/docs/tutorial/run-analysis.mdx +20 -22
  242. package/docs/tutorial/ship-it.mdx +19 -19
  243. package/docs/tutorial/team-playbooks.mdx +9 -9
  244. package/docs/use-cases.mdx +13 -11
  245. package/package.json +1 -1
  246. package/docs/guides/instrumentation/migration.md +0 -96
  247. 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, without starting a conversation of its own.
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 plus first-class platform channels, and you can author your own. Browse the full set in the [Integrations](/integrations) gallery and choose the Channels filter.
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
- After a channel dispatches a message, eve runs the same agent runtime regardless of where the event came from. Tools and instructions do not need channel-specific logic.
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 sending an agent reply to the webhook's source.
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 assigns an observability audience:
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 controls access and supplies the session principal. See [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 alone reads it:
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 it privately where the platform can (Slack and Chat SDK adapters with ephemeral messages; Telegram once the requester presses **Authorize**) and posts a status without the link. Otherwise the status asks the person to continue in a direct message with the agent. Teams channels and Discord servers and group DMs work this way. On GitHub, where every comment is public, the status says the person who asked must sign in.
43
- - When the sign-in ends, eve edits the status where it can, or posts how it ended, and once the person connects, shows the turn resuming.
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 instead.
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"`. Before assistant answer output or local tool execution begins, a message can interrupt pending model generation and continue the same turn with the correction. Executing tools finish and checkpoint their results before steering reaches the next model call. After answer output starts, steering waits for the next committed workflow boundary. The turn ID stays the same.
44
+ Channels default to `turnPolicy: "steer"`, which adds a new message to the running turn. The turn ID stays the same.
50
45
 
51
- Reasoning and search progress do not count as answer output. Interrupted provider-managed search may run again; completed local tools are preserved.
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 can 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; eve does not regroup messages across intervening senders. Anonymous deliveries stay separate. Turns still share the session's conversation history.
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 also accept a per-send `turnPolicy` override. Pure `answers` deliveries answer their pending request without steering. Explicit `cancel()` remains the stop-without-replacement operation.
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 delivery already sent to the session can interrupt pending generation before the channel's `deliver` hook processes it. If that hook ignores the correction, eve resumes the original request with its original auth, delivery provenance, and channel state.
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 sending non-public, sensitive, regulated, or production data through a channel, confirm that the channel provider and your configured scopes, signature checks, route auth, and delivery behavior are appropriate for your use case.
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 contributed channel IDs but does not change their route paths. Local subagents do not declare channels.
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`. You can also author the file by hand.
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 framework's default HTTP session API, the routes the terminal UI, [`useEveAgent`](../guides/frontend/overview), and `curl` all talk to. Its selected `channels/eve.ts` source owns health, inspection, callbacks, task input, and the session protocol as one replaceable surface. eve supplies the source when no `agent/channels/eve.ts` file exists; author that file to replace it, most often to change route auth. See [HTTP channel](./eve) for routes, auth, replacement, and disablement.
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.) for composing rich Slack messages. When you build a card with the [Slack channel](./slack), the underlying primitives come from the Chat SDK and get converted to Slack Block Kit at post time.
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 use eve-owned runtimes for webhook handling, verification, event parsing, and thread management. The optional [Chat SDK channel](./chat-sdk) is the exception: it accepts a Chat SDK adapter and exposes its `Chat` and `Thread` primitives. Use `slackChannel` for eve's first-class Slack integration, `defineChannel(...)` for an eve-native custom channel, or `chatSdkChannel` when you intentionally want a Chat SDK adapter and runtime.
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 delegating durable work | [MCP](./mcp) |
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, it is your responsibility to ensure your agent complies with applicable laws.
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, you may be required to disclose that they are interacting with an automated AI system where law requires it. eve does not add this disclosure automatically; configure it in your instructions and/or channel responses. See [Responsible use](../responsible-use) for the full deployer responsibilities.
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): expose the agent as a durable invocation service
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`
@@ -3,14 +3,9 @@ title: Photon
3
3
  description: Connect an eve agent to iMessage through Photon.
4
4
  ---
5
5
 
6
- Use `photonIMessageChannel` to receive and reply to iMessages through a Photon project.
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 default webhook route is `/eve/v1/photon`. The channel verifies forwarded
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"` when every response should finish before Photon starts the next message.
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 uses inbound message IDs as [delivery idempotency keys](./custom#retried-deliveries).
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. Photon's
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 dispatch with `onMessage`. Return `null` to ignore a message, or return `title` alongside `auth` to set the title when the dispatch starts a run:
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 override the webhook path or `webhookVerifier` to use a different
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
- The agent reads an accepted tapback as a message in the form iMessage uses when
88
- it shows a tapback as text, such as `Tapback: Loved “See you at 7”`. Photon
89
- reports only added tapbacks, so `tapback.added` is always `true` and removing a
90
- tapback never reaches `onTapback`. The quoted text appears when Photon can return the message the tapback is on. `tapback.tapback` is `love`,
91
- `like`, `dislike`, `laugh`, `emphasize`, or `question`, or the emoji itself for
92
- an emoji tapback. `tapback.messageId` and `tapback.author` identify the message
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
- To let the agent send tapbacks, export the channel's tapback tool from a file in
97
- `agent/tools/`. The file name becomes the tool name:
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": "🎉" }`, and eve reacts to the latest message someone sent in the conversation. A standard tapback's own emoji, such as `👍`, sends that tapback. 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). The tool is never added on its own, and subagents don't receive it. In a session that didn't come through this channel, such as a web chat, or before anyone has sent a message, the call fails with an error the model reads.
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 input request eve posted in the message the tapback is on. A [tool approval](/docs/human-in-the-loop#approvals) offers the options `approve` and `cancel`, so a like or dislike on the approval prompt can approve or cancel it:
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` settles only the request posted in that message, and only while it is still waiting and offers that option. A tapback on any other message, or on a prompt that was already answered, reaches the agent as an ordinary tapback, such as `Tapback: Liked “Got it”`. The approval's response policy still decides whether the person who sent the tapback may answer. For a [question](/docs/human-in-the-loop#questions), return one of its option ids. To replace the text the agent receives for a tapback, return `message`. Don't set `message` to an option's id, label, or number: eve reads that text like a typed reply, which answers the first waiting approval no matter which message the tapback is on.
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
- For a host without Vercel Connect, choose **Use portable credentials** during
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, use lazy environment-backed credentials:
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.