eve 0.85.0 → 0.87.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +34 -3073
- package/README.md +7 -4
- package/dist/src/acp/adapter.d.ts +2 -26
- package/dist/src/acp/adapter.js +1 -1
- package/dist/src/acp/server.d.ts +0 -3
- package/dist/src/ai/decision-adapter.d.ts +5 -3
- package/dist/src/ai/decision-adapter.js +1 -1
- package/dist/src/ai/decision-types.d.ts +4 -3
- package/dist/src/channel/adapter.d.ts +0 -14
- package/dist/src/channel/auth/definitions.d.ts +0 -4
- package/dist/src/channel/channel-address.d.ts +1 -1
- package/dist/src/channel/channel-address.js +1 -1
- package/dist/src/channel/channel-operations.d.ts +2 -2
- package/dist/src/channel/channel-operations.js +1 -1
- package/dist/src/channel/prompt-queue.d.ts +0 -2
- package/dist/src/channel/session-not-active-error.d.ts +10 -5
- package/dist/src/channel/session-not-active-error.js +1 -1
- package/dist/src/channel/session-stranded-error.d.ts +1 -1
- package/dist/src/channel/session.d.ts +3 -4
- package/dist/src/channel/session.js +1 -1
- package/dist/src/channel/types.d.ts +5 -14
- package/dist/src/chunks/{use-eve-agent-B2jCfcnG.js → use-eve-agent-BExXjBv6.js} +82 -72
- package/dist/src/chunks/{use-eve-agent-DCLFi26P.js → use-eve-agent-C0KHCyb9.js} +82 -72
- 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/command-options.d.ts +4 -4
- package/dist/src/cli/dev/command.js +1 -1
- package/dist/src/cli/dev/tui/runner.d.ts +1 -1
- package/dist/src/cli/dev/tui/runner.js +2 -2
- package/dist/src/cli/dev/tui/test/fake-eve-server.js +1 -1
- package/dist/src/cli/dev/tui/tool-format.d.ts +2 -2
- package/dist/src/cli/dev/ui-options.d.ts +4 -4
- package/dist/src/cli/dev/ui-options.js +1 -1
- package/dist/src/cli/run.js +1 -1
- package/dist/src/client/agent-info-error.d.ts +4 -1
- package/dist/src/client/agent-info-error.js +1 -1
- package/dist/src/client/agent-session.d.ts +1 -4
- package/dist/src/client/agent-session.js +1 -1
- package/dist/src/client/agent-stream-follower.js +1 -1
- package/dist/src/client/client-error.d.ts +13 -4
- package/dist/src/client/client-error.js +1 -1
- package/dist/src/client/delivery.d.ts +2 -17
- package/dist/src/client/health-response-error.d.ts +4 -1
- package/dist/src/client/health-response-error.js +1 -1
- package/dist/src/client/index.d.ts +5 -3
- package/dist/src/client/index.js +1 -1
- package/dist/src/client/open-stream.d.ts +7 -12
- package/dist/src/client/open-stream.js +1 -1
- package/dist/src/client/session-controls.d.ts +2 -2
- package/dist/src/client/session-controls.js +1 -1
- package/dist/src/client/session-event-stream.d.ts +2 -2
- package/dist/src/client/session-event-stream.js +1 -1
- package/dist/src/client/session-store.d.ts +2 -6
- package/dist/src/client/session-store.js +1 -1
- package/dist/src/client/session.d.ts +4 -13
- package/dist/src/client/session.js +1 -1
- package/dist/src/client/sessions.d.ts +3 -6
- package/dist/src/client/types.d.ts +23 -32
- package/dist/src/compiled/.vendor-stamp.json +4 -4
- package/dist/src/compiled/@vercel/agent-runs/LICENSE +202 -0
- package/dist/src/compiled/@vercel/schedules/index.d.ts +45 -6
- package/dist/src/compiled/@vercel/schedules/index.js +2 -2
- package/dist/src/compiler/manifest.js +1 -1
- package/dist/src/compiler/normalize-agent-config.js +1 -1
- package/dist/src/compiler/normalize-connection.d.ts +1 -1
- package/dist/src/compiler/normalize-connection.js +1 -1
- package/dist/src/compiler/normalize-instructions.js +1 -1
- package/dist/src/compiler/normalize-skill.js +1 -1
- package/dist/src/compiler/resolve-workspace-subagent.js +1 -1
- package/dist/src/context/memory-tools.d.ts +9 -5
- package/dist/src/discover/sandbox.js +1 -1
- package/dist/src/dynamic/definition.d.ts +11 -5
- package/dist/src/dynamic/definition.js +1 -1
- package/dist/src/evals/mock-model.d.ts +1 -1
- package/dist/src/evals/session-manager.d.ts +0 -2
- package/dist/src/evals/session.d.ts +1 -11
- package/dist/src/evals/session.js +1 -1
- package/dist/src/eve-channel/index.js +1 -1
- package/dist/src/eve-channel/support.js +1 -1
- package/dist/src/execution/dynamic-workflow/tool.js +1 -1
- package/dist/src/execution/effective-agent-config.js +1 -1
- package/dist/src/execution/proxied-deliver-step.js +1 -1
- package/dist/src/execution/sandbox/bindings/just-bash-runtime.d.ts +1 -2
- package/dist/src/execution/sandbox/bindings/just-bash-runtime.js +1 -1
- package/dist/src/execution/sandbox/bindings/just-bash.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/principal.d.ts +8 -0
- package/dist/src/execution/session/principal.js +1 -1
- 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/tools/agent-router-workflow.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/instrumentation/ai-sdk-telemetry.d.ts +0 -2
- package/dist/src/instrumentation/providers.d.ts +1 -38
- package/dist/src/instrumentation/providers.js +1 -1
- package/dist/src/instrumentation/setup-context.d.ts +1 -7
- package/dist/src/internal/application/package.d.ts +1 -0
- package/dist/src/internal/application/package.js +1 -1
- package/dist/src/internal/application/stamped-package-version.js +1 -1
- package/dist/src/internal/authored-definition/core.js +1 -1
- package/dist/src/internal/authored-definition/schema-backed.js +1 -1
- package/dist/src/internal/classify-model-routing.d.ts +2 -3
- package/dist/src/internal/nitro/host/create-application-nitro.js +1 -1
- package/dist/src/internal/nitro/routes/schedule-collection-consumer.js +1 -1
- package/dist/src/internal/runtime-model.d.ts +9 -4
- package/dist/src/internal/runtime-model.js +1 -1
- package/dist/src/internal/workflow-bundle/authored-workflow-directives.js +1 -1
- package/dist/src/internal/workflow-bundle/builder-support.d.ts +1 -1
- package/dist/src/internal/workflow-bundle/builder-support.js +1 -1
- package/dist/src/internal/workflow-bundle/workflow-transformer.js +1 -1
- package/dist/src/models/auto.js +1 -1
- package/dist/src/protocol/delivery.d.ts +1 -0
- package/dist/src/protocol/reset-session.d.ts +0 -2
- package/dist/src/protocol/routes.d.ts +9 -2
- package/dist/src/protocol/routes.js +1 -1
- package/dist/src/public/channels/chat-sdk/chatSdkChannel.d.ts +1 -22
- package/dist/src/public/channels/discord/discordChannel.d.ts +3 -12
- package/dist/src/public/channels/discord/gateway/{index.d.ts → relay.d.ts} +2 -2
- package/dist/src/public/channels/discord/gateway/relay.js +1 -0
- package/dist/src/public/channels/discord/messages.d.ts +4 -4
- package/dist/src/public/channels/github/state.d.ts +0 -2
- package/dist/src/public/channels/index.d.ts +1 -2
- package/dist/src/public/channels/index.js +1 -1
- package/dist/src/public/channels/linear/index.d.ts +1 -1
- package/dist/src/public/channels/linear/index.js +1 -1
- package/dist/src/public/channels/linear/linearChannel.d.ts +0 -5
- package/dist/src/public/channels/linq/index.d.ts +1 -1
- package/dist/src/public/channels/linq/linqChannel.d.ts +7 -5
- package/dist/src/public/channels/photon/index.d.ts +1 -1
- package/dist/src/public/channels/photon/photonIMessageChannel.d.ts +15 -4
- package/dist/src/public/channels/slack/api.d.ts +1 -1
- package/dist/src/public/channels/slack/api.js +1 -1
- package/dist/src/public/channels/slack/blocks.d.ts +1 -1
- package/dist/src/public/channels/slack/blocks.js +2 -2
- package/dist/src/public/channels/slack/cards.d.ts +2 -297
- package/dist/src/public/channels/slack/cards.js +1 -1
- package/dist/src/public/channels/slack/index.d.ts +2 -2
- package/dist/src/public/channels/slack/index.js +1 -1
- package/dist/src/public/channels/slack/session-operations.d.ts +2 -2
- package/dist/src/public/channels/slack/session-operations.js +1 -1
- package/dist/src/public/channels/slack/slackChannel.d.ts +11 -72
- package/dist/src/public/channels/slack/slackChannel.js +1 -1
- package/dist/src/public/channels/teams/teamsChannel.d.ts +4 -3
- package/dist/src/public/channels/telegram/hitl.d.ts +2 -9
- package/dist/src/public/channels/telegram/index.d.ts +1 -1
- package/dist/src/public/channels/telegram/telegramChannel.d.ts +0 -2
- package/dist/src/public/channels/twilio/twilioChannel.d.ts +0 -2
- package/dist/src/public/channels/undelivered-reply.d.ts +0 -5
- package/dist/src/public/definitions/agent.d.ts +15 -7
- package/dist/src/public/definitions/agent.js +1 -1
- package/dist/src/public/definitions/channel.d.ts +7 -5
- package/dist/src/public/definitions/channel.js +1 -1
- package/dist/src/public/definitions/connections/protocol.d.ts +1 -7
- package/dist/src/public/definitions/connections/protocol.js +1 -1
- package/dist/src/public/experimental/channels/discord/gateway.d.ts +1 -0
- package/dist/src/public/experimental/channels/discord/gateway.js +1 -0
- package/dist/src/public/experimental/sandbox/just-bash.d.ts +1 -0
- package/dist/src/public/experimental/sandbox/just-bash.js +1 -0
- package/dist/src/public/experimental/workspace/index.d.ts +1 -0
- package/dist/src/public/experimental/workspace/index.js +1 -0
- package/dist/src/public/index.d.ts +2 -2
- package/dist/src/public/index.js +1 -1
- package/dist/src/public/instrumentation/otel.d.ts +1 -1
- package/dist/src/public/instrumentation/provider.d.ts +1 -1
- package/dist/src/public/instrumentation/provider.js +1 -1
- package/dist/src/public/memory/file/backend.d.ts +1 -1
- package/dist/src/public/memory/file/backends/in-memory.js +1 -1
- package/dist/src/public/memory/file/backends/vercel-blob.js +1 -1
- package/dist/src/public/memory/file/provider.js +1 -1
- package/dist/src/public/memory/index.d.ts +3 -11
- package/dist/src/public/models/anthropic/index.d.ts +1 -1
- package/dist/src/public/models/index.d.ts +1 -0
- package/dist/src/public/models/openai/index.d.ts +2 -2
- package/dist/src/public/next/index.d.ts +2 -2
- package/dist/src/public/sandbox/just-bash-sandbox.d.ts +27 -20
- package/dist/src/public/sandbox/just-bash.d.ts +0 -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/sessions/index.d.ts +1 -0
- package/dist/src/public/sessions/index.js +1 -1
- package/dist/src/public/tools/index.d.ts +1 -1
- package/dist/src/public/tools/index.js +1 -1
- package/dist/src/public/workflow/api.d.ts +25 -0
- package/dist/src/public/workflow/api.js +1 -0
- package/dist/src/public/workflow/index.d.ts +76 -0
- package/dist/src/public/workflow/index.js +1 -0
- package/dist/src/public/workflow-modules.d.ts +2 -17
- package/dist/src/react/use-eve-agent.d.ts +3 -2
- package/dist/src/react/use-eve-agent.js +1 -1
- package/dist/src/reactions/kinds/model.js +1 -1
- package/dist/src/runtime/agent/resolve-model.js +1 -1
- package/dist/src/runtime/resolve-agent.js +1 -1
- package/dist/src/runtime/resolve-dynamic.js +1 -1
- package/dist/src/runtime/subagents/dynamic-agent-config.js +1 -1
- package/dist/src/runtime/subagents/workflow.js +1 -1
- package/dist/src/sandbox/providers/default.js +1 -1
- package/dist/src/self-modification/extension/subagents/agent/agent.d.ts +2 -2
- package/dist/src/self-modification/sandbox.js +1 -1
- package/dist/src/setup/integrations/discord/daemon.js +2 -2
- package/dist/src/setup/scaffold/create/project.js +2 -2
- package/dist/src/setup/scaffold/create/web-template.d.ts +2 -2
- package/dist/src/setup/scaffold/create/web-template.js +2 -2
- package/dist/src/setup/verified-remote-agent.d.ts +1 -3
- package/dist/src/shared/agent-definition.d.ts +18 -9
- package/dist/src/shared/eve-error.d.ts +22 -0
- package/dist/src/shared/eve-error.js +1 -0
- package/dist/src/shared/session.d.ts +2 -2
- package/dist/src/shared/token-usage.d.ts +7 -1
- package/dist/src/svelte/index.js +1 -1
- package/dist/src/svelte/use-eve-agent.d.ts +2 -1
- package/dist/src/svelte/use-eve-agent.js +1 -1
- package/dist/src/tools/definition.d.ts +7 -5
- package/dist/src/tools/definition.js +1 -1
- package/dist/src/tools/provided/ask-question-workflow.js +1 -1
- package/dist/src/tools/provided/sleep-workflow.js +1 -1
- package/dist/src/tracing/eve/batch-span-processor.d.ts +1 -1
- package/dist/src/tracing/eve/content-span-processor.d.ts +1 -19
- package/dist/src/tracing/eve/otel-configuration.d.ts +6 -0
- package/dist/src/tracing/eve/otel-declaration.d.ts +6 -19
- package/dist/src/tracing/eve/span-export-policy.d.ts +0 -2
- package/dist/src/tracing/local/instrumentation-runtime.d.ts +0 -3
- package/dist/src/tracing/local/traces.d.ts +0 -13
- package/dist/src/vue/index.js +1 -1
- package/dist/src/vue/use-eve-agent.d.ts +3 -2
- package/dist/src/vue/use-eve-agent.js +1 -1
- package/docs/agent-config.md +15 -11
- package/docs/channels/custom.mdx +26 -10
- package/docs/channels/discord.mdx +10 -10
- package/docs/channels/eve.mdx +15 -13
- package/docs/channels/linear.mdx +11 -0
- package/docs/channels/linq.mdx +5 -1
- package/docs/channels/photon.mdx +6 -1
- package/docs/channels/slack.mdx +73 -14
- package/docs/channels/telegram.mdx +6 -0
- package/docs/code-extension.mdx +25 -0
- package/docs/concepts/default-harness.md +2 -2
- package/docs/concepts/execution-model-and-durability.mdx +11 -11
- package/docs/concepts/project-structure.mdx +1 -1
- package/docs/concepts/security-model.md +6 -2
- package/docs/concepts/sessions-runs-and-streaming.md +23 -10
- package/docs/concepts/upgrade-to-v27-events.md +70 -1
- package/docs/connections/overview.mdx +4 -0
- package/docs/evals/reporters.mdx +21 -0
- package/docs/extensions.md +12 -0
- package/docs/getting-started.mdx +6 -0
- package/docs/guides/auth-and-route-protection.md +2 -1
- package/docs/guides/client/continuations.mdx +12 -10
- package/docs/guides/client/messages.mdx +24 -1
- package/docs/guides/client/overview.mdx +8 -6
- package/docs/guides/client/streaming.mdx +25 -7
- package/docs/guides/decide.md +3 -3
- package/docs/guides/deployment/self-hosting.md +1 -1
- package/docs/guides/deployment/vercel.mdx +1 -1
- package/docs/guides/dev-tui.md +2 -2
- 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 +18 -16
- package/docs/guides/frontend/use-eve-agent-vue.mdx +18 -16
- package/docs/guides/frontend/use-eve-agent.mdx +385 -0
- package/docs/guides/hooks.md +1 -1
- package/docs/guides/instrumentation/otel.mdx +3 -1
- package/docs/guides/prepare-for-1-0.md +255 -0
- package/docs/guides/remote-agents.md +26 -22
- package/docs/guides/self-modification.md +6 -0
- package/docs/instructions.mdx +1 -1
- package/docs/memory/custom-provider.md +1 -1
- package/docs/memory/file.md +11 -2
- package/docs/meta.json +1 -0
- package/docs/reference/agent-files.md +17 -17
- package/docs/reference/cli.md +15 -11
- package/docs/reference/typescript-api.md +46 -20
- package/docs/sandbox/custom-providers.mdx +2 -0
- package/docs/sandbox/default.mdx +6 -6
- package/docs/sandbox/index.mdx +6 -6
- package/docs/sandbox/just-bash.mdx +30 -21
- package/docs/subagents/index.mdx +4 -4
- package/docs/tools/human-in-the-loop.md +1 -1
- package/docs/tools/workflows.mdx +52 -8
- package/docs/tutorial/first-agent.mdx +1 -1
- package/package.json +46 -27
- package/dist/src/public/channels/discord/gateway/index.js +0 -1
- package/dist/src/self-modification/agent.d.ts +0 -12
- package/dist/src/self-modification/agent.js +0 -1
|
@@ -60,7 +60,7 @@ Then configure the public `https://…/eve/v1/discord` route as the application'
|
|
|
60
60
|
|
|
61
61
|
## Reply to DMs and mentions (experimental)
|
|
62
62
|
|
|
63
|
-
Discord sends ordinary messages, such as DMs, mentions, and thread replies, only over its [Gateway WebSocket](https://discord.com/developers/docs/events/gateway), not as HTTP Interactions. Gateway support is experimental, and its API may change. To receive them, run `
|
|
63
|
+
Discord sends ordinary messages, such as DMs, mentions, and thread replies, only over its [Gateway WebSocket](https://discord.com/developers/docs/events/gateway), not as HTTP Interactions. Gateway support is experimental, and its API may change. To receive them, run `runDiscordGatewayRelay` from `eve/experimental/channels/discord/gateway` in a process that stays connected, and enable the matching route on the channel. The relay forwards each `MESSAGE_CREATE` dispatch to the agent unchanged, and the channel replies through the same handlers it uses for commands, including HITL buttons and error messages.
|
|
64
64
|
|
|
65
65
|
```text
|
|
66
66
|
Discord Gateway ── WebSocket ──▶ relay (Vercel Daemon) ── POST /eve/v1/discord/gateway ──▶ agent ── REST ──▶ Discord
|
|
@@ -88,9 +88,9 @@ A Vercel Daemon keeps the relay connected. Vercel Daemons are in beta. When you
|
|
|
88
88
|
|
|
89
89
|
```ts title="daemon/main.ts"
|
|
90
90
|
import { connectDiscordCredentials } from "@vercel/connect/eve";
|
|
91
|
-
import {
|
|
91
|
+
import { runDiscordGatewayRelay } from "eve/experimental/channels/discord/gateway";
|
|
92
92
|
|
|
93
|
-
await
|
|
93
|
+
await runDiscordGatewayRelay({
|
|
94
94
|
credentials: connectDiscordCredentials("discord/my-agent"),
|
|
95
95
|
messageContent: false,
|
|
96
96
|
url: process.env.EVE_URL,
|
|
@@ -145,7 +145,7 @@ https://discord.com/oauth2/authorize?client_id=<APPLICATION_ID>&scope=bot+applic
|
|
|
145
145
|
|
|
146
146
|
### Run the relay outside Vercel
|
|
147
147
|
|
|
148
|
-
`
|
|
148
|
+
`runDiscordGatewayRelay` runs on any host that keeps a Node.js 24 process up, such as a VM, a container platform, or a home server, while the agent stays on Vercel. Run exactly one relay per bot. Three things change off Vercel:
|
|
149
149
|
|
|
150
150
|
- **Credentials.** Vercel Connect authenticates callers with your project's Vercel OIDC token, which other hosts don't have, so give the relay the bot token directly. The agent can keep using Connect.
|
|
151
151
|
- **URL.** The relay can't read `VERCEL_PROJECT_PRODUCTION_URL`, so pass the agent's URL as `url`.
|
|
@@ -173,9 +173,9 @@ On the relay, set `DISCORD_BOT_TOKEN` to the token from **Bot** → **Reset Toke
|
|
|
173
173
|
|
|
174
174
|
```ts title="relay/main.ts"
|
|
175
175
|
import { httpBasic } from "eve/agents/auth";
|
|
176
|
-
import {
|
|
176
|
+
import { runDiscordGatewayRelay } from "eve/experimental/channels/discord/gateway";
|
|
177
177
|
|
|
178
|
-
await
|
|
178
|
+
await runDiscordGatewayRelay({
|
|
179
179
|
// Reads DISCORD_BOT_TOKEN when `credentials` is omitted.
|
|
180
180
|
url: process.env.EVE_URL,
|
|
181
181
|
auth: httpBasic({ username: "discord-relay", password: process.env.DISCORD_RELAY_SECRET! }),
|
|
@@ -207,7 +207,7 @@ A mention in a text channel starts a thread, as the Slack channel does, so each
|
|
|
207
207
|
|
|
208
208
|
Mention the bot's user, not the role with the same name that Discord creates for it. Discord's autocomplete offers both, and a role mention doesn't address the bot.
|
|
209
209
|
|
|
210
|
-
Discord sends the text of messages that neither mention the bot nor arrive as a DM only to bots with the privileged **Message Content** intent. Without it, thread follow-ups that skip the mention, and replies whose author turned off the reply ping, arrive empty and are ignored. `eve add channel/discord` turns the intent on and sets `messageContent: true` when Discord allows it, which it does for bots in fewer than 100 servers. Otherwise, enable **Message Content Intent** under **Bot** in the Discord Developer Portal, then pass `messageContent: true` to `
|
|
210
|
+
Discord sends the text of messages that neither mention the bot nor arrive as a DM only to bots with the privileged **Message Content** intent. Without it, thread follow-ups that skip the mention, and replies whose author turned off the reply ping, arrive empty and are ignored. `eve add channel/discord` turns the intent on and sets `messageContent: true` when Discord allows it, which it does for bots in fewer than 100 servers. Otherwise, enable **Message Content Intent** under **Bot** in the Discord Developer Portal, then pass `messageContent: true` to `runDiscordGatewayRelay`. Discord refuses the relay's connection if you request the intent before enabling it, and the relay stops with an error naming the close code.
|
|
211
211
|
|
|
212
212
|
To choose which messages run the agent, under what `auth`, or which session they join, set `gateway.onMessage(ctx, message)`. It runs for every message from a person and returns `{ auth }` to dispatch or `null` to ignore. `message.addressed` reports whether the default would answer, and `message.referencedMessageId` names the message it replies to. `defaultDiscordMessageAuth(message)` gives the author the same principal `defaultDiscordAuth` gives them for commands and button presses, so requester-only approvals work across both:
|
|
213
213
|
|
|
@@ -278,7 +278,7 @@ export default discordChannel({
|
|
|
278
278
|
|
|
279
279
|
### Forward messages from your own relay
|
|
280
280
|
|
|
281
|
-
The route accepts any relay that holds a Gateway connection, such as an existing discord.js bot, so you don't have to run `
|
|
281
|
+
The route accepts any relay that holds a Gateway connection, such as an existing discord.js bot, so you don't have to run `runDiscordGatewayRelay`. Forward each Gateway dispatch payload unchanged, as the JSON body of a `POST` to `/eve/v1/discord/gateway`:
|
|
282
282
|
|
|
283
283
|
```json
|
|
284
284
|
{
|
|
@@ -301,7 +301,7 @@ The route handles `MESSAGE_CREATE` and acknowledges other dispatch types without
|
|
|
301
301
|
| `429` | Rate limited before the route ran. | Retry with backoff. |
|
|
302
302
|
| `5xx` | Unknown. The route answers `500` before dispatch when `onMessage` throws, but a platform `502` or `504` can come after a turn started. | Not retry, unless your relay deduplicates. |
|
|
303
303
|
|
|
304
|
-
eve does not deduplicate messages. If the relay retries after eve already started a turn, for example because the response was lost, the agent answers twice. `
|
|
304
|
+
eve does not deduplicate messages. If the relay retries after eve already started a turn, for example because the response was lost, the agent answers twice. `runDiscordGatewayRelay` retries only a `429`, or a connection that failed before the request reached eve.
|
|
305
305
|
|
|
306
306
|
### Run the relay locally
|
|
307
307
|
|
|
@@ -317,7 +317,7 @@ Scale the production daemon to zero while you do this. Every connection receives
|
|
|
317
317
|
|
|
318
318
|
- Run one relay per bot. Each connection receives every message. Bots large enough to need Discord's sharding are out of scope.
|
|
319
319
|
- Messages sent while no relay is connected are not delivered. On a deploy, Vercel sends `SIGTERM` to the old daemon and starts the new one at the same time. The old relay disconnects right away, so messages sent while the new daemon boots and connects, usually a few seconds, are lost. A crash or restart leaves the same gap. The relay does not resume the previous Gateway session in a new process, so Discord does not replay these messages.
|
|
320
|
-
- `
|
|
320
|
+
- `runDiscordGatewayRelay` drops a message, rather than retrying it, when eve answers with a `5xx`, takes longer than 30 seconds to accept it, or the connection fails after the request is sent. eve may have started the turn already, and a retry could answer twice. The relay logs each dropped message.
|
|
321
321
|
|
|
322
322
|
## How the channel handles messages
|
|
323
323
|
|
package/docs/channels/eve.mdx
CHANGED
|
@@ -35,10 +35,6 @@ eve link
|
|
|
35
35
|
eve add channel/web
|
|
36
36
|
```
|
|
37
37
|
|
|
38
|
-
`eve init --channel-web-nextjs` keeps its existing scaffolding behavior and does
|
|
39
|
-
not provision authentication. Sign-in setup runs through `eve add channel/web`
|
|
40
|
-
or the terminal UI's channel picker.
|
|
41
|
-
|
|
42
38
|
The generated Next.js app uses Better Auth sessions. The selected agent's HTTP
|
|
43
39
|
channel verifies the same session, while retaining Vercel OIDC and local
|
|
44
40
|
development access. In an agent workspace, setup configures only the selected
|
|
@@ -95,7 +91,7 @@ The default eve channel inspects the agent, creates sessions, accepts callbacks
|
|
|
95
91
|
- `POST /eve/v1/session/:sessionId/cancel` (cancel the in-flight turn)
|
|
96
92
|
- `POST /eve/v1/session/:sessionId/clear` (clear the session's model history)
|
|
97
93
|
- `POST /eve/v1/session/:sessionId/compact` (compact the session's context)
|
|
98
|
-
- `POST /eve/v1/session/:sessionId/
|
|
94
|
+
- `POST /eve/v1/session/:sessionId/end` (retire the session)
|
|
99
95
|
- `GET /eve/v1/session/:sessionId/stream` (stream events as NDJSON)
|
|
100
96
|
|
|
101
97
|
The session routes use only durable session IDs. Create a session explicitly, then put its returned ID in every follow-up, control, and stream path.
|
|
@@ -109,7 +105,7 @@ deployment, `accepted` (HTTP 202) when a background preparation hint has been qu
|
|
|
109
105
|
`unsupported` when the World or owner cannot prepare, or `no_active_session` when no live
|
|
110
106
|
owner exists. Other successful statuses use HTTP 200. Acceptance does not mean the handoff
|
|
111
107
|
has completed. Idle preparation preserves the session ID, stream, history, and expiry;
|
|
112
|
-
active work is not interrupted. See the [frontend guide](../guides/frontend/
|
|
108
|
+
active work is not interrupted. See the [frontend guide](../guides/frontend/use-eve-agent#prewarming)
|
|
113
109
|
for client usage and deployment routing.
|
|
114
110
|
|
|
115
111
|
`GET /eve/v1/health` is public and returns `{ ok: true, status: "ready", workflowId: string }`. `GET /eve/v1/info` uses the channel's auth policy and returns agent-info version 6. The TypeScript client validates both successful payloads: malformed health JSON throws `HealthResponseError`, malformed inspection JSON throws `AgentInfoResponseError`, and a non-success response from either route throws `ClientError`.
|
|
@@ -130,7 +126,7 @@ repeating the request with the same key returns the same `deliveryId`, and the i
|
|
|
130
126
|
again. Unlike a channel's [retried deliveries](./custom#retried-deliveries), whose duplicates get a
|
|
131
127
|
new receipt settled `ignored`, the repeat's receipt is the original's. The session remembers its
|
|
132
128
|
last 1,024 keys, so use a new key for new input. The compact and clear routes
|
|
133
|
-
accept no body fields; omit the body or send `{}`. Cancel accepts `turnId`;
|
|
129
|
+
accept no body fields; omit the body or send `{}`. Cancel accepts `turnId`; end accepts `reason`.
|
|
134
130
|
|
|
135
131
|
Open payload objects such as `clientContext` keep their existing contracts. Delegated requests
|
|
136
132
|
with a `callback` accept, and ignore, the retired `activityObserver` field so older senders keep
|
|
@@ -242,7 +238,7 @@ export default eveChannel({
|
|
|
242
238
|
|
|
243
239
|
Stream a session as newline-delimited JSON from `GET /eve/v1/session/:sessionId/stream`. The [session protocol](../concepts/sessions-runs-and-streaming#stream-a-session) defines the event set, envelopes, cursors, and reconnection behavior.
|
|
244
240
|
|
|
245
|
-
Following a stranded session's stream returns `409 session_stranded`, just like a send. The TypeScript client reports `ClientSessionStrandedError` without retrying. Pass `follow=false` to read the recorded history instead: the response ends at the durable tail, carries the `x-eve-stream-tail-index` header, and never inspects or changes the session, so it works before
|
|
241
|
+
Following a stranded session's stream returns `409 session_stranded`, just like a send. The TypeScript client reports `ClientSessionStrandedError` without retrying. Pass `follow=false` to read the recorded history instead: the response ends at the durable tail, carries the `x-eve-stream-tail-index` header, and never inspects or changes the session, so it works before ending the session. End attempts to append its control delivery's `delivery.admitted` (`source: { control: "reset" }`) and `delivery.settled`, then `session.ended` with `outcome: "failed"`, error code `session_stranded`, and cause `{ deliveryId }` naming that delivery, then close the stream. Existing readers finish when the stream ends.
|
|
246
242
|
|
|
247
243
|
A session started by an eve version before v27 stores v26 events. Its stream route serves them as the v27 lines they record, so v27 clients render that history: messages, reasoning, tool calls and results, approvals, questions, sign-ins, subagents, clears, and compactions. Streamed text previews aren't translated, so a v26 session that is still running shows each part once it completes.
|
|
248
244
|
|
|
@@ -258,15 +254,17 @@ See [Cancel the in-flight turn](../concepts/sessions-runs-and-streaming#cancel-t
|
|
|
258
254
|
|
|
259
255
|
### Clear context
|
|
260
256
|
|
|
261
|
-
Post to `/eve/v1/session/:sessionId/clear` to remove model-message history while preserving the session ID, system prompt, tools, skills, durable state, limits, and sandbox. A stranded session cannot run the clear, so the route returns `409 session_stranded` and changes nothing; post to the `
|
|
257
|
+
Post to `/eve/v1/session/:sessionId/clear` to remove model-message history while preserving the session ID, system prompt, tools, skills, durable state, limits, and sandbox. A stranded session cannot run the clear, so the route returns `409 session_stranded` and changes nothing; post to the `end` route instead. See [Compact, clear, and end](../concepts/sessions-runs-and-streaming#compact-clear-and-end).
|
|
262
258
|
|
|
263
259
|
### Compact context
|
|
264
260
|
|
|
265
|
-
Post to `/eve/v1/session/:sessionId/compact` to summarize context without sending a user message. The operation waits for an active turn to settle and reports its result on the stream. See [Compact, clear, and
|
|
261
|
+
Post to `/eve/v1/session/:sessionId/compact` to summarize context without sending a user message. The operation waits for an active turn to settle and reports its result on the stream. See [Compact, clear, and end](../concepts/sessions-runs-and-streaming#compact-clear-and-end).
|
|
262
|
+
|
|
263
|
+
<a id="reset-a-session" />
|
|
266
264
|
|
|
267
|
-
###
|
|
265
|
+
### End a session
|
|
268
266
|
|
|
269
|
-
Post to `/eve/v1/session/:sessionId/
|
|
267
|
+
Post to `/eve/v1/session/:sessionId/end` to terminally retire that session. End never replaces the ID automatically; create a new session explicitly for a fresh conversation. End also works on a stranded session: eve cancels the stranded workflow run directly instead of delivering the command to it. See [Compact, clear, and end](../concepts/sessions-runs-and-streaming#compact-clear-and-end).
|
|
270
268
|
|
|
271
269
|
## Replace or disable the defaults
|
|
272
270
|
|
|
@@ -344,6 +342,10 @@ export default eveChannel({
|
|
|
344
342
|
});
|
|
345
343
|
```
|
|
346
344
|
|
|
345
|
+
Audience also selects the default [run-data retention](../agent-config#run-data-retention).
|
|
346
|
+
Outside development, private and unknown-audience sessions request deletion when
|
|
347
|
+
they end. The Workflow World must support deletion to enforce it.
|
|
348
|
+
|
|
347
349
|
`audience` controls observability content capture; it does not change who may
|
|
348
350
|
call the endpoint. `auth` still controls access. For a classification that
|
|
349
351
|
depends on channel state or application-specific verified data, use a [custom
|
|
@@ -448,7 +450,7 @@ export default defineChannel({
|
|
|
448
450
|
|
|
449
451
|
The client then resumes that session by id, for example with `useEveAgent({ initialSession: { sessionId, streamIndex: 0 }, resume: true })`. `created` is `false` when a session already owned the address, or another `create()` or `send()` claimed it first. That session comes back unchanged and your `history` was not added, so check `created` before treating the session as seeded. Use a new address for each new conversation or branch.
|
|
450
452
|
|
|
451
|
-
When the session at the address is [stranded](../guides/deployment/self-hosting#recover-a-stranded-session), `create()` throws `SessionStrandedError` instead of replacing it, because that session may hold the conversation you meant to import. Call `
|
|
453
|
+
When the session at the address is [stranded](../guides/deployment/self-hosting#recover-a-stranded-session), `create()` throws `SessionStrandedError` instead of replacing it, because that session may hold the conversation you meant to import. Call `end()` on the address, then `create()` again.
|
|
452
454
|
|
|
453
455
|
`create()` returns once the new session claims its address, so a `send()` right after it reaches that session. It throws if no session claims the address within 15 seconds.
|
|
454
456
|
|
package/docs/channels/linear.mdx
CHANGED
|
@@ -101,6 +101,17 @@ Files uploaded to Linear and referenced in an Agent Session prompt, whether as m
|
|
|
101
101
|
|
|
102
102
|
Event handlers receive `channel.linear`, which exposes `createActivity`, `listActivities`, and `updateSession` for custom Agent Activity delivery and Agent Session metadata.
|
|
103
103
|
|
|
104
|
+
### Low-level API helpers
|
|
105
|
+
|
|
106
|
+
Import `callLinearGraphQL` and `createLinearAgentActivity` from
|
|
107
|
+
`eve/channels/linear` when a custom integration needs a direct API call.
|
|
108
|
+
`callLinearGraphQL<T>({ query, queryName, variables?, credentials?, api? })`
|
|
109
|
+
returns the response's `data` as `T` and throws `LinearApiError` for HTTP or
|
|
110
|
+
GraphQL errors. `createLinearAgentActivity({ activity, credentials?, api? })`
|
|
111
|
+
posts an activity to a Linear Agent Session and returns `{ id, success }`.
|
|
112
|
+
Both accept `credentials.accessToken` and optional API overrides; prefer the
|
|
113
|
+
channel context's API handle when it already has the configured credentials.
|
|
114
|
+
|
|
104
115
|
## Custom hooks
|
|
105
116
|
|
|
106
117
|
Return `{ auth }` to dispatch, or `null` to acknowledge without waking the agent. Return `title` alongside `auth` to set the title when the dispatch starts a run.
|
package/docs/channels/linq.mdx
CHANGED
|
@@ -37,10 +37,14 @@ export default linqChannel({
|
|
|
37
37
|
});
|
|
38
38
|
```
|
|
39
39
|
|
|
40
|
-
Set `route` to override the webhook path or `webhookVerifier` to use a different trusted-forwarder verifier. A verifier rejects a webhook by throwing or returning a falsy value such as `null` or `false`.
|
|
40
|
+
Set `route` to override the webhook path or `webhookVerifier` (typed `LinqWebhookVerifier` from `eve/channels/linq`) to use a different trusted-forwarder verifier. A verifier receives the request and its raw body bytes, and rejects a webhook by throwing or returning a falsy value such as `null` or `false`.
|
|
41
41
|
|
|
42
42
|
## Tapbacks
|
|
43
43
|
|
|
44
|
+
`IMESSAGE_TAPBACKS` from `eve/channels/linq` lists the built-in tapback names.
|
|
45
|
+
Use it to populate a picker or validate a named reaction. Tapback APIs can also
|
|
46
|
+
accept a single emoji; the list does not enumerate those.
|
|
47
|
+
|
|
44
48
|
eve ignores tapbacks people send unless you pass `onTapback`. It receives the tapback and returns the same result as `onMessage`, or `null` to ignore it:
|
|
45
49
|
|
|
46
50
|
```ts title="agent/channels/linq.ts"
|
package/docs/channels/photon.mdx
CHANGED
|
@@ -59,10 +59,15 @@ export default photonIMessageChannel({
|
|
|
59
59
|
```
|
|
60
60
|
|
|
61
61
|
Set `route` to override the webhook path or `webhookVerifier` to use a different
|
|
62
|
-
trusted-forwarder verifier.
|
|
62
|
+
trusted-forwarder verifier. `eve/channels/photon` exports the `PhotonIMessageWebhookVerifier`,
|
|
63
|
+
`PhotonIMessageChannelCredentials`, and `PhotonProjectCredentials` types for these options.
|
|
63
64
|
|
|
64
65
|
## Tapbacks
|
|
65
66
|
|
|
67
|
+
`IMESSAGE_TAPBACKS` from `eve/channels/photon` lists the built-in tapback names.
|
|
68
|
+
Use it to populate a picker or validate a named reaction. Tapback APIs can also
|
|
69
|
+
accept a single emoji; the list does not enumerate those.
|
|
70
|
+
|
|
66
71
|
eve ignores tapbacks people send unless you pass `onTapback`. It receives the
|
|
67
72
|
tapback and returns the same result as `onMessage`, or `null` to ignore it:
|
|
68
73
|
|
package/docs/channels/slack.mdx
CHANGED
|
@@ -278,7 +278,7 @@ async onAppMention(ctx) {
|
|
|
278
278
|
await ctx.cancel();
|
|
279
279
|
await ctx.compact();
|
|
280
280
|
await ctx.clear();
|
|
281
|
-
await ctx.
|
|
281
|
+
await ctx.end({ reason: "Start over" });
|
|
282
282
|
const session = await ctx.resolveSession();
|
|
283
283
|
return { auth: null };
|
|
284
284
|
}
|
|
@@ -286,9 +286,11 @@ async onAppMention(ctx) {
|
|
|
286
286
|
|
|
287
287
|
These calls are independent examples; a handler normally chooses one. `ctx.send()` is the only method that can create a session when the thread is unowned. It derives Slack auth from the inbound user unless `auth` is supplied explicitly. Use `await ctx.resolveSession()` only when later work must stay pinned to the currently owning durable session ID.
|
|
288
288
|
|
|
289
|
-
|
|
289
|
+
<a id="reset-a-conversation" />
|
|
290
290
|
|
|
291
|
-
|
|
291
|
+
#### End a conversation
|
|
292
|
+
|
|
293
|
+
Use the thread-bound `ctx.end({ reason? })` method to retire the conversation. End terminally retires the session that currently owns the thread, including any in-flight turn. The next delivered message starts a new session with fresh history, state, and a new session-scoped sandbox:
|
|
292
294
|
|
|
293
295
|
```ts title="agent/channels/slack.ts"
|
|
294
296
|
export default slackChannel({
|
|
@@ -296,14 +298,14 @@ export default slackChannel({
|
|
|
296
298
|
async onMessage(ctx, message) {
|
|
297
299
|
if (message.text.trim() !== "/new") return null;
|
|
298
300
|
|
|
299
|
-
await ctx.
|
|
301
|
+
await ctx.end({ reason: "Slack user requested /new" });
|
|
300
302
|
await ctx.thread.post("Started a fresh conversation.");
|
|
301
303
|
return null;
|
|
302
304
|
},
|
|
303
305
|
});
|
|
304
306
|
```
|
|
305
307
|
|
|
306
|
-
|
|
308
|
+
End 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 end 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.
|
|
307
309
|
|
|
308
310
|
#### Serve Slack code channels
|
|
309
311
|
|
|
@@ -465,7 +467,7 @@ await ctx.respond(answers, { auth: null, target });
|
|
|
465
467
|
await ctx.cancel({ target, turnId });
|
|
466
468
|
await ctx.compact({ target });
|
|
467
469
|
await ctx.clear({ target });
|
|
468
|
-
await ctx.
|
|
470
|
+
await ctx.end({ reason: "Start over", target });
|
|
469
471
|
const session = await ctx.resolveSession({ target });
|
|
470
472
|
```
|
|
471
473
|
|
|
@@ -900,23 +902,80 @@ renderers: [
|
|
|
900
902
|
|
|
901
903
|
The private authorization button uses the label **Sign in**, so long connection display names do not make the button invalid. The public status identifies the connection.
|
|
902
904
|
|
|
905
|
+
### Cards
|
|
906
|
+
|
|
907
|
+
Use the card builders from `eve/channels/slack` for typed message layouts, or pass raw Slack blocks with `{ blocks, text }`. Cards are plain data, not JSX components.
|
|
908
|
+
|
|
909
|
+
| Builders | Use |
|
|
910
|
+
| --------------------------------------- | -------------------------------------------- |
|
|
911
|
+
| `Card`, `CardText`, `CardLink` | Build a card with text and links. |
|
|
912
|
+
| `Section`, `Divider`, `Image` | Group content, separate it, or add an image. |
|
|
913
|
+
| `Fields`, `Field`, `Table` | Display labeled values or tabular data. |
|
|
914
|
+
| `Actions`, `Button`, `LinkButton` | Group action buttons and links. |
|
|
915
|
+
| `Select`, `SelectOption`, `RadioSelect` | Add fixed-choice controls inside `Actions`. |
|
|
916
|
+
|
|
917
|
+
For example, post a review link from a message hook:
|
|
918
|
+
|
|
919
|
+
```ts title="agent/channels/slack.ts"
|
|
920
|
+
import { Actions, Card, CardText, LinkButton, slackChannel } from "eve/channels/slack";
|
|
921
|
+
|
|
922
|
+
export default slackChannel({
|
|
923
|
+
async onAppMention(ctx) {
|
|
924
|
+
await ctx.thread.post({
|
|
925
|
+
card: Card({
|
|
926
|
+
title: "Review ready",
|
|
927
|
+
children: [
|
|
928
|
+
CardText("Alice's draft is ready for review."),
|
|
929
|
+
Actions([LinkButton({ label: "Open draft", url: "https://example.com/draft" })]),
|
|
930
|
+
],
|
|
931
|
+
}),
|
|
932
|
+
fallbackText: "Alice's draft is ready for review.",
|
|
933
|
+
});
|
|
934
|
+
return null;
|
|
935
|
+
},
|
|
936
|
+
});
|
|
937
|
+
```
|
|
938
|
+
|
|
939
|
+
Handle your own button and select callbacks in `onInteraction`. To build eve-owned approval or question controls, use the [HITL helpers](#render-and-decode-hitl-controls-yourself). `cardToBlocks(card)` converts a card to Slack blocks; `cardToFallbackText(card)` produces notification and accessibility text. `thread.post({ card })` runs `cardToBlocks` automatically, and runs `cardToFallbackText` unless you supply `fallbackText`.
|
|
940
|
+
|
|
941
|
+
Message cards do not support modals, text inputs, or external selects. Use `CardText` for labels. For custom modals, send native Slack view data with `ctx.slack.request("views.open", ...)`; see [interactive callbacks](#message-hooks).
|
|
942
|
+
|
|
903
943
|
### Proactive sessions
|
|
904
944
|
|
|
905
945
|
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).
|
|
906
946
|
|
|
907
947
|
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:
|
|
908
948
|
|
|
909
|
-
| Field | Use
|
|
910
|
-
| -------------------- |
|
|
911
|
-
| `threadTs` | Continue an existing thread instead of creating one.
|
|
912
|
-
| `initialMessage` | Post a
|
|
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`.
|
|
949
|
+
| Field | Use |
|
|
950
|
+
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
951
|
+
| `threadTs` | Continue an existing thread instead of creating one. |
|
|
952
|
+
| `initialMessage` | Post a `SlackPostInput` as the thread root before the agent runs: `{ markdown }`, `{ text }`, `{ blocks, text? }`, or `{ card, fallbackText? }`. Cannot be combined with `threadTs` or `codeChannel`. |
|
|
953
|
+
| `installationTeamId` | Select the app installation workspace when using a function-form bot token. |
|
|
954
|
+
| `codeChannel` | Open a [code channel](#build-your-own-code-channel-tool) from a message in `channelId` and start the session there. Requires `codeChannels: true`. |
|
|
955
|
+
| `audience` | Set the destination's visibility when you know it. Defaults to `unknown`. |
|
|
916
956
|
|
|
917
957
|
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.
|
|
918
958
|
|
|
919
|
-
|
|
959
|
+
`initialMessage` uses the same explicit inputs as `thread.post`, including cards and optional files. It always posts a root message first, then uploads files into that thread. A retried proactive send repeats both the root post and any uploads, so don't use it as an exactly-once notification. For example, start a thread with a Markdown root:
|
|
960
|
+
|
|
961
|
+
```ts title="agent/channels/slack.ts"
|
|
962
|
+
import { slackChannel } from "eve/channels/slack";
|
|
963
|
+
|
|
964
|
+
export default slackChannel({
|
|
965
|
+
async onEvent(ctx, event) {
|
|
966
|
+
if (event.type !== "team_join") return;
|
|
967
|
+
await ctx.send("Prepare a welcome message for the new teammate.", {
|
|
968
|
+
auth: null,
|
|
969
|
+
target: {
|
|
970
|
+
channelId: "C0123ABC",
|
|
971
|
+
initialMessage: { markdown: "A new teammate joined. Preparing their welcome." },
|
|
972
|
+
},
|
|
973
|
+
});
|
|
974
|
+
},
|
|
975
|
+
});
|
|
976
|
+
```
|
|
977
|
+
|
|
978
|
+
The root is posted before the agent runs; the agent's replies appear under it. 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).
|
|
920
979
|
|
|
921
980
|
For a Slack post without an agent turn, use `ctx.thread.post(...)` in an inbound handler or `ctx.channel.thread.post(...)` in a renderer's event handler. Outside a handler, use [`callSlackApi(...)`](#slack-api-calls-outside-a-handler).
|
|
922
981
|
|
|
@@ -43,6 +43,12 @@ Forum topics carry `message_thread_id` in the continuation token, so each topic
|
|
|
43
43
|
|
|
44
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.
|
|
45
45
|
|
|
46
|
+
Custom `onMessage` hooks can import `defaultTelegramAuth` from
|
|
47
|
+
`eve/channels/telegram` and return `{ auth: defaultTelegramAuth(message) }` to
|
|
48
|
+
keep the default actor identity. The helper uses the message's `from` user,
|
|
49
|
+
scopes group identities to the chat, and returns `null` when no user is present.
|
|
50
|
+
For a button press, pass the button presser as `from`, not the message's author.
|
|
51
|
+
|
|
46
52
|
### Delivery
|
|
47
53
|
|
|
48
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`.
|
package/docs/code-extension.mdx
CHANGED
|
@@ -164,6 +164,31 @@ export default git({
|
|
|
164
164
|
|
|
165
165
|
`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`.
|
|
166
166
|
|
|
167
|
+
## Override bundled tools
|
|
168
|
+
|
|
169
|
+
`eve/extensions/code/tools` exports the reusable `apply_patch` and `grep` tool
|
|
170
|
+
definitions. Import one in an override to change approval or other tool options
|
|
171
|
+
without copying its implementation. With the file mount above, put the override
|
|
172
|
+
in the agent-root slot named after the qualified tool, `code__apply_patch`:
|
|
173
|
+
|
|
174
|
+
```ts title="agent/tools/code__apply_patch.ts"
|
|
175
|
+
import { apply_patch } from "eve/extensions/code/tools";
|
|
176
|
+
import { defineTool } from "eve/tools";
|
|
177
|
+
import { always } from "eve/tools/approval";
|
|
178
|
+
|
|
179
|
+
export default defineTool({ ...apply_patch, approval: always() });
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
`agent/extensions/code/tools/apply_patch.ts` works only when the mount is a
|
|
183
|
+
directory, `agent/extensions/code/extension.ts`.
|
|
184
|
+
|
|
185
|
+
For a custom GitHub command tool, `eve/extensions/git/sandbox` exports
|
|
186
|
+
`executeGitHubShell(input, config, dependencies)` and `githubShellApproval(input)`.
|
|
187
|
+
The execution helper enforces repository and command constraints and brokers a
|
|
188
|
+
credential lease; dependencies supply the session ID and sandbox access. Reuse
|
|
189
|
+
`githubShellApproval` to reject invalid command inputs through the approval
|
|
190
|
+
policy rather than bypassing those constraints.
|
|
191
|
+
|
|
167
192
|
## Prepare the sandbox
|
|
168
193
|
|
|
169
194
|
Install the CLI tooling in your sandbox environment's `prepare` callback:
|
|
@@ -7,13 +7,13 @@ The default harness is eve's built-in agent loop. It manages model calls, compac
|
|
|
7
7
|
|
|
8
8
|
## Compaction
|
|
9
9
|
|
|
10
|
-
The harness keeps a long session from overflowing the model's context window. Before comparing the conversation with `
|
|
10
|
+
The harness keeps a long session from overflowing the model's context window. Before comparing the conversation with `compaction.threshold` (`0.9` by default), it adds the estimated fixed envelope of the checkpoint prompt used for compaction. It then summarizes the older turns and keeps going. The prompt asks the compaction model to distinguish completed progress and decisions from remaining work and to retain the constraints, preferences, data, and references needed to continue. When eve compacts again, it passes the previous checkpoint separately and without the transcript's per-message truncation, then replaces it with the updated checkpoint. The summary uses the active turn model unless you override it. After compacting, the harness keeps the most recent messages word for word next to the summary, up to 20,000 tokens (or half of the threshold, if that is smaller), with tool results shortened to 2,000 characters. The current user message is always part of that, so when it alone is larger than the budget the harness keeps only its start and its end, with a note where the middle was cut, and summarizes the cut-out middle with the older turns. If a compaction cannot bring the history under the threshold, the session fails with an error instead of compacting again, and the step is not retried: start a new session or send a smaller message. Tune when and how it kicks in under [`compaction`](../agent-config#compaction) in `agent.ts`:
|
|
11
11
|
|
|
12
12
|
```ts title="agent/agent.ts"
|
|
13
13
|
export default defineAgent({
|
|
14
14
|
model: "anthropic/claude-opus-5.5",
|
|
15
15
|
compaction: {
|
|
16
|
-
|
|
16
|
+
threshold: 0.75,
|
|
17
17
|
},
|
|
18
18
|
});
|
|
19
19
|
```
|
|
@@ -58,7 +58,7 @@ eve treats every world other than Vercel Workflow as running one eve version at
|
|
|
58
58
|
|
|
59
59
|
eve ends a stranded session without running any of its code. When that happens depends on the kind of run:
|
|
60
60
|
|
|
61
|
-
- **A root session**, one that a channel or client started, stays where it is. It keeps its address and executes nothing until a new channel message replaces it,
|
|
61
|
+
- **A root session**, one that a channel or client started, stays where it is. It keeps its address and executes nothing until a new channel message replaces it, an explicit end retires it, or its session timeout elapses, whichever comes first.
|
|
62
62
|
- **A subagent session or workflow tool run**, including a task, is cancelled the next time the world delivers work to it, for example when the local world or Postgres recovers active runs at startup. No later message could resume its interrupted work, so eve does not wait.
|
|
63
63
|
|
|
64
64
|
See [How a stranded session ends](#how-a-stranded-session-ends) for the details.
|
|
@@ -66,18 +66,18 @@ See [How a stranded session ends](#how-a-stranded-session-ends) for the details.
|
|
|
66
66
|
For a root session, what happens next depends on how the message is addressed:
|
|
67
67
|
|
|
68
68
|
- **A channel address**, such as a Slack thread or any `from(address).send(...)`, resets the stranded session and starts a fresh session at the same address. The message becomes the fresh session's first turn. Concurrent messages to the address produce one fresh session. The fresh session names the session it replaced, whose recorded conversation your instructions can read; see [What a replacement session receives](#what-a-replacement-session-receives). A delivery that carries input responses, with or without a message, throws `SessionStrandedError` and leaves the stranded session in place, because a fresh session has no request for them to answer. See [custom channels](../channels/custom#channel-operations-and-session-handles).
|
|
69
|
-
- **`create()` on a channel address** throws `SessionStrandedError` and leaves the stranded session in place. Call `
|
|
69
|
+
- **`create()` on a channel address** throws `SessionStrandedError` and leaves the stranded session in place. Call `end()` on the address, then `create()` again; see [Start from prior history](../channels/eve#start-from-prior-history).
|
|
70
70
|
- **A session ID** is never reset implicitly. The eve HTTP channel returns `409` with `code: "session_stranded"` and the `eveVersion` that built the session when it recorded one. `Session.send()` and `Session.respond()` throw `SessionStrandedError` from `eve/channels`, and the TypeScript client's `ClientSession.send()` and `respond()` throw `ClientSessionStrandedError` from `eve/client`. Nothing is delivered, and the stranded run keeps its status and event log. See [Start and continue a session](../channels/eve#start-and-continue-a-session).
|
|
71
71
|
- **Following a stream** of a stranded session returns the same `409 session_stranded`. The TypeScript client stops reconnecting and reports `ClientSessionStrandedError`; the TUI explains how to recover. An existing connection learns this when it reconnects. Messages accepted before the upgrade are not redelivered.
|
|
72
|
-
- **Reading recorded history** still works. A bounded read (`stream({ follow: false })`, or `follow=false` on the stream route) returns the events recorded so far without inspecting or changing the session, so you can read a stranded conversation before deciding to
|
|
73
|
-
- **
|
|
74
|
-
- **Session timeouts** end a stranded session the same way
|
|
72
|
+
- **Reading recorded history** still works. A bounded read (`stream({ follow: false })`, or `follow=false` on the stream route) returns the events recorded so far without inspecting or changing the session, so you can read a stranded conversation before deciding to end it.
|
|
73
|
+
- **End** works on a stranded session through a channel address or a session ID. **Clear** would keep a session that cannot run, so it is refused: `Session.clear()` throws `SessionStrandedError`, the eve HTTP channel returns `409 session_stranded`, and nothing changes. End the session instead.
|
|
74
|
+
- **Session timeouts** end a stranded session the same way an explicit end does; see [How a stranded session ends](#how-a-stranded-session-ends).
|
|
75
75
|
|
|
76
|
-
|
|
76
|
+
An explicit `end()` retires the stranded session without running any of its code and waits for its channel addresses to be released. If another run has taken ownership in the meantime, ending fails without retiring the new owner and can be retried. The stranded session's `session.ended` hooks do not run; a replacement session runs `session.started` as usual. eve attempts to record the end delivery and a `session.ended` fact with `outcome: "failed"` and error code `session_stranded`, then close the old stream. Publication is best effort: unavailable storage or a stalled write does not prevent retirement, so a terminal fact may be missing. An end that fails partway through can be retried.
|
|
77
77
|
|
|
78
|
-
Each
|
|
78
|
+
Each retirement logs a `warn` record, `Reset stranded session`, with the previous session ID, both eve versions, and the `trigger`: `message`, `reset`, or `timeout`. The internal command and log value remain `reset` for compatibility; the public control is `end()`.
|
|
79
79
|
|
|
80
|
-
|
|
80
|
+
Ending a session cannot be undone. A fresh session started by a message can read at most the stranded conversation's text; an explicit end leaves the next session no link to the stranded one. Rolling back to the eve version that built a session helps only before the session ends. On a world other than Vercel Workflow, pin the exact eve version in `package.json` so upgrades happen only when you choose them.
|
|
81
81
|
|
|
82
82
|
#### What a replacement session receives
|
|
83
83
|
|
|
@@ -135,9 +135,9 @@ The transcript is context only: tools, approvals, files, sandbox contents, autho
|
|
|
135
135
|
|
|
136
136
|
#### How a stranded session ends
|
|
137
137
|
|
|
138
|
-
A stranded root session ends on its next channel message,
|
|
138
|
+
A stranded root session ends on its next channel message, an explicit end, or its [session timeout](../agent-config#runtime-limits), whichever comes first. It executes nothing while it waits. When the local world or Postgres recovers active runs at startup, eve acknowledges the root session's delivery without replaying it and logs a warning naming the run and both eve versions. The run keeps its `pending` or `running` status and its addresses. A later restart skips it the same way.
|
|
139
139
|
|
|
140
|
-
The timeout is the session's own durable timer, which its last owner armed for the end of an idle window (30 days by default). An owner re-arms the timer only when the timer fires before the window ends, so a stranded session ends at most `sessionTimeoutMs` after its last turn settled, and possibly sooner. The timer still works after the upgrade. When it fires on a stranded session, it retires the session without starting a fresh one. The next message to the address then starts an ordinary session. A session with `sessionTimeoutMs: false` has no timer, so a stranded one stays until a message or
|
|
140
|
+
The timeout is the session's own durable timer, which its last owner armed for the end of an idle window (30 days by default). An owner re-arms the timer only when the timer fires before the window ends, so a stranded session ends at most `sessionTimeoutMs` after its last turn settled, and possibly sooner. The timer still works after the upgrade. When it fires on a stranded session, it retires the session without starting a fresh one. The next message to the address then starts an ordinary session. A session with `sessionTimeoutMs: false` has no timer, so a stranded one stays until a message or an explicit end, just as a healthy one would stay open.
|
|
141
141
|
|
|
142
142
|
Ending a root session does not immediately cancel its subagent sessions and workflow tool runs. Each is retired when a delivery for it reaches the current deployment, and the runtime logs identify the stranded run. A run that never receives a delivery, such as one parked in a dormant `eve dev` generation, can stay active; cancel it in your Workflow world if you need to. Cancellation does not run authored cleanup or lifecycle hooks, undo side effects, or stop independent external jobs, and results and approvals do not carry over to a replacement session.
|
|
143
143
|
|
|
@@ -262,7 +262,7 @@ session claims both its stable session-ID inbox and its initial channel address
|
|
|
262
262
|
before processing the first turn, and fails creation if another run already
|
|
263
263
|
owns the channel address. Aliasing adds another continuation address to the
|
|
264
264
|
same session; every previously claimed address remains active until the session
|
|
265
|
-
ends
|
|
265
|
+
ends. An ID-only HTTP session has the stable inbox and no channel
|
|
266
266
|
continuation address. When cold starts race for the same address, the losing
|
|
267
267
|
candidate forwards its accepted message to the owner and exits.
|
|
268
268
|
|
|
@@ -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:
|
|
@@ -18,7 +18,7 @@ The app runtime is the trusted side. Your tool implementations, model calls, con
|
|
|
18
18
|
|
|
19
19
|
The sandbox is the isolated side. The model runs shell commands and accesses files there through the default `bash`, `read_file`, and `write_file` tools and any opt-in sandbox tools such as `glob` and `grep`. It gets its own `/workspace` filesystem, but no `process.env`, no secrets, and no path back into the app runtime. (On Vercel, each sandbox is a [Vercel Sandbox](https://vercel.com/docs/sandbox) microVM with hardware-level isolation.) Only shell commands execute in the sandbox. Even the built-in `bash`/`read_file`/`write_file` tools live in the app runtime and _proxy_ into the sandbox. The model sees tool definitions and results, never your secrets.
|
|
20
20
|
|
|
21
|
-
The [just-bash provider](../sandbox/just-bash) has a weaker boundary. Its shell is a JavaScript interpreter with a virtual filesystem that runs inside the app runtime process, not a separate container or VM. It provides no network isolation, and any `customCommands` you register run as host application code outside the virtual filesystem. Use a Vercel or Docker sandbox when the model runs commands you would not run in the app runtime.
|
|
21
|
+
The [just-bash provider](../sandbox/just-bash) has a weaker boundary. Its shell is a JavaScript interpreter with a virtual filesystem that runs inside the app runtime process, not a separate container or VM. It provides no network isolation, and any `experimental.customCommands` you register run as host application code outside the virtual filesystem. Use a Vercel or Docker sandbox when the model runs commands you would not run in the app runtime.
|
|
22
22
|
|
|
23
23
|
A concrete trace makes the boundary clear. When the model calls a custom `charge_card` tool, its `execute` runs in the app runtime, reads `process.env.STRIPE_KEY`, calls Stripe, and returns `{ ok: true }`. The model sees only `{ ok: true }`: the key never leaves the app runtime, and nothing about the call touches the sandbox. The built-in `write_file` is the mirror image, running in the app runtime and proxying the write into the sandbox `/workspace`. Either way the model drives the work through tool calls and their results, never by holding a credential or reaching the runtime directly.
|
|
24
24
|
|
|
@@ -41,7 +41,7 @@ flowchart LR
|
|
|
41
41
|
eve sends data where your agent configuration and runtime choices send it:
|
|
42
42
|
|
|
43
43
|
- Inbound channel data flows through the channel provider you configure, then into the eve app runtime.
|
|
44
|
-
- Model inputs and outputs flow to the model or routing path selected in `agent.ts`, such as a Vercel AI Gateway model id or a provider
|
|
44
|
+
- Model inputs and outputs flow to the model or routing path selected in `agent.ts`, such as a Vercel AI Gateway model id or a provider model instance (`EveLanguageModel`).
|
|
45
45
|
- Tool and connection calls flow to the external services, MCP servers, OpenAPI endpoints, and channels you configure.
|
|
46
46
|
- Sandbox commands can reach network destinations allowed by the sandbox network policy.
|
|
47
47
|
- Telemetry flows to destinations configured under `agent/instrumentation/`.
|
|
@@ -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.
|