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
@@ -4,7 +4,7 @@ description: "Reach your agent from Microsoft Teams via the Bot Framework Activi
4
4
  type: integration
5
5
  ---
6
6
 
7
- The Teams channel runs your agent inside Microsoft Teams as a bot. It takes Bot Framework Activity POSTs, checks the Bot Connector bearer JWT and its `serviceurl` binding on each one, and routes message activities to your agent. Human-in-the-loop (HITL) prompts come back as Adaptive Cards, and replies go out over the Bot Framework Connector REST API. See [Channels](./overview) for the contract this builds on.
7
+ The Teams channel runs your agent as a Microsoft Teams bot. It lives in `agent/channels/teams.ts`. It checks each incoming Bot Framework Activity's Bot Connector bearer JWT and `serviceurl` claim. It replies through the Bot Framework Connector REST API. Approvals and questions render as Adaptive Cards.
8
8
 
9
9
  ## Add the channel
10
10
 
@@ -22,9 +22,7 @@ For a managed Teams bot on Vercel, run:
22
22
  eve add channel/teams
23
23
  ```
24
24
 
25
- The guided flow runs the Vercel Connect CLI, which takes you through managed
26
- Microsoft Teams app creation and installation. It routes verified Activities to
27
- `/eve/v1/teams` and writes:
25
+ The guided flow runs the Vercel Connect CLI to create and install a managed Microsoft Teams app, and routes verified Activities to `/eve/v1/teams`. It writes:
28
26
 
29
27
  ```ts title="agent/channels/teams.ts"
30
28
  import { connectTeamsCredentials } from "@vercel/connect/eve";
@@ -35,13 +33,11 @@ export default teamsChannel({
35
33
  });
36
34
  ```
37
35
 
38
- Vercel Connect owns the Microsoft administrator consent and app installation
39
- flow. After deployment, mention the bot in a channel or send it a personal
40
- message.
36
+ Vercel Connect handles Microsoft administrator consent and app installation. After you deploy, mention the bot in a channel or send it a personal message.
41
37
 
42
38
  ### Portable credentials
43
39
 
44
- To manage the bot registration and credentials yourself, configure:
40
+ To manage the bot registration and credentials yourself, set:
45
41
 
46
42
  ```bash
47
43
  MICROSOFT_APP_ID=...
@@ -49,21 +45,24 @@ MICROSOFT_APP_PASSWORD=...
49
45
  MICROSOFT_TENANT_ID=... # optional, single-tenant bots
50
46
  ```
51
47
 
52
- By default the channel mounts at `POST /eve/v1/teams`. Point your Azure Bot or Teams app messaging endpoint at that public URL. To mount somewhere else, pass `route: "/api/teams/activity"`.
48
+ The channel mounts at `POST /eve/v1/teams`. Pass `route`, such as `route: "/api/teams/activity"`, to mount it elsewhere. Point your Azure Bot or Teams app messaging endpoint at that public URL.
53
49
 
54
50
  ## How the channel handles messages
55
51
 
56
52
  ### Dispatch
57
53
 
58
- The default `onMessage` handles two cases: personal-chat messages, and channel or group-chat messages that mention the bot directly. Ambient resource-specific-consent messages are dropped unless you override it. Return `title` alongside `auth` to set the title when the dispatch starts a run. Before dispatch, eve strips the mention, adds `<teams_context>` with `user_id`, `bot_id`, and `is_mentioned`, and scopes channel and group threads by root activity id (`replyToId ?? id`).
54
+ By default, the bot answers personal-chat messages, and channel or group-chat messages that mention it. It ignores messages that reach it through resource-specific consent without a mention. Each channel or group-chat thread gets its own session, keyed by its root activity id.
59
55
 
60
- For example, use the contextual `isSubscribed()` helper to continue active threads without requiring another mention:
56
+ eve strips the bot mention from the text. The model sees a `<teams_context>` block with `user_id`, `bot_id`, and `is_mentioned`.
57
+
58
+ A custom `onMessage` returns `{ auth }` to run the agent, optionally with `title` to set the run title, or `null` to ignore the message. To continue active threads without another mention, use `ctx.isSubscribed()`. It reports whether a session already answers in the thread:
61
59
 
62
60
  ```ts
63
61
  import { defaultTeamsAuth, teamsChannel } from "eve/channels/teams";
64
62
 
65
63
  export default teamsChannel({
66
64
  async onMessage(ctx, message) {
65
+ // Never answer bots, including this one.
67
66
  if (message.from.role === "bot" || message.from.id === message.recipient.id) return null;
68
67
  const isDirectMessage = message.scope === "personal";
69
68
  return isDirectMessage || message.isBotMentioned || (await ctx.isSubscribed())
@@ -73,41 +72,44 @@ export default teamsChannel({
73
72
  });
74
73
  ```
75
74
 
76
- `isSubscribed()` checks whether the conversation has previously involved the agent.
77
-
78
75
  ### Delivery
79
76
 
80
- Native Bot Connector verification requires the activity's `serviceUrl` to match the verified token's `serviceurl` claim. A custom `webhookVerifier` replaces this verification and must authenticate the forwarded activity and its service URL. Proactive conversation references are trusted application input: load them from your own verified records, not a caller-supplied URL. Outbound Connector requests require HTTPS without URL credentials, query strings, or fragments, and do not follow redirects.
77
+ Replies post as Markdown (`textFormat: "markdown"`), and long text is split across messages. A typing indicator shows when a turn starts and on each tool call. `thread.mentionUser()` shows the display name, or the user ID, as literal text, while the mention still targets the original user.
81
78
 
82
- HTTP service URLs used by Bot Framework Emulator are not supported, even with a custom verifier. Use an HTTPS endpoint or proxy for local Connector testing.
79
+ Each activity's `serviceUrl` must match the `serviceurl` claim in its verified token. A custom `webhookVerifier` replaces this check, so it must authenticate both the activity and its service URL. Load proactive conversation references from your own verified records, never from a URL a caller supplies.
83
80
 
84
- Replies post as Markdown (`textFormat: "markdown"`), with oversized text split across messages and a typing indicator sent on turn start and action requests. `thread.mentionUser()` escapes the display name (or fallback user ID) as literal text inside the mention; the mention entity retains the original identity fields.
81
+ Outbound Connector requests need an HTTPS URL without credentials, a query string, or a fragment, and don't follow redirects. Bot Framework Emulator's HTTP service URLs don't work, even with a custom verifier. Use an HTTPS endpoint or proxy to test the Connector locally.
85
82
 
86
83
  ### Human-in-the-loop (HITL)
87
84
 
88
- A human-in-the-loop (HITL) request, an `interaction.opened` fact, renders as an Adaptive Card. Approval cards show the tool input in the card and fallback text. Buttons and options map to `Action.Submit`, selects to `Input.ChoiceSet`, and freeform to `Input.Text`. Teams may return a submission as a message or invoke; eve handles both before the normal message mention gate and resumes the thread recorded in the card.
85
+ Each approval or question (`interaction.opened`) renders as an Adaptive Card. Approval cards show the tool input in the card and in the fallback text. Buttons and options map to `Action.Submit`, selects to `Input.ChoiceSet`, and free text to `Input.Text`. Submissions don't need a mention, and each one resumes the thread recorded in its card.
89
86
 
90
- By default, submissions use the Teams identity of the user who clicked the card. If you customize `onMessage` for an allowlist, configure the same policy in `onAnswers`; eve otherwise rejects HITL submissions rather than bypassing the message gate.
87
+ By default, a submission answers as the Teams user who clicked. If you customize `onMessage`, for example for an allowlist, set the same policy in `onAnswers`. Otherwise eve rejects every card submission.
91
88
 
92
- When a tool approval settles, eve replaces its Adaptive Card with the outcome and responder name. A response rejected by an approval policy leaves the shared card unchanged. A submission to a card whose session is no longer active, for example because its run was cancelled outside eve, replaces the card with its prompt and `No longer active`, and the invoke response tells the person who submitted to send a new message.
89
+ When a tool approval is decided, eve replaces its card with the outcome and the responder's name. A response the approval policy rejects leaves the card unchanged. A submission to a card whose session has ended replaces the card with its prompt and `No longer active`. eve then tells the submitter to send a new message.
93
90
 
94
91
  ### Connection sign-ins
95
92
 
96
- When a connection needs the person to sign in, eve's `interaction.opened` handler posts an Adaptive Card for the sign-in. In a personal chat, the card includes the sign-in link and any confirmation code. In group chats and channels, the shared card only says who has to sign in and has a **Sign in** button (`Action.Execute`). When someone presses it, eve resolves who they are the same way it does for HITL answers (`onAnswers`). If that's the person who needs to sign in, eve sends back a card with the link and code, and Teams shows that card only to them. Anyone else is told they can't open it. That way another member can't finish the sign-in with their own account and have it saved under the requester's identity.
93
+ When a connection needs the person to sign in, eve posts an Adaptive Card:
97
94
 
98
- If you customize `onMessage` without also setting `onAnswers`, nobody can open a sign-in from a group chat or channel, because eve rejects every press.
95
+ - **In a personal chat**, the card has the sign-in link and any confirmation code.
96
+ - **In group chats and channels**, the shared card says who has to sign in and has a **Sign in** button (`Action.Execute`). eve identifies whoever presses it through `onAnswers`. The requester gets a card with the link and code that only they can see. Anyone else is told they can't open it, so no other member can save their account under the requester's identity.
99
97
 
100
- For invokes that aren't HITL, handle them in `onInvoke(ctx, activity)`.
98
+ If you customize `onMessage` without setting `onAnswers`, eve rejects every press, so nobody can open a sign-in from a group chat or channel.
101
99
 
102
100
  ### Proactive sessions
103
101
 
104
- Proactive sessions need an existing conversation reference, because the Bot Framework v1 surface cannot create new chats by Azure Active Directory (AAD) user id. Pass `serviceUrl`, `conversationId`, and the other reference fields to `receive(teams, { target })`.
102
+ Proactive sessions need an existing conversation reference, because the Bot Framework v1 API can't create chats by Azure Active Directory (AAD) user id. Pass `serviceUrl`, `conversationId`, and the other reference fields as the target. Call `to(teams, target).send(message, { auth })` from a schedule `run` handler, or `ctx.to(teams, target).send(message, { auth })` from another channel.
105
103
 
106
104
  ### Attachments
107
105
 
108
- Inbound files reach the agent as file parts. eve downloads images pasted into a message from Microsoft Bot Connector hosts with your bot credentials, and files uploaded in a personal chat from their pre-authenticated SharePoint download URL (`*.sharepoint.com` or `*.sharepoint.us`). A failed download, or one over the upload limit (25 MB unless `files.uploadPolicy` sets `maxBytes`), reaches the agent as a short note. Personal-chat uploads need `supportsFiles: true` on the bot in your Teams app manifest.
106
+ Inbound files reach the agent as files:
107
+
108
+ - eve downloads pasted images from Microsoft Bot Connector hosts with your bot credentials.
109
+ - eve downloads personal-chat uploads from their pre-authenticated SharePoint URL (`*.sharepoint.com` or `*.sharepoint.us`). They need `supportsFiles: true` on the bot in your Teams app manifest.
110
+ - A failed download, or a file over the upload limit (25 MB unless `files.uploadPolicy` sets `maxBytes`), reaches the agent as a short note.
109
111
 
110
- Use `allowedHosts` to download from other hosts, unauthenticated, or `enabled: false` to drop attachments:
112
+ Use `allowedHosts` to download from other hosts without credentials, or `enabled: false` to drop attachments:
111
113
 
112
114
  ```ts
113
115
  export default teamsChannel({
@@ -115,7 +117,19 @@ export default teamsChannel({
115
117
  });
116
118
  ```
117
119
 
120
+ ## Options
121
+
122
+ | Option | Default | What it does |
123
+ | -------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------- |
124
+ | `credentials` | `MICROSOFT_APP_ID`, `MICROSOFT_APP_PASSWORD`, `MICROSOFT_TENANT_ID` | Bot credentials, or `connectTeamsCredentials()`. |
125
+ | `route` | `/eve/v1/teams` | Path of the messaging endpoint. |
126
+ | `onMessage(ctx, message)` | Personal chats and mentions, as the sender | Returns `{ auth }` to run the agent, or `null` to ignore the message. |
127
+ | `onAnswers(ctx, activity)` | The user who clicked; rejects all with a custom `onMessage` | Decides who a card submission or **Sign in** press comes from. |
128
+ | `onInvoke(ctx, activity)` | `200 OK` | Handles Teams invokes that aren't card submissions or sign-ins. |
129
+ | `files` | Downloads from Microsoft hosts, up to 25 MB | `allowedHosts`, `uploadPolicy`, and `enabled` for inbound files. |
130
+ | `events` | Built-in handlers | Replaces the default handler for each event you set. |
131
+
118
132
  ## What to read next
119
133
 
120
- - [Channels overview](./overview): the channel contract and every built-in channel
134
+ - [Channels overview](./overview): what every channel shares, and every built-in channel
121
135
  - [Auth & route protection](../guides/auth-and-route-protection): authenticating inbound traffic
@@ -4,7 +4,7 @@ description: "Reach your agent from Telegram bot webhooks, with inline-keyboard
4
4
  type: integration
5
5
  ---
6
6
 
7
- The Telegram channel puts your agent behind a Telegram bot. It takes Bot API webhooks, checks the `X-Telegram-Bot-Api-Secret-Token` header before trusting anything, and routes the messages it cares about (private chats plus group messages that address the bot) to a reply over `sendMessage`. See [Channels](./overview) for the contract this builds on.
7
+ The Telegram channel runs your agent as a Telegram bot. It lives in `agent/channels/telegram.ts`. It checks the `X-Telegram-Bot-Api-Secret-Token` header on each Bot API webhook, and replies with `sendMessage`. See [Channels](./overview) for what every channel shares.
8
8
 
9
9
  ## Add the channel
10
10
 
@@ -21,7 +21,7 @@ TELEGRAM_BOT_TOKEN=123456:... # replies, typing, callbacks, proactive sen
21
21
  TELEGRAM_WEBHOOK_SECRET_TOKEN=... # must match the secret_token you register
22
22
  ```
23
23
 
24
- You can pass the same values via `credentials: { botToken, webhookSecretToken }`. The channel mounts `POST /eve/v1/telegram`. Register the deployed URL yourself; eve does not call `setWebhook`:
24
+ Or pass them as `credentials: { botToken, webhookSecretToken }`. The channel mounts `POST /eve/v1/telegram`. eve doesn't call `setWebhook`, so register the deployed URL yourself:
25
25
 
26
26
  ```bash
27
27
  curl -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \
@@ -35,13 +35,13 @@ curl -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \
35
35
 
36
36
  ### Dispatch
37
37
 
38
- In a private chat, text, captions, photos, and documents all go through. Groups are stricter. Only three things wake the bot: a command (`/ask`, `/ask@my_bot`), an `@my_bot` mention (when `botUsername` is set), or a reply to one of the bot's own messages. Everything else is ignored.
38
+ In a private chat, text, captions, photos, and documents all reach the agent. In a group, only a command (`/ask`, `/ask@my_bot`), an `@my_bot` mention (when `botUsername` is set), or a reply to one of the bot's messages does.
39
39
 
40
- The model-visible `<telegram_context>` includes `bot_username` and `is_mentioned`. `is_mentioned` is `true` only for an exact `@bot_username` token or targeted command such as `/ask@my_bot`; other accepted messages set it to `false`.
40
+ The model sees a `<telegram_context>` block with `bot_username` and `is_mentioned`. `is_mentioned` is `true` only for an exact `@bot_username` token or a targeted command such as `/ask@my_bot`.
41
41
 
42
- Forum topics carry `message_thread_id` in the continuation token, so each topic stays on its own thread.
42
+ Each forum topic gets its own session, keyed by `message_thread_id`.
43
43
 
44
- To customize auth or filtering, override `onMessage`. Return `title` alongside `auth` to set the title when the dispatch starts a run. Group privacy mode itself lives in BotFather, not here.
44
+ Override `onMessage` to choose which messages run the agent, and as whom. Return `{ auth }` to run it, optionally with `title` to set the run title. Set group privacy mode in BotFather.
45
45
 
46
46
  Custom `onMessage` hooks can import `defaultTelegramAuth` from
47
47
  `eve/channels/telegram` and return `{ auth: defaultTelegramAuth(message) }` to
@@ -51,23 +51,23 @@ For a button press, pass the button presser as `from`, not the message's author.
51
51
 
52
52
  ### Delivery
53
53
 
54
- The default `content.completed` handler sends each reply part as plain text via `sendMessage`. It passes no `parse_mode`, so any Markdown shows up literally. Replies longer than Telegram's 4096-char limit are split across messages. Custom handlers use `ctx.channel.telegram`.
54
+ By default, the bot sends each reply as plain text with `sendMessage` and no `parse_mode`, so Markdown shows as typed. Replies over Telegram's 4096-character limit are split across messages. Custom handlers use `ctx.channel.telegram`.
55
55
 
56
56
  ### Human-in-the-loop (HITL)
57
57
 
58
- Human-in-the-loop (HITL) turns option requests into inline-keyboard buttons and freeform requests into `ForceReply`. Telegram caps `callback_data` at 64 bytes, so eve keeps compact callback ids in channel state instead. It acknowledges its own callbacks with `answerCallbackQuery`; anything it doesn't recognize goes to `onCallbackQuery`. A press on a prompt whose session is no longer active replaces the keyboard with `No longer active`, and the acknowledgement tells the person to send a new message.
58
+ Approvals and questions with options render as inline-keyboard buttons, and free-text questions as `ForceReply`. eve acknowledges its own callbacks with `answerCallbackQuery` and passes others to `onCallbackQuery`. A press on a prompt whose session has ended replaces the keyboard with `No longer active` and tells the person to send a new message.
59
59
 
60
- A text reply to a bot message is sent as a normal message, with the replied-to message id in `state.replyToBotMessageId`. When that id matches a pending `ForceReply` prompt, the channel's `deliver` hook turns the reply into the answer. Otherwise the reply reaches the agent as a message, and starts a new session when none owns the thread.
60
+ A text reply to a pending `ForceReply` prompt answers it. A reply to any other bot message reaches the agent as a new message. It starts a new session when no session answers in that thread.
61
61
 
62
62
  ### Proactive sessions
63
63
 
64
- Start a session without an inbound message through `to(telegram, target).send(message, { auth })` from a schedule `run` handler, or `ctx.to(telegram, target).send(message, { auth })` from another channel. `target.chatId` is required. Add `messageThreadId` to land in a specific forum topic.
64
+ To start a session without an incoming message, call `to(telegram, target).send(message, { auth })` from a schedule `run` handler, or `ctx.to(telegram, target).send(message, { auth })` from another channel. `target.chatId` is required; add `messageThreadId` to post in a forum topic.
65
65
 
66
- Private proactive chats stay keyed to the chat, or to the chat plus `messageThreadId` when you target a topic. Group and supergroup proactive sends anchor to the bot message id returned by Telegram, so replies to different bot messages can resume different sessions in the same chat. If Telegram does not return a recognized chat type for an outbound send, eve keeps the session unanchored instead of guessing.
66
+ A private-chat session is keyed to the chat, or the chat and topic. A group or supergroup session is keyed to the bot message Telegram returns. Replies to different bot messages can resume different sessions in one chat. If Telegram returns no recognized chat type, the session stays unanchored.
67
67
 
68
68
  ### Attachments
69
69
 
70
- Inbound photos and documents are supported. eve fetches them on demand via `getFile`, only when an upload policy allows the type:
70
+ Inbound photos and documents reach the agent when `uploadPolicy` allows their type. eve downloads them with `getFile`. Omit `uploadPolicy` to accept any type up to 25 MB:
71
71
 
72
72
  ```ts
73
73
  export default telegramChannel({
@@ -78,5 +78,5 @@ export default telegramChannel({
78
78
 
79
79
  ## What to read next
80
80
 
81
- - [Channels overview](./overview): the channel contract and every built-in channel
81
+ - [Channels overview](./overview): what every channel shares, and every built-in channel
82
82
  - [Auth & route protection](../guides/auth-and-route-protection): authenticating inbound traffic
@@ -4,7 +4,7 @@ description: "Reach your agent over SMS and speech-transcribed phone calls with
4
4
  type: integration
5
5
  ---
6
6
 
7
- The Twilio channel puts your agent on a phone number, so people can text it or call it. Inbound SMS arrives as a webhook. Inbound calls are answered with TwiML `<Gather input="speech">`, and the resulting transcript feeds the same eve session that SMS uses, so a caller and a texter look identical downstream. Every request is checked against `X-Twilio-Signature` before anything else runs. The raw continuation token is `From:To`. See [Channels](./overview) for the contract this builds on.
7
+ The Twilio channel puts your agent on a phone number that people can text or call. It lives in `agent/channels/twilio.ts`. eve answers calls with TwiML `<Gather input="speech">`. The transcript joins the same eve session as SMS from that number, keyed by `From:To`. eve checks `X-Twilio-Signature` on every request first. See [Channels](./overview) for what every channel shares.
8
8
 
9
9
  ## Add the channel
10
10
 
@@ -22,25 +22,25 @@ TWILIO_ACCOUNT_SID=AC... # required for default outbound SMS
22
22
  TWILIO_AUTH_TOKEN=... # required for inbound signature verification
23
23
  ```
24
24
 
25
- To skip env vars, pass the same values via `credentials: { accountSid, authToken }`. The channel mounts three routes:
25
+ Or pass them as `credentials: { accountSid, authToken }`. The channel mounts three routes:
26
26
 
27
27
  - `POST /eve/v1/twilio/messages`: Messaging webhook
28
28
  - `POST /eve/v1/twilio/voice`: inbound call webhook
29
29
  - `POST /eve/v1/twilio/voice/transcription`: speech transcript callback
30
30
 
31
- Point your Twilio number's Messaging webhook at `/messages` and Voice webhook at `/voice`, using the exact public URL Twilio will call.
31
+ Point your Twilio number's Messaging webhook at `/messages` and Voice webhook at `/voice`, using the exact public URL Twilio calls.
32
32
 
33
33
  ## How the channel handles messages
34
34
 
35
35
  ### Dispatch
36
36
 
37
- `allowFrom` is required. It gates who can reach the inbound hooks. Pass a single number, a list, an async resolver, or `"*"`. The wildcard is dangerous; only use it with an explicit check inside `onText`/`onVoice`.
37
+ `allowFrom` is required and decides which phone numbers reach `onText`, `onVoice`, and `onVoiceTranscription`. Pass a number, a list, an async resolver, or `"*"`. The wildcard admits any caller, so use it only with an explicit check in `onText` and `onVoice`.
38
38
 
39
39
  ```ts
40
40
  export default twilioChannel({ allowFrom: ["+15551234567", "+15557654321"] });
41
41
  ```
42
42
 
43
- `onText` and `onVoiceTranscription` decide dispatch and `auth`. Return `{ auth }` to proceed, `null` to drop the message, or `title` alongside `auth` to set the title when the dispatch starts a run. `onVoice` fires the moment a call comes in. Return `null` to reject it, or return an object to override the spoken prompt, language, `<Say voice>`, and speech-recognition options.
43
+ `onText` and `onVoiceTranscription` decide whether a message runs the agent, and as whom. Return `{ auth }` to run it, optionally with `title` to set the run title, or `null` to ignore the message. `onVoice` fires when a call comes in. Return `null` to reject it, or an object to override the spoken prompt, language, `<Say voice>`, and speech-recognition options.
44
44
 
45
45
  ```ts
46
46
  export default twilioChannel({
@@ -58,27 +58,27 @@ export default twilioChannel({
58
58
 
59
59
  ### Delivery
60
60
 
61
- The default `content.completed` handler sends each reply part as SMS through Twilio's Messages API. A reply to an inbound message can reuse the webhook's `To` as the sender, but a proactive send has nothing to reuse, so it needs `messaging.from` or `messaging.messagingServiceSid`. Behind a proxy, set `webhookUrl` so signature verification matches the exact configured URL, and `publicBaseUrl` so voice TwiML can build absolute callback URLs.
61
+ By default, the bot sends each reply as SMS through Twilio's Messages API. A reply to an inbound message can use the webhook's `To` as the sender; a proactive send needs `messaging.from` or `messaging.messagingServiceSid`. Behind a proxy, set `webhookUrl` so signature verification matches the configured URL, and `publicBaseUrl` so voice TwiML builds absolute callback URLs.
62
62
 
63
63
  ### Human-in-the-loop (HITL)
64
64
 
65
- SMS has no buttons or cards, so the default `interaction.opened` handler sends each question and tool approval as an SMS with its options numbered. A reply with an option's number or label answers the pending request, so `1` or `approve` runs an approval-gated tool and `2` or `cancel` stops it. If the question allows a custom answer, any other text is taken as that answer. Callers on a voice call get the question by SMS too. To render questions differently, declare your own `events["interaction.opened"]` handler.
65
+ By default, each question and tool approval goes out as an SMS with numbered options, including to callers on a voice call. A reply with an option's number or label answers the request, so `1` or `approve` runs an approval-gated tool and `2` or `cancel` stops it. If the question allows a custom answer, any other text is taken as the answer. To render questions differently, set `events["interaction.opened"]`.
66
66
 
67
67
  ### Proactive sessions
68
68
 
69
- Start a session without an inbound message through `to(twilio, target).send(message, { auth })` from a schedule `run` handler, or `ctx.to(twilio, target).send(message, { auth })` from another channel. `target.phoneNumber` is required, and the channel needs `messaging.from` or `messaging.messagingServiceSid` for the outbound sender.
69
+ To start a session without an incoming message, call `to(twilio, target).send(message, { auth })` from a schedule `run` handler, or `ctx.to(twilio, target).send(message, { auth })` from another channel. `target.phoneNumber` is required, and the channel needs `messaging.from` or `messaging.messagingServiceSid` as the sender.
70
70
 
71
71
  ### Attachments
72
72
 
73
- MMS media reaches the agent as file parts. eve downloads each media URL with the account SID and auth token, and only from the Twilio API origin (`https://api.twilio.com`, or `api.apiBaseUrl` when set). If a download fails, the agent gets a short note in place of the file and the text turn continues.
73
+ MMS media reaches the agent as file parts. eve downloads each media URL with the account SID and auth token, only from the Twilio API origin (`https://api.twilio.com`, or `api.apiBaseUrl` when set). A failed download becomes a short note, and the turn continues.
74
74
 
75
75
  ## Disclaimer
76
76
 
77
77
  As the deployer, it is your responsibility to ensure your agent complies with applicable laws.
78
78
 
79
- For example, you may be required to inform callers and texters that calls are recorded/transcribed and processed by an automated AI system, and obtain consent where required (including two-party-consent jurisdictions). For outbound SMS or calls you initiate, you may be required to get prior express consent, honor STOP/opt-out and quiet-hour rules, and complete required carrier registration.
79
+ For example, you may need to tell callers and texters that an automated AI system records, transcribes, and processes their calls. You may also need their consent, including in two-party-consent jurisdictions. For outbound SMS or calls you start, you may need prior express consent. You may also need to honor STOP/opt-out and quiet-hour rules and complete carrier registration.
80
80
 
81
81
  ## What to read next
82
82
 
83
- - [Channels overview](./overview): the channel contract and every built-in channel
83
+ - [Channels overview](./overview): what every channel shares, and every built-in channel
84
84
  - [Auth & route protection](../guides/auth-and-route-protection): authenticating inbound traffic
@@ -3,7 +3,7 @@ title: "Code Extension"
3
3
  description: "Mount eve's coding extension, eve-code, and see its latest benchmark results against other coding agent harnesses."
4
4
  ---
5
5
 
6
- `eve/extensions/code` (eve-code) turns an eve agent into a coding agent. It ships inside the `eve` package, so you mount it without installing anything else. The extension contributes file-editing and search tools, coding skills, a read-only worker subagent, and sandbox bootstrap helpers. GitHub and pull request work lives in the companion [`eve/extensions/git`](#publish-with-the-git-extension) extension.
6
+ `eve/extensions/code` (eve-code) turns an eve agent into a coding agent. It ships inside the `eve` package, so you mount it without installing anything else. The extension adds file-editing and search tools, coding skills, a read-only worker subagent, and helpers that install coding tools in the sandbox. GitHub and pull request work lives in the companion [`eve/extensions/git`](#publish-with-the-git-extension) extension.
7
7
 
8
8
  ## Benchmark results
9
9
 
@@ -15,7 +15,7 @@ description: "Mount eve's coding extension, eve-code, and see its latest benchma
15
15
  | `eve-code` | 67% (24/36) | 53%–81% | 235.4s | 389.7s | 2026-09-30 |
16
16
  | `opencode` | 50% (18/36) | 28%–72% | 611.7s | 1170.3s | 2026-09-30 |
17
17
 
18
- These results show baseline performance. Each harness uses its standard setup with high reasoning. The results do not show how a harness performs with other models, settings, or tasks.
18
+ These results show baseline performance, with each harness in its standard setup and high reasoning. Other models, settings, or tasks can perform differently.
19
19
 
20
20
  <details>
21
21
  <summary>How the benchmark works</summary>
@@ -39,16 +39,16 @@ The line on each correctness row shows the 95% interval. When the lines of two h
39
39
 
40
40
  1. A maintainer runs the `eve-code` workflow on `main` with the `deepswe-lean` dataset.
41
41
  2. The workflow runs eve-code, opencode, and pi. It saves each complete result in the eve-bench result store.
42
- 3. The workflow writes a summary of the result to `apps/docs/lib/evals/eve-code-benchmark.json`. Then it commits the file to `main`.
42
+ 3. The workflow commits a summary of the result to `main`.
43
43
  4. The next docs deployment shows the new results.
44
44
 
45
- The workflow does not publish incomplete runs, single-task runs, or pull request runs. Results can be older than `main`, because a maintainer starts each run. Select a harness name to open the GitHub Actions run for that result.
45
+ The workflow skips incomplete runs, single-task runs, and pull request runs. Results can be older than `main`, because a maintainer starts each run. Select a harness name to open the GitHub Actions run for that result.
46
46
 
47
47
  </details>
48
48
 
49
49
  ## Mount the extension
50
50
 
51
- Create an extension file in your agent. The file name sets the mount name, which prefixes every contributed tool and subagent ID (for example, `code__grep`):
51
+ Create an extension file in your agent. The file name sets the prefix of every tool and subagent the extension adds, such as `code__grep`:
52
52
 
53
53
  ```ts title="agent/extensions/code.ts"
54
54
  import code from "eve/extensions/code";
@@ -56,17 +56,17 @@ import code from "eve/extensions/code";
56
56
  export default code({});
57
57
  ```
58
58
 
59
- `code({})` mounts the extension without Vercel authentication. Add the options below when the agent needs them.
59
+ `code({})` mounts the extension without Vercel authentication. Omit `worker` to run the `worker` subagent on `openai/gpt-5.6-terra-fast` with `xhigh` reasoning.
60
60
 
61
61
  ## Configure the extension
62
62
 
63
63
  | Option | Required | Effect |
64
64
  | ------------------------------ | ------------- | ---------------------------------------------------------------------------------------------- |
65
- | `vercel.connector` | With `vercel` | Connector that requests an app-subject Vercel token |
65
+ | `vercel.connector` | With `vercel` | Vercel Connect connector that gets a Vercel token for the app, not for a user |
66
66
  | `vercel.delivery` | No | `"firewall"` (default) or `"command"` |
67
67
  | `broker` | No | `broker(sandbox, rules)` callback that merges Vercel credential rules into your network policy |
68
- | `worker.model` | With `worker` | Model for the `worker` subagent. Defaults to `openai/gpt-5.6-terra-fast` |
69
- | `worker.reasoning` | With `worker` | Reasoning level for the `worker` subagent. Defaults to `xhigh` |
68
+ | `worker.model` | With `worker` | Model for the `worker` subagent |
69
+ | `worker.reasoning` | With `worker` | Reasoning level for the `worker` subagent |
70
70
  | `worker.openaiReasoningEffort` | No | Passed to OpenAI models as `reasoningEffort` |
71
71
 
72
72
  ```ts title="agent/extensions/code.ts"
@@ -80,13 +80,13 @@ export default code({
80
80
 
81
81
  ### Credentials stay outside the sandbox
82
82
 
83
- With firewall delivery, Vercel tokens never enter sandbox processes. Firewall delivery without a top-level `broker` requires a sandbox provider that exposes `setNetworkPolicy()`, and fails otherwise. Set `vercel.delivery: "command"` for providers without a mutable network policy.
83
+ With firewall delivery, Vercel tokens never enter sandbox processes. Firewall delivery needs a top-level `broker` or a sandbox provider with `setNetworkPolicy()`. For other providers, set `vercel.delivery: "command"`.
84
84
 
85
- To use a personal access token or another credential provider, omit the connector and call `authenticateGitHub` or `authenticateVercel` from `eve/extensions/code/sandbox` in your own sandbox lifecycle. These helpers authenticate commands you run yourself; they do not configure the `gh` tool.
85
+ To use a personal access token or another credential provider, omit the connector. Call `authenticateGitHub` or `authenticateVercel` from `eve/extensions/code/sandbox` in your own sandbox setup code. These helpers authenticate commands you run yourself, not the `gh` tool.
86
86
 
87
87
  ## Publish with the git extension
88
88
 
89
- `eve/extensions/git` contributes the GitHub instructions and the `pr` skill. Mount it next to the code extension when the agent should open pull requests:
89
+ `eve/extensions/git` adds the GitHub instructions and the `pr` skill. Mount it next to the code extension when the agent should open pull requests. `code()` rejects a `github` option, so configure GitHub here. Import `gh` and the GitHub sandbox helpers from `eve/extensions/git/tools` and `eve/extensions/git/sandbox`:
90
90
 
91
91
  ```ts title="agent/extensions/git.ts"
92
92
  import git from "eve/extensions/git";
@@ -94,9 +94,9 @@ import git from "eve/extensions/git";
94
94
  export default git({});
95
95
  ```
96
96
 
97
- `git({})` assumes the agent's shell already has GitHub credentials. The agent uses the `gh` and `git` CLIs in `bash`, and `git__pr` commits, pushes, and opens a draft with `gh pr create --draft`. No tool is added.
97
+ `git({})` adds no tool and assumes the agent's shell already has GitHub credentials. The agent uses the `gh` and `git` CLIs in `bash`, and `git__pr` commits, pushes, and opens a draft with `gh pr create --draft`.
98
98
 
99
- Configure `github` to broker GitHub access through Connect instead. The extension then adds the authenticated `git__gh` tool, tells the agent to use it for every authenticated GitHub operation, and switches `git__pr` to `gh-signed-commit` for repositories that require verified signatures.
99
+ Configure `github` to get GitHub tokens through Vercel Connect instead. The extension then adds the authenticated `git__gh` tool and tells the agent to use it for every authenticated GitHub operation. `git__pr` switches to `gh-signed-commit` for repositories that require verified signatures.
100
100
 
101
101
  | Option | Required | Effect |
102
102
  | ---------------------- | ------------- | ------------------------------------------------------------------------------------------ |
@@ -106,14 +106,18 @@ Configure `github` to broker GitHub access through Connect instead. The extensio
106
106
  | `github.authorize` | With `github` | `authorize(request)` returns `true` to let a `gh` call run |
107
107
  | `github.attribution` | No | `attribution(ctx)` returns the current turn's `{ name, email }` co-author, or `null` |
108
108
 
109
- Each `gh` call runs one `gh`, `git`, or `gh-signed-commit` command. The sandbox process receives a placeholder `GH_TOKEN`, and the firewall exchanges it on matching GitHub requests. Your `github.broker` callback receives the header-transform rules for the command, then `null` to remove the lease. The callback must preserve your other network rules. GitHub authentication has no command-delivery option.
109
+ Each `gh` call runs one `gh`, `git`, or `gh-signed-commit` command. Processes in the sandbox see only a placeholder `GH_TOKEN`. The sandbox firewall replaces it with the real token on GitHub requests. Your `github.broker` callback receives the header rules before the command runs, then `null` after it to remove them. The callback must keep your other network rules. GitHub authentication has no `"command"` delivery option.
110
110
 
111
111
  ### Control access with `authorize`
112
112
 
113
- `github.authorize` is the agent's only access control: a command runs only when it returns `true`, and the token never reaches the sandbox otherwise. It runs before every `gh` call with the parsed `argv`, the caller's `auth`, the `repository` the call declared (or `null`), and the minted `token`. What the token reaches depends on `principalType`:
113
+ `github.authorize` is the agent's only access control. A command runs only when it returns `true`; otherwise the token never reaches the sandbox. It runs before every `gh` call and receives the parsed `argv`, the caller's `auth`, the declared `repository` (or `null`), and the minted `token`. What the token can reach depends on `principalType`:
114
114
 
115
- - **`"app"`**: a GitHub App installation token for the declared repository, or for the whole installation when the call declares only an owner. `authorize` also receives that `owner`.
116
- - **`"user"`**: the caller's own token, which reaches whatever the caller can on GitHub. eve signs the caller in when needed and again when GitHub rejects the token. `authorize` receives no `owner`, because the token is not scoped to one. `repository` is only what the model declared, and nothing ties it to the command, so it is a hint, not a boundary. Gate user-mode calls on `auth` instead, for example `({ auth }) => auth !== null`.
115
+ | `principalType` | Token | `authorize` also receives |
116
+ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
117
+ | `"app"` | A GitHub App installation token for the declared repository, or for the whole installation when the call declares only an owner. | `owner` |
118
+ | `"user"` | The caller's own token, which reaches everything the caller can reach on GitHub. eve asks the caller to sign in when needed and when GitHub rejects the token. | No `owner` |
119
+
120
+ With `"user"`, `repository` is only what the model declared, and nothing ties it to the command. Treat it as a hint, not a boundary, and check `auth` instead, for example `({ auth }) => auth !== null`.
117
121
 
118
122
  ```ts title="agent/extensions/git.ts"
119
123
  import git from "eve/extensions/git";
@@ -132,14 +136,14 @@ export default git({
132
136
 
133
137
  ### Credit the person behind a turn
134
138
 
135
- Commits made by the `gh` tool are authored by the GitHub App. Return a verified user mapping from
136
- `github.attribution` to add that person's `Co-authored-by` trailer to `gh-signed-commit` messages
137
- and `gh pr create` bodies passed through `--body` or `--body-file`. The callback receives the tool
138
- context, including `ctx.session.auth.current` and `ctx.getToken`. Return `null` to omit attribution.
139
- Existing co-author trailers are preserved; commands without a body flag and direct `gh api` calls
140
- are not attributed.
139
+ The GitHub App is the author of commits that the `gh` tool makes. Return a verified user from
140
+ `github.attribution` to add that person's `Co-authored-by` trailer. eve adds it to
141
+ `gh-signed-commit` messages and to `gh pr create` bodies passed through `--body` or `--body-file`.
142
+ The callback receives the tool context, including `ctx.session.auth.current` and `ctx.getToken`.
143
+ Return `null` to omit attribution. eve keeps existing co-author trailers. Commands without a body
144
+ flag and direct `gh api` calls get no attribution.
141
145
 
142
- For example, resolve the author through your application's authenticated user mapping:
146
+ For example, resolve the author through your application's user mapping:
143
147
 
144
148
  ```ts title="agent/extensions/git.ts"
145
149
  import git from "eve/extensions/git";
@@ -156,16 +160,9 @@ export default git({
156
160
  });
157
161
  ```
158
162
 
159
- ### Migrate from `code({ github })`
160
-
161
- `code({ github })` is rejected. Move the `github` option to `git({ github })`, and import `gh` and the GitHub sandbox helpers from `eve/extensions/git/tools` and `eve/extensions/git/sandbox`.
162
-
163
163
  ## Override bundled tools
164
164
 
165
- `eve/extensions/code/tools` exports the reusable `apply_patch` and `grep` tool
166
- definitions. Import one in an override to change approval or other tool options
167
- without copying its implementation. With the file mount above, put the override
168
- in the agent-root slot named after the qualified tool, `code__apply_patch`:
165
+ `eve/extensions/code/tools` exports the `apply_patch` and `grep` tool definitions. Import one in an override to change its approval or other options without copying the implementation. With the file mount above, name the override after the qualified tool, `code__apply_patch`:
169
166
 
170
167
  ```ts title="agent/tools/code__apply_patch.ts"
171
168
  import { apply_patch } from "eve/extensions/code/tools";
@@ -175,15 +172,9 @@ import { always } from "eve/tools/approval";
175
172
  export default defineTool({ ...apply_patch, approval: always() });
176
173
  ```
177
174
 
178
- `agent/extensions/code/tools/apply_patch.ts` works only when the mount is a
179
- directory, `agent/extensions/code/extension.ts`.
175
+ `agent/extensions/code/tools/apply_patch.ts` works only when the mount is a directory, `agent/extensions/code/extension.ts`.
180
176
 
181
- For a custom GitHub command tool, `eve/extensions/git/sandbox` exports
182
- `executeGitHubShell(input, config, dependencies)` and `githubShellApproval(input)`.
183
- The execution helper parses the command, calls `authorize`, and brokers a
184
- credential lease; dependencies supply the session ID and sandbox access. Reuse
185
- `githubShellApproval` to reject invalid command inputs through the approval
186
- policy rather than bypassing those constraints.
177
+ For a custom GitHub command tool, `eve/extensions/git/sandbox` exports `executeGitHubShell(input, config, dependencies)` and `githubShellApproval(input)`. `executeGitHubShell` parses the command, calls `authorize`, and installs the credential rules. `dependencies` supply the session ID and sandbox access. Use `githubShellApproval` as the tool's approval policy so invalid commands are still rejected.
187
178
 
188
179
  ## Prepare the sandbox
189
180
 
@@ -205,7 +196,14 @@ export default defineSandbox(() => environment.open());
205
196
 
206
197
  Preparation installs `gh`, wrappers for `gh`, `vc`, and `gh-signed-commit`, and TypeScript diagnostics. With the git extension's `github` configured, repositories that require verified signatures can use `gh-signed-commit` through the `gh` tool after staging changes.
207
198
 
208
- eve derives the prepared environment generation from the sandbox file and environment options, not from imported helpers. Upgrading eve alone does not rebuild an existing prepared environment.
199
+ eve rebuilds a prepared environment only when the sandbox file or environment options change. A change to an imported helper or to the eve version doesn't rebuild it.
200
+
201
+ ## Troubleshooting
202
+
203
+ | What you see | What to do |
204
+ | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
205
+ | `eve-code firewall credential delivery requires a sandbox provider with mutable network policy (setNetworkPolicy).` | Set `vercel.delivery: "command"`, or pass a top-level `broker` callback. |
206
+ | `The current caller is not authorized to access <repository>.` | Your `github.authorize` callback returned `false` for that caller and repository. Check the callback's rule. |
209
207
 
210
208
  ## What to read next
211
209