eve 0.89.0 → 0.91.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 +39 -9
- package/dist/src/channel/adapter.d.ts +12 -3
- package/dist/src/channel/adapter.js +1 -1
- package/dist/src/channel/auth/definitions.d.ts +7 -20
- package/dist/src/channel/auth/definitions.js +1 -1
- package/dist/src/channel/auth/http-basic.js +1 -1
- package/dist/src/channel/auth/jwt-ecdsa.js +1 -1
- package/dist/src/channel/auth/jwt-hmac.js +1 -1
- package/dist/src/channel/auth/oidc.js +1 -1
- package/dist/src/channel/auth/result.d.ts +2 -3
- package/dist/src/channel/auth/result.js +1 -1
- 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 +1 -1
- package/dist/src/channel/schedule.js +1 -1
- package/dist/src/channel/types.d.ts +2 -0
- package/dist/src/chunks/{use-eve-agent-Bbl4H5aA.js → use-eve-agent-Bwloorf8.js} +77 -63
- package/dist/src/chunks/{use-eve-agent-CNpxgKEH.js → use-eve-agent-XCB0-tLX.js} +77 -63
- package/dist/src/cli/dev/environment.js +1 -1
- package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
- package/dist/src/cli/dev/tui/remote-connection-probe.js +1 -1
- package/dist/src/cli/dev/tui/remote-connection-types.d.ts +1 -0
- package/dist/src/cli/dev/tui/runner.js +2 -2
- package/dist/src/cli/dev/tui/status-line.d.ts +2 -2
- package/dist/src/cli/dev/tui/status-line.js +1 -1
- package/dist/src/client/agent-info-schema.d.ts +341 -326
- package/dist/src/client/agent-info-schema.js +1 -1
- package/dist/src/client/agent-info-types.d.ts +13 -10
- package/dist/src/client/client-error.d.ts +1 -1
- package/dist/src/client/client.d.ts +5 -3
- package/dist/src/client/client.js +1 -1
- package/dist/src/client/session.d.ts +1 -1
- package/dist/src/compiled/.vendor-stamp.json +1 -1
- package/dist/src/evals/target.js +1 -1
- package/dist/src/eve-channel/auth.d.ts +19 -0
- package/dist/src/eve-channel/auth.js +1 -0
- package/dist/src/eve-channel/index.d.ts +1 -0
- package/dist/src/eve-channel/index.js +1 -1
- package/dist/src/eve-channel/types.d.ts +23 -4
- package/dist/src/execution/catalog/connection-entry.js +1 -1
- package/dist/src/execution/coordination-dispatch-shared.js +1 -1
- package/dist/src/execution/dynamic-workflow/tool.js +1 -1
- package/dist/src/execution/proxied-deliver-step.js +1 -1
- package/dist/src/execution/sandbox/bash.js +2 -2
- package/dist/src/execution/session/active-turn.js +1 -1
- package/dist/src/execution/session/admission.d.ts +6 -0
- package/dist/src/execution/session/admission.js +1 -1
- package/dist/src/execution/session/delivery-facts.js +1 -1
- package/dist/src/execution/session/next-input.d.ts +2 -2
- package/dist/src/execution/session/next-input.js +1 -1
- package/dist/src/execution/session/program.js +1 -1
- package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
- package/dist/src/execution/session-inbox/inbox.js +1 -1
- package/dist/src/execution/session-inbox/protocol.js +1 -1
- package/dist/src/execution/tools/agent-router-workflow.js +1 -1
- package/dist/src/harness/compaction/engine.js +2 -2
- package/dist/src/harness/current-messages.js +1 -1
- package/dist/src/harness/emission.d.ts +3 -0
- package/dist/src/harness/emission.js +1 -1
- package/dist/src/harness/facts.d.ts +5 -2
- package/dist/src/harness/facts.js +1 -1
- package/dist/src/harness/model-call/call.d.ts +7 -1
- package/dist/src/harness/model-call/call.js +3 -1
- package/dist/src/harness/provider-tool-history.d.ts +8 -0
- package/dist/src/harness/provider-tool-history.js +1 -1
- package/dist/src/harness/session-machine/transitions.d.ts +3 -2
- package/dist/src/harness/step/after-model.js +1 -1
- package/dist/src/harness/step/context.js +1 -1
- package/dist/src/harness/step/intake.js +1 -1
- package/dist/src/harness/step/prompt.js +1 -1
- package/dist/src/harness/tool-history-repair.d.ts +2 -0
- package/dist/src/harness/tool-history-repair.js +1 -1
- package/dist/src/harness/tool-loop.js +1 -1
- package/dist/src/internal/application/stamped-package-version.js +1 -1
- package/dist/src/internal/authored-module-graph.js +1 -1
- package/dist/src/internal/nitro/routes/agent-info/build-agent-info-response.d.ts +2 -2
- package/dist/src/protocol/routes.d.ts +7 -1
- package/dist/src/protocol/routes.js +1 -1
- package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
- package/dist/src/protocol/session-events/families/delivery.js +1 -1
- package/dist/src/protocol/session-projection/fold.js +1 -1
- package/dist/src/public/channels/discord/hitl.js +1 -1
- package/dist/src/public/channels/github/githubChannel.js +1 -1
- package/dist/src/public/channels/github/state.d.ts +7 -0
- package/dist/src/public/channels/github/state.js +1 -1
- package/dist/src/public/channels/mcp.js +1 -1
- package/dist/src/public/channels/slack/hitl.d.ts +2 -1
- package/dist/src/public/channels/slack/hitl.js +3 -3
- package/dist/src/public/channels/slack/interaction-cards.js +1 -1
- package/dist/src/public/channels/slack/request-card-render.js +1 -1
- package/dist/src/public/channels/teams/hitl.js +1 -1
- package/dist/src/public/channels/teams/verify.js +1 -1
- package/dist/src/public/channels/telegram/telegramChannel.js +1 -1
- package/dist/src/public/connections/index.d.ts +1 -1
- package/dist/src/public/definitions/channel.js +1 -1
- package/dist/src/public/definitions/connections/tool-call.d.ts +2 -2
- package/dist/src/public/definitions/hook.d.ts +90 -7
- package/dist/src/public/definitions/hook.js +1 -1
- package/dist/src/public/hooks/index.d.ts +3 -2
- package/dist/src/reactions/continuation.d.ts +19 -0
- package/dist/src/reactions/continuation.js +1 -0
- package/dist/src/reactions/frame.js +1 -1
- package/dist/src/reactions/intents.d.ts +10 -4
- package/dist/src/reactions/intents.js +1 -1
- package/dist/src/reactions/kinds/hook.js +1 -1
- package/dist/src/reactions/runner.js +1 -1
- package/dist/src/reactions/state.d.ts +15 -2
- package/dist/src/reactions/state.js +1 -1
- package/dist/src/runtime/channels/registry.d.ts +2 -2
- package/dist/src/runtime/channels/registry.js +1 -1
- package/dist/src/runtime/connections/approval-scope.d.ts +9 -0
- package/dist/src/runtime/connections/approval-scope.js +1 -0
- package/dist/src/runtime/connections/mcp-client.d.ts +1 -1
- package/dist/src/runtime/connections/mcp-client.js +1 -1
- package/dist/src/runtime/connections/provided-arguments.js +1 -1
- package/dist/src/runtime/resolve-connection.js +1 -1
- package/dist/src/runtime/subagents/workflow.js +1 -1
- package/dist/src/setup/primitives/open-url.js +1 -1
- package/dist/src/setup/scaffold/create/project.js +1 -1
- package/dist/src/shared/agent-info-access.d.ts +5 -0
- package/dist/src/shared/agent-info-access.js +1 -0
- package/dist/src/shared/connection-types.d.ts +21 -4
- package/dist/src/shared/value-delta.d.ts +5 -4
- package/dist/src/shared/value-delta.js +1 -1
- package/dist/src/svelte/index.js +1 -1
- package/dist/src/svelte/use-eve-agent.js +1 -1
- package/dist/src/tools/provided/ask-question-workflow.js +1 -1
- package/dist/src/tools/provided/sleep-workflow.js +1 -1
- package/dist/src/tools/provided/web-fetch.js +1 -1
- package/dist/src/vue/index.js +1 -1
- package/dist/src/vue/use-eve-agent.js +1 -1
- package/docs/agent-config.md +199 -222
- package/docs/channels/chat-sdk.mdx +60 -64
- package/docs/channels/custom.mdx +265 -280
- package/docs/channels/discord.mdx +176 -123
- package/docs/channels/eve.mdx +136 -204
- package/docs/channels/github.mdx +24 -22
- package/docs/channels/linear.mdx +30 -30
- package/docs/channels/linq.mdx +25 -13
- package/docs/channels/mcp.mdx +154 -116
- package/docs/channels/overview.mdx +31 -32
- package/docs/channels/photon.mdx +32 -56
- package/docs/channels/slack.mdx +538 -375
- package/docs/channels/teams.mdx +40 -26
- package/docs/channels/telegram.mdx +13 -13
- package/docs/channels/twilio.mdx +11 -11
- package/docs/code-extension.mdx +40 -42
- package/docs/concepts/built-in-tools.md +89 -57
- package/docs/concepts/context-control.md +20 -20
- package/docs/concepts/default-harness.md +20 -36
- package/docs/concepts/execution-model-and-durability.mdx +96 -160
- package/docs/concepts/project-structure.mdx +21 -14
- package/docs/concepts/security-model.md +27 -27
- package/docs/concepts/sessions-runs-and-streaming.md +184 -194
- package/docs/concepts/state.md +7 -15
- package/docs/connections/mcp.mdx +109 -93
- package/docs/connections/openapi.mdx +57 -59
- package/docs/connections/overview.mdx +205 -170
- package/docs/evals/assertions.mdx +36 -29
- package/docs/evals/cases.mdx +38 -42
- package/docs/evals/judge.mdx +21 -29
- package/docs/evals/overview.mdx +42 -38
- package/docs/evals/reporters.mdx +54 -27
- package/docs/evals/running.mdx +15 -8
- package/docs/evals/targets.mdx +17 -18
- package/docs/evals/tool-stubs.mdx +111 -97
- package/docs/experimental/dynamic-schedules.mdx +118 -63
- package/docs/extensions.md +58 -65
- package/docs/getting-started.mdx +4 -6
- package/docs/guides/auth-and-route-protection.md +100 -70
- package/docs/guides/client/continuations.mdx +23 -26
- package/docs/guides/client/messages.mdx +47 -66
- package/docs/guides/client/output-schema.mdx +8 -8
- package/docs/guides/client/overview.mdx +47 -41
- package/docs/guides/client/streaming.mdx +62 -71
- package/docs/guides/decide.md +24 -79
- package/docs/guides/deployment/meta.json +1 -1
- package/docs/guides/deployment/overview.md +27 -18
- package/docs/guides/deployment/self-hosted-operations.md +99 -0
- package/docs/guides/deployment/self-hosting.md +63 -80
- package/docs/guides/deployment/vercel.mdx +31 -27
- package/docs/guides/deployment/workflow-worlds.md +100 -0
- package/docs/guides/dev-tui.md +48 -41
- package/docs/guides/dynamic-capabilities.md +49 -50
- package/docs/guides/frontend/nextjs.mdx +2 -2
- package/docs/guides/frontend/nuxt.mdx +11 -11
- package/docs/guides/frontend/overview.mdx +1 -1
- package/docs/guides/frontend/sveltekit.mdx +11 -11
- package/docs/guides/frontend/tanstack.mdx +16 -16
- package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
- package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
- package/docs/guides/frontend/use-eve-agent.mdx +25 -25
- package/docs/guides/hooks.md +152 -106
- package/docs/guides/instrumentation/agent-runs.mdx +26 -30
- package/docs/guides/instrumentation/instrumentation.mdx +49 -76
- package/docs/guides/instrumentation/meta.json +1 -1
- package/docs/guides/instrumentation/otel.mdx +113 -179
- package/docs/guides/prepare-for-1-0.md +23 -1
- package/docs/guides/remote-agents.md +125 -187
- package/docs/guides/self-modification.md +18 -18
- package/docs/guides/session-context.md +16 -16
- package/docs/install-integrations.mdx +26 -24
- package/docs/instructions.mdx +37 -42
- package/docs/memory/custom-provider.md +35 -41
- package/docs/memory/file.md +93 -76
- package/docs/memory/overview.mdx +145 -156
- package/docs/patterns/durable-cross-channel-notifications.md +15 -19
- package/docs/patterns/dynamic-scheduling.md +19 -23
- package/docs/patterns/multi-tenant-approvals.md +17 -22
- package/docs/patterns/multi-tenant-auth.md +43 -42
- package/docs/patterns/multi-tenant-memory.md +39 -36
- package/docs/patterns/voice-notes.md +3 -3
- package/docs/protocols/acp.md +13 -13
- package/docs/protocols/ucp.mdx +7 -7
- package/docs/reference/agent-files.md +6 -6
- package/docs/reference/cli.md +99 -98
- package/docs/reference/telemetry.md +1 -1
- package/docs/reference/typescript-api.md +52 -53
- package/docs/responsible-use.md +2 -2
- package/docs/sandbox/custom-providers.mdx +60 -56
- package/docs/sandbox/default.mdx +23 -24
- package/docs/sandbox/docker.mdx +16 -10
- package/docs/sandbox/index.mdx +93 -61
- package/docs/sandbox/just-bash.mdx +17 -11
- package/docs/sandbox/troubleshooting.mdx +29 -23
- package/docs/sandbox/vercel.mdx +45 -52
- package/docs/schedules.mdx +65 -54
- package/docs/skills.mdx +74 -49
- package/docs/subagents/index.mdx +97 -136
- package/docs/tools/human-in-the-loop.md +160 -90
- package/docs/tools/meta.json +1 -1
- package/docs/tools/overview.mdx +229 -237
- package/docs/tools/tasks.md +118 -117
- package/docs/tools/workflows.mdx +447 -543
- package/docs/tutorial/connect-a-warehouse.mdx +11 -13
- package/docs/tutorial/first-agent.mdx +14 -16
- package/docs/tutorial/guard-the-spend.mdx +6 -8
- package/docs/tutorial/how-it-runs.mdx +8 -8
- package/docs/tutorial/query-sample-data.mdx +8 -8
- package/docs/tutorial/remember-definitions.mdx +4 -4
- package/docs/tutorial/run-analysis.mdx +20 -22
- package/docs/tutorial/ship-it.mdx +19 -19
- package/docs/tutorial/team-playbooks.mdx +9 -9
- package/docs/use-cases.mdx +13 -11
- package/package.json +1 -1
- package/docs/guides/instrumentation/migration.md +0 -96
- package/docs/tools/tasks-upgrade.md +0 -218
package/docs/channels/eve.mdx
CHANGED
|
@@ -3,11 +3,11 @@ title: "eve"
|
|
|
3
3
|
description: "The default HTTP API for an agent, covering session routes, auth, and customization."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
The eve channel is the framework's default HTTP API
|
|
6
|
+
The eve channel is the framework's default HTTP API under `/eve/v1`. The terminal UI, [`useEveAgent`](../guides/frontend/overview), `curl`, and SDK clients use it to start sessions, send messages, and stream events. It also serves the health, agent info, callback, and task input routes.
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
Each deployment serves its own API with its own host and authentication policy. `eve.dev` hosts framework documentation only; it is not a shared API, authorization server, MCP server, or A2A server.
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
eve supplies the channel when `agent/channels/eve.ts` doesn't exist. Most apps never write this file. Add it only to change the defaults, usually who may call the routes:
|
|
11
11
|
|
|
12
12
|
```ts title="agent/channels/eve.ts"
|
|
13
13
|
import { eveChannel } from "eve/channels/eve";
|
|
@@ -18,71 +18,9 @@ export default eveChannel({
|
|
|
18
18
|
});
|
|
19
19
|
```
|
|
20
20
|
|
|
21
|
-
## Web Chat with Sign in with Vercel
|
|
22
|
-
|
|
23
|
-
Run `eve add channel/web`, or select **Web Chat** from the terminal UI's channel
|
|
24
|
-
picker. Choose **Next.js**, a hosting layout, then **Sign in with Vercel**. Sign
|
|
25
|
-
in with Vercel is available only for the Next.js Web Chat app. Setup uses a
|
|
26
|
-
linked Vercel project and creates a Vercel App that only members of that
|
|
27
|
-
project's team can sign in to.
|
|
28
|
-
|
|
29
|
-
For a new agent, initialize it first, then link a project and add Web Chat:
|
|
30
|
-
|
|
31
|
-
```bash
|
|
32
|
-
eve init my-agent --non-interactive
|
|
33
|
-
cd my-agent
|
|
34
|
-
eve link
|
|
35
|
-
eve add channel/web
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
The generated Next.js app uses Better Auth sessions. The selected agent's HTTP
|
|
39
|
-
channel verifies the same session, while retaining Vercel OIDC and local
|
|
40
|
-
development access. In an agent workspace, setup configures only the selected
|
|
41
|
-
agent. Other agents keep their own authentication policies.
|
|
42
|
-
|
|
43
|
-
Setup registers `/api/auth/callback/vercel` as a project redirect URI, so Vercel
|
|
44
|
-
validates callbacks against the project's deployment domains. The app uses the
|
|
45
|
-
`authorization_code` grant, `client_secret_post` authentication, and the
|
|
46
|
-
`openid`, `email`, and `profile` scopes. Setup writes `VERCEL_APP_CLIENT_ID`,
|
|
47
|
-
`VERCEL_APP_CLIENT_SECRET`, and `BETTER_AUTH_SECRET` to production and preview;
|
|
48
|
-
secret values are marked sensitive and are never printed or written to source.
|
|
49
|
-
Run `eve deploy` after setup to publish the app. Local development continues
|
|
50
|
-
without browser sign-in.
|
|
51
|
-
|
|
52
|
-
For automation, supply the setup answers explicitly:
|
|
53
|
-
|
|
54
|
-
```bash
|
|
55
|
-
eve add channel/web --non-interactive \
|
|
56
|
-
--answer 'web-hosting="vercel"' \
|
|
57
|
-
--answer 'web-authentication="vercel"'
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
Use a linked project with permission to manage Vercel Apps and project
|
|
61
|
-
environment variables. A team owner can complete setup if your role cannot
|
|
62
|
-
create apps. The searchable team picker lists eligible teams first. Disabled
|
|
63
|
-
teams show `needs permission` or `couldn't verify`, with shared recovery guidance
|
|
64
|
-
below the list. If permissions cannot be verified, that team stays
|
|
65
|
-
disabled until you sign in or retry. Linked projects are checked before
|
|
66
|
-
interactive auth setup.
|
|
67
|
-
If setup reports a missing prerequisite, complete it and resume with
|
|
68
|
-
`eve add channel/web --skip-install`. Compatible existing apps
|
|
69
|
-
and credentials are reused; conflicting app settings or credentials stop setup
|
|
70
|
-
with an error. Authored channel or UI files are preserved unless you explicitly
|
|
71
|
-
pass `--overwrite`.
|
|
72
|
-
|
|
73
|
-
If the team has reached its Vercel App limit, remove an unused app in team
|
|
74
|
-
settings and retry. If a generated app name or slug is taken by an incompatible
|
|
75
|
-
app, rename the Vercel project in its settings and retry. Compatible apps from a
|
|
76
|
-
concurrent setup are reused. A client-secret limit requires removing an unused
|
|
77
|
-
secret from the app's settings; setup never removes an existing secret for you.
|
|
78
|
-
|
|
79
|
-
Choose **Configure authentication myself** (`web-authentication=custom`) to
|
|
80
|
-
keep the current channel policy. The default placeholder rejects production
|
|
81
|
-
browser requests until you configure your own authentication.
|
|
82
|
-
|
|
83
21
|
## Routes
|
|
84
22
|
|
|
85
|
-
The default eve channel
|
|
23
|
+
The default eve channel serves these routes:
|
|
86
24
|
|
|
87
25
|
- `GET /eve/v1/health` (check whether the application is reachable)
|
|
88
26
|
- `GET /eve/v1/info` (inspect the agent)
|
|
@@ -94,48 +32,30 @@ The default eve channel inspects the agent, creates sessions, accepts callbacks
|
|
|
94
32
|
- `POST /eve/v1/session/:sessionId/end` (retire the session)
|
|
95
33
|
- `GET /eve/v1/session/:sessionId/stream` (stream events as NDJSON)
|
|
96
34
|
|
|
97
|
-
|
|
35
|
+
Create a session, then put its returned ID in every follow-up, control, and stream path.
|
|
98
36
|
|
|
99
|
-
`POST /eve/v1/session/:sessionId` with no body or `{}` prepares an existing session
|
|
100
|
-
the channel's auth policy, without calling `onMessage` or creating a delivery. Non-empty bodies
|
|
101
|
-
keep the message and answer behavior, including unknown-field validation; empty or invalid
|
|
102
|
-
messages, an empty `answers` array, and payloads with neither input are rejected. Preparation
|
|
103
|
-
returns `{ ok: true, status }`: `ready` when the owner already uses the serving
|
|
104
|
-
deployment, `accepted` (HTTP 202) when a background preparation hint has been queued,
|
|
105
|
-
`unsupported` when the World or owner cannot prepare, or `no_active_session` when no live
|
|
106
|
-
owner exists. Other successful statuses use HTTP 200. Acceptance does not mean the handoff
|
|
107
|
-
has completed. Idle preparation preserves the session ID, stream, history, and expiry;
|
|
108
|
-
active work is not interrupted. See the [frontend guide](../guides/frontend/use-eve-agent#prewarming)
|
|
109
|
-
for client usage and deployment routing.
|
|
37
|
+
`POST /eve/v1/session/:sessionId` with no body or `{}` prepares an existing session to answer from the serving deployment. It checks the channel's auth policy, but calls no `onMessage` and sends no message. Preparation keeps the session ID, stream, history, and expiry, and doesn't interrupt running work. It returns `{ ok: true, status }`:
|
|
110
38
|
|
|
111
|
-
|
|
39
|
+
| `status` | HTTP | Meaning |
|
|
40
|
+
| ------------------- | ---- | ------------------------------------------------------------------ |
|
|
41
|
+
| `ready` | 200 | The session already runs on the serving deployment. |
|
|
42
|
+
| `accepted` | 202 | A request to move the session is queued; the move may not be done. |
|
|
43
|
+
| `unsupported` | 200 | The World or the session can't move to the serving deployment. |
|
|
44
|
+
| `no_active_session` | 200 | No running session has this ID. |
|
|
112
45
|
|
|
113
|
-
|
|
46
|
+
A non-empty body is a message or answer, validated in full. eve rejects empty or invalid messages, an empty `answers` array, and payloads with neither input. See [Prewarming](../guides/frontend/use-eve-agent#prewarming) for client usage and deployment routing.
|
|
47
|
+
|
|
48
|
+
`GET /eve/v1/health` is public and returns `{ ok: true, status: "ready", workflowId: string }`. `GET /eve/v1/info` returns agent-info version 5. It checks the channel's auth policy, then serves only operator callers: `service` and `runtime` callers, and, when the channel's auth includes `localDev()`, callers it admits on a development server. Other callers, such as `user` or `anonymous` ones, get `403` with code `info_forbidden`, because the payload includes authored instructions, skill and schedule Markdown, and server paths. The TypeScript client throws `HealthResponseError` or `AgentInfoResponseError` on a malformed payload, and `ClientError` on a non-success response from either route.
|
|
114
49
|
|
|
115
|
-
|
|
116
|
-
unknown top-level JSON fields with `400 Bad Request`. The error names the unknown fields and
|
|
117
|
-
lists the accepted fields for that route. Field names are case-sensitive: `outputschema` is
|
|
118
|
-
not `outputSchema`. Invalid requests do not create sessions, dispatch messages, or apply controls.
|
|
50
|
+
### Request validation
|
|
119
51
|
|
|
120
|
-
|
|
121
|
-
is accepted on session creation but rejected on follow-up messages.
|
|
52
|
+
Session creation, follow-up and input-response requests, and session controls reject unknown top-level JSON fields with `400 Bad Request`. The error names the unknown fields and lists the route's accepted fields. Field names are case-sensitive (`outputschema` is not `outputSchema`), and each route has its own set: `operationId` is accepted on session creation but rejected on follow-ups. A rejected request creates no session, sends no message, and applies no control. Correct the field or upgrade the server; don't strip behavior-changing options and retry.
|
|
122
53
|
|
|
123
|
-
|
|
124
|
-
for a retry that can't tell whether the first request was accepted. The key names the delivery:
|
|
125
|
-
repeating the request with the same key returns the same `deliveryId`, and the input doesn't run
|
|
126
|
-
again. Unlike a channel's [retried deliveries](./custom#retried-deliveries), whose duplicates get a
|
|
127
|
-
new receipt settled `ignored`, the repeat's receipt is the original's. The session remembers its
|
|
128
|
-
last 1,024 keys, so use a new key for new input. The compact and clear routes
|
|
129
|
-
accept no body fields; omit the body or send `{}`. Cancel accepts `turnId`; end accepts `reason`.
|
|
54
|
+
Request bodies can't contain eve's own attachment markers (`eve-url:`, `eve-sandbox:`, and `chat-sdk-file:`). A request that does returns `400 Bad Request`.
|
|
130
55
|
|
|
131
|
-
|
|
132
|
-
with a `callback` accept, and ignore, the retired `activityObserver` field so older senders keep
|
|
133
|
-
working. No other unknown fields are accepted. Authentication and existing value validation still
|
|
134
|
-
apply, including permission checks for forwarded principals and tool stubs.
|
|
56
|
+
Compact and clear accept no body fields; omit the body or send `{}`. Cancel accepts `turnId`, and end accepts `reason`. The unknown-field check applies to top-level fields, not to open payload objects such as `clientContext`. Delegated requests with a `callback` also accept and ignore an `activityObserver` field. Authentication and value validation still apply, including permission checks for forwarded caller identities and tool stubs.
|
|
135
57
|
|
|
136
|
-
|
|
137
|
-
rather than silently losing the requested behavior. Correct the field or upgrade the server;
|
|
138
|
-
do not automatically remove behavior-changing options and retry.
|
|
58
|
+
Follow-up and input-response requests accept an `idempotencyKey` of 1 to 256 characters for retries that can't tell whether the first request was accepted. A repeat with the same key returns the original receipt and `deliveryId` without running the input again. A channel's [retried deliveries](./custom#retried-deliveries) differ: they get a new receipt whose result is `ignored`. The session remembers its last 1,024 keys, so use a new key for new input.
|
|
139
59
|
|
|
140
60
|
### Start and continue a session
|
|
141
61
|
|
|
@@ -146,12 +66,7 @@ curl -X POST https://<deployment>/eve/v1/session
|
|
|
146
66
|
# {"ok":true,"sessionId":"wrun_A"}
|
|
147
67
|
```
|
|
148
68
|
|
|
149
|
-
See [Start a session](../concepts/sessions-runs-and-streaming#start-a-session) for the
|
|
150
|
-
initialization boundary, first-turn identity, readiness response, and retry behavior.
|
|
151
|
-
|
|
152
|
-
The create request still requires route auth. Session audience and the timeout are selected
|
|
153
|
-
at creation; they do not change when the first message arrives. Turn-scoped fields such as
|
|
154
|
-
`clientContext` and `outputSchema` require a message on the create request.
|
|
69
|
+
The create request requires route auth and fixes the session's audience and timeout. Fields that apply to one turn, such as `clientContext` and `outputSchema` need a message on the create request. See [Start a session](../concepts/sessions-runs-and-streaming#start-a-session) for the initialization boundary, first-turn identity, readiness response, and retry behavior.
|
|
155
70
|
|
|
156
71
|
Include an initial message to create the session and start its first turn in one request:
|
|
157
72
|
|
|
@@ -162,14 +77,7 @@ curl -X POST https://<deployment>/eve/v1/session \
|
|
|
162
77
|
# {"ok":true,"sessionId":"wrun_A","deliveryId":"delivery_A"}
|
|
163
78
|
```
|
|
164
79
|
|
|
165
|
-
|
|
166
|
-
create-once semantics. Once the operation owner is active, the same operation under the same
|
|
167
|
-
authenticated principal returns that session instead of dispatching the input again. The create
|
|
168
|
-
route does not wait for a concurrently starting request to publish ownership: simultaneous
|
|
169
|
-
requests can receive different accepted candidate IDs, while only the candidate that claims the
|
|
170
|
-
operation runs its first turn. Retry the operation after startup when you need its canonical
|
|
171
|
-
session ID. Anonymous callers cannot use `operationId`, and operation ownership expires when the
|
|
172
|
-
session is no longer resumable.
|
|
80
|
+
An authenticated caller that may retry a create request can pass an `operationId` so the session is created once. Once that session is active, the same `operationId` from the same caller returns it without sending the input again. Simultaneous requests can receive different session IDs, but only one runs the first turn. Retry after startup to get the final session ID. Anonymous callers can't use `operationId`. An `operationId` is free again once its session can no longer resume.
|
|
173
81
|
|
|
174
82
|
```bash
|
|
175
83
|
curl -X POST https://<deployment>/eve/v1/session \
|
|
@@ -179,8 +87,7 @@ curl -X POST https://<deployment>/eve/v1/session \
|
|
|
179
87
|
# {"ok":true,"sessionId":"wrun_A","deliveryId":"delivery_A"}
|
|
180
88
|
```
|
|
181
89
|
|
|
182
|
-
|
|
183
|
-
`message` or `answers`; use the latter to answer a pending HITL request:
|
|
90
|
+
A follow-up request accepts exactly one of `message` or `answers`. Use `answers` to answer a pending approval or question:
|
|
184
91
|
|
|
185
92
|
```bash
|
|
186
93
|
curl -X POST https://<deployment>/eve/v1/session/wrun_A \
|
|
@@ -188,15 +95,13 @@ curl -X POST https://<deployment>/eve/v1/session/wrun_A \
|
|
|
188
95
|
-d '{"answers":[{"interactionId":"req_A","optionId":"approve"}]}'
|
|
189
96
|
```
|
|
190
97
|
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
Set `turnPolicy: "queue"` on `eveChannel(...)` when follow-ups should wait for active turns to finish. `answers` answer their addressed requests.
|
|
98
|
+
A follow-up message joins the running turn by default; see [Overlapping messages](./overview#overlapping-messages). Set `turnPolicy: "queue"` on `eveChannel(...)` to make follow-ups wait for running turns to finish. `answers` only answer the requests they name.
|
|
194
99
|
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
that built it
|
|
100
|
+
| Session state | Response |
|
|
101
|
+
| ------------------------------------- | ------------------------------------------------------------------------------------------------ |
|
|
102
|
+
| Unknown or terminal | `409` with `{"code":"session_not_active","error":"The session is no longer active.","ok":false}` |
|
|
103
|
+
| Workflow exists but inbox isn't ready | `409 session_not_ready` |
|
|
104
|
+
| Built by another eve version | `409 session_stranded` with the `eveVersion` that built it |
|
|
200
105
|
|
|
201
106
|
### Send files
|
|
202
107
|
|
|
@@ -208,11 +113,9 @@ curl -X POST https://<deployment>/eve/v1/session/wrun_A \
|
|
|
208
113
|
-d '{"message":[{"type":"text","text":"Summarize this report."},{"type":"file","mediaType":"application/pdf","filename":"report.pdf","data":"data:application/pdf;base64,JVBERi0xLjQK..."}]}'
|
|
209
114
|
```
|
|
210
115
|
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
`uploadPolicy` sets the size cap and allowed media types, 25 MB and every type by default. A request whose inline file breaks the policy returns `413` for size or `415` for type. Inline bytes also count toward the request body limit of the platform that serves the channel. On Vercel Functions that limit is 4.5 MB, so a base64 file stops at about 3.3 MB.
|
|
116
|
+
`uploadPolicy` sets the size cap and allowed media types; omit it for 25 MB and every type. An inline file that breaks the policy returns `413` for size or `415` for type. Inline bytes also count toward the hosting platform's request body limit: 4.5 MB on Vercel Functions, so about 3.3 MB of file before base64.
|
|
214
117
|
|
|
215
|
-
For larger files, upload
|
|
118
|
+
For larger files, upload from the browser to your own storage and send the URL in the file part. Add `fetchFile` to load your URLs after eve accepts the message, so the bytes never pass through the request:
|
|
216
119
|
|
|
217
120
|
```ts title="agent/channels/eve.ts"
|
|
218
121
|
import { eveChannel } from "eve/channels/eve";
|
|
@@ -232,62 +135,105 @@ export default eveChannel({
|
|
|
232
135
|
});
|
|
233
136
|
```
|
|
234
137
|
|
|
235
|
-
`fetchFile` follows the [custom channel contract](./custom#file-uploads): return bytes to
|
|
138
|
+
`fetchFile` follows the [custom channel contract](./custom#file-uploads): return bytes to save the file to the sandbox, or `null` for a URL that isn't yours. eve downloads a public `https:` URL itself and passes any other URL to the model as a note. `uploadPolicy` also checks fetched and downloaded files by their actual bytes and detected media type. A violating file reaches the model as a note instead of failing the request. See [Inbound attachments](../sandbox#inbound-attachments) for how eve stores files and shows them to the model.
|
|
236
139
|
|
|
237
140
|
### Stream events
|
|
238
141
|
|
|
239
142
|
Stream a session as newline-delimited JSON from `GET /eve/v1/session/:sessionId/stream`. The [session protocol](../concepts/sessions-runs-and-streaming#stream-a-session) defines the event set, envelopes, cursors, and reconnection behavior.
|
|
240
143
|
|
|
241
|
-
Following a stranded session's stream returns `409 session_stranded`,
|
|
144
|
+
Following a stranded session's stream returns `409 session_stranded`, and the TypeScript client reports `ClientSessionStrandedError` without retrying. Pass `follow=false` to read the recorded history instead. The response ends at the last recorded event and carries the `x-eve-stream-tail-index` header. It doesn't change the session, so it works before you end the session.
|
|
242
145
|
|
|
243
|
-
|
|
146
|
+
Ending a stranded session tries to append these events, then closes the stream so existing readers finish:
|
|
244
147
|
|
|
245
|
-
|
|
148
|
+
1. `delivery.admitted` with `source: { control: "reset" }`, then `delivery.settled`, for the end request.
|
|
149
|
+
2. `session.ended` with `outcome: "failed"`, error code `session_stranded`, and cause `{ deliveryId }`.
|
|
246
150
|
|
|
247
|
-
|
|
151
|
+
A session started by an eve version before v27 stores v26 events, and the stream route serves them as v27 lines. Translation covers messages, reasoning, tool calls and results, approvals, questions, sign-ins, subagents, clears, and compactions.
|
|
152
|
+
|
|
153
|
+
- Streamed text previews aren't translated, so a running v26 session shows each part once it completes.
|
|
154
|
+
- Cursors count stored lines. A stored event with nothing to translate, such as a streamed delta, arrives as a `position` marker.
|
|
155
|
+
- When no running deployment can add to the stream, a follow ends at the last event with `stream.ended`, so clients stop reconnecting.
|
|
156
|
+
|
|
157
|
+
The World keeps an ended session's stream only for its retention period. After that, reading it returns `410 session_expired`, and the TypeScript client fails with a `ClientError` whose `code` is `"session_expired"`, without retrying.
|
|
248
158
|
|
|
249
159
|
### Cancel a turn
|
|
250
160
|
|
|
251
|
-
Post to `/eve/v1/session/:sessionId/cancel` to
|
|
161
|
+
Post to `/eve/v1/session/:sessionId/cancel` to cancel the active turn. Include the observed `turnId` so a late request can't cancel a newer turn. Cancellation is asynchronous; confirm it on the stream as `turn.settled` with `outcome: "cancelled"`.
|
|
252
162
|
|
|
253
|
-
See [Cancel the in-flight turn](../concepts/sessions-runs-and-streaming#cancel-the-in-flight-turn) for
|
|
163
|
+
See [Cancel the in-flight turn](../concepts/sessions-runs-and-streaming#cancel-the-in-flight-turn) for receipts, HTTP status codes, subagent cancellation, and race behavior.
|
|
254
164
|
|
|
255
165
|
### Clear context
|
|
256
166
|
|
|
257
|
-
Post to `/eve/v1/session/:sessionId/clear` to remove model-message history
|
|
167
|
+
Post to `/eve/v1/session/:sessionId/clear` to cancel a running turn and every working task, then remove model-message history. The session ID, system prompt, tools, skills, state, limits, and sandbox stay. On a stranded session, clear returns `409 session_stranded` and changes nothing; use `end` instead. See [Compact, clear, and end](../concepts/sessions-runs-and-streaming#compact-clear-and-end).
|
|
258
168
|
|
|
259
169
|
### Compact context
|
|
260
170
|
|
|
261
|
-
Post to `/eve/v1/session/:sessionId/compact` to summarize context without sending a user message. The operation waits for
|
|
171
|
+
Post to `/eve/v1/session/:sessionId/compact` to summarize context without sending a user message. The operation waits for a running turn to finish and reports its result on the stream. See [Compact, clear, and end](../concepts/sessions-runs-and-streaming#compact-clear-and-end).
|
|
262
172
|
|
|
263
173
|
<a id="reset-a-session" />
|
|
264
174
|
|
|
265
175
|
### End a session
|
|
266
176
|
|
|
267
|
-
Post to `/eve/v1/session/:sessionId/end` to
|
|
177
|
+
Post to `/eve/v1/session/:sessionId/end` to end that session for good. Ending doesn't create a replacement; create a new session for a fresh conversation. On a stranded session, eve cancels the workflow run directly. See [Compact, clear, and end](../concepts/sessions-runs-and-streaming#compact-clear-and-end).
|
|
268
178
|
|
|
269
|
-
##
|
|
179
|
+
## Authentication
|
|
270
180
|
|
|
271
|
-
|
|
181
|
+
The `auth` option decides who can call `/eve/v1/info` and the session routes. The built-in helpers cover development and trusted infrastructure:
|
|
272
182
|
|
|
273
|
-
|
|
183
|
+
- `localDev()` accepts requests during local development.
|
|
184
|
+
- `vercelOidc()` lets the local CLI and your team's other deployments call a deployed agent.
|
|
274
185
|
|
|
275
|
-
|
|
276
|
-
import { disableRoute } from "eve/channels";
|
|
186
|
+
Neither admits browser users or external clients in production. For a public app, wire the channel to your own auth: Clerk, Auth.js, OIDC/JWT verification, an API-key verifier, or any custom `AuthFn`. Use Vercel OIDC only when Vercel-issued deployment tokens are part of your trust model.
|
|
277
187
|
|
|
278
|
-
|
|
188
|
+
`eve init` scaffolds `agent/channels/eve.ts` with `vercelOidc()`, `localDev()`, and `placeholderAuth()`, which returns a setup-focused 401 in production until you replace it with real auth. Without the file, eve uses the same `[vercelOidc(), localDev(), placeholderAuth()]` policy, which rejects production requests without a valid Vercel OIDC token.
|
|
189
|
+
|
|
190
|
+
`/eve/v1/info` also requires an operator caller. To let your own operator credential read it, return `principalType: "service"` from its `AuthFn`, as `jwtHmac()` and `jwtEcdsa()` do, or return `allowAgentInfo: true` from an `EveAuthFn`. See [Agent info access](../guides/auth-and-route-protection#agent-info-access). Keep end-user strategies returning `"user"` without the grant, so end users can't read it.
|
|
191
|
+
|
|
192
|
+
For the full auth model and helper list, see [Auth & route protection](../guides/auth-and-route-protection).
|
|
193
|
+
|
|
194
|
+
## Web Chat with Sign in with Vercel
|
|
195
|
+
|
|
196
|
+
To let your team sign in to a browser chat, run `eve add channel/web` or select **Web Chat** from the terminal UI's channel picker. Then choose **Next.js**, a hosting layout, and **Sign in with Vercel**. Sign in with Vercel is available only for the Next.js Web Chat app. Setup creates a Vercel App on the linked project that only members of the project's team can sign in to.
|
|
197
|
+
|
|
198
|
+
For a new agent, initialize it first, then link a project and add Web Chat:
|
|
199
|
+
|
|
200
|
+
```bash
|
|
201
|
+
eve init my-agent --non-interactive
|
|
202
|
+
cd my-agent
|
|
203
|
+
eve link
|
|
204
|
+
eve add channel/web
|
|
279
205
|
```
|
|
280
206
|
|
|
281
|
-
|
|
207
|
+
`eve init --channel-web-nextjs` scaffolds the app without authentication; sign-in setup runs only through `eve add channel/web` or the channel picker.
|
|
282
208
|
|
|
283
|
-
|
|
209
|
+
The generated Next.js app signs users in with Better Auth. The agent's eve channel accepts the same sign-in, and still accepts Vercel OIDC and local development requests. In an agent workspace, setup configures only the selected agent.
|
|
284
210
|
|
|
285
|
-
The
|
|
286
|
-
permissive browser CORS with preflight handling, or pass an options object to
|
|
287
|
-
narrow origins, methods, and headers. Route auth still runs on the actual
|
|
288
|
-
session requests.
|
|
211
|
+
Setup registers `/api/auth/callback/vercel` as a project redirect URI, so Vercel validates callbacks against the project's deployment domains. The app uses the `authorization_code` grant, `client_secret_post` authentication, and the `openid`, `email`, and `profile` scopes. Setup writes `VERCEL_APP_CLIENT_ID`, `VERCEL_APP_CLIENT_SECRET`, and `BETTER_AUTH_SECRET` to production and preview as sensitive values, and never prints them or writes them to source. Run `eve deploy` after setup to publish the app. Local development runs without browser sign-in.
|
|
289
212
|
|
|
290
|
-
|
|
213
|
+
For automation, supply the setup answers explicitly:
|
|
214
|
+
|
|
215
|
+
```bash
|
|
216
|
+
eve add channel/web --non-interactive \
|
|
217
|
+
--answer 'web-hosting="vercel"' \
|
|
218
|
+
--answer 'web-authentication="vercel"'
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
Setup needs a linked project and permission to manage Vercel Apps and project environment variables. If your role can't create apps, a team owner can complete setup. The team picker lists eligible teams first and disables teams marked `needs permission` or `couldn't verify` until you sign in or retry.
|
|
222
|
+
|
|
223
|
+
Setup reuses compatible existing apps and credentials, and stops with an error on conflicting app settings or credentials. It preserves authored channel and UI files unless you pass `--overwrite`.
|
|
224
|
+
|
|
225
|
+
| What you see | What to do |
|
|
226
|
+
| ----------------------------------------------- | ------------------------------------------------------------------------------- |
|
|
227
|
+
| Setup reports a missing prerequisite | Complete it, then resume with `eve add channel/web --skip-install`. |
|
|
228
|
+
| The team has reached its Vercel App limit | Remove an unused app in team settings and retry. |
|
|
229
|
+
| The generated app name or slug is already taken | Rename the Vercel project in its settings and retry. |
|
|
230
|
+
| The app has reached its client-secret limit | Remove an unused secret in the app's settings; setup never removes one for you. |
|
|
231
|
+
|
|
232
|
+
Choose **Configure authentication myself** (`web-authentication=custom`) to keep the current channel policy. The default placeholder rejects production browser requests until you configure your own authentication.
|
|
233
|
+
|
|
234
|
+
## CORS
|
|
235
|
+
|
|
236
|
+
The eve channel sends no CORS headers by default. When browser clients call the channel directly, pass `cors: true` for permissive CORS with preflight handling, or an options object to narrow origins, methods, and headers. Route auth still runs on the session requests.
|
|
291
237
|
|
|
292
238
|
```ts title="agent/channels/eve.ts"
|
|
293
239
|
import { eveChannel } from "eve/channels/eve";
|
|
@@ -303,34 +249,17 @@ export default eveChannel({
|
|
|
303
249
|
});
|
|
304
250
|
```
|
|
305
251
|
|
|
306
|
-
## Authentication
|
|
307
|
-
|
|
308
|
-
The `auth` option decides who can call `/eve/v1/info` and the session routes. The built-in helpers cover development and trusted infrastructure:
|
|
309
|
-
|
|
310
|
-
- `localDev()` accepts requests during local development.
|
|
311
|
-
- `vercelOidc()` lets the local CLI reach a deployed agent, and lets other internal deployments from your team call it.
|
|
312
|
-
|
|
313
|
-
Neither admits browser users or external clients in production. For a public app, wire the channel to your own auth (Clerk, Auth.js, your own OIDC/JWT verification, an API-key verifier, or any custom `AuthFn`). Vercel OIDC is optional; use it only when Vercel-issued deployment tokens are part of your trust model.
|
|
314
|
-
|
|
315
|
-
`eve init` scaffolds an `agent/channels/eve.ts` with a production placeholder so you replace it before going live. The generated channel checks Vercel OIDC before falling back to localhost access, and includes `placeholderAuth()`, which returns a setup-focused 401 in production until you swap it for real auth. Delete the file and eve selects its default channel source with `[vercelOidc(), localDev(), placeholderAuth()]`, which rejects all production traffic.
|
|
316
|
-
|
|
317
|
-
For the full auth model and helper list, see [Auth & route protection](../guides/auth-and-route-protection).
|
|
318
|
-
|
|
319
252
|
## Audience
|
|
320
253
|
|
|
321
|
-
The eve channel
|
|
322
|
-
audience controls whether instrumentation may capture session content:
|
|
323
|
-
|
|
324
|
-
| Session creator | Default audience |
|
|
325
|
-
| ----------------------------------------- | ---------------- |
|
|
326
|
-
| Anonymous caller | `unknown` |
|
|
327
|
-
| `user`, `service`, or `runtime` principal | `private` |
|
|
328
|
-
| Any other principal type | `unknown` |
|
|
254
|
+
The eve channel sets each new session's audience from its caller. The audience controls whether traces may capture session content, not who may call the endpoint:
|
|
329
255
|
|
|
330
|
-
|
|
256
|
+
| Session creator | Default audience |
|
|
257
|
+
| -------------------------------------- | ---------------- |
|
|
258
|
+
| Anonymous caller | `unknown` |
|
|
259
|
+
| `user`, `service`, or `runtime` caller | `private` |
|
|
260
|
+
| Any other caller type | `unknown` |
|
|
331
261
|
|
|
332
|
-
For
|
|
333
|
-
set a constant audience:
|
|
262
|
+
`user`, `service`, and `runtime` sessions are `private` because they belong to one identified party. For `unknown` sessions, traces record metadata but leave out content by default in preview and production. Set a constant `audience: "public"` only when every conversation on the endpoint is intentionally public:
|
|
334
263
|
|
|
335
264
|
```ts title="agent/channels/eve.ts"
|
|
336
265
|
import { vercelOidc } from "eve/channels/auth";
|
|
@@ -342,22 +271,11 @@ export default eveChannel({
|
|
|
342
271
|
});
|
|
343
272
|
```
|
|
344
273
|
|
|
345
|
-
|
|
346
|
-
Outside development, private and unknown-audience sessions request deletion when
|
|
347
|
-
they end. The Workflow World must support deletion to enforce it.
|
|
274
|
+
`audience` also accepts a function that receives `caller`, channel, and deployment environment. The audience is fixed when the session is created, so a later turn from a different caller doesn't change it. For an audience that depends on channel state or verified application data, use a [custom channel audience](./custom#conversation-audience).
|
|
348
275
|
|
|
349
|
-
|
|
350
|
-
call the endpoint. `auth` still controls access. For a classification that
|
|
351
|
-
depends on channel state or application-specific verified data, use a [custom
|
|
352
|
-
channel audience](./custom#conversation-audience).
|
|
276
|
+
Audience also selects the default [run-data retention](../agent-config#run-data-retention). Outside development, private and unknown-audience sessions request deletion when they end, if the Workflow world supports deletion.
|
|
353
277
|
|
|
354
|
-
|
|
355
|
-
environment. Classification is fixed at session creation, so a later
|
|
356
|
-
turn from a different caller does not reclassify the session.
|
|
357
|
-
|
|
358
|
-
For a remote agent, a trusted dispatch can forward the original audience and
|
|
359
|
-
its trace-content ceiling. See [Preserving trace
|
|
360
|
-
content](../guides/remote-agents#preserving-trace-content).
|
|
278
|
+
For a remote agent, a trusted caller can forward the original audience and its trace-content ceiling. See [Preserving trace content](../guides/remote-agents#preserving-trace-content).
|
|
361
279
|
|
|
362
280
|
## Customization
|
|
363
281
|
|
|
@@ -387,13 +305,13 @@ export default eveChannel({
|
|
|
387
305
|
});
|
|
388
306
|
```
|
|
389
307
|
|
|
390
|
-
`onMessage` must return an auth result. Return `title` alongside `auth` to set the title when the
|
|
308
|
+
`onMessage` must return an auth result, so every accepted message starts or continues a session. Return `title` alongside `auth` to set the session title. It applies when the message creates the session, or is the first message to one created without a message.
|
|
391
309
|
|
|
392
310
|
### Turn context
|
|
393
311
|
|
|
394
|
-
`context` strings
|
|
312
|
+
`context` strings are saved as user messages in session history. For context that applies to one turn only, return `clientContext`. It replaces the request's [`clientContext`](../guides/client/messages) for every model call in the turn and isn't kept in session history.
|
|
395
313
|
|
|
396
|
-
`ctx.eve.clientContext` holds the request's `clientContext`
|
|
314
|
+
`ctx.eve.clientContext` holds the request's `clientContext` as sent, or `undefined`. Use it to check or correct client-supplied state before the model sees it:
|
|
397
315
|
|
|
398
316
|
```ts title="agent/channels/eve.ts"
|
|
399
317
|
import { eveChannel, defaultEveAuth } from "eve/channels/eve";
|
|
@@ -412,15 +330,15 @@ export default eveChannel({
|
|
|
412
330
|
```
|
|
413
331
|
|
|
414
332
|
- Omit `clientContext` to keep the request's context. Return `[]` to drop it.
|
|
415
|
-
- The returned value
|
|
333
|
+
- The returned value has the request's `ClientContextValue` shape, exported from `eve/channels/eve`: a string, an array of strings, or a JSON object.
|
|
416
334
|
- eve labels client-supplied entries `Client context:` for the model. Returned context is sent without the label.
|
|
417
|
-
- `onMessage` runs only for requests with a message. An
|
|
335
|
+
- `onMessage` runs only for requests with a message. An answer keeps the context its request sent.
|
|
418
336
|
|
|
419
337
|
### Start from prior history
|
|
420
338
|
|
|
421
|
-
Pass `history` to bring in conversation eve
|
|
339
|
+
Pass `history` to bring in conversation eve didn't produce, such as a stored transcript or a branch of an earlier exchange. The model sees each entry as a real user or assistant turn.
|
|
422
340
|
|
|
423
|
-
|
|
341
|
+
Call `create()` on a channel address to create a session from stored history. No turn runs until a message arrives:
|
|
424
342
|
|
|
425
343
|
```ts title="agent/channels/app.ts"
|
|
426
344
|
import { defineChannel, POST } from "eve/channels";
|
|
@@ -448,25 +366,39 @@ export default defineChannel({
|
|
|
448
366
|
});
|
|
449
367
|
```
|
|
450
368
|
|
|
451
|
-
The client then resumes
|
|
452
|
-
|
|
453
|
-
When the session at the address is [stranded](../guides/deployment/self-hosting#recover-a-stranded-session), `create()` throws `SessionStrandedError` instead of replacing it, because that session may hold the conversation you meant to import. Call `end()` on the address, then `create()` again.
|
|
369
|
+
The client then resumes the session by id, for example with `useEveAgent({ initialSession: { sessionId, streamIndex: 0 }, resume: true })`. `created` is `false` when another session already owned the address or another `create()` or `send()` claimed it first. That session comes back unchanged, without your `history`. Use a new address for each new conversation or branch.
|
|
454
370
|
|
|
455
|
-
`create()` returns once the new session claims its address, so
|
|
371
|
+
`create()` returns once the new session claims its address, so an immediate `send()` reaches it. It throws if no session claims the address within 15 seconds. On a [stranded](../guides/deployment/self-hosted-operations#recover-a-stranded-session) session, `create()` throws `SessionStrandedError` instead of replacing a conversation you may mean to import; call `end()` on the address, then `create()` again.
|
|
456
372
|
|
|
457
|
-
`send()` accepts the same `history` option
|
|
373
|
+
`send()` accepts the same `history` option and adds the entries right before that message and its `context`, whether it creates or continues the session. The eve channel's `onMessage` can return `history` too, which applies to every message it's returned for.
|
|
458
374
|
|
|
459
|
-
Each entry has a `role` of `"user"` or `"assistant"`, non-empty `text`, and an optional `id`
|
|
375
|
+
Each entry has a `role` of `"user"` or `"assistant"`, non-empty `text`, and an optional `id` unique within the call. eve rejects an entry with any other field, so map your stored messages to these fields. Invalid history throws an `InvalidSessionHistoryError`, exported from `eve/channels`, naming the entry and the broken rule. eve doesn't cap entries or text, so trim long conversations in your route. Tool calls, files, and reasoning are not supported.
|
|
460
376
|
|
|
461
377
|
eve never accepts `history` from a client request body. Resolve it on the server and authorize the caller against the stored conversation.
|
|
462
378
|
|
|
463
|
-
The stream records the entries on the `delivery.consumed` of the message that brought them
|
|
379
|
+
The stream records the entries in `data.history` on the `delivery.consumed` of the message that brought them. History from `create()` is recorded with the first accepted message. When one turn takes in several messages, the model reads all their history first. `transcriptOf()` from `eve/client` returns entries in that order as `{ role, text }` messages you can pass back as `history` to branch a session.
|
|
380
|
+
|
|
381
|
+
Frontend `messages` show imported entries before their message, with `metadata.imported` set and your `id` in `metadata.historyId`. Imported messages have no `metadata.turnId`, so a turn's reply never streams into one. Their message ids stay unique even when a later call reuses an `id`. Compaction, `clear()`, and handoffs treat them like any other history.
|
|
382
|
+
|
|
383
|
+
## Replace or disable the defaults
|
|
384
|
+
|
|
385
|
+
An authored `agent/channels/eve.ts` replaces the whole default eve channel. An `eveChannel(...)` replacement keeps the standard routes with your options. A `defineChannel(...)` replacement serves only the routes you declare, without the health, info, or callback routes.
|
|
386
|
+
|
|
387
|
+
Export `disableRoute()` to remove every `/eve/v1` route:
|
|
388
|
+
|
|
389
|
+
```ts title="agent/channels/eve.ts"
|
|
390
|
+
import { disableRoute } from "eve/channels";
|
|
391
|
+
|
|
392
|
+
export default disableRoute();
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
The default home page at `GET /` and `HEAD /` is a separate `home` channel. Author `agent/channels/home.ts` to replace it, or export `disableRoute()` there to remove it without affecting `/eve/v1`.
|
|
464
396
|
|
|
465
397
|
## Clients
|
|
466
398
|
|
|
467
399
|
The browser side of this API lives in the [Frontend](../guides/frontend/overview) docs, where `useEveAgent` drives the eve channel from React UI.
|
|
468
400
|
|
|
469
|
-
For scripts, server-to-server calls, evals, tests, and custom clients, use the [Client SDK](../guides/client/overview)
|
|
401
|
+
For scripts, server-to-server calls, evals, tests, and custom clients, use the [Client SDK](../guides/client/overview), which wraps the session routes, stream cursor, and reconnect loop.
|
|
470
402
|
|
|
471
403
|
## What to read next
|
|
472
404
|
|