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
|
@@ -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
|
@@ -98,19 +98,35 @@ export default git({});
|
|
|
98
98
|
|
|
99
99
|
Configure `github` to broker GitHub access through Connect instead. The extension then adds the authenticated `git__gh` tool, tells the agent to use it for every authenticated GitHub operation, and switches `git__pr` to `gh-signed-commit` for repositories that require verified signatures.
|
|
100
100
|
|
|
101
|
-
| Option
|
|
102
|
-
|
|
|
103
|
-
| `github.connector`
|
|
104
|
-
| `github.
|
|
105
|
-
| `github.
|
|
106
|
-
| `github.
|
|
107
|
-
| `github.attribution`
|
|
101
|
+
| Option | Required | Effect |
|
|
102
|
+
| ---------------------- | ------------- | -------------------------------------------------------------------------------------------- |
|
|
103
|
+
| `github.connector` | With `github` | Connector that mints a GitHub token |
|
|
104
|
+
| `github.broker` | With `github` | `broker(sandbox, rules)` callback that installs, then removes, the GitHub credential rules |
|
|
105
|
+
| `github.authorize` | With `github` | `authorize({ auth, repository, token })` decides whether each `gh` tool invocation may run |
|
|
106
|
+
| `github.principalType` | No | `"app"` (default) for GitHub App installation tokens, or `"user"` for the caller's own token |
|
|
107
|
+
| `github.attribution` | No | `attribution(ctx)` returns the current turn's `{ name, email }` co-author, or `null` |
|
|
108
108
|
|
|
109
|
-
|
|
109
|
+
Each `gh` invocation declares exactly one `owner/name` repository, and every explicit command target must match it. By default the tool requests a GitHub App installation token for that owner's installation, scoped to that one repository; with `github.principalType` set to `"user"` it resolves the caller's own token instead. The sandbox process receives a placeholder `GH_TOKEN`, and the firewall exchanges it on matching GitHub requests. Your `github.broker` callback receives the header-transform rules for the command, then `null` to remove the lease. The callback must preserve your other network rules. GitHub authentication has no command-delivery option.
|
|
110
110
|
|
|
111
|
-
`github.authorize` runs during each `gh` tool execution, not when the session starts. The order is: validate the command and repository, mint the
|
|
111
|
+
`github.authorize` is the agent's only repository access control, so it is required: a command runs only when it returns `true`. It runs during each `gh` tool execution, not when the session starts. The order is: validate the command and repository, mint the token, await `authorize({ auth, repository, token })`, install the credential lease, then run the command. `auth` is the session's current caller at tool invocation, or `null`. Returning `false` stops execution before the lease is installed or the command runs, so the token never reaches the sandbox or GitHub. The decision applies to that invocation only; it is neither cached for the session nor repeated for each GitHub API request.
|
|
112
112
|
|
|
113
|
-
|
|
113
|
+
The simplest policy limits the agent to one organization. Compare owners case-insensitively, as GitHub does:
|
|
114
|
+
|
|
115
|
+
```ts title="agent/extensions/git.ts"
|
|
116
|
+
import git from "eve/extensions/git";
|
|
117
|
+
|
|
118
|
+
import { brokerGitHubLease } from "../lib/github";
|
|
119
|
+
|
|
120
|
+
export default git({
|
|
121
|
+
github: {
|
|
122
|
+
connector: "github/my-agent",
|
|
123
|
+
broker: brokerGitHubLease,
|
|
124
|
+
authorize: ({ repository }) => repository.toLowerCase().startsWith("acme/"),
|
|
125
|
+
},
|
|
126
|
+
});
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
`authorize` can also use the token to check the caller, for example their collaborator status (allowed commands still use the app token's permissions, not the collaborator's):
|
|
114
130
|
|
|
115
131
|
```ts title="agent/extensions/git.ts"
|
|
116
132
|
import git from "eve/extensions/git";
|
|
@@ -120,10 +136,10 @@ import { brokerGitHubLease } from "../lib/github";
|
|
|
120
136
|
export default git({
|
|
121
137
|
github: {
|
|
122
138
|
connector: "github/my-agent",
|
|
123
|
-
org: "acme",
|
|
124
139
|
broker: brokerGitHubLease,
|
|
125
140
|
// GitHub channel sessions carry the commenter's login as `auth.subject`.
|
|
126
141
|
async authorize({ auth, repository, token }) {
|
|
142
|
+
if (!repository.toLowerCase().startsWith("acme/")) return false;
|
|
127
143
|
if (auth?.authenticator !== "github-webhook" || !auth.subject) return false;
|
|
128
144
|
const response = await fetch(
|
|
129
145
|
`https://api.github.com/repos/${repository}/collaborators/${auth.subject}`,
|
|
@@ -135,6 +151,29 @@ export default git({
|
|
|
135
151
|
});
|
|
136
152
|
```
|
|
137
153
|
|
|
154
|
+
### Run commands as the caller
|
|
155
|
+
|
|
156
|
+
By default each `gh` invocation mints a GitHub App installation token, so commands run with the installation's permissions. Set `github.principalType` to `"user"` to run them with the caller's own GitHub permissions instead, as `connect({ connector, principalType: "user" })` does for connections:
|
|
157
|
+
|
|
158
|
+
```ts title="agent/extensions/git.ts"
|
|
159
|
+
import git from "eve/extensions/git";
|
|
160
|
+
|
|
161
|
+
import { brokerGitHubLease } from "../lib/github";
|
|
162
|
+
|
|
163
|
+
export default git({
|
|
164
|
+
github: {
|
|
165
|
+
connector: "github/my-agent",
|
|
166
|
+
broker: brokerGitHubLease,
|
|
167
|
+
authorize: ({ repository }) => repository.toLowerCase().startsWith("acme/"),
|
|
168
|
+
principalType: "user",
|
|
169
|
+
},
|
|
170
|
+
});
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
The tool resolves the caller's token from `github.connector` through `ctx.getToken`. When the caller has no grant, eve signs them in and re-runs the call. The token request carries no repository details, so one grant covers every repository and later commands resolve tokens without another sign-in. When GitHub rejects the token (`HTTP 401`, `Bad credentials`, `Authentication failed`, or a `gh-signed-commit` `failed: 401`), the tool calls `ctx.requireAuth`, which evicts the token and signs the caller in again.
|
|
174
|
+
|
|
175
|
+
A user token carries the caller's GitHub permissions across every account where the GitHub App is installed, not only the declared repository. The tool description and GitHub instructions tell the model that access is limited to what the caller can reach. `github.authorize` still runs before every command, with the caller's token, and remains the agent's repository policy.
|
|
176
|
+
|
|
138
177
|
### Credit the person behind a turn
|
|
139
178
|
|
|
140
179
|
Commits made by the `gh` tool are authored by the GitHub App. Return a verified user mapping from
|
|
@@ -153,8 +192,8 @@ import { brokerGitHubLease, coAuthorFor } from "../lib/github";
|
|
|
153
192
|
export default git({
|
|
154
193
|
github: {
|
|
155
194
|
connector: "github/my-agent",
|
|
156
|
-
org: "acme",
|
|
157
195
|
broker: brokerGitHubLease,
|
|
196
|
+
authorize: ({ repository }) => repository.toLowerCase().startsWith("acme/"),
|
|
158
197
|
attribution: (ctx) => coAuthorFor(ctx.session.auth.current),
|
|
159
198
|
},
|
|
160
199
|
});
|
|
@@ -164,6 +203,31 @@ export default git({
|
|
|
164
203
|
|
|
165
204
|
`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
205
|
|
|
206
|
+
## Override bundled tools
|
|
207
|
+
|
|
208
|
+
`eve/extensions/code/tools` exports the reusable `apply_patch` and `grep` tool
|
|
209
|
+
definitions. Import one in an override to change approval or other tool options
|
|
210
|
+
without copying its implementation. With the file mount above, put the override
|
|
211
|
+
in the agent-root slot named after the qualified tool, `code__apply_patch`:
|
|
212
|
+
|
|
213
|
+
```ts title="agent/tools/code__apply_patch.ts"
|
|
214
|
+
import { apply_patch } from "eve/extensions/code/tools";
|
|
215
|
+
import { defineTool } from "eve/tools";
|
|
216
|
+
import { always } from "eve/tools/approval";
|
|
217
|
+
|
|
218
|
+
export default defineTool({ ...apply_patch, approval: always() });
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
`agent/extensions/code/tools/apply_patch.ts` works only when the mount is a
|
|
222
|
+
directory, `agent/extensions/code/extension.ts`.
|
|
223
|
+
|
|
224
|
+
For a custom GitHub command tool, `eve/extensions/git/sandbox` exports
|
|
225
|
+
`executeGitHubShell(input, config, dependencies)` and `githubShellApproval(input)`.
|
|
226
|
+
The execution helper enforces repository and command constraints and brokers a
|
|
227
|
+
credential lease; dependencies supply the session ID and sandbox access. Reuse
|
|
228
|
+
`githubShellApproval` to reject invalid command inputs through the approval
|
|
229
|
+
policy rather than bypassing those constraints.
|
|
230
|
+
|
|
167
231
|
## Prepare the sandbox
|
|
168
232
|
|
|
169
233
|
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);
|
|
@@ -54,13 +54,36 @@ or terminal session throws `SessionNotActiveError` immediately with `retryable:
|
|
|
54
54
|
[stranded](../../concepts/execution-model-and-durability#stranded-sessions) session throws
|
|
55
55
|
`ClientSessionStrandedError`, a `ClientError` with `code: "session_stranded"` and the
|
|
56
56
|
`eveVersion` that built the session when it recorded one. It is never retried automatically. Call
|
|
57
|
-
`session.
|
|
57
|
+
`session.end()` and create a new session.
|
|
58
58
|
The client never creates a replacement session. Following or reconnecting to a stranded session's
|
|
59
59
|
stream reports the same typed error without retrying, including when you were waiting for a
|
|
60
60
|
response to a message accepted before the upgrade. That accepted message is not redelivered.
|
|
61
61
|
`session.clear()` throws the same error, because clearing would keep a session that cannot run.
|
|
62
62
|
`session.stream({ follow: false })` and `session.snapshot()` still read the recorded history.
|
|
63
63
|
|
|
64
|
+
The typed errors `eve/client` throws (`ClientError` and its subclasses, `SessionNotActiveError`,
|
|
65
|
+
`HealthResponseError`, and `AgentInfoResponseError`) extend `EveError` and have a stable snake_case
|
|
66
|
+
`code`: `SessionNotActiveError` uses `session_not_active` or `session_not_ready`; `ClientError` carries
|
|
67
|
+
the response's code (such as `session_stranded` or `session_expired`), or `http_error` when the
|
|
68
|
+
response had none. Narrow with the static `is()` of the class you expect instead of `instanceof`,
|
|
69
|
+
so errors from a separately bundled copy of eve still match:
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
import { ClientError, SessionNotActiveError } from "eve/client";
|
|
73
|
+
|
|
74
|
+
try {
|
|
75
|
+
await session.send("Continue.");
|
|
76
|
+
} catch (error) {
|
|
77
|
+
if (SessionNotActiveError.is(error) && !error.retryable) {
|
|
78
|
+
// Start a new session.
|
|
79
|
+
} else if (ClientError.is(error) && error.code === "unauthorized") {
|
|
80
|
+
// Sign in again.
|
|
81
|
+
} else {
|
|
82
|
+
throw error;
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
```
|
|
86
|
+
|
|
64
87
|
## Send a full turn payload
|
|
65
88
|
|
|
66
89
|
Pass the full payload to `create()` for the first turn or `send()` for a follow-up:
|
|
@@ -113,11 +113,13 @@ await response.result();
|
|
|
113
113
|
|
|
114
114
|
Per-request headers override client-level values with the same name. For example, a turn can set its application user's `Authorization` header while `vercelOidc` continues to send the deployment-protection credential in `x-vercel-trusted-oidc-idp-token`.
|
|
115
115
|
|
|
116
|
-
##
|
|
116
|
+
## Faster sends with `inbox`
|
|
117
117
|
|
|
118
118
|
Keep the complete `session.state` when saving and restoring a conversation. It can include an
|
|
119
|
-
opaque `inbox`
|
|
120
|
-
|
|
119
|
+
opaque `inbox` value issued by the server. The client sends it back with later messages to avoid
|
|
120
|
+
another hook lookup. Persist it and pass it back unchanged: do
|
|
121
|
+
not inspect, edit, or construct it, because eve may change or extend its contents in any release.
|
|
122
|
+
A missing, stale, or rejected value only costs a slower lookup.
|
|
121
123
|
|
|
122
124
|
Set `EVE_INBOX_HANDLE_SECRET` to the same server-only random secret (at least 32 characters)
|
|
123
125
|
on the deployments that share sessions. Without this key, handles are neither issued nor used.
|
|
@@ -131,7 +133,7 @@ is configured. This change keeps the released SDK dependencies; adopting the SDK
|
|
|
131
133
|
enables the optimization. Handles exclude user metadata, live capabilities, and trace carriers,
|
|
132
134
|
which may contain private server baggage. The signature authenticates a handle; it does not hide its contents.
|
|
133
135
|
|
|
134
|
-
The server checks that the handle addresses the requested inbox. Workflow still validates the
|
|
136
|
+
The server checks that the handle addresses the requested session's inbox. Workflow still validates the
|
|
135
137
|
hook, persists the message, and wakes the workflow. A definite stale-owner rejection resolves
|
|
136
138
|
the current inbox again. An uncertain write is surfaced without submitting a second delivery.
|
|
137
139
|
|
|
@@ -182,10 +184,10 @@ for await (const event of session.stream({ follow: false })) {
|
|
|
182
184
|
console.log(event.type);
|
|
183
185
|
}
|
|
184
186
|
|
|
185
|
-
await session.
|
|
187
|
+
await session.end({ reason: "User requested a fresh session" });
|
|
186
188
|
```
|
|
187
189
|
|
|
188
|
-
`client.sessions` stores the session ID, stream cursor, and optional opaque inbox
|
|
190
|
+
`client.sessions` stores the session ID, stream cursor, and optional opaque `inbox` value. Every method calls an ID-addressed `/eve/v1/session/:sessionId/...` route. Sending through a handle for an unknown or terminal ID fails instead of creating a replacement, and `end()` leaves the handle pinned to the retired ID. Replace calls to the old `reset()` method with `end()`; use `client.sessions.create()` to start a different session. Upgrade the server before using a new client's `end()` method: earlier servers do not serve `/end`.
|
|
189
191
|
|
|
190
192
|
A client can own many independent fixed sessions at once:
|
|
191
193
|
|