eve 0.86.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 +67 -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/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/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/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 +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/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/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
|
|
|
@@ -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/`.
|
|
@@ -32,8 +32,11 @@ A session completes after 30 idle days by default; configure
|
|
|
32
32
|
timeout. The idle window restarts each time a turn settles, and a session never
|
|
33
33
|
expires while a turn is open. At expiration, eve emits `session.ended` with `outcome: "completed"` and
|
|
34
34
|
releases the session's continuation addresses so the next qualifying channel
|
|
35
|
-
message starts fresh. Stored
|
|
36
|
-
[
|
|
35
|
+
message starts fresh. Stored data follows the session's
|
|
36
|
+
[run-data retention policy](../agent-config#run-data-retention). Under the default
|
|
37
|
+
policy outside development, eve requests deletion when private and unknown-audience
|
|
38
|
+
sessions end. The Workflow World must support deletion to enforce it. See
|
|
39
|
+
[Agent config](../agent-config#runtime-limits) for timeout settings.
|
|
37
40
|
|
|
38
41
|
React, Vue, and Svelte apps reach for [`useEveAgent()`](../guides/frontend/overview) instead of calling these routes by hand. Next.js and Nuxt apps can proxy them to the eve runtime from the same origin.
|
|
39
42
|
|
|
@@ -115,6 +118,13 @@ The full catalog, its outcome sets, and TypeScript types are exported from `eve/
|
|
|
115
118
|
import { FACT_CATALOG, foldEvents, activeTurn, reply } from "eve/events";
|
|
116
119
|
```
|
|
117
120
|
|
|
121
|
+
The family-specific arrays `SESSION_OUTCOMES`, `DELIVERY_OUTCOMES`, `TURN_OUTCOMES`,
|
|
122
|
+
`MODEL_OUTCOMES`, `CALL_OUTCOMES`, `TASK_OUTCOMES`, `INTERACTION_OUTCOMES`,
|
|
123
|
+
`RESPONSE_OUTCOMES`, and `CONTEXT_OUTCOMES` list the outcomes known to this release.
|
|
124
|
+
`TERMINAL_OUTCOMES` maps terminal fact types to those arrays. `isTerminal(fact)`
|
|
125
|
+
narrows a fact to one that ends its entity; it does not test whether the whole
|
|
126
|
+
session has ended. These helpers come from `eve/events`.
|
|
127
|
+
|
|
118
128
|
#### What a later release can add
|
|
119
129
|
|
|
120
130
|
Within stream version 27, a later minor release can add:
|
|
@@ -152,7 +162,7 @@ Spend is recorded on `usage.recorded`, once per model run (`owner: { runId }`) a
|
|
|
152
162
|
|
|
153
163
|
### Deliveries and responses
|
|
154
164
|
|
|
155
|
-
Everything that reaches a session arrives as a delivery: a message, an answer, a control such as `cancel` or `
|
|
165
|
+
Everything that reaches a session arrives as a delivery: a message, an answer, a control such as `cancel` or `end`, or a sign-in callback. `delivery.admitted` records it, with the sender's `principal` and its `source`. A message that a turn takes in is `delivery.consumed`, with the `parts` it received: text, plus file metadata without raw bytes or internal sandbox paths. A delivery that brought [prior history](../channels/eve#start-from-prior-history) also carries it there, in `history`. Every delivery ends with exactly one `delivery.settled`, except after a degraded termination (see below):
|
|
156
166
|
|
|
157
167
|
| Outcome | Meaning |
|
|
158
168
|
| ---------------- | --------------------------------------------------------------------------------------------------- |
|
|
@@ -165,8 +175,9 @@ Everything that reaches a session arrives as a delivery: a message, an answer, a
|
|
|
165
175
|
|
|
166
176
|
`POST /eve/v1/session/:sessionId` returns the message's `deliveryId`, so a client resuming from an old cursor knows which `delivery.settled` ends its response. Steering and coalesced messages each keep their own delivery. The id is assigned before dispatch,
|
|
167
177
|
not derived from stream position. An answer-only delivery stops on its own `delivery.settled`.
|
|
168
|
-
|
|
169
|
-
`session.ended.data.cause.deliveryId` naming
|
|
178
|
+
Ending a stranded session records the control's admission and settlement, with
|
|
179
|
+
`session.ended.data.cause.deliveryId` naming that delivery. Its stream control value
|
|
180
|
+
remains `"reset"` for compatibility with recorded history.
|
|
170
181
|
An answer and message sent together by someone other than the turn's caller become separate deliveries: the answer reaches the waiting turn, and the message retains the receipt and waits. Follow the answer through its interaction.
|
|
171
182
|
|
|
172
183
|
To follow an accepted receipt in a client view, use `delivery(view, receipt.deliveryId)` from
|
|
@@ -232,6 +243,8 @@ const observed = call(agent.view, callId);
|
|
|
232
243
|
if (observed?.state === "failed") console.error(observed.error.message);
|
|
233
244
|
```
|
|
234
245
|
|
|
246
|
+
`callOutputSource(view, callId)` returns the observation of the call that produced a call's output. `call(view, callId)?.output` already follows `outputOf`, so use `callOutputSource` when you need the producing call itself, such as its `callId` or label.
|
|
247
|
+
|
|
235
248
|
Calls include their resolved `turnId`, `runId`, and `taskId` when known, so applications do not
|
|
236
249
|
join calls to runs to find their turn. `turns`, `deliveries`, `tasks`, `runs`, `parts`, and
|
|
237
250
|
`children` return curated observations. Identity lookups include `turn`,
|
|
@@ -362,14 +375,14 @@ Custom channel routes request the same cancellation through
|
|
|
362
375
|
`from(address).cancel()` or `attachSession(sessionId).cancel()`. See
|
|
363
376
|
[custom channels](../channels/custom#channel-operations-and-session-handles).
|
|
364
377
|
|
|
365
|
-
## Compact, clear, and
|
|
378
|
+
## Compact, clear, and end
|
|
366
379
|
|
|
367
380
|
All session controls are ID-addressed and accept no continuation token:
|
|
368
381
|
|
|
369
382
|
```bash
|
|
370
383
|
curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/compact
|
|
371
384
|
curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/clear
|
|
372
|
-
curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/
|
|
385
|
+
curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/end \
|
|
373
386
|
-H 'content-type: application/json' \
|
|
374
387
|
-d '{"reason":"Start over"}'
|
|
375
388
|
```
|
|
@@ -380,9 +393,9 @@ Clear removes model-message history in place, including static and dynamic user-
|
|
|
380
393
|
|
|
381
394
|
A cancel stops turns, not a compaction or clear: one that arrives while either runs settles `ignored`, and the change finishes. A cancel, clear, or compact sent to a prewarmed session before its first message has nothing to act on, and settles `ignored` once the session starts.
|
|
382
395
|
|
|
383
|
-
|
|
396
|
+
End terminally retires the exact session ID. An ended ID never becomes a new session; create another session explicitly for a fresh conversation. All controls return delivery receipts when accepted. An inactive target throws `SessionNotActiveError` from a handle or returns `409 session_not_active` over HTTP.
|
|
384
397
|
|
|
385
|
-
A [stranded session](./execution-model-and-durability#stranded-sessions) cannot run commands.
|
|
398
|
+
A [stranded session](./execution-model-and-durability#stranded-sessions) cannot run commands. End still works: eve retires the stranded workflow run and returns its delivery. Its settlement follows retirement and address release. Clear and compact cannot repair a stranded owner; use end instead.
|
|
386
399
|
|
|
387
400
|
## Reconnect and rewind
|
|
388
401
|
|
|
@@ -431,7 +444,7 @@ for await (const event of events) {
|
|
|
431
444
|
}
|
|
432
445
|
```
|
|
433
446
|
|
|
434
|
-
`stream()` takes `SessionStreamOptions` from `eve/sessions`: `startIndex` (a durable line position, with negative values counting back from the tail), `follow`, and `signal`. Client readers also accept `
|
|
447
|
+
`stream()` takes `SessionStreamOptions` from `eve/sessions`: `startIndex` (a durable line position, with negative values counting back from the tail), `follow`, and `signal`. Client readers also accept `reconnect: false` or a `ReconnectOptions` object from `eve/client`. Key stored events on [`meta.position`](#positions), which stays stable across reads. With `follow: false`, the read ends at the durable tail observed when it opens; otherwise it keeps following new events until the stream closes or the signal aborts.
|
|
435
448
|
|
|
436
449
|
A read reflects events that are already durable. A hook runs after its line is written, so a bounded read there includes the event that triggered it. `sessions` reads any session ID without channel auth, so check that a caller may read a session before passing an ID from a request. It is available only in code that runs inside the eve server.
|
|
437
450
|
|
|
@@ -120,7 +120,7 @@ export default defineHook({
|
|
|
120
120
|
|
|
121
121
|
**Instrumentation** uses `session.ended`, `turn.settled`, `call.requested`/`call.settled`, and `interaction.opened`/`interaction.settled`, with terminal `outcome` instead of separate success/failure event names. `channel.delivery.*` becomes `delivery.consumed`/`delivery.settled`; `step.attempt.*` becomes `model.started`/`model.retried`/`model.settled`. See [Instrumentation](/docs/observability/instrumentation#lifecycle-events).
|
|
122
122
|
|
|
123
|
-
**Clients** receive a `Delivery` immediately on acceptance. Use `delivery.result()` for its settlement or `delivery.stream()` for its events; each read is independent and can take a read signal. `result().status` describes the request (`completed`, `awaiting-input`, `failed`, `cancelled`), not session termination: check `sessionEnded` separately. Results no longer include an `events` array. Frontend hooks expose `view`, `messages`, `agents`, `events`, `session`, `status`, and `error` directly, not under `data`. `newSession()` clears local state; `
|
|
123
|
+
**Clients** receive a `Delivery` immediately on acceptance. Use `delivery.result()` for its settlement or `delivery.stream()` for its events; each read is independent and can take a read signal. `result().status` describes the request (`completed`, `awaiting-input`, `failed`, `cancelled`), not session termination: check `sessionEnded` separately. Results no longer include an `events` array. Frontend hooks expose `view`, `messages`, `agents`, `events`, `session`, `status`, and `error` directly, not under `data`. `newSession()` clears local state; `end()` retires the server session (renamed from `reset()`). Persist events and cursor as they change so paused turns survive reloads. See [Client streaming](../guides/client/streaming) and [Frontend](../guides/frontend/overview).
|
|
124
124
|
|
|
125
125
|
**Evals** match v27 facts and use `view` queries. Rename `loadedSkill` to `calledSkill`, `calledSubagent` to `calledAgent`, `noFailedActions` to `noFailedCalls`, and `parked()` to `awaitingInput()`. Use `t.target.attach(id)` instead of `attachSession(id)` and `turn.waitForToolCall()` instead of the old action matcher. See [Evals](../evals/overview).
|
|
126
126
|
|
|
@@ -134,6 +134,7 @@ export default defineHook({
|
|
|
134
134
|
- Replace connection auth's `credentialOwner` with `principalType: "app" | "user"`. With `getToken` alone, omitted ownership defaults to `"app"`; set `"user"` for per-user tokens. See [connection credential ownership](/docs/connections#choose-app-vs-user-auth).
|
|
135
135
|
- Dynamic capabilities use `defineDynamic(ctx => value)`, not lifecycle event maps. Replace `defineDurableCallback` and `defineDurableSchema` wrappers with ordinary functions and schemas; put external JSON observations in `ctx.memo(key, fn)`. See [Dynamic capabilities](../guides/dynamic-capabilities).
|
|
136
136
|
- Recalled memory stays outside durable conversation history and is recalled before turns, not during compaction. Remove memory `visibility` options; a failed memory capture now prevents compaction. See [Memory providers](../memory/custom-provider).
|
|
137
|
+
- Memory document backend `read()` and `write()` inputs use `signal` again, restoring the pre-`0.84.0` contract. Backends written for `0.83.x` or earlier need no change; replace `abortSignal` only in backends and calls written for `0.84.x`. Memory and tool execution contexts keep `ctx.abortSignal`. See [Custom backends](../memory/file#custom-backend).
|
|
137
138
|
- `grep` lists matching files by default. Set `outputMode: "content"` when the caller needs matching lines; see [Built-in tools](./built-in-tools#grep).
|
|
138
139
|
- Replace `eve remote invoke` with `eve remote connect --print <prompt>` for one-shot requests. Use `eve/client` for scripted multi-turn sessions and answers; see the [CLI reference](../reference/cli#eve-remote-connect).
|
|
139
140
|
- MCP's `input_required` now covers sign-ins as well as approvals and questions. Answer non-sign-in interactions using `responses: [{ interactionId, optionId?, text? }]`; complete sign-ins externally. Direct `invokeTool` calls return call-shaped outcomes, not conversational pauses. See [MCP](../channels/mcp).
|
|
@@ -10,6 +10,10 @@ Connections live under `agent/connections/`. A static connection's runtime name
|
|
|
10
10
|
|
|
11
11
|
A connection owns its name and every name that starts with `<name>__`, so `linear__list_issues` always means the `linear` connection's `list_issues` tool. The compiler rejects a tool, subagent, or connection whose name is a static connection's name or starts with its `<name>__` prefix. eve applies the same rule to dynamic connections, tools, and subagents when they resolve, except that a dynamic connection with exactly a static connection's name replaces that static connection; see [Naming and conflicts](/docs/guides/dynamic-capabilities#naming-and-conflicts). Both errors name the two sides of the conflict; rename either one.
|
|
12
12
|
|
|
13
|
+
Static and dynamic connection definitions must use `defineMcpClientConnection`
|
|
14
|
+
or `defineOpenAPIConnection` from `eve/connections`. Plain object exports are
|
|
15
|
+
rejected because they do not identify a protocol.
|
|
16
|
+
|
|
13
17
|
## MCP connections
|
|
14
18
|
|
|
15
19
|
Use an MCP connection when the external service already exposes an MCP server. The server publishes its tools and schemas, and eve makes the matched tools callable by the model. Each tool's JSON Schema reaches the model as published, minus any arguments you supply with `toolCall.providedArguments`, and eve checks the model's arguments against it before it calls the server.
|
package/docs/evals/reporters.mdx
CHANGED
|
@@ -9,6 +9,27 @@ You are responsible for ensuring any observability or eval provider is approved
|
|
|
9
9
|
|
|
10
10
|
Reporters attach in two places. Declare them in `evals.config.ts` to observe **every** eval in the run, the usual choice for a shared destination like one Braintrust experiment, so you don't repeat the reporter in each file. Or list them on an individual eval's `reporters` to scope a destination to that eval (or to a group of evals that share one instance).
|
|
11
11
|
|
|
12
|
+
## Console
|
|
13
|
+
|
|
14
|
+
The CLI adds `consoleReporter()` from `eve/evals/reporters` unless you pass
|
|
15
|
+
`--json`. There is no public runner API, so reporters compose only through
|
|
16
|
+
`evals.config.ts` and per-eval `reporters`. A custom console reporter mostly
|
|
17
|
+
makes sense with `--json`, for example logging to stderr so stdout stays valid
|
|
18
|
+
JSON:
|
|
19
|
+
|
|
20
|
+
```ts title="evals/evals.config.ts"
|
|
21
|
+
import { defineEvalConfig } from "eve/evals";
|
|
22
|
+
import { consoleReporter } from "eve/evals/reporters";
|
|
23
|
+
|
|
24
|
+
export default defineEvalConfig({
|
|
25
|
+
reporters: [consoleReporter({ color: false, log: (line) => console.error(line) })],
|
|
26
|
+
});
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Both options are optional; the default logger is `console.log` and color
|
|
30
|
+
follows whether stdout is a terminal. Without `--json`, another console reporter
|
|
31
|
+
duplicates the CLI's output.
|
|
32
|
+
|
|
12
33
|
## Braintrust
|
|
13
34
|
|
|
14
35
|
`braintrustReporter(...)` uploads eval results to Braintrust experiments. Put one instance in the config so it covers the whole run:
|
package/docs/extensions.md
CHANGED
|
@@ -340,6 +340,18 @@ Hooks and instruction fragments are additive, so they cannot be replaced. To rep
|
|
|
340
340
|
|
|
341
341
|
You can also place an override in the corresponding agent-root slot by using the final qualified name. For example, `agent/tools/crm__search.ts` replaces `tools/search.ts` from the extension package or its directory override. Application sources have the highest precedence, so an agent-root override wins when both forms exist.
|
|
342
342
|
|
|
343
|
+
### Computer-use overrides
|
|
344
|
+
|
|
345
|
+
The bundled `eve/extensions/computer-use` extension exports `computer_use` from
|
|
346
|
+
`eve/extensions/computer-use/tools`. Reuse that tool definition in a same-named
|
|
347
|
+
override, as with the [code extension's tools](/docs/code-extension#override-bundled-tools).
|
|
348
|
+
|
|
349
|
+
For a custom sandbox, `eve/extensions/computer-use/sandbox` exports
|
|
350
|
+
`installComputerUse(sandbox)` and `startComputerUse(sandbox)`. Run the installer
|
|
351
|
+
in the environment's preparation callback to install desktop packages and the
|
|
352
|
+
driver; it requires an apt-based image with root or passwordless sudo. Start
|
|
353
|
+
the managed display and driver after opening each session sandbox.
|
|
354
|
+
|
|
343
355
|
### Use an extension tool result in a hook
|
|
344
356
|
|
|
345
357
|
To retain an extension tool's result type in a consumer hook, import its definition from `./tools` and pass it to [`toolResultFrom`](/docs/guides/hooks#narrowing-tool-results):
|
package/docs/getting-started.mdx
CHANGED
|
@@ -84,7 +84,11 @@ npm install eve@latest ai zod
|
|
|
84
84
|
|
|
85
85
|
Declare Node.js 24 in `package.json`, then create `agent/instructions.md` and, when you need runtime configuration, `agent/agent.ts`.
|
|
86
86
|
|
|
87
|
-
|
|
87
|
+
The installed package's `node_modules/eve/CHANGELOG.md` contains that version's release notes and a link to the full changelog through that version. For an upgrade across multiple releases, review each version between the installed and target versions in the target version's changelog at `https://raw.githubusercontent.com/vercel/eve/refs/tags/eve%40<version>/packages/eve/CHANGELOG.md`.
|
|
88
|
+
|
|
89
|
+
## Upgrade an existing project
|
|
90
|
+
|
|
91
|
+
For the coordinated pre-1.0 API cleanup, follow [Prepare for 1.0](./guides/prepare-for-1-0) before updating an existing server, client, or authored agent.
|
|
88
92
|
|
|
89
93
|
## Continue with the tutorial
|
|
90
94
|
|
|
@@ -16,7 +16,7 @@ The route-auth policy lives on the HTTP channel factory (`agent/channels/eve.ts`
|
|
|
16
16
|
|
|
17
17
|
- `POST /eve/v1/session`
|
|
18
18
|
- `POST /eve/v1/session/:sessionId`
|
|
19
|
-
- `POST /eve/v1/session/:sessionId/{cancel,compact,clear,
|
|
19
|
+
- `POST /eve/v1/session/:sessionId/{cancel,compact,clear,end}`
|
|
20
20
|
- `GET /eve/v1/session/:sessionId/stream`
|
|
21
21
|
|
|
22
22
|
These routes are protected by the channel's auth policy. eve fails closed by default: production traffic is rejected unless you configure an authenticator that accepts it, and anonymous access requires an explicit `none()`.
|
|
@@ -27,6 +27,8 @@ The state is deliberately small:
|
|
|
27
27
|
interface ClientSessionState {
|
|
28
28
|
sessionId: string;
|
|
29
29
|
streamIndex: number;
|
|
30
|
+
/** Opaque; persist it and pass it back unchanged. eve may extend it. */
|
|
31
|
+
inbox?: string;
|
|
30
32
|
}
|
|
31
33
|
```
|
|
32
34
|
|
|
@@ -41,15 +43,14 @@ Attach a fixed handle to the saved ID and restore its cursor:
|
|
|
41
43
|
import type { ClientSessionState } from "eve/client";
|
|
42
44
|
|
|
43
45
|
const saved = (await loadSessionState()) as ClientSessionState;
|
|
44
|
-
const session = client.sessions.attach(saved.sessionId,
|
|
45
|
-
streamIndex: saved.streamIndex,
|
|
46
|
-
});
|
|
46
|
+
const session = client.sessions.attach(saved.sessionId, saved);
|
|
47
47
|
|
|
48
48
|
const response = await session.send("Now shorten it.");
|
|
49
49
|
console.log((await response.result()).message);
|
|
50
50
|
```
|
|
51
51
|
|
|
52
|
-
|
|
52
|
+
Pass the whole saved state so its optional [`inbox`](./overview#faster-sends-with-inbox) value
|
|
53
|
+
reaches later sends. `attach()` performs no request. Every later operation targets exactly
|
|
53
54
|
`saved.sessionId`; it never follows or creates a replacement.
|
|
54
55
|
|
|
55
56
|
`send()` correlates its response with the message accepted by the server. If the
|
|
@@ -63,14 +64,17 @@ If a configured reconnect limit ends the stream before the accepted turn reaches
|
|
|
63
64
|
a boundary, collecting its response throws. A partial stream is not a completed
|
|
64
65
|
result.
|
|
65
66
|
|
|
66
|
-
|
|
67
|
+
<a id="waiting-completed-and-reset-sessions" />
|
|
68
|
+
|
|
69
|
+
## Waiting, completed, and ended sessions
|
|
67
70
|
|
|
68
71
|
A session that hasn't ended (`session.ended`) accepts another message through the
|
|
69
|
-
same handle.
|
|
72
|
+
same handle. An ended session does not. Start a fresh conversation
|
|
70
73
|
explicitly with another `client.sessions.create(firstTurn)` call.
|
|
71
74
|
|
|
72
75
|
```ts
|
|
73
|
-
const
|
|
76
|
+
const ended = await session.end({ reason: "Start over" });
|
|
77
|
+
await ended.result();
|
|
74
78
|
const { session: fresh, delivery } = await client.sessions.create({ message: "Begin again." });
|
|
75
79
|
```
|
|
76
80
|
|
|
@@ -102,9 +106,7 @@ The shared `Client` owns the base URL, auth, headers, and redirect policy. Each
|
|
|
102
106
|
read:
|
|
103
107
|
|
|
104
108
|
```ts
|
|
105
|
-
const session = client.sessions.attach(saved.sessionId,
|
|
106
|
-
streamIndex: saved.streamIndex,
|
|
107
|
-
});
|
|
109
|
+
const session = client.sessions.attach(saved.sessionId, saved);
|
|
108
110
|
|
|
109
111
|
for await (const event of session.stream()) {
|
|
110
112
|
console.log(event.type);
|