eve 0.84.1 → 0.86.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +7 -4
- package/dist/CHANGELOG.md +38 -0
- package/dist/src/channel/channel-operations.d.ts +2 -18
- package/dist/src/channel/compiled-channel.d.ts +3 -7
- package/dist/src/channel/cross-channel-receive.d.ts +9 -10
- package/dist/src/channel/cross-channel-receive.js +1 -1
- package/dist/src/channel/schedule.js +1 -1
- package/dist/src/channel/session.d.ts +26 -4
- package/dist/src/channel/session.js +1 -1
- package/dist/src/chunks/{use-eve-agent-DMeP0JOF.js → use-eve-agent-B2jCfcnG.js} +3 -2
- package/dist/src/chunks/{use-eve-agent-DP5Rso9C.js → use-eve-agent-DCLFi26P.js} +3 -2
- package/dist/src/cli/commands/agent-prompt/collect-intent.md +2 -1
- package/dist/src/cli/commands/agent-prompt/scaffold.md +1 -2
- package/dist/src/cli/dev/tui/runner.d.ts +1 -1
- package/dist/src/cli/dev/tui/runner.js +1 -1
- package/dist/src/cli/run.js +1 -1
- package/dist/src/client/client.js +1 -1
- package/dist/src/client/open-stream.js +1 -1
- package/dist/src/client/types.d.ts +5 -4
- package/dist/src/compiled/.vendor-stamp.json +4 -4
- package/dist/src/compiled/@vercel/schedules/index.d.ts +45 -6
- package/dist/src/compiled/@vercel/schedules/index.js +2 -2
- package/dist/src/context/keys.d.ts +7 -0
- package/dist/src/context/keys.js +1 -1
- package/dist/src/execution/agent-sessions/context.d.ts +5 -1
- package/dist/src/execution/agent-sessions/context.js +1 -1
- package/dist/src/execution/dynamic-workflow/tool.js +1 -1
- package/dist/src/execution/legacy-session/snapshot.d.ts +1 -2
- package/dist/src/execution/legacy-session/snapshot.js +1 -1
- package/dist/src/execution/proxied-deliver-step.js +1 -1
- package/dist/src/execution/public-destination.d.ts +3 -0
- package/dist/src/execution/public-destination.js +1 -1
- package/dist/src/execution/publish-session-events.js +1 -1
- package/dist/src/execution/session/active-turn.js +1 -1
- package/dist/src/execution/session/answer-caller.d.ts +9 -5
- package/dist/src/execution/session/answer-caller.js +1 -1
- package/dist/src/execution/session/checkpoint-migrations.d.ts +16 -5
- package/dist/src/execution/session/checkpoint-migrations.js +1 -1
- package/dist/src/execution/session/checkpoint-refusal.d.ts +4 -0
- package/dist/src/execution/session/checkpoint-refusal.js +1 -0
- package/dist/src/execution/session/entry.js +1 -1
- package/dist/src/execution/session/handoff-steps.d.ts +7 -1
- package/dist/src/execution/session/handoff-steps.js +1 -1
- package/dist/src/execution/session/imported-conversation.d.ts +2 -0
- package/dist/src/execution/session/imported-conversation.js +1 -0
- package/dist/src/execution/session/interrupted-step.js +1 -1
- package/dist/src/execution/session/pre-v27-checkpoint.d.ts +36 -0
- package/dist/src/execution/session/pre-v27-checkpoint.js +1 -0
- package/dist/src/execution/session/principal.d.ts +8 -0
- package/dist/src/execution/session/principal.js +1 -1
- package/dist/src/execution/session/program.d.ts +2 -0
- package/dist/src/execution/session/program.js +1 -1
- package/dist/src/execution/session/turn-step.js +1 -1
- package/dist/src/execution/session/turn.js +1 -1
- package/dist/src/execution/session-callback-request.js +1 -1
- package/dist/src/execution/tool-auth.js +1 -1
- package/dist/src/execution/tools/agent-router-workflow.js +1 -1
- package/dist/src/execution/tools/channel-to.d.ts +12 -0
- package/dist/src/execution/tools/channel-to.js +1 -0
- package/dist/src/execution/tools/workflow/body.d.ts +3 -0
- package/dist/src/execution/tools/workflow/body.js +1 -1
- package/dist/src/execution/tools/workflow/step-context.d.ts +5 -0
- package/dist/src/execution/tools/workflow/step-execution.js +1 -1
- package/dist/src/execution/tools/workflow/step.js +1 -1
- package/dist/src/execution/workflow-callback-url.d.ts +2 -3
- package/dist/src/execution/workflow-callback-url.js +1 -1
- package/dist/src/execution/workflow-runtime.js +1 -1
- package/dist/src/harness/attachment-staging.d.ts +2 -2
- package/dist/src/harness/attachment-staging.js +1 -1
- package/dist/src/harness/compaction/step.js +1 -1
- package/dist/src/harness/model-call/call.js +1 -1
- package/dist/src/harness/model-call/run.js +1 -1
- package/dist/src/harness/session-machine/transitions.js +1 -1
- package/dist/src/internal/application/stamped-package-version.js +1 -1
- package/dist/src/internal/attachments/limited-read.d.ts +2 -0
- package/dist/src/internal/attachments/limited-read.js +1 -1
- package/dist/src/internal/attachments/url-refs.js +1 -1
- package/dist/src/internal/capability-error.d.ts +3 -0
- package/dist/src/internal/capability-error.js +1 -0
- package/dist/src/internal/nitro/routes/schedule-collection-consumer.js +1 -1
- package/dist/src/public/channels/chat-sdk/chatSdkChannel.js +1 -1
- package/dist/src/public/channels/discord/discordChannel.js +1 -1
- package/dist/src/public/channels/github/githubChannel.js +1 -1
- package/dist/src/public/channels/linear/linearChannel.js +1 -1
- package/dist/src/public/channels/linq/inboundContent.js +1 -1
- package/dist/src/public/channels/slack/answers.d.ts +2 -3
- package/dist/src/public/channels/slack/answers.js +1 -1
- package/dist/src/public/channels/slack/api.d.ts +23 -3
- package/dist/src/public/channels/slack/api.js +1 -1
- package/dist/src/public/channels/slack/app-manifest.d.ts +2 -0
- package/dist/src/public/channels/slack/app-manifest.js +1 -1
- package/dist/src/public/channels/slack/auth.d.ts +2 -1
- package/dist/src/public/channels/slack/auth.js +1 -1
- package/dist/src/public/channels/slack/code-channel.d.ts +42 -0
- package/dist/src/public/channels/slack/code-channel.js +1 -0
- package/dist/src/public/channels/slack/defaults.d.ts +7 -3
- package/dist/src/public/channels/slack/defaults.js +3 -3
- package/dist/src/public/channels/slack/hitl.d.ts +7 -17
- package/dist/src/public/channels/slack/hitl.js +1 -1
- package/dist/src/public/channels/slack/index.d.ts +4 -3
- package/dist/src/public/channels/slack/index.js +1 -1
- package/dist/src/public/channels/slack/interaction-cards.d.ts +0 -2
- package/dist/src/public/channels/slack/interaction-cards.js +1 -1
- package/dist/src/public/channels/slack/interactions.js +1 -1
- package/dist/src/public/channels/slack/open-code-channel.d.ts +30 -0
- package/dist/src/public/channels/slack/open-code-channel.js +1 -0
- package/dist/src/public/channels/slack/private-approval-delivery.d.ts +16 -4
- package/dist/src/public/channels/slack/private-approval-delivery.js +1 -1
- package/dist/src/public/channels/slack/renderers.d.ts +58 -6
- package/dist/src/public/channels/slack/renderers.js +1 -1
- package/dist/src/public/channels/slack/reply-delivery.d.ts +4 -0
- package/dist/src/public/channels/slack/reply-delivery.js +1 -1
- package/dist/src/public/channels/slack/request-card-render.d.ts +45 -0
- package/dist/src/public/channels/slack/request-card-render.js +1 -0
- package/dist/src/public/channels/slack/request-cards.d.ts +35 -0
- package/dist/src/public/channels/slack/request-cards.js +3 -0
- package/dist/src/public/channels/slack/sign-in-cancel.d.ts +3 -5
- package/dist/src/public/channels/slack/sign-in-cancel.js +1 -1
- package/dist/src/public/channels/slack/slackChannel.d.ts +109 -22
- package/dist/src/public/channels/slack/slackChannel.js +1 -1
- package/dist/src/public/channels/slack/task-card.d.ts +3 -3
- package/dist/src/public/channels/slack/task-card.js +1 -1
- package/dist/src/public/channels/slack/thread-status.js +1 -1
- package/dist/src/public/channels/teams/api.js +1 -1
- package/dist/src/public/channels/teams/defaults.js +1 -1
- package/dist/src/public/channels/teams/teamsChannel.js +1 -1
- package/dist/src/public/channels/teams/verify.d.ts +9 -5
- package/dist/src/public/channels/teams/verify.js +1 -1
- package/dist/src/public/channels/telegram/telegramChannel.js +1 -1
- package/dist/src/public/channels/twilio/twilioChannel.js +1 -1
- package/dist/src/public/schedules/providers/vercel.d.ts +2 -0
- package/dist/src/public/schedules/providers/vercel.js +1 -1
- package/dist/src/public/schedules/subscription.d.ts +10 -1
- package/dist/src/runtime/subagents/workflow.js +1 -1
- package/dist/src/setup/index.d.ts +1 -1
- package/dist/src/setup/primitives/index.d.ts +1 -1
- package/dist/src/setup/primitives/pm/run.d.ts +0 -2
- package/dist/src/setup/scaffold/create/project.js +1 -1
- package/dist/src/shared/channel-definition.d.ts +4 -4
- package/dist/src/subagents/adapter.js +1 -1
- package/dist/src/subagents/parent-notification.js +1 -1
- package/dist/src/svelte/index.js +1 -1
- package/dist/src/svelte/use-eve-agent.js +1 -1
- package/dist/src/tools/definition.d.ts +21 -0
- package/dist/src/tools/provided/ask-question-workflow.js +1 -1
- package/dist/src/tools/provided/sleep-workflow.js +1 -1
- package/dist/src/tools/workflow-definition.d.ts +4 -4
- package/dist/src/vue/index.js +1 -1
- package/dist/src/vue/use-eve-agent.js +1 -1
- package/docs/channels/custom.mdx +16 -3
- package/docs/channels/eve.mdx +3 -5
- package/docs/channels/linq.mdx +1 -1
- package/docs/channels/slack.mdx +185 -18
- package/docs/channels/teams.mdx +6 -2
- package/docs/concepts/project-structure.mdx +1 -1
- package/docs/concepts/security-model.md +4 -0
- package/docs/concepts/upgrade-to-v27-events.md +70 -2
- package/docs/experimental/dynamic-schedules.mdx +2 -2
- package/docs/getting-started.mdx +2 -0
- package/docs/guides/auth-and-route-protection.md +1 -0
- package/docs/guides/client/overview.mdx +1 -1
- package/docs/guides/client/streaming.mdx +1 -1
- package/docs/guides/deployment/self-hosting.md +1 -1
- package/docs/guides/frontend/meta.json +1 -0
- package/docs/guides/frontend/nextjs.mdx +329 -121
- package/docs/guides/frontend/overview.mdx +115 -335
- package/docs/guides/frontend/tanstack.mdx +1 -1
- package/docs/guides/frontend/use-eve-agent-svelte.mdx +5 -5
- package/docs/guides/frontend/use-eve-agent-vue.mdx +5 -5
- package/docs/guides/frontend/use-eve-agent.mdx +385 -0
- package/docs/guides/hooks.md +1 -1
- package/docs/guides/remote-agents.md +10 -0
- package/docs/guides/self-modification.md +6 -0
- package/docs/patterns/fork-conversations-into-new-threads.md +159 -0
- package/docs/patterns/meta.json +1 -0
- package/docs/reference/cli.md +1 -2
- package/docs/sandbox/index.mdx +1 -1
- package/docs/schedules.mdx +1 -1
- package/docs/tools/overview.mdx +34 -0
- package/docs/tools/workflows.mdx +47 -5
- package/package.json +13 -21
- package/CHANGELOG.md +0 -3076
- package/dist/src/public/channels/slack/approval-cards.d.ts +0 -25
- package/dist/src/public/channels/slack/approval-cards.js +0 -2
- package/dist/src/self-modification/agent.d.ts +0 -12
- package/dist/src/self-modification/agent.js +0 -1
package/docs/channels/slack.mdx
CHANGED
|
@@ -106,12 +106,13 @@ Message hooks return `{ auth }` to dispatch, `null` to drop, `{ auth, context }`
|
|
|
106
106
|
- `onAppMention(ctx, message)` handles only `app_mention` and takes precedence over `onMessage`. Its default derives workspace-scoped auth.
|
|
107
107
|
- `onDirectMessage(ctx, message)` handles only DMs and takes precedence over `onMessage`. Bot-authored messages and edits are filtered first; Slack requires `message.im` and `im:history`.
|
|
108
108
|
|
|
109
|
-
| Incoming event
|
|
110
|
-
|
|
|
111
|
-
| App mention
|
|
112
|
-
| Direct message
|
|
113
|
-
|
|
|
114
|
-
| Other
|
|
109
|
+
| Incoming event | Handler order |
|
|
110
|
+
| --------------------------------- | ------------------------------------------------------------------- |
|
|
111
|
+
| App mention | `onAppMention` → `onMessage` → `onEvent` → built-in mention default |
|
|
112
|
+
| Direct message | `onDirectMessage` → `onMessage` → `onEvent` → built-in DM default |
|
|
113
|
+
| Un-mentioned code channel message | `onMessage` → `onAppMention` → `onEvent` → built-in default |
|
|
114
|
+
| Other Slack message | `onMessage` → `onEvent` → ignore |
|
|
115
|
+
| Other Events API event | `onEvent` → ignore |
|
|
115
116
|
|
|
116
117
|
Only the first available handler runs. A message hook returning `null` drops the message; it does not continue down the table.
|
|
117
118
|
|
|
@@ -304,9 +305,127 @@ export default slackChannel({
|
|
|
304
305
|
|
|
305
306
|
Reset returns a `Delivery` for the retiring session; `await delivery.result()` waits for retirement and address release. An already unowned thread throws `SessionNotActiveError`. Returning `null` after reset consumes the triggering message as a command; return `{ auth }` instead to deliver that message as the first turn of the fresh session. Custom `onInteraction` handlers receive the same flat operations, which is useful for a New conversation button.
|
|
306
307
|
|
|
308
|
+
#### Serve Slack code channels
|
|
309
|
+
|
|
310
|
+
A [Slack code channel](https://docs.slack.dev/ai/slack-code) is a channel dedicated to one agent task. eve serves the whole code channel as one session: every message in it, top-level or threaded, reaches the same session. Replies post top-level, or in the thread when someone writes in one. The session status stays on the channel either way. While a turn runs, eve sets the Slack session status to `processing` in place of the thread status line, `suspended` while the turn waits on a person, and `active` when the turn ends or is cancelled. When someone stops the session in Slack, eve cancels the active turn, or sets the status back to `active` when no turn is running.
|
|
311
|
+
|
|
312
|
+
Set `codeChannels` to answer messages in a code channel without a mention:
|
|
313
|
+
|
|
314
|
+
```ts title="agent/channels/slack.ts"
|
|
315
|
+
import { connectSlackCredentials } from "@vercel/connect/eve";
|
|
316
|
+
import { slackChannel } from "eve/channels/slack";
|
|
317
|
+
|
|
318
|
+
export default slackChannel({
|
|
319
|
+
credentials: connectSlackCredentials("slack/my-agent"),
|
|
320
|
+
codeChannels: true,
|
|
321
|
+
});
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
Every member of a code channel can start turns, with auth derived from each message's author, the same as in an ordinary thread. Messages that don't mention the bot go to `onMessage` when you define it, else to `onAppMention`, else the default handler, so a mention handler that filters who can reach the agent also filters code channel messages. `ctx.isBotMentioned()` still returns `true` only for messages that mention the bot; use `ctx.slack.codeChannel` to tell code channel messages apart. Without `codeChannels`, eve never looks a channel up and treats a code channel like any other channel.
|
|
325
|
+
|
|
326
|
+
A code channel session has no single thread, so `ctx.slack.threadTs` is empty, `SlackChannelState.threadTs` is `null`, and its Slack auth has no `thread_ts`. `ctx.slack.codeChannel`, `codeChannel: true` in state, and `codeChannel: true` in the channel metadata that tools and dynamic resolvers read as `ctx.channel.metadata` say it's a code channel. To address its session yourself, target `{ channelId, codeChannel: true }` in `onEvent` operations, or build its continuation token with `slackCodeChannelContinuationToken(channelId)`.
|
|
327
|
+
|
|
328
|
+
A code channel someone opens from Slack's UI starts without the origin conversation. When Slack opens a code channel from a message, it posts a quote of that message into the channel. eve skips the quote, so it never starts a turn, and doesn't add it to the session either. To start a code channel with the conversation so far, open it from eve with [`openCodeChannel()`](#open-a-code-channel-from-a-thread), which copies the conversation, or with [`ctx.openCodeChannel()`](#open-a-code-channel-from-a-message-hook) and pass `history`.
|
|
329
|
+
|
|
330
|
+
eve detects a code channel with Slack's `conversations.info` API, so the app needs `channels:read` (and `groups:read` for private code channels). If the lookup fails, eve logs an error, serves the channel per thread, and retries the lookup a minute later. With `codeChannels` set, the generated app manifest enables the code channels feature, adds the `code_channels:manage`, `channels:history`, `channels:read`, `groups:history`, and `groups:read` bot scopes (plus `im:read` and `mpim:read`, so eve can read a DM or group DM origin), and subscribes to the `message.session` and `agent_session_stopped` events. For Vercel Connect, add the same scopes and events under **Advanced** when you create the connector. To tell whether you're in a code channel, use `ctx.slack.codeChannel` in message hooks and `channel.state.codeChannel` in [renderers](#customize-rendering).
|
|
331
|
+
|
|
332
|
+
#### Open a code channel from a thread
|
|
333
|
+
|
|
334
|
+
To let the agent move a request that needs more than one message into a new code channel, give it a tool that calls `openCodeChannel()` with your Slack channel:
|
|
335
|
+
|
|
336
|
+
```ts title="agent/tools/open_code_channel.ts"
|
|
337
|
+
import { openCodeChannel } from "eve/channels/slack";
|
|
338
|
+
import { defineTool } from "eve/tools";
|
|
339
|
+
import { z } from "zod";
|
|
340
|
+
import slack from "../channels/slack";
|
|
341
|
+
|
|
342
|
+
export default defineTool({
|
|
343
|
+
description: [
|
|
344
|
+
"Move this Slack conversation into a new code channel for multi-step work: code changes, builds, tests, pull requests, investigations, or long output.",
|
|
345
|
+
"Answer in place when one message answers the request. Call it once per request; Slack links the new channel here, so afterward reply in one short sentence at most.",
|
|
346
|
+
"If it returns unavailable or Slack refuses, continue here and say why; don't retry.",
|
|
347
|
+
].join(" "),
|
|
348
|
+
inputSchema: z.object({
|
|
349
|
+
message: z
|
|
350
|
+
.string()
|
|
351
|
+
.describe("The task and where to start. The channel sees the conversation so far."),
|
|
352
|
+
name: z.string().max(80).describe("A short title, such as `Fix the flaky login test`."),
|
|
353
|
+
}),
|
|
354
|
+
async execute({ message, name }, ctx) {
|
|
355
|
+
return await openCodeChannel(ctx, slack, message, { name });
|
|
356
|
+
},
|
|
357
|
+
});
|
|
358
|
+
```
|
|
359
|
+
|
|
360
|
+
`openCodeChannel(ctx, slack, message, { name })` opens the code channel from the message that triggered the turn, and starts the code channel's session with the conversation the model saw, then `message`. Without `name`, Slack names the channel from the message. Slack links the new channel in the origin thread, invites the person who wrote the origin message, and gives the channel the origin's privacy. eve reads the origin before creating anything and asks Slack for a private channel when the origin is private. If Slack still returns a public channel, eve archives it and doesn't copy the conversation. The origin thread keeps its own session for quick follow-ups.
|
|
361
|
+
|
|
362
|
+
It needs `codeChannels: true` on the Slack channel you pass. Outside Slack or inside a code channel, it returns `{ status: "unavailable", reason }` and the model continues in the thread. When Slack refuses, for example for a Slack Connect conversation, when code channels are disabled, or when a scope is missing, it throws Slack's error, which the model relays. eve retries transient Slack errors such as rate limits first. Like every [`ctx.to()`](/docs/tools#start-channel-sessions-ctxto), it works only in a tool on the root agent.
|
|
363
|
+
|
|
364
|
+
One person gets one code channel per message. A retried tool call reaches the same channel and session once. A second call for the same message reaches the same channel and delivers the conversation again, so a session someone started by writing in the new channel first still gets the thread's history.
|
|
365
|
+
|
|
366
|
+
#### Build your own code channel tool
|
|
367
|
+
|
|
368
|
+
To change more than the description and inputs, send to the Slack channel with a `codeChannel` target yourself. `ctx.channel.metadata` names the Slack conversation the tool was called from: `channelId` and `threadTs`. In a code channel, `threadTs` is `null`. The metadata doesn't depend on the session's auth, so the tool keeps working when a message hook returns its own `auth`:
|
|
369
|
+
|
|
370
|
+
```ts title="agent/tools/move_to_code_channel.ts"
|
|
371
|
+
import { defineTool } from "eve/tools";
|
|
372
|
+
import { z } from "zod";
|
|
373
|
+
import slack from "../channels/slack";
|
|
374
|
+
|
|
375
|
+
export default defineTool({
|
|
376
|
+
description: "Move this request into a new Slack code channel.",
|
|
377
|
+
inputSchema: z.object({ task: z.string() }),
|
|
378
|
+
async execute({ task }, ctx) {
|
|
379
|
+
const channelId = ctx.channel.metadata?.channelId;
|
|
380
|
+
const threadTs = ctx.channel.metadata?.threadTs;
|
|
381
|
+
if (typeof channelId !== "string" || typeof threadTs !== "string") {
|
|
382
|
+
return { status: "unavailable" };
|
|
383
|
+
}
|
|
384
|
+
const session = await ctx
|
|
385
|
+
.to(slack, {
|
|
386
|
+
channelId,
|
|
387
|
+
// Opens the channel from the thread's root message.
|
|
388
|
+
codeChannel: { name: task.slice(0, 80), originThreadTs: threadTs, originTs: threadTs },
|
|
389
|
+
})
|
|
390
|
+
.send(task, {
|
|
391
|
+
auth: ctx.session.auth.current,
|
|
392
|
+
idempotencyKey: `${ctx.session.id}:${ctx.callId}`,
|
|
393
|
+
});
|
|
394
|
+
return { sessionId: session.id, status: "opened" };
|
|
395
|
+
},
|
|
396
|
+
});
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
`codeChannel` takes the origin message's `originTs`, its thread's `originThreadTs`, and optionally the channel's `name`; without one, Slack names the channel from the message. The new channel gets the origin's privacy, and its session's audience follows it. A tool, route, schedule, or `onEvent` handler can open one from any message the app can see, so pass the origin of the conversation the tool was called from, as `openCodeChannel()` does. Pass `history` to start the code channel's session with earlier messages; `openCodeChannel()` passes the text of `ctx.messages`.
|
|
400
|
+
|
|
401
|
+
#### Open a code channel from a message hook
|
|
402
|
+
|
|
403
|
+
To open a code channel without the model deciding, call `ctx.openCodeChannel({ name })` in `onAppMention`, `onDirectMessage`, or `onMessage`. It opens the channel from the inbound message and returns the same session operations as `ctx`, bound to the code channel's session. Send the first turn there and return `null`, so the thread gets no turn. For example, an agent that works only in code channels:
|
|
404
|
+
|
|
405
|
+
```ts title="agent/channels/slack.ts"
|
|
406
|
+
import { connectSlackCredentials } from "@vercel/connect/eve";
|
|
407
|
+
import { defaultSlackAuth, slackChannel } from "eve/channels/slack";
|
|
408
|
+
|
|
409
|
+
export default slackChannel({
|
|
410
|
+
credentials: connectSlackCredentials("slack/my-agent"),
|
|
411
|
+
codeChannels: true,
|
|
412
|
+
async onAppMention(ctx, message) {
|
|
413
|
+
// Messages in the code channel reach its session as usual.
|
|
414
|
+
if (ctx.slack.codeChannel) return { auth: defaultSlackAuth(message, ctx) };
|
|
415
|
+
const codeChannel = await ctx.openCodeChannel({ name: message.text.slice(0, 80) });
|
|
416
|
+
await codeChannel.send(message.text);
|
|
417
|
+
return null;
|
|
418
|
+
},
|
|
419
|
+
});
|
|
420
|
+
```
|
|
421
|
+
|
|
422
|
+
The returned `send` defaults to the message author's auth and moves Slack auth you pass to the code channel. Omit `name` to let Slack name the channel from the message.
|
|
423
|
+
|
|
424
|
+
Unlike the tool, `ctx.openCodeChannel()` copies no conversation: the code channel's session starts with only what you send. Pass `history` to `send` if it should see earlier messages, such as the thread's replies. `ctx.openCodeChannel()` opens the channel the same way as a `codeChannel` target: one channel per author and message, the origin's privacy, and the session's audience from it. It throws without `codeChannels: true`, for a message already in a code channel, and when Slack refuses to create the channel, like the other `ctx` operations.
|
|
425
|
+
|
|
307
426
|
### Other Events API callbacks
|
|
308
427
|
|
|
309
|
-
Use `onEvent` for subscribed events such as `reaction_added`, `team_join`, or `channel_created`. It receives the raw, open-ended Slack event and owns control flow. Call `ctx.send(message, { target, auth,
|
|
428
|
+
Use `onEvent` for subscribed events such as `reaction_added`, `team_join`, or `channel_created`. It receives the raw, open-ended Slack event and owns control flow. Call `ctx.send(message, { target, auth, ...options })` zero, one, or many times to start turns. It takes the same options as [`to().send()`](./custom#cross-channel-hand-off), such as `title`, which sets the run title without changing the message sent to the model, `history`, which adds prior conversation before the message (see [Start from prior history](./eve#start-from-prior-history)), and `idempotencyKey`. Each call returns a delivery receipt; use its `sessionId` to attach a session handle.
|
|
310
429
|
|
|
311
430
|
```ts title="agent/channels/slack.ts"
|
|
312
431
|
import { connectSlackCredentials } from "@vercel/connect/eve";
|
|
@@ -350,6 +469,8 @@ await ctx.reset({ reason: "Start over", target });
|
|
|
350
469
|
const session = await ctx.resolveSession({ target });
|
|
351
470
|
```
|
|
352
471
|
|
|
472
|
+
For a [code channel](#serve-slack-code-channels)'s session, which spans all of its threads, target `{ channelId, codeChannel: true }` in every operation except `send`.
|
|
473
|
+
|
|
353
474
|
`onEvent` is the raw fallback after the message hooks. If an event is not claimed by `onAppMention`, `onDirectMessage`, or `onMessage`, an authored `onEvent` receives it; otherwise eve applies the built-in mention/DM default or ignores it.
|
|
354
475
|
|
|
355
476
|
`onEvent` covers JSON `event_callback` deliveries only. URL verification, slash commands, and interactive payloads do not reach it. Slash commands reach `onSlashCommand`; add every desired event and required OAuth scope to the Slack app's Event Subscriptions configuration so other callbacks reach their handlers.
|
|
@@ -462,11 +583,12 @@ eve writes the card from the session's own events as they happen, and only when
|
|
|
462
583
|
|
|
463
584
|
### Customize rendering
|
|
464
585
|
|
|
465
|
-
Without `renderers`, eve renders everything above with its default renderer. Pass `renderers` to change what the agent posts without replacing that default. Each renderer wraps the ones after it, ending with eve's default renderer, and has
|
|
586
|
+
Without `renderers`, eve renders everything above with its default renderer. Pass `renderers` to change what the agent posts without replacing that default. Each renderer wraps the ones after it, ending with eve's default renderer, and has four optional parts:
|
|
466
587
|
|
|
467
588
|
- `received(message, channel, next)` acknowledges a mention or DM the moment it arrives, and another channel message once `onMessage` dispatches it. eve's default sets `Thinking...`.
|
|
468
589
|
- `events` handles session facts such as `content.completed` or `interaction.opened`. Each handler receives `(event, ctx, next)`: the whole fact with its `type`, `data`, and `scope`, and a context whose `ctx.channel` holds Slack's platform handles, `ctx.channel.thread` and `ctx.channel.slack`, along with `ctx.position` and `ctx.view`.
|
|
469
590
|
- `taskCard(view, next)` returns the task card's blocks and notification text, or `null` for no card.
|
|
591
|
+
- `interactionCard(card, next)` returns the messages for one approval, question, or budget prompt.
|
|
470
592
|
|
|
471
593
|
Call `next()` to run the rest of the chain, ending with eve's default. Call it after your own work, before it, or with a changed fact, as in `next({ ...event, data: { ...event.data, value } })`; the rest of the chain runs at most once. Skip `next` to replace the default for that event. This renderer adds feedback buttons below each final reply and a context row to the finished task card:
|
|
472
594
|
|
|
@@ -562,6 +684,48 @@ A turn keeps one card unless it starts a task after every task on its card ended
|
|
|
562
684
|
|
|
563
685
|
`taskCard` is synchronous and pure: eve posts the card and updates it as the tables change. eve's default returns `null` for a card without tasks. Its block keeps the same `block_id` for the whole turn; keep that `block_id` on a block you build in its place. To change a row's title in every channel, give the tool a [label](/docs/tools#label-tool-activity) instead.
|
|
564
686
|
|
|
687
|
+
`interactionCard` restyles the card for one approval, question, or budget prompt. It receives:
|
|
688
|
+
|
|
689
|
+
- `interaction`: the request as the session holds it, with its `status`, `outcome`, `call` (including the tool `input`), and `answer`. Once the request settles, `answer` is the answer that decided it. While it's open, `answer` is the latest admitted answer, if any; an answer still being checked, for example by an approval response policy, or one that was refused doesn't count.
|
|
690
|
+
- `destination`: `"thread"` or `"direct-message"`, as [`approvalChannel`](#human-in-the-loop-hitl) decided. In a code channel, `"thread"` means the code channel itself.
|
|
691
|
+
- `audience`: who reads the message. A direct message is always `private`; a thread request has the thread's audience, as on the task card.
|
|
692
|
+
- `answeredBy`: the Slack user ID whose answer stands or decided the request, when known.
|
|
693
|
+
- `view`: the session snapshot, for the selectors from `eve/events`.
|
|
694
|
+
|
|
695
|
+
It returns `controls`, the message holding eve's buttons or select, and an optional `details` message, which eve posts before the controls. Each is a `SlackCardMessage` with `blocks` and `text`, the same shape `taskCard` returns. Requests asked together share one details message, which eve deletes once its last open request settles. Slack sends the whole controls message back with every click, so put long content such as tool input in `details`. eve's default posts details only for an approval with tool input, but a renderer can give any request details, including a question. This renderer shows a `plan-create` tool's steps as the approval's details:
|
|
696
|
+
|
|
697
|
+
```ts title="agent/channels/slack.ts"
|
|
698
|
+
import { defineSlackRenderer, slackChannel } from "eve/channels/slack";
|
|
699
|
+
|
|
700
|
+
const plan = defineSlackRenderer({
|
|
701
|
+
interactionCard(card, next) {
|
|
702
|
+
const parts = next(card);
|
|
703
|
+
const { call, status } = card.interaction;
|
|
704
|
+
if (call?.name !== "plan-create" || status !== "open") return parts;
|
|
705
|
+
const { steps = [] } = (call.input ?? {}) as { steps?: string[] };
|
|
706
|
+
if (steps.length === 0) return parts;
|
|
707
|
+
const text = steps.map((step, index) => `${index + 1}. ${step}`).join("\n");
|
|
708
|
+
return {
|
|
709
|
+
...parts,
|
|
710
|
+
details: { blocks: [{ type: "section", text: { type: "mrkdwn", text } }], text },
|
|
711
|
+
};
|
|
712
|
+
},
|
|
713
|
+
});
|
|
714
|
+
|
|
715
|
+
export default slackChannel({ renderers: [plan] });
|
|
716
|
+
```
|
|
717
|
+
|
|
718
|
+
eve calls `interactionCard` when a request opens, when an answer is admitted or refused, and when the request settles, and updates the Slack message only when its blocks changed. Requests in one message that settle together update it once. Pass `next` a changed card, such as one with a shorter `interaction.request.prompt`, to have eve's default render it. eve's default renders an open request as buttons or a select, and an answered or settled one as a single block that names the answer and, when known, who gave it. `interactionCard` doesn't run for sign-ins.
|
|
719
|
+
|
|
720
|
+
eve still routes, batches, and posts the messages, and owns the controls' action IDs, so clicks keep reaching the session. You can relabel eve's controls, reorder them, or nest them in your own blocks, within these rules:
|
|
721
|
+
|
|
722
|
+
- While the request is open and unanswered, `controls` holds exactly the controls `next` renders, each once, with the same `value` or option values. Every eve control's `action_id` starts with `eve_input:` or `eve_input_freeform:`.
|
|
723
|
+
- Once the request is answered or settled, `controls` holds no eve controls.
|
|
724
|
+
- `details` never holds eve controls, and each message holds at most 50 blocks.
|
|
725
|
+
- A message holds at most 50 blocks, including the requests eve grouped with yours. An update that would pass that uses eve's default for the changed request instead, and if that doesn't fit either, only the block holding eve's controls, so an open request always shows them.
|
|
726
|
+
|
|
727
|
+
If `interactionCard` throws or breaks these rules, eve logs it and renders that request with its default, since a request nobody can answer would hold the turn. If Slack refuses a rendered message's content, such as with `invalid_blocks` or `msg_too_long`, eve sends that message once more with its defaults. eve doesn't resend after any other failure, such as a timeout or `rate_limited`, because the first message may have landed.
|
|
728
|
+
|
|
565
729
|
Renderers run in the order you list them, and the first one is outermost. `onInteraction` receives clicks on buttons a renderer posts, such as the feedback buttons above.
|
|
566
730
|
|
|
567
731
|
### Show your own tool on the task card
|
|
@@ -652,9 +816,9 @@ export default slackChannel({
|
|
|
652
816
|
|
|
653
817
|
The callback receives the `Interaction` and current `SessionContext`, so it can switch on `request.kind`, `call`, or prompt presentation properties. Omit it to keep every request in the thread, or return `"direct-message"` unconditionally to make every request private. If eve cannot resolve the triggering Slack user for a direct message, it logs the undelivered request and posts no fallback, so private delivery fails closed. The existing `onAnswers` or tool approval response policy still decides whether the person who clicks may respond.
|
|
654
818
|
|
|
655
|
-
|
|
819
|
+
Each card updates from the session as its request changes. Once an answer is admitted, the card shows the answer and who gave it in place of the buttons, even while other approvals from the same step still wait for theirs. Clicks can't change an admitted answer, since the buttons are gone; if a policy or check refuses the answer, the buttons come back. Once the request settles, the separate tool-input post is deleted after the last open request it covers settles, and a direct-message request's `Waiting on approval` note in the thread changes to the outcome the card shows. This applies to approvals, questions, and budget prompts, however they end: a click, a typed reply in the thread, or a withdrawal, in which case the card reads `No longer needed`. When several requests share one message, answering one updates only its part of the message. To change how these cards look, use [`interactionCard`](#customize-rendering).
|
|
656
820
|
|
|
657
|
-
A click on any request whose session is no longer active, for example because its run was cancelled outside eve, can never be answered. eve removes the card's buttons, marks it `No longer active`, and tells the person who clicked, in an ephemeral message, to send a new message.
|
|
821
|
+
A click on any request whose session is no longer active, for example because its run was cancelled outside eve, can never be answered. eve removes the card's buttons, marks it `No longer active`, and tells the person who clicked, in an ephemeral message, to send a new message. eve has no session to render from at that point, so it edits the message Slack sent with the click. A freeform answer submitted from the **Type your answer** modal at that point replaces the whole message, including any requests grouped with it.
|
|
658
822
|
|
|
659
823
|
A renderer's `interaction.opened` handler can extend delivery and then hand the request on to eve with `next()`. For example, an application can add non-sensitive context to the Slack thread before eve renders the actionable controls. The configured `approvalChannel` still sends sensitive reviews to a DM and keeps ordinary requests in the thread:
|
|
660
824
|
|
|
@@ -710,7 +874,7 @@ answerFromSlackAction({ actionId: button.action_id, value: button.value });
|
|
|
710
874
|
// { response: { optionId: "approve", interactionId: request.interactionId } }
|
|
711
875
|
```
|
|
712
876
|
|
|
713
|
-
Use them to test a custom renderer against eve's wire format, or to post eve's controls from your own renderer. A click on these controls in the session's Slack thread resumes the session through `onAnswers`, the same as eve's own controls. eve does not track controls you post yourself, so update or remove those messages from your renderer's `interaction.settled` handler. To pass `response` to `respond()` yourself, validate it first with `parseAnswers` from `eve/client`.
|
|
877
|
+
Use them to test a custom renderer against eve's wire format, or to post eve's controls from your own renderer. To restyle the cards eve posts, use `interactionCard` instead, which keeps eve's batching and card updates. A click on these controls in the session's Slack thread resumes the session through `onAnswers`, the same as eve's own controls. eve does not track controls you post yourself, so update or remove those messages from your renderer's `interaction.settled` handler. To pass `response` to `respond()` yourself, validate it first with `parseAnswers` from `eve/client`.
|
|
714
878
|
|
|
715
879
|
Authorization prompts split public status from private credentials. A sign-in challenge (OAuth URL, device code) is a credential. Anyone who completes it binds their identity to the session's connection. A sign-in is an `interaction.opened` with `request.kind: "sign-in"`. The default handler posts a public, link-free status in the thread, delivers the actual challenge ephemerally to the Slack user behind the interaction's `audience.principalIds`, device code included, and then updates that public status when its `interaction.settled` fires. For a sign-in, a renderer's `interaction.opened` handler receives a private-delivery context as `ctx.channel`, with `postEphemeral`, `postDirectMessage` (needs the `im:write` scope), and `state`. There is, intentionally, no public `post` and no raw API access. Its `next()` reaches eve's default, which posts the public status; skip `next` to deliver the challenge yourself, as this handler does by direct message. `state.slackUsersByPrincipal` maps each principal eve has seen in the thread, through a message or an input response, to its Slack user ID. If the principal has no entry, the challenge is not sent privately.
|
|
716
880
|
|
|
@@ -738,16 +902,19 @@ The private authorization button uses the label **Sign in**, so long connection
|
|
|
738
902
|
|
|
739
903
|
### Proactive sessions
|
|
740
904
|
|
|
741
|
-
Start a Slack conversation from a [webhook on another channel](./custom#cross-channel-hand-off)
|
|
905
|
+
Start a Slack conversation from a [webhook on another channel](./custom#cross-channel-hand-off), a [schedule](../schedules#handler-form-run), or a [tool](../tools#start-channel-sessions-ctxto), without waiting for someone to message the app. To copy an existing conversation into a new thread or someone's direct messages, see [Fork conversations into a new thread](../patterns/fork-conversations-into-new-threads).
|
|
742
906
|
|
|
743
907
|
Pass `{ channelId }` as the target to start a new thread. The agent's first post becomes the thread's root message. You can also set these target fields:
|
|
744
908
|
|
|
745
|
-
| Field | Use
|
|
746
|
-
| -------------------- |
|
|
747
|
-
| `threadTs` | Continue an existing thread instead of creating one.
|
|
748
|
-
| `initialMessage` | Post a card as the thread root before the agent runs. Cannot be combined with `threadTs`.
|
|
749
|
-
| `installationTeamId` | Select the app installation workspace when using a function-form bot token.
|
|
750
|
-
| `
|
|
909
|
+
| Field | Use |
|
|
910
|
+
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
911
|
+
| `threadTs` | Continue an existing thread instead of creating one. |
|
|
912
|
+
| `initialMessage` | Post a card as the thread root before the agent runs. Cannot be combined with `threadTs`. |
|
|
913
|
+
| `installationTeamId` | Select the app installation workspace when using a function-form bot token. |
|
|
914
|
+
| `codeChannel` | Open a [code channel](#build-your-own-code-channel-tool) from a message in `channelId` and start the session there. Requires `codeChannels: true`. |
|
|
915
|
+
| `audience` | Set the destination's visibility when you know it. Defaults to `unknown`. |
|
|
916
|
+
|
|
917
|
+
A send with an `idempotencyKey` and no `threadTs` or `initialMessage` derives the new thread's session from the key, so a retry with the same key reaches the same session instead of starting a second thread. Because the key chooses the session, two different sends that reuse a key land in the same thread and the second is ignored. Use a key that identifies the delivery across every sender to this channel, not only across retries of one sender.
|
|
751
918
|
|
|
752
919
|
The default mention handler lets teammates continue the session by mentioning the app in the thread. To accept replies without a mention, [configure an `onMessage` hook and the required Slack subscriptions and scopes](#continue-conversations-without-repeated-mentions).
|
|
753
920
|
|
package/docs/channels/teams.mdx
CHANGED
|
@@ -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 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 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.
|
|
8
8
|
|
|
9
9
|
## Add the channel
|
|
10
10
|
|
|
@@ -77,7 +77,11 @@ export default teamsChannel({
|
|
|
77
77
|
|
|
78
78
|
### Delivery
|
|
79
79
|
|
|
80
|
-
|
|
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.
|
|
81
|
+
|
|
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.
|
|
83
|
+
|
|
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
85
|
|
|
82
86
|
### Human-in-the-loop (HITL)
|
|
83
87
|
|
|
@@ -95,7 +95,7 @@ Move its `evals/` directory, if present, to `agents/support/evals/`. Keep `packa
|
|
|
95
95
|
Before adding the next agent:
|
|
96
96
|
|
|
97
97
|
- Update `tsconfig.json` to include `agents/**/*.ts`, preserving any application includes. Update moved-file imports and path aliases, including scaffolded `package.json#imports` entries that point at `./agent/*` or `./evals/*`.
|
|
98
|
-
- Update scripts that assume one agent. Use `--agent support` for agent-scoped commands; build an agent-only Vercel workspace with root `eve build`. For a Next.js app, keep the framework scripts and follow its [build instructions](/docs/guides/frontend/nextjs#
|
|
98
|
+
- Update scripts that assume one agent. Use `--agent support` for agent-scoped commands; build an agent-only Vercel workspace with root `eve build`. For a Next.js app, keep the framework scripts and follow its [build instructions](/docs/guides/frontend/nextjs#run-build-and-deploy).
|
|
99
99
|
- Update HTTP clients and webhook registrations for the named agent's public routes. In a root Next.js app, remove a single-agent `eveRoot` override to enable workspace discovery, and select `support` in the client hook. Store the agent name alongside durable-session links.
|
|
100
100
|
|
|
101
101
|
Then add the second agent and check discovery:
|
|
@@ -75,6 +75,10 @@ A [channel](../channels/overview) is your agent's front door, so authenticating
|
|
|
75
75
|
|
|
76
76
|
A custom channel that accepts dashboard-style webhooks should follow the same shape: authenticate the raw body with an HMAC, compare signatures in constant time, and trust any body-supplied principal only after the signature verifies.
|
|
77
77
|
|
|
78
|
+
## A turn runs as one principal
|
|
79
|
+
|
|
80
|
+
A turn's principal (its authenticator, issuer, principal type and id) never changes while the turn runs; only its claims may update. Only that principal's messages steer the turn or answer its pending questions by text. In a shared thread, another person's message waits for the turn to end and then runs as their own turn, so their text never drives the turn's credentials and the turn never continues under their identity. Another person can still settle a pending request with a button or structured answer; they are recorded as its responder, and the turn keeps its caller. See [What reaches `ctx.session.auth`](../guides/auth-and-route-protection#what-reaches-ctxsessionauth).
|
|
81
|
+
|
|
78
82
|
## Authored markdown is data
|
|
79
83
|
|
|
80
84
|
[Skill](../skills) and [schedule](../schedules) files are markdown with YAML frontmatter, and eve treats that frontmatter strictly as data. The code-capable engines (`---js` / `---javascript`, which would `eval()` the frontmatter body the moment the file is parsed) are disabled, so such a fence throws rather than running. Frontmatter has to parse to a plain YAML object.
|
|
@@ -8,12 +8,13 @@ This guide covers breaking changes to agent definitions, approvals, channels, cl
|
|
|
8
8
|
## Before you upgrade
|
|
9
9
|
|
|
10
10
|
- Rebuild and republish installed extensions. Earlier epoch-based distributions cannot be loaded by this release; see [Extensions](../extensions).
|
|
11
|
-
- Keep the deployments that own existing sessions available.
|
|
11
|
+
- Keep the deployments that own existing sessions available. A session whose deployment runs eve 0.69 through 0.83 moves to this release the next time it receives a message while idle, or earlier when a channel prepares it for the next message. A session that has a background task, including an idle resumable one, stays on the deployment that owns it until the task finishes, and a session whose deployment runs an earlier release stays there. When a session moves, eve compacts its earlier conversation, so the model continues from a summary while the stored transcript stays intact. The session also starts over on remembered tool approvals and usage limits. On worlds without deployment routing, follow the [stranded-session recovery guidance](./execution-model-and-durability#stranded-sessions).
|
|
12
12
|
- Update event consumers, frontend persistence, and custom channel handlers using the mappings below. See [Sessions, runs & streaming](./sessions-runs-and-streaming) for the current stream contract.
|
|
13
|
+
- If your application saves session history, follows streams itself, or derives outcomes from events, plan that work with [Migrate application-owned state](#migrate-application-owned-state).
|
|
13
14
|
|
|
14
15
|
## Restore saved history
|
|
15
16
|
|
|
16
|
-
New sessions use v27. Sessions started on an earlier deployment keep
|
|
17
|
+
New sessions use v27. Sessions started on an earlier deployment keep the lines they already stored in the earlier format. When such a session moves to this release, it appends v27 facts to the same stream, and a current deployment serves the whole stream as v27 events.
|
|
17
18
|
|
|
18
19
|
Don't pass event arrays saved before the upgrade as `initialEvents`. When the session's stream is still available, read it again from position 0 and replace what you saved. Saved cursors still count the same stored lines.
|
|
19
20
|
|
|
@@ -30,6 +31,17 @@ Save the converted events with their metadata unchanged and pass them as `Sessio
|
|
|
30
31
|
|
|
31
32
|
A session saved mid-turn stays unfinished. Convert each session separately: the function throws for an array that doesn't start at `session.started`, that holds a second session, or that holds current events. `convertLegacyEvents` is a migration aid with no compatibility promise and will be removed in a later release.
|
|
32
33
|
|
|
34
|
+
Saved records often hold more than one stream's worth of history. Before you hydrate or convert:
|
|
35
|
+
|
|
36
|
+
- **Select one session.** A chat record can hold several sessions, for example after a chat moves to a new session or a fork copies its parent's history. Pass only the current session's events, from its `session.started`, to `initialEvents` or `convertLegacyEvents`.
|
|
37
|
+
- **Split mixed prefixes.** A record written across the upgrade can hold v26 events followed by v27 events. If its stream has expired, convert only the v26 prefix and keep the later v27 events and their metadata unchanged.
|
|
38
|
+
- **Don't convert folded caches.** Message lists produced by v26 reducers aren't raw events. Re-read the stream, or render those caches as read-only records.
|
|
39
|
+
- **End computed cursors at a complete line.** An event with `meta.endOfLine: false` has more events in the same line. If you compute a cursor yourself, stop at the last complete line.
|
|
40
|
+
- **Treat missing data as unknown.** A partial read must not overwrite a fuller archive, and an expired stream must not replace saved history with an empty one. A child session you can no longer read hasn't necessarily completed.
|
|
41
|
+
- **Guard concurrent writes.** Browser saves, server catch-up reads, and background capture can race. Bind each write to its session, reject a cursor that moves backward, and track each child session's progress separately from its parent's.
|
|
42
|
+
- **Keep copied history inert.** Interactions in a fork, shared copy, or historical transcript belong to the original session. Render them read-only, not as live approval or sign-in controls.
|
|
43
|
+
- **Qualify IDs with the session.** Turn and message IDs aren't unique across sessions. When one record holds several sessions, include the session ID in keys for derived UI state.
|
|
44
|
+
|
|
33
45
|
## Event mapping
|
|
34
46
|
|
|
35
47
|
| v26 | v27 |
|
|
@@ -126,3 +138,59 @@ export default defineHook({
|
|
|
126
138
|
- Replace `eve remote invoke` with `eve remote connect --print <prompt>` for one-shot requests. Use `eve/client` for scripted multi-turn sessions and answers; see the [CLI reference](../reference/cli#eve-remote-connect).
|
|
127
139
|
- MCP's `input_required` now covers sign-ins as well as approvals and questions. Answer non-sign-in interactions using `responses: [{ interactionId, optionId?, text? }]`; complete sign-ins externally. Direct `invokeTool` calls return call-shaped outcomes, not conversational pauses. See [MCP](../channels/mcp).
|
|
128
140
|
- Remote agent protocol 3 supports relaying interactions. A protocol-3 caller relays a protocol-2 remote agent's approvals, questions, and sign-ins, but a protocol-3 remote agent can't relay them to a protocol-2 caller, so upgrade callers before the remote agents they call. Older peers can still exchange results. See [Upgrading callers and remote agents](../guides/remote-agents#upgrading-callers-and-remote-agents).
|
|
141
|
+
|
|
142
|
+
## Migrate application-owned state
|
|
143
|
+
|
|
144
|
+
The tables above cover renamed events and APIs. Applications that save history, follow streams, or track lifecycle state themselves also need to decide which of that state they still own.
|
|
145
|
+
|
|
146
|
+
### Decide what eve owns
|
|
147
|
+
|
|
148
|
+
Let eve own live execution and observation: turn lifecycle, streaming and reconnection, optimistic sends, and interaction state. Use `useEveAgent` or `SessionStore` to follow a session, `view` queries from `eve/events` for lifecycle questions, and `delivery.result()` for a request's outcome.
|
|
149
|
+
|
|
150
|
+
Keep the records eve doesn't hold: saved archives and their cursors, forks and shared copies, feedback, authorization and responder policy, budgets you authored, and ledgers of external effects such as uploads or published changes.
|
|
151
|
+
|
|
152
|
+
- Replace an application-owned lifecycle model as a whole. A second reducer layered on the store becomes another source of truth that can disagree with it.
|
|
153
|
+
- Adapt at the presentation boundary. Map `messages`, `view`, and interaction parts into your existing components instead of rebuilding a lifecycle to feed them.
|
|
154
|
+
|
|
155
|
+
### Find every consumer
|
|
156
|
+
|
|
157
|
+
A clean typecheck doesn't find every v26 consumer. Code that parses NDJSON or saved JSON with locally declared event types compiles against any `eve` version and ignores facts it doesn't recognize.
|
|
158
|
+
|
|
159
|
+
- Search for v26 event names such as `message.completed`, `action.result`, `actions.requested`, and `authorization.required`, not only for `eve` imports. Include scripts, test helpers, and server routes that proxy streams.
|
|
160
|
+
- Run a recorded v27 stream through each consumer and check its output. A reducer that returns nothing, or a filter that matches nothing, still compiles.
|
|
161
|
+
- Check server code that filters or redacts streamed content before it reaches a browser. A filter keyed on v26 event types passes v27 `content.delta` and `content.completed` events through unchanged.
|
|
162
|
+
- Check consumers in other deployments, such as remote agents and their callers, along with their protocol versions.
|
|
163
|
+
|
|
164
|
+
### Attribute results to their delivery
|
|
165
|
+
|
|
166
|
+
- Bind each outcome to the delivery that requested it. Use `delivery.result()` or that delivery's own turn, not the session's latest turn or every event after a polling cursor. Otherwise a queued or concurrent turn can claim another turn's output.
|
|
167
|
+
- For a child session that several calls reuse, follow the `child.sent` links from a call to the child delivery it sent, for example with `agentCallActivity(state, callId)` from `eve/client`. Don't count `delivery.consumed` on the child's stream: answers to the child's questions are deliveries too. See [Child agents](../guides/frontend/use-eve-agent#child-agents).
|
|
168
|
+
- Decide approvals from the interaction's `outcome`, not the call's state. Only `accepted` and `declined` record a decision. An approval that settled `withdrawn` or `interrupted`, for example because its turn was cancelled, wasn't approved. See [Interactions](../guides/frontend/use-eve-agent#interactions).
|
|
169
|
+
- Don't identify runs by the shape of their input. A steering message adds a run to the same turn, and a retry reuses its run ID. Use `turn.started` for once-per-turn work, and `runId` with `turnId` when you need a specific run.
|
|
170
|
+
- Treat acceptance as admission, not completion. When an outcome is unconfirmed, read it again instead of resending after a timeout. Use `operationId` for create requests that you retry; see [the eve channel](../channels/eve).
|
|
171
|
+
- Read payloads by their documented shape. `turn.settled.data.reply` lists the reply's part IDs, not its text; use `reply(ctx.view, turnId)` in hooks and channels, or `messages` in the frontend.
|
|
172
|
+
|
|
173
|
+
### Simplify code eve now owns
|
|
174
|
+
|
|
175
|
+
Application code that mirrors eve's state is usually removable. Measure the result by the state owners you remove, not only by deleted lines.
|
|
176
|
+
|
|
177
|
+
| Usually replaceable | Replacement |
|
|
178
|
+
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
|
|
179
|
+
| Custom stream followers, reconnect loops, and optimistic-send state | `useEveAgent` or `SessionStore` |
|
|
180
|
+
| Hook or session state that mirrors turns, calls, tasks, or models | `ctx.view` and selectors from `eve/events` |
|
|
181
|
+
| Folds over raw events for status, replies, timing, usage, or cursors | The queries in [Use eve's answers](../guides/frontend/use-eve-agent#use-eves-answers) |
|
|
182
|
+
| Hand-written finite stream readers and history scanners | `session.stream({ follow: false })` or `session.snapshot()` |
|
|
183
|
+
| Conversions from `Interaction` to a custom request shape and back | Native `Interaction` values and the channel's interaction rendering |
|
|
184
|
+
| Retirement code for Slack approval cards and sign-in messages eve posted | Slack's native settlement. Check each channel's docs before removing code for other cards, such as questions |
|
|
185
|
+
| An explicit `turnPolicy: "steer"` on follow-ups | Omit it: messages steer an open turn by default |
|
|
186
|
+
| Event-keyed dynamic capability maps | `defineDynamic(ctx => value)` |
|
|
187
|
+
| Local v26-to-v27 event translators | `convertLegacyEvents` during migration, or a fresh read from position 0 |
|
|
188
|
+
| Tests that only exercised removed machinery | Delete them with that machinery; keep tests for behavior that remains |
|
|
189
|
+
|
|
190
|
+
Keep code that enforces your application's own contracts: archive storage and cursor guards, effect ledgers and deduplication receipts, authorization and responder checks, budgets you authored, `operationId` retries, and product UI such as composers, branches, and sharing.
|
|
191
|
+
|
|
192
|
+
### Verify the migration
|
|
193
|
+
|
|
194
|
+
- Build fixtures from real saved history. Record v26 data with the release you're upgrading from, and pass it through a JSON round trip so tests use the shape you actually store.
|
|
195
|
+
- Test history paths explicitly: expired streams, sessions saved mid-turn, forks, records holding several sessions, and caches written across the upgrade.
|
|
196
|
+
- Test interaction endings other than an answer: cancel a turn while an approval is pending, and send a message while a sign-in is pending.
|
|
@@ -158,11 +158,11 @@ Updates, enable, disable, and delete affect future scheduling, not emitted callb
|
|
|
158
158
|
|
|
159
159
|
## Handle occurrences and retries
|
|
160
160
|
|
|
161
|
-
`run` receives `payload`, `occurrence`, `auth`, `to`, and `waitUntil`. It may start zero or several sessions or perform application work directly. `to(channel, target).send(message)` is bound to the resolved creator; no auth argument is needed or accepted. It starts fresh, unattended sessions through an authored channel, even when the target names an existing thread. It does not steer an existing conversation.
|
|
161
|
+
`run` receives `payload`, `occurrence`, `auth`, `to`, and `waitUntil`. It may start zero or several sessions or perform application work directly. `to(channel, target).send(message, options)` is bound to the resolved creator; no auth argument is needed or accepted. It starts fresh, unattended sessions through an authored channel, even when the target names an existing thread. It does not steer an existing conversation. `options` takes `context`, `history`, `idempotencyKey`, `outputSchema`, and `title`, as on a route handler's [`to().send()`](../channels/custom#cross-channel-hand-off). It takes no `turnPolicy`, because a send never reaches a session the schedule didn't start.
|
|
162
162
|
|
|
163
163
|
eve awaits the callback and its registered `waitUntil` promises before reporting `occurrence.dispatched`. That event includes `sessionIds`; it means dispatch succeeded, not that the agent completed its task or delivered a successful result. Channels own output delivery and session-level failure reporting. Unattended sessions cannot wait for approvals or questions; configure tools accordingly.
|
|
164
164
|
|
|
165
|
-
Provider retries may repeat the callback and start new sessions. This is an at-least-once callback contract, not exactly-once side effects. Use `occurrence.executionId` together with the schedule/resource identity to deduplicate application effects where the destination supports it. An observer failure can also cause callback retry. `occurrence.failed` reports permanent provider failures or exhaustion of the provider retry budget.
|
|
165
|
+
Provider retries may repeat the callback and start new sessions. This is an at-least-once callback contract, not exactly-once side effects. Use `occurrence.executionId` together with the schedule/resource identity to deduplicate application effects where the destination supports it. For sessions, pass it in the send's key, for example `` idempotencyKey: `${occurrence.executionId}:digest` ``. A retried callback's send with the same key and target then reaches the session the first attempt started instead of starting another. Keys are scoped to the schedule, and the [usual limits](../channels/custom#retried-deliveries) apply. An observer failure can also cause callback retry. `occurrence.failed` reports permanent provider failures or exhaustion of the provider retry budget.
|
|
166
166
|
|
|
167
167
|
## Choose a provider and test locally
|
|
168
168
|
|
package/docs/getting-started.mdx
CHANGED
|
@@ -84,6 +84,8 @@ npm install eve@latest ai zod
|
|
|
84
84
|
|
|
85
85
|
Declare Node.js 24 in `package.json`, then create `agent/instructions.md` and, when you need runtime configuration, `agent/agent.ts`.
|
|
86
86
|
|
|
87
|
+
When present, the installed package's `node_modules/eve/dist/CHANGELOG.md` contains that version's release notes and a link to the full changelog through that version. Older packages contain the full history at `node_modules/eve/CHANGELOG.md` instead. For an upgrade across multiple releases, review each version between the installed and target versions in the target version's changelog at `https://raw.githubusercontent.com/vercel/eve/refs/tags/eve%40<version>/packages/eve/CHANGELOG.md`.
|
|
88
|
+
|
|
87
89
|
## Continue with the tutorial
|
|
88
90
|
|
|
89
91
|
The [Tutorial](/docs/tutorial/first-agent) builds a data analytics agent step by step. It adds tools, state, sandboxed analysis, reusable skills, and human approval before deploying the result.
|
|
@@ -298,6 +298,7 @@ Inside runtime code, `ctx.session.auth` carries the result of the channel's rout
|
|
|
298
298
|
- `auth.current`: the caller on the active inbound turn.
|
|
299
299
|
- `auth.initiator`: the caller that started the durable session.
|
|
300
300
|
- A follow-up message updates `auth.current` but leaves `auth.initiator` alone. When a different caller follows up on the same session, `auth.current` tracks the new caller for that turn while `auth.initiator` stays pinned to whoever started it.
|
|
301
|
+
- Within a turn the principal is fixed; only its claims may update. A message from the turn's own principal, including a typed answer to a pending `ctx.ask()` or `ask_question`, joins the turn and updates `auth.current` with its claims. A message from anyone else waits for the turn to end and runs as its own turn. Someone else can still answer a pending request with a button or structured response; that settles the request with them as its responder, and the turn keeps its `auth.current`.
|
|
301
302
|
- `auth.current` is whatever the channel passed as `auth` when it dispatched the message. Route auth either accepts the request or returns `401`, but a route handler or channel hook can still dispatch with `auth: null`, such as `source.send(message, { auth: null })` or a Slack `onMessage` hook that returns `{ auth: null }`. On a new session, both values are then `null`. On a continuation, `auth.current` is `null` while `auth.initiator` stays pinned to the session's original caller. Internal runtime paths, such as subagents, can also have no caller auth.
|
|
302
303
|
|
|
303
304
|
Use the principal on `auth.current` (or `auth.initiator`) to scope tools, resolve [dynamic capabilities](./dynamic-capabilities) per principal, or enforce tenant boundaries. There's no second per-session ownership ACL stacked on top of route auth. Access is decided at the HTTP boundary, and the durable session carries the caller snapshot forward into your runtime code.
|
|
@@ -99,7 +99,7 @@ const client = new Client({
|
|
|
99
99
|
});
|
|
100
100
|
```
|
|
101
101
|
|
|
102
|
-
|
|
102
|
+
Clients reject redirects by default (`redirect: "error"`) so fetch cannot forward custom credentials to a redirected destination. Use `redirect: "manual"` to stop at a redirect without following it. Node.js exposes the response status and headers; browsers return an opaque redirect response with no readable status, headers, or body. The policy applies to inspection requests, custom fetches, session creation, and event streams, and overrides per-request redirect settings. Only opt into `redirect: "follow"` when you trust every possible redirect destination to receive your custom headers and request data.
|
|
103
103
|
|
|
104
104
|
Per-request headers can be attached to an individual turn:
|
|
105
105
|
|
|
@@ -317,7 +317,7 @@ try {
|
|
|
317
317
|
|
|
318
318
|
Construction does not start reads. `observe()` activates a reference-counted scope and returns an idempotent cleanup function. Root streaming also activates child following; framework bindings activate and release scopes after mount. The store continues refreshing admitted children within an active scope even if `followWhile` closes the root stream. There is no full-tree catch-up barrier.
|
|
319
319
|
|
|
320
|
-
`followAgents: true` recursively follows all eligible recorded children within fixed depth, admission, and request limits. A predicate such as `({ depth }) => depth === 1` selects only immediate children. See [child observations](../frontend/
|
|
320
|
+
`followAgents: true` recursively follows all eligible recorded children within fixed depth, admission, and request limits. A predicate such as `({ depth }) => depth === 1` selects only immediate children. See [child observations](../frontend/use-eve-agent#child-agents) for limits, states, and cursor semantics. Child conversations are whole-session views; their messages do not replace authoritative call results.
|
|
321
321
|
|
|
322
322
|
Stop the old scope and construct a new store when the principal or tenant changes. Token refresh callbacks resolve again for each request without changing observation identity. For a cross-origin browser connection, expose `x-eve-observation-key` in the channel's CORS configuration alongside the stream version and tail headers.
|
|
323
323
|
|
|
@@ -114,7 +114,7 @@ A frontend under `apps/web/` is another service managed by your host, not by `ev
|
|
|
114
114
|
|
|
115
115
|
For path-based mounts, strip the public prefix before forwarding requests to the agent and set `EVE_PUBLIC_ROUTE_PREFIX` in that agent's build and runtime environments. Forward its workflow callback routes as well as its eve routes. Keep the browser client, callback URLs, and peer transports consistent with the public mounts.
|
|
116
116
|
|
|
117
|
-
You can instead use [`eve/next`](../frontend/nextjs#
|
|
117
|
+
You can instead use [`eve/next`](../frontend/nextjs#self-host) if you want Next.js to start built agent processes and provide the browser-facing proxy routes. That integration is optional; `eve/vercel` configuration is not used by a self-hosted process manager.
|
|
118
118
|
|
|
119
119
|
## Run schedules
|
|
120
120
|
|