eve 0.86.0 → 0.88.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 +25 -0
- package/README.md +1 -1
- 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/dev/command-options.d.ts +4 -4
- package/dist/src/cli/dev/command.js +1 -1
- package/dist/src/cli/dev/tui/runner.js +1 -1
- 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/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 +3 -3
- package/dist/src/compiled/@vercel/agent-runs/LICENSE +202 -0
- 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/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/tools/agent-router-workflow.js +1 -1
- package/dist/src/extensions/git/extension/extension.d.ts +5 -2
- package/dist/src/extensions/git/extension/extension.js +1 -1
- package/dist/src/extensions/git/extension/instructions/github.js +1 -1
- package/dist/src/extensions/git/extension/lib/connect-user-auth.d.ts +15 -0
- package/dist/src/extensions/git/extension/lib/connect-user-auth.js +1 -0
- package/dist/src/extensions/git/extension/lib/gh-tool.d.ts +8 -1
- package/dist/src/extensions/git/extension/lib/gh-tool.js +1 -1
- package/dist/src/extensions/git/extension/lib/github-guidance.d.ts +2 -1
- package/dist/src/extensions/git/extension/lib/github-guidance.js +14 -1
- package/dist/src/extensions/git/extension/lib/github-shell.d.ts +12 -4
- package/dist/src/extensions/git/extension/lib/github-shell.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/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/app-manifest.d.ts +4 -0
- package/dist/src/public/channels/slack/app-manifest.js +1 -1
- package/dist/src/public/channels/slack/auth.d.ts +1 -0
- package/dist/src/public/channels/slack/auth.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/defaults.js +1 -1
- package/dist/src/public/channels/slack/inbound.d.ts +7 -0
- package/dist/src/public/channels/slack/index.d.ts +3 -2
- package/dist/src/public/channels/slack/index.js +1 -1
- package/dist/src/public/channels/slack/model-context.d.ts +3 -2
- package/dist/src/public/channels/slack/model-context.js +3 -3
- 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 +37 -72
- package/dist/src/public/channels/slack/slackChannel.js +1 -1
- package/dist/src/public/channels/slack/user-info.d.ts +64 -0
- package/dist/src/public/channels/slack/user-info.js +1 -0
- 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/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 +14 -8
- 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 +141 -15
- package/docs/channels/telegram.mdx +6 -0
- package/docs/code-extension.mdx +76 -12
- package/docs/concepts/default-harness.md +2 -2
- package/docs/concepts/execution-model-and-durability.mdx +11 -11
- package/docs/concepts/security-model.md +2 -2
- package/docs/concepts/sessions-runs-and-streaming.md +23 -10
- package/docs/concepts/upgrade-to-v27-events.md +2 -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 +5 -1
- package/docs/guides/auth-and-route-protection.md +1 -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 +24 -6
- package/docs/guides/decide.md +3 -3
- package/docs/guides/deployment/vercel.mdx +1 -1
- package/docs/guides/dev-tui.md +2 -2
- package/docs/guides/frontend/overview.mdx +1 -1
- package/docs/guides/frontend/use-eve-agent-svelte.mdx +13 -11
- package/docs/guides/frontend/use-eve-agent-vue.mdx +13 -11
- package/docs/guides/frontend/use-eve-agent.mdx +4 -4
- package/docs/guides/instrumentation/otel.mdx +3 -1
- package/docs/guides/prepare-for-1-0.md +255 -0
- package/docs/guides/remote-agents.md +22 -20
- 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 +14 -9
- 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 +5 -5
- 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 +36 -9
- package/dist/CHANGELOG.md +0 -38
- package/dist/src/public/channels/discord/gateway/index.js +0 -1
package/docs/agent-config.md
CHANGED
|
@@ -24,9 +24,11 @@ dev TUI with `/model anthropic/claude-opus-5.5`.
|
|
|
24
24
|
The root `agent.ts` can be omitted when no runtime config is needed. eve then selects its default `agent.ts` source at the same slot, configured with `openai/gpt-6-luna-fast` and `reasoning: "high"`; authoring the file replaces that source.
|
|
25
25
|
When `agent.ts` is present, `model` is required.
|
|
26
26
|
|
|
27
|
-
|
|
27
|
+
An `agent.ts` that configures a local agent, root or subagent, must export the value `defineAgent` returns, and a dynamic subagent resolver that selects a local agent must return one. The compiler rejects a plain object export with `Export defineAgent({...}) from "<path>".`
|
|
28
28
|
|
|
29
|
-
|
|
29
|
+
A config that selects a static Gateway model is compile-only. A config that contains a dynamic model or a direct-provider model instance remains a runtime entry because eve must resolve that authored value while the agent runs. See [Authored module lifecycle](./reference/typescript-api#authored-module-lifecycle).
|
|
30
|
+
|
|
31
|
+
`model` accepts a gateway model id string, which routes through the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway). To call a provider directly and configure the model in code, pass a model instance. eve types it as `EveLanguageModel` (exported from `eve` and `eve/models`), which every AI SDK language model satisfies.
|
|
30
32
|
|
|
31
33
|
Use eve's helpers for direct OpenAI or Anthropic access without installing another provider package:
|
|
32
34
|
|
|
@@ -43,9 +45,9 @@ export default defineAgent({
|
|
|
43
45
|
|
|
44
46
|
For a local ChatGPT subscription, use `chatgpt()` from `eve/models/openai` and sign in with `/login`. It defaults to `gpt-6-luna-fast` and cannot run in a deployment.
|
|
45
47
|
|
|
46
|
-
`/login` can switch a static Gateway string to an eve helper and manage its import. `/model` changes the selected model and settings immediately. Custom provider SDK calls and dynamic expressions retain their authored behavior and require manual source edits. You can still install an AI SDK provider package and pass its
|
|
48
|
+
`/login` can switch a static Gateway string to an eve helper and manage its import. `/model` changes the selected model and settings immediately. Custom provider SDK calls and dynamic expressions retain their authored behavior and require manual source edits. You can still install an AI SDK provider package and pass its language model when you need provider-specific configuration.
|
|
47
49
|
|
|
48
|
-
Model use is subject to the terms, data-processing commitments, retention behavior, and available controls of the selected provider and routing path. Review the [AI Gateway model catalog](https://vercel.com/ai-gateway/models) for gateway-routed models, and review the provider's terms when you configure a direct
|
|
50
|
+
Model use is subject to the terms, data-processing commitments, retention behavior, and available controls of the selected provider and routing path. Review the [AI Gateway model catalog](https://vercel.com/ai-gateway/models) for gateway-routed models, and review the provider's terms when you configure a direct model instance.
|
|
49
51
|
|
|
50
52
|
For every OpenAI or Anthropic model call, eve fills the provider's end-user
|
|
51
53
|
safety identifier from the active turn's
|
|
@@ -166,7 +168,7 @@ export default defineAgent({
|
|
|
166
168
|
});
|
|
167
169
|
```
|
|
168
170
|
|
|
169
|
-
The function returns a Gateway model ID, an AI SDK
|
|
171
|
+
The function returns a Gateway model ID, a model instance such as an AI SDK language model, or a selection object. See
|
|
170
172
|
[Dynamic capabilities](./guides/dynamic-capabilities) for the context and memo rules.
|
|
171
173
|
|
|
172
174
|
- **When it changes.** eve evaluates before each ordinary model call. A memo keyed by
|
|
@@ -235,13 +237,13 @@ Gateway models; use `providerOptions.gateway.caching` instead.
|
|
|
235
237
|
|
|
236
238
|
## Compaction
|
|
237
239
|
|
|
238
|
-
Compaction summarizes older turns as you approach the context window. It's on by default, so you only tune when it kicks in. eve adds the estimated fixed checkpoint-prompt envelope to the trigger count, so compaction starts sooner than the conversation-only estimate. Lower `
|
|
240
|
+
Compaction summarizes older turns as you approach the context window. It's on by default, so you only tune when it kicks in. eve adds the estimated fixed checkpoint-prompt envelope to the trigger count, so compaction starts sooner than the conversation-only estimate. Lower `compaction.threshold` (a fraction from 0 to 1) to compact sooner:
|
|
239
241
|
|
|
240
242
|
```ts title="agent/agent.ts"
|
|
241
243
|
export default defineAgent({
|
|
242
244
|
model: "anthropic/claude-opus-5.5",
|
|
243
245
|
compaction: {
|
|
244
|
-
|
|
246
|
+
threshold: 0.75, // default 0.9
|
|
245
247
|
},
|
|
246
248
|
});
|
|
247
249
|
```
|
|
@@ -282,8 +284,9 @@ disable the timeout. Session expiration follows
|
|
|
282
284
|
[run-data retention](#run-data-retention); a zero-retention session loses its
|
|
283
285
|
stored payloads when it ends.
|
|
284
286
|
|
|
285
|
-
`sessionUsage` gets two
|
|
286
|
-
`
|
|
287
|
+
`sessionUsage` gets two `TokenUsage` records (exported from `eve`) with
|
|
288
|
+
`inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, and
|
|
289
|
+
`costUsd`: `total` is everything
|
|
287
290
|
the session has spent, and `window` is what it spent since the last approved
|
|
288
291
|
continuation. `inputTokens` includes cache reads and writes. Subtract
|
|
289
292
|
`cacheReadTokens` to count only new input; cache reads are the history a
|
|
@@ -325,8 +328,8 @@ export default defineAgent({
|
|
|
325
328
|
});
|
|
326
329
|
```
|
|
327
330
|
|
|
328
|
-
Set `sessionUsage:
|
|
329
|
-
false`
|
|
331
|
+
Set `sessionUsage: false` to leave sessions uncapped. A callback that always
|
|
332
|
+
returns `false` has the same effect. eve calls a configured callback before each model call once
|
|
330
333
|
the window has usage. The model call that crosses a limit is allowed to finish
|
|
331
334
|
because exact usage arrives after the call completes. Before the next model
|
|
332
335
|
call, eve pauses the turn (`turn.paused`) and sends a deterministic
|
|
@@ -466,6 +469,7 @@ when the session starts; destination export filters and lifecycle-provider
|
|
|
466
469
|
policies do not change it.
|
|
467
470
|
|
|
468
471
|
Set `experimental.workflow.retention` explicitly to override this behavior.
|
|
472
|
+
This override is experimental and has no compatibility promise.
|
|
469
473
|
Use `0` to request deletion regardless of the tracing policy, or `"default"` to
|
|
470
474
|
keep run data for the World's default period regardless of the tracing policy:
|
|
471
475
|
|
package/docs/channels/custom.mdx
CHANGED
|
@@ -27,7 +27,7 @@ export default defineChannel({
|
|
|
27
27
|
const source = from(params.threadId);
|
|
28
28
|
|
|
29
29
|
if (body.message === "/new") {
|
|
30
|
-
return Response.json(await source.
|
|
30
|
+
return Response.json(await source.end({ reason: "User requested /new" }));
|
|
31
31
|
}
|
|
32
32
|
|
|
33
33
|
const delivery = await source.send(body.message, { auth: null });
|
|
@@ -82,7 +82,7 @@ A route's `path` is its app URL; the channel filename does not prefix it. The ro
|
|
|
82
82
|
|
|
83
83
|
Each route receives these operation surfaces:
|
|
84
84
|
|
|
85
|
-
- `from(address)` binds `send`, `respond`, `cancel`, `compact`, `clear`, and `
|
|
85
|
+
- `from(address)` binds `send`, `respond`, `cancel`, `compact`, `clear`, and `end` to a channel-local continuation address.
|
|
86
86
|
- `resolveSession(address)` snapshots the session currently owning a channel-local continuation address.
|
|
87
87
|
- `attachSession(sessionId)` creates an I/O-free handle pinned to one durable session ID.
|
|
88
88
|
- `to(channel, target).send(message, options)` hands work to another authored channel.
|
|
@@ -128,7 +128,7 @@ await source.respond(answers, { auth });
|
|
|
128
128
|
await source.cancel({ turnId });
|
|
129
129
|
await source.compact();
|
|
130
130
|
await source.clear();
|
|
131
|
-
await source.
|
|
131
|
+
await source.end({ reason: "Start over" });
|
|
132
132
|
|
|
133
133
|
const currentSession = await resolveSession(threadId);
|
|
134
134
|
```
|
|
@@ -157,7 +157,7 @@ await session.respond(answers, { auth });
|
|
|
157
157
|
await session.cancel({ turnId });
|
|
158
158
|
await session.compact();
|
|
159
159
|
await session.clear();
|
|
160
|
-
await session.
|
|
160
|
+
await session.end({ reason: "Retire this session" });
|
|
161
161
|
for await (const event of session.stream({ startIndex: 12 })) render(event);
|
|
162
162
|
```
|
|
163
163
|
|
|
@@ -169,7 +169,7 @@ For a stranded session, `Session.send()`, `Session.respond()`, and a following
|
|
|
169
169
|
read through `Session.stream()` throw `SessionStrandedError` from `eve/channels` and deliver nothing.
|
|
170
170
|
`stream({ follow: false })` still reads the recorded history up to the current tail without
|
|
171
171
|
changing the session. `error.owner.eveVersion` names the eve release that built the session when it recorded one. Call
|
|
172
|
-
`
|
|
172
|
+
`end()` to retire the stranded session, then start a new one:
|
|
173
173
|
|
|
174
174
|
```ts
|
|
175
175
|
import { SessionStrandedError } from "eve/channels";
|
|
@@ -178,7 +178,7 @@ try {
|
|
|
178
178
|
await attachSession(sessionId).send(text, { auth });
|
|
179
179
|
} catch (error) {
|
|
180
180
|
if (!SessionStrandedError.is(error)) throw error;
|
|
181
|
-
await attachSession(sessionId).
|
|
181
|
+
await attachSession(sessionId).end({ reason: "Session was stranded by an upgrade" });
|
|
182
182
|
}
|
|
183
183
|
```
|
|
184
184
|
|
|
@@ -325,12 +325,12 @@ Keep each route's `method` and `path` unless you mean to move the endpoint.
|
|
|
325
325
|
`kind: "compaction"`.
|
|
326
326
|
- `clear` removes model-message history in place. It preserves the system prompt,
|
|
327
327
|
skills, tools, durable state, limits, address ownership, and session sandbox.
|
|
328
|
-
- `
|
|
328
|
+
- `end` terminally retires the current session. A later address `send()` creates
|
|
329
329
|
a fresh session; a fixed `Session` handle remains pinned to the retired ID.
|
|
330
330
|
|
|
331
331
|
Control operations never create a session. Unknown or inactive targets throw
|
|
332
332
|
`SessionNotActiveError`; an accepted no-op cancellation settles with `outcome: "ignored"`. Authenticate and deduplicate command webhooks before
|
|
333
|
-
calling `
|
|
333
|
+
calling `end`, because a delayed duplicate can retire a newer address owner.
|
|
334
334
|
|
|
335
335
|
## CORS
|
|
336
336
|
|
|
@@ -536,11 +536,27 @@ slackContinuationToken({ channelId: "C0123ABC", threadTs: "1800000000.001234" })
|
|
|
536
536
|
twilioContinuationToken({ from: "+15551234567", to: "+15557654321" }); // "+15551234567:+15557654321"
|
|
537
537
|
```
|
|
538
538
|
|
|
539
|
+
Built-in channels export token builders from their own `eve/channels/<platform>` entry:
|
|
540
|
+
|
|
541
|
+
| Builder | Address fields |
|
|
542
|
+
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
543
|
+
| `slackContinuationToken` | `channelId`, `threadTs` |
|
|
544
|
+
| `slackCodeChannelContinuationToken` | `channelId` (positional argument) |
|
|
545
|
+
| `twilioContinuationToken` | `from`, optional `to` |
|
|
546
|
+
| `githubContinuationToken` | `repositoryId`, `conversationKind`, and the matching `issueNumber`, `pullRequestNumber`, or `reviewThreadRootCommentId` |
|
|
547
|
+
| `discordContinuationToken` | `channelId`, optional `conversationId` |
|
|
548
|
+
| `teamsContinuationToken` | `conversationId`, optional `tenantId` and `replyToActivityId` |
|
|
549
|
+
| `telegramContinuationToken` | `chatId`, optional `messageThreadId` and `conversationId` |
|
|
550
|
+
| `linearContinuationToken` | `agentSessionId` |
|
|
551
|
+
|
|
552
|
+
Pass the resulting channel-local token to that channel's `from(...)` helper.
|
|
553
|
+
Tokens are routing addresses, not credentials or substitutes for authorization.
|
|
554
|
+
|
|
539
555
|
Custom channels write their own function that joins the identity fields. The framework derives nothing for you; the channel owns its token format.
|
|
540
556
|
|
|
541
557
|
When another identity should address a session, add it with `channel.continuation?.alias(rawToken)`. The runtime preserves the current channel namespace and exposes the new token as `channel.continuation.token` for later handlers.
|
|
542
558
|
|
|
543
|
-
Aliasing adds an address to the current session. Earlier addresses continue to resolve to the same session and accept the same payloads. `
|
|
559
|
+
Aliasing adds an address to the current session. Earlier addresses continue to resolve to the same session and accept the same payloads. `end` terminally retires the current session and makes all its addresses available to later `send()` calls. `cancel` stops only the active turn and leaves the session, history, and continuation-token ownership intact.
|
|
544
560
|
|
|
545
561
|
The `context(state, channel)` config option builds the per-step context read as `ctx.channel`
|
|
546
562
|
in event handlers. Its second argument is `ChannelContext` from `eve/channels`: live
|
|
@@ -575,7 +591,7 @@ defineChannel<{ ref: string | null }>({
|
|
|
575
591
|
});
|
|
576
592
|
```
|
|
577
593
|
|
|
578
|
-
At the next workflow boundary, the runtime adds the new address to the session's merged inbox. If another active session already owns the new token, the aliasing session fails instead of taking it over. Every address claimed by the session remains active until the session ends
|
|
594
|
+
At the next workflow boundary, the runtime adds the new address to the session's merged inbox. If another active session already owns the new token, the aliasing session fails instead of taking it over. Every address claimed by the session remains active until the session ends. Sessions with continuation addresses remain on their current deployment until Workflow supports atomic ownership transfer.
|
|
579
595
|
|
|
580
596
|
Tokens must be nonempty. A session supports up to 256 addresses, including its stable inbox; repeating an existing alias does not consume another address.
|
|
581
597
|
|
|
@@ -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
|
@@ -91,7 +91,7 @@ The default eve channel inspects the agent, creates sessions, accepts callbacks
|
|
|
91
91
|
- `POST /eve/v1/session/:sessionId/cancel` (cancel the in-flight turn)
|
|
92
92
|
- `POST /eve/v1/session/:sessionId/clear` (clear the session's model history)
|
|
93
93
|
- `POST /eve/v1/session/:sessionId/compact` (compact the session's context)
|
|
94
|
-
- `POST /eve/v1/session/:sessionId/
|
|
94
|
+
- `POST /eve/v1/session/:sessionId/end` (retire the session)
|
|
95
95
|
- `GET /eve/v1/session/:sessionId/stream` (stream events as NDJSON)
|
|
96
96
|
|
|
97
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.
|
|
@@ -126,7 +126,7 @@ repeating the request with the same key returns the same `deliveryId`, and the i
|
|
|
126
126
|
again. Unlike a channel's [retried deliveries](./custom#retried-deliveries), whose duplicates get a
|
|
127
127
|
new receipt settled `ignored`, the repeat's receipt is the original's. The session remembers its
|
|
128
128
|
last 1,024 keys, so use a new key for new input. The compact and clear routes
|
|
129
|
-
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`.
|
|
130
130
|
|
|
131
131
|
Open payload objects such as `clientContext` keep their existing contracts. Delegated requests
|
|
132
132
|
with a `callback` accept, and ignore, the retired `activityObserver` field so older senders keep
|
|
@@ -238,7 +238,7 @@ export default eveChannel({
|
|
|
238
238
|
|
|
239
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.
|
|
240
240
|
|
|
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
|
|
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.
|
|
242
242
|
|
|
243
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.
|
|
244
244
|
|
|
@@ -254,15 +254,17 @@ See [Cancel the in-flight turn](../concepts/sessions-runs-and-streaming#cancel-t
|
|
|
254
254
|
|
|
255
255
|
### Clear context
|
|
256
256
|
|
|
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 `
|
|
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).
|
|
258
258
|
|
|
259
259
|
### Compact context
|
|
260
260
|
|
|
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
|
|
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
262
|
|
|
263
|
-
|
|
263
|
+
<a id="reset-a-session" />
|
|
264
264
|
|
|
265
|
-
|
|
265
|
+
### End a session
|
|
266
|
+
|
|
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).
|
|
266
268
|
|
|
267
269
|
## Replace or disable the defaults
|
|
268
270
|
|
|
@@ -340,6 +342,10 @@ export default eveChannel({
|
|
|
340
342
|
});
|
|
341
343
|
```
|
|
342
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
|
+
|
|
343
349
|
`audience` controls observability content capture; it does not change who may
|
|
344
350
|
call the endpoint. `auth` still controls access. For a classification that
|
|
345
351
|
depends on channel state or application-specific verified data, use a [custom
|
|
@@ -444,7 +450,7 @@ export default defineChannel({
|
|
|
444
450
|
|
|
445
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.
|
|
446
452
|
|
|
447
|
-
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.
|
|
448
454
|
|
|
449
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.
|
|
450
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
|
@@ -139,10 +139,77 @@ export default slackChannel({
|
|
|
139
139
|
});
|
|
140
140
|
```
|
|
141
141
|
|
|
142
|
-
|
|
142
|
+
Each model-visible `<slack_message>` groups its metadata into blocks: `<sender>` with the sender's `type` and `id`, `<bot>` with the receiving app's `id` and the `mentioned` value from `ctx.isBotMentioned()` (inbound messages only), and `<thread>` with `team_id`, `channel_id`, `thread_ts`, and `message_ts`:
|
|
143
|
+
|
|
144
|
+
```text
|
|
145
|
+
<slack_message>
|
|
146
|
+
<sender>
|
|
147
|
+
type: user
|
|
148
|
+
id: U01234567
|
|
149
|
+
</sender>
|
|
150
|
+
<bot>
|
|
151
|
+
id: U07654321
|
|
152
|
+
mentioned: true
|
|
153
|
+
</bot>
|
|
154
|
+
<thread>
|
|
155
|
+
team_id: T01234567
|
|
156
|
+
channel_id: C01234567
|
|
157
|
+
thread_ts: 1700000000.000001
|
|
158
|
+
message_ts: 1700000000.000004
|
|
159
|
+
</thread>
|
|
160
|
+
<content>
|
|
161
|
+
<@U07654321> Who owns the deploy?
|
|
162
|
+
</content>
|
|
163
|
+
</slack_message>
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
Its `<content>` keeps `<@USER_ID>` intact while converting other mrkdwn to Markdown; routing is unchanged.
|
|
143
167
|
|
|
144
168
|
When a Slack message includes a link preview, eve includes its attachment text in `<content>` alongside the sender's message, including when the link has words around it. Shared Slack messages work the same way: eve extracts the forwarded message body from Slack's message-unfurl attachment and keeps any top-level comment.
|
|
145
169
|
|
|
170
|
+
#### Add sender names and emails
|
|
171
|
+
|
|
172
|
+
Slack user ids identify every sender without a lookup. When the agent should also know who someone is, enable `messageContext.users`:
|
|
173
|
+
|
|
174
|
+
```ts
|
|
175
|
+
import { slackChannel } from "eve/channels/slack";
|
|
176
|
+
import { connectSlackCredentials } from "@vercel/connect/eve";
|
|
177
|
+
|
|
178
|
+
export default slackChannel({
|
|
179
|
+
credentials: connectSlackCredentials("slack/my-agent"),
|
|
180
|
+
messageContext: { users: { email: true } },
|
|
181
|
+
});
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
eve looks up each human sender with `users.info` and adds `display_name` and `real_name` to their `<sender>` block, plus `email` with `email: true`. Set `name: false` with `email: true` to add emails only. Thread context replies get the same fields. The triggering author is also written to `message.author` (`fullName`, `displayName`, `email`) and to the `full_name` and `email` attributes of [`defaultSlackAuth`](#restrict-who-can-invoke-the-agent), so a hook can gate on them. Mentions and DMs are looked up before `onAppMention` or `onDirectMessage` runs. Other channel messages are looked up only once a hook delivers them, so their hooks see the unresolved author.
|
|
185
|
+
|
|
186
|
+
`users: true` adds names only. Results are cached in memory per workspace and user for an hour, and a failed lookup is retried after a minute. A lookup that fails or takes longer than two seconds is left out, and the message is still delivered. To use your own cache, pass `resolve`; `next()` is eve's uncached `users.info` call:
|
|
187
|
+
|
|
188
|
+
```ts
|
|
189
|
+
import { slackChannel } from "eve/channels/slack";
|
|
190
|
+
import { connectSlackCredentials } from "@vercel/connect/eve";
|
|
191
|
+
import { profileCache } from "../lib/profile-cache";
|
|
192
|
+
|
|
193
|
+
export default slackChannel({
|
|
194
|
+
credentials: connectSlackCredentials("slack/my-agent"),
|
|
195
|
+
messageContext: {
|
|
196
|
+
users: {
|
|
197
|
+
email: true,
|
|
198
|
+
resolve: async ({ userId, teamId }, next) => {
|
|
199
|
+
const key = `${teamId}:${userId}`;
|
|
200
|
+
const cached = await profileCache.get(key);
|
|
201
|
+
if (cached) return cached;
|
|
202
|
+
const profile = await next();
|
|
203
|
+
await profileCache.set(key, profile);
|
|
204
|
+
return profile;
|
|
205
|
+
},
|
|
206
|
+
},
|
|
207
|
+
},
|
|
208
|
+
});
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
`teamId` is the workspace whose installation received the message, so key caches on it. `messageContext.users` adds the `users:read` scope to the app manifest, and `users:read.email` with `email: true`; reinstall the Slack app after enabling it. It is off by default because names and emails then reach model context, session history, and traces.
|
|
212
|
+
|
|
146
213
|
#### Restrict who can invoke the agent
|
|
147
214
|
|
|
148
215
|
A valid Slack signature proves that Slack sent the event. It does not decide which channel or person your agent should trust. Fail closed in the inbound handler before returning auth, especially when the app is installed in a shared Slack Connect channel:
|
|
@@ -278,7 +345,7 @@ async onAppMention(ctx) {
|
|
|
278
345
|
await ctx.cancel();
|
|
279
346
|
await ctx.compact();
|
|
280
347
|
await ctx.clear();
|
|
281
|
-
await ctx.
|
|
348
|
+
await ctx.end({ reason: "Start over" });
|
|
282
349
|
const session = await ctx.resolveSession();
|
|
283
350
|
return { auth: null };
|
|
284
351
|
}
|
|
@@ -286,9 +353,11 @@ async onAppMention(ctx) {
|
|
|
286
353
|
|
|
287
354
|
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
355
|
|
|
289
|
-
|
|
356
|
+
<a id="reset-a-conversation" />
|
|
357
|
+
|
|
358
|
+
#### End a conversation
|
|
290
359
|
|
|
291
|
-
Use the thread-bound `ctx.
|
|
360
|
+
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
361
|
|
|
293
362
|
```ts title="agent/channels/slack.ts"
|
|
294
363
|
export default slackChannel({
|
|
@@ -296,14 +365,14 @@ export default slackChannel({
|
|
|
296
365
|
async onMessage(ctx, message) {
|
|
297
366
|
if (message.text.trim() !== "/new") return null;
|
|
298
367
|
|
|
299
|
-
await ctx.
|
|
368
|
+
await ctx.end({ reason: "Slack user requested /new" });
|
|
300
369
|
await ctx.thread.post("Started a fresh conversation.");
|
|
301
370
|
return null;
|
|
302
371
|
},
|
|
303
372
|
});
|
|
304
373
|
```
|
|
305
374
|
|
|
306
|
-
|
|
375
|
+
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
376
|
|
|
308
377
|
#### Serve Slack code channels
|
|
309
378
|
|
|
@@ -465,7 +534,7 @@ await ctx.respond(answers, { auth: null, target });
|
|
|
465
534
|
await ctx.cancel({ target, turnId });
|
|
466
535
|
await ctx.compact({ target });
|
|
467
536
|
await ctx.clear({ target });
|
|
468
|
-
await ctx.
|
|
537
|
+
await ctx.end({ reason: "Start over", target });
|
|
469
538
|
const session = await ctx.resolveSession({ target });
|
|
470
539
|
```
|
|
471
540
|
|
|
@@ -900,23 +969,80 @@ renderers: [
|
|
|
900
969
|
|
|
901
970
|
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
971
|
|
|
972
|
+
### Cards
|
|
973
|
+
|
|
974
|
+
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.
|
|
975
|
+
|
|
976
|
+
| Builders | Use |
|
|
977
|
+
| --------------------------------------- | -------------------------------------------- |
|
|
978
|
+
| `Card`, `CardText`, `CardLink` | Build a card with text and links. |
|
|
979
|
+
| `Section`, `Divider`, `Image` | Group content, separate it, or add an image. |
|
|
980
|
+
| `Fields`, `Field`, `Table` | Display labeled values or tabular data. |
|
|
981
|
+
| `Actions`, `Button`, `LinkButton` | Group action buttons and links. |
|
|
982
|
+
| `Select`, `SelectOption`, `RadioSelect` | Add fixed-choice controls inside `Actions`. |
|
|
983
|
+
|
|
984
|
+
For example, post a review link from a message hook:
|
|
985
|
+
|
|
986
|
+
```ts title="agent/channels/slack.ts"
|
|
987
|
+
import { Actions, Card, CardText, LinkButton, slackChannel } from "eve/channels/slack";
|
|
988
|
+
|
|
989
|
+
export default slackChannel({
|
|
990
|
+
async onAppMention(ctx) {
|
|
991
|
+
await ctx.thread.post({
|
|
992
|
+
card: Card({
|
|
993
|
+
title: "Review ready",
|
|
994
|
+
children: [
|
|
995
|
+
CardText("Alice's draft is ready for review."),
|
|
996
|
+
Actions([LinkButton({ label: "Open draft", url: "https://example.com/draft" })]),
|
|
997
|
+
],
|
|
998
|
+
}),
|
|
999
|
+
fallbackText: "Alice's draft is ready for review.",
|
|
1000
|
+
});
|
|
1001
|
+
return null;
|
|
1002
|
+
},
|
|
1003
|
+
});
|
|
1004
|
+
```
|
|
1005
|
+
|
|
1006
|
+
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`.
|
|
1007
|
+
|
|
1008
|
+
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).
|
|
1009
|
+
|
|
903
1010
|
### Proactive sessions
|
|
904
1011
|
|
|
905
1012
|
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
1013
|
|
|
907
1014
|
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
1015
|
|
|
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`.
|
|
1016
|
+
| Field | Use |
|
|
1017
|
+
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1018
|
+
| `threadTs` | Continue an existing thread instead of creating one. |
|
|
1019
|
+
| `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`. |
|
|
1020
|
+
| `installationTeamId` | Select the app installation workspace when using a function-form bot token. |
|
|
1021
|
+
| `codeChannel` | Open a [code channel](#build-your-own-code-channel-tool) from a message in `channelId` and start the session there. Requires `codeChannels: true`. |
|
|
1022
|
+
| `audience` | Set the destination's visibility when you know it. Defaults to `unknown`. |
|
|
916
1023
|
|
|
917
1024
|
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
1025
|
|
|
919
|
-
|
|
1026
|
+
`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:
|
|
1027
|
+
|
|
1028
|
+
```ts title="agent/channels/slack.ts"
|
|
1029
|
+
import { slackChannel } from "eve/channels/slack";
|
|
1030
|
+
|
|
1031
|
+
export default slackChannel({
|
|
1032
|
+
async onEvent(ctx, event) {
|
|
1033
|
+
if (event.type !== "team_join") return;
|
|
1034
|
+
await ctx.send("Prepare a welcome message for the new teammate.", {
|
|
1035
|
+
auth: null,
|
|
1036
|
+
target: {
|
|
1037
|
+
channelId: "C0123ABC",
|
|
1038
|
+
initialMessage: { markdown: "A new teammate joined. Preparing their welcome." },
|
|
1039
|
+
},
|
|
1040
|
+
});
|
|
1041
|
+
},
|
|
1042
|
+
});
|
|
1043
|
+
```
|
|
1044
|
+
|
|
1045
|
+
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
1046
|
|
|
921
1047
|
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
1048
|
|