eve 0.90.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 +34 -23
- package/dist/src/channel/auth/http-basic.js +1 -1
- package/dist/src/channel/channel-operations.d.ts +1 -1
- package/dist/src/channel/types.d.ts +2 -0
- package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
- package/dist/src/client/session.d.ts +1 -1
- package/dist/src/compiled/.vendor-stamp.json +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/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/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/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/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/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/value-delta.d.ts +5 -4
- package/dist/src/shared/value-delta.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/docs/agent-config.md +199 -222
- package/docs/channels/chat-sdk.mdx +60 -64
- package/docs/channels/custom.mdx +264 -281
- package/docs/channels/discord.mdx +176 -123
- package/docs/channels/eve.mdx +136 -206
- 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 -198
- 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 +175 -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 +16 -19
- 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 +87 -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 +45 -43
- 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/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
|
@@ -3,7 +3,7 @@ title: "Messages"
|
|
|
3
3
|
description: "Send text, full turn payloads, client context, attachments, and HITL responses with eve/client."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
Create a session with its first turn, then
|
|
6
|
+
A message is one turn of input to a session. Create a session with its first turn, then send follow-ups through the returned `ClientSession`, which targets that one session ID.
|
|
7
7
|
|
|
8
8
|
## Send text
|
|
9
9
|
|
|
@@ -24,42 +24,41 @@ const result = await delivery.result();
|
|
|
24
24
|
console.log(result.status, result.reply);
|
|
25
25
|
```
|
|
26
26
|
|
|
27
|
-
`delivery.result()` reads
|
|
27
|
+
`delivery.result()` reads until the request finishes or pauses for input, then returns a `DeliveryResult`.
|
|
28
28
|
Import `Delivery`, `DeliveryReadOptions`, and `DeliveryResult` from `eve/sessions`:
|
|
29
29
|
|
|
30
|
-
| Field | Meaning
|
|
31
|
-
| -------------- |
|
|
32
|
-
| `reply` | The request's reply text, from the parts `turn.settled.reply` lists.
|
|
33
|
-
| `status` | `awaiting-input`, `completed`, `failed`, or `cancelled` for this
|
|
34
|
-
| `sessionEnded` | Whether the session ended
|
|
35
|
-
| `deliveryId` | The accepted
|
|
36
|
-
| `outcome` |
|
|
37
|
-
| `error` | Required `ErrorInfo` when `status` is `failed`.
|
|
38
|
-
| `interactions` |
|
|
39
|
-
| `sessionId` | Session ID for streaming and inspection.
|
|
40
|
-
| `data` | Structured output when the turn requested an [output schema](./output-schema).
|
|
41
|
-
|
|
42
|
-
A
|
|
43
|
-
`error.message` to recover. HTTP failures and reads interrupted before
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
`
|
|
54
|
-
[
|
|
55
|
-
|
|
56
|
-
`
|
|
57
|
-
`session.
|
|
58
|
-
|
|
59
|
-
stream
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
`session.stream({ follow: false })` and `session.snapshot()` still read the recorded history.
|
|
30
|
+
| Field | Meaning |
|
|
31
|
+
| -------------- | -------------------------------------------------------------------------------------------------------- |
|
|
32
|
+
| `reply` | The request's reply text, from the parts `turn.settled.reply` lists. |
|
|
33
|
+
| `status` | `awaiting-input`, `completed`, `failed`, or `cancelled` for this request. |
|
|
34
|
+
| `sessionEnded` | Whether the session ended when this request finished. |
|
|
35
|
+
| `deliveryId` | The ID of the accepted message or control. |
|
|
36
|
+
| `outcome` | What happened to the request: `handled`, `awaiting-input`, `applied`, `ignored`, `refused`, or `failed`. |
|
|
37
|
+
| `error` | Required `ErrorInfo` when `status` is `failed`. |
|
|
38
|
+
| `interactions` | Approvals, questions, and sign-ins still waiting for a person, safe to display. |
|
|
39
|
+
| `sessionId` | Session ID for streaming and inspection. |
|
|
40
|
+
| `data` | Structured output when the turn requested an [output schema](./output-schema). |
|
|
41
|
+
|
|
42
|
+
A failed request returns `status: "failed"` with `error`; inspect `error.code` and
|
|
43
|
+
`error.message` to recover. HTTP failures and reads interrupted before the request finishes throw instead.
|
|
44
|
+
An `awaiting-input` result is complete. Answering the prompt sends a new request with its own result.
|
|
45
|
+
Results don't include an event log; capture `delivery.stream()` when you need one.
|
|
46
|
+
|
|
47
|
+
`session.send()` retries `409 session_not_ready` with backoff for up to 20 seconds while the
|
|
48
|
+
session starts. The caller's abort signal cancels the wait. Other errors, `session.respond()`,
|
|
49
|
+
control methods, and raw HTTP requests are not retried.
|
|
50
|
+
|
|
51
|
+
| Error | When |
|
|
52
|
+
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
|
53
|
+
| `SessionNotActiveError` | Unknown or terminal session, thrown immediately (`retryable: false`), or the `session_not_ready` retry expired (`retryable: true`). |
|
|
54
|
+
| `ClientSessionStrandedError` | [Stranded](../../concepts/execution-model-and-durability#stranded-sessions) session. |
|
|
55
|
+
|
|
56
|
+
`ClientSessionStrandedError` is a `ClientError` with `code: "session_stranded"` and, when recorded,
|
|
57
|
+
the `eveVersion` that built the session. It is never retried, and the client never creates a
|
|
58
|
+
replacement: call `session.end()` and create a new session. Following the stranded session's
|
|
59
|
+
stream, `send()`, and `session.clear()` throw the same error, and a message accepted before the
|
|
60
|
+
session stranded is not redelivered. `session.stream({ follow: false })` and `session.snapshot()`
|
|
61
|
+
still read the recorded history.
|
|
63
62
|
|
|
64
63
|
The typed errors `eve/client` throws (`ClientError` and its subclasses, `SessionNotActiveError`,
|
|
65
64
|
`HealthResponseError`, and `AgentInfoResponseError`) extend `EveError` and have a stable snake_case
|
|
@@ -101,27 +100,11 @@ const { session, delivery } = await client.sessions.create({
|
|
|
101
100
|
await delivery.result();
|
|
102
101
|
```
|
|
103
102
|
|
|
104
|
-
`clientContext` is ephemeral context for the current turn.
|
|
103
|
+
`clientContext` is ephemeral context for the current turn. A string becomes a user-role context message, an array of strings becomes several, and an object is JSON-serialized into one. Every model call in the turn sees it. It isn't saved to session history and doesn't start a turn by itself.
|
|
105
104
|
|
|
106
105
|
## Send attachments
|
|
107
106
|
|
|
108
|
-
`send()` accepts `MessageContent`, so a message can mix text and file parts. A file part's `data` is the file inline (bytes, base64, or a `data:` URL) or a URL:
|
|
109
|
-
|
|
110
|
-
```ts
|
|
111
|
-
const response = await session.send([
|
|
112
|
-
{ type: "text", text: "Summarize this report." },
|
|
113
|
-
{
|
|
114
|
-
type: "file",
|
|
115
|
-
data: reportDataUrl,
|
|
116
|
-
mediaType: "application/pdf",
|
|
117
|
-
filename: "report.pdf",
|
|
118
|
-
},
|
|
119
|
-
]);
|
|
120
|
-
|
|
121
|
-
await response.result();
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
For local files, read the file and send a base64 `data:` URL:
|
|
107
|
+
`send()` accepts `MessageContent`, so a message can mix text and file parts. A file part's `data` is the file inline (bytes, base64, or a `data:` URL) or a URL. For a local file, send a base64 `data:` URL:
|
|
125
108
|
|
|
126
109
|
```ts
|
|
127
110
|
import { readFile } from "node:fs/promises";
|
|
@@ -142,10 +125,9 @@ const response = await session.send([
|
|
|
142
125
|
await response.result();
|
|
143
126
|
```
|
|
144
127
|
|
|
145
|
-
The stream confirms the turn with `delivery.consumed
|
|
146
|
-
|
|
147
|
-
attachments](../../sandbox#inbound-attachments) for how eve stages
|
|
148
|
-
sandbox and prepares them for each model call.
|
|
128
|
+
The stream confirms the turn with `delivery.consumed`, whose `data.parts` holds text and file
|
|
129
|
+
metadata for rendering attachments, never raw bytes or sandbox paths. See [Inbound
|
|
130
|
+
attachments](../../sandbox#inbound-attachments) for how eve stages files in the session sandbox.
|
|
149
131
|
|
|
150
132
|
## Answer human input requests
|
|
151
133
|
|
|
@@ -165,9 +147,9 @@ const resumed = await session.respond(
|
|
|
165
147
|
await resumed.result();
|
|
166
148
|
```
|
|
167
149
|
|
|
168
|
-
The
|
|
150
|
+
The stream records a `response.submitted` event for each answer. Each request then ends with an `interaction.settled` event that carries its `interactionId`, final `outcome`, and the `response` that decided it. Save `interaction.settled`, not the client's optimistic state, when you rebuild message history.
|
|
169
151
|
|
|
170
|
-
|
|
152
|
+
Pass `clientContext`, `outputSchema`, headers, or stream options in the second argument to `send(message, options)` or `respond(answers, options)`.
|
|
171
153
|
|
|
172
154
|
## Reusable delivery reads
|
|
173
155
|
|
|
@@ -180,14 +162,13 @@ for await (const event of response.stream()) {
|
|
|
180
162
|
const result = await response.result();
|
|
181
163
|
```
|
|
182
164
|
|
|
183
|
-
Each read
|
|
184
|
-
|
|
185
|
-
interval again can open another HTTP stream. A completed summary may be cached.
|
|
165
|
+
Each read covers the request from when the server accepts it until it finishes, independently of other readers.
|
|
166
|
+
Repeated and concurrent reads are supported, and each may open another HTTP stream.
|
|
186
167
|
|
|
187
|
-
Pass `{ signal }` to `stream()` or `result()` to abort that read. An aborted or failed read
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
168
|
+
Pass `{ signal }` to `stream()` or `result()` to abort that read. An aborted or failed read doesn't
|
|
169
|
+
consume the handle or cancel the work, so retry the same delivery instead of sending again. Use
|
|
170
|
+
`session.cancel()` to cancel work. A signal passed to `send()` covers only submission, so pass it
|
|
171
|
+
to the read too when a timeout must cover both.
|
|
191
172
|
|
|
192
173
|
## What to read next
|
|
193
174
|
|
|
@@ -3,11 +3,11 @@ title: "Output Schema"
|
|
|
3
3
|
description: "Request structured results from eve client turns and read typed data from DeliveryResult."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
`outputSchema` requests structured data from a client turn instead of only assistant text. The model must satisfy the schema before the turn ends, and the payload arrives as a `content.completed` part with `kind: "result"`.
|
|
7
7
|
|
|
8
8
|
## JSON Schema
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
Pass a JSON Schema object directly:
|
|
11
11
|
|
|
12
12
|
```ts
|
|
13
13
|
import { Client } from "eve/client";
|
|
@@ -42,7 +42,7 @@ console.log(result.data?.count);
|
|
|
42
42
|
|
|
43
43
|
## Standard Schema
|
|
44
44
|
|
|
45
|
-
The client also accepts Standard Schema implementations such as Zod, Valibot, and ArkType
|
|
45
|
+
The client also accepts Standard Schema implementations such as Zod, Valibot, and ArkType, and converts them to JSON Schema before sending:
|
|
46
46
|
|
|
47
47
|
```ts
|
|
48
48
|
import { z } from "zod";
|
|
@@ -61,11 +61,11 @@ const response = await session.send<Summary>("Summarize this turn.", {
|
|
|
61
61
|
const { data } = await response.result();
|
|
62
62
|
```
|
|
63
63
|
|
|
64
|
-
The server
|
|
64
|
+
The server validates the result. The client types `DeliveryResult.data` from your generic and schema but doesn't revalidate it.
|
|
65
65
|
|
|
66
66
|
## Stream the result event
|
|
67
67
|
|
|
68
|
-
|
|
68
|
+
When you consume events manually, read the `content.completed` part with `kind: "result"`:
|
|
69
69
|
|
|
70
70
|
```ts
|
|
71
71
|
const response = await session.send<Summary>("Summarize this turn.", {
|
|
@@ -80,11 +80,11 @@ for await (const event of response.stream()) {
|
|
|
80
80
|
}
|
|
81
81
|
```
|
|
82
82
|
|
|
83
|
-
If more than one result part appears
|
|
83
|
+
If more than one result part appears, `result()` returns the most recent one as `data`.
|
|
84
84
|
|
|
85
85
|
## Send payloads with output schema
|
|
86
86
|
|
|
87
|
-
Pass `outputSchema` in the second argument to `send()` or `respond()
|
|
87
|
+
Pass `outputSchema` in the second argument to `send()` or `respond()`, alongside headers, signal, or client context:
|
|
88
88
|
|
|
89
89
|
```ts
|
|
90
90
|
const response = await session.send<Summary>("Summarize this PDF.", {
|
|
@@ -107,7 +107,7 @@ const result = await response.result();
|
|
|
107
107
|
|
|
108
108
|
## Per-turn scope
|
|
109
109
|
|
|
110
|
-
Client `outputSchema`
|
|
110
|
+
Client `outputSchema` applies only to the turn that sends it:
|
|
111
111
|
|
|
112
112
|
```ts
|
|
113
113
|
const response = await session.send("Return a structured summary.", { outputSchema });
|
|
@@ -3,9 +3,9 @@ title: "Client SDK"
|
|
|
3
3
|
description: "Call an eve agent from TypeScript with Client, sessions, auth, and health checks."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
The `eve/client` entrypoint is the typed client for eve's default HTTP API.
|
|
6
|
+
The `eve/client` entrypoint is the typed TypeScript client for eve's default HTTP API. It replaces a hand-written POST and NDJSON (newline-delimited JSON) stream loop in scripts, server-to-server integrations, tests, evals, backend jobs, and custom UIs.
|
|
7
7
|
|
|
8
|
-
For browser chat UIs, start with [`useEveAgent`](../frontend/overview). For wire-level details, read [Sessions, runs & streaming](../../concepts/sessions-runs-and-streaming).
|
|
8
|
+
For browser chat UIs, start with [`useEveAgent`](../frontend/overview). For wire-level details, read [Sessions, runs & streaming](../../concepts/sessions-runs-and-streaming).
|
|
9
9
|
|
|
10
10
|
## Create a client
|
|
11
11
|
|
|
@@ -19,35 +19,46 @@ const client = new Client({
|
|
|
19
19
|
});
|
|
20
20
|
```
|
|
21
21
|
|
|
22
|
-
`baseUrl` is the URL where the eve routes are mounted
|
|
22
|
+
`baseUrl` is the URL where the eve routes are mounted, often `""` in a same-origin browser integration. Query parameters on `baseUrl` are sent on every request, including event streams. When names overlap, request-specific parameters such as a stream cursor win.
|
|
23
23
|
|
|
24
24
|
## Check health
|
|
25
25
|
|
|
26
|
-
|
|
26
|
+
`health()` lets a script fail early before creating a session:
|
|
27
27
|
|
|
28
28
|
```ts
|
|
29
29
|
const health = await client.health();
|
|
30
30
|
console.log(health.status, health.workflowId);
|
|
31
31
|
```
|
|
32
32
|
|
|
33
|
-
|
|
33
|
+
A successful response must match `{ ok: true, status: "ready", workflowId: string }`. A non-2xx response throws `ClientError` with the HTTP `status` and response `body`; invalid JSON or a malformed payload throws `HealthResponseError`.
|
|
34
34
|
|
|
35
35
|
## Inspect an agent
|
|
36
36
|
|
|
37
|
-
|
|
37
|
+
`info()` returns the agent's inspection payload. The client accepts only a complete agent-info version 5 response:
|
|
38
38
|
|
|
39
39
|
```ts
|
|
40
40
|
const info = await client.info();
|
|
41
41
|
console.log(info.agent.name, info.agent.model.id);
|
|
42
42
|
```
|
|
43
43
|
|
|
44
|
-
Pass `info({ signal })` to cancel the HTTP request. The signal
|
|
44
|
+
Pass `info({ signal })` to cancel the HTTP request. The signal applies only after custom header and credential callbacks resolve, so it doesn't bound how long those callbacks take.
|
|
45
45
|
|
|
46
|
-
The response
|
|
46
|
+
The response contains:
|
|
47
47
|
|
|
48
|
-
|
|
48
|
+
- static definitions and dynamic resolvers, each with the source that defines it
|
|
49
|
+
- composition diagnostics and memory slots
|
|
50
|
+
- local and remote agents, listed separately
|
|
51
|
+
- the compiled channel route order
|
|
49
52
|
|
|
50
|
-
|
|
53
|
+
The response includes authored instructions, skill and schedule Markdown, and server paths. So the server answers only operator callers, with `principalType` `service`, `runtime`, or `local-dev`, unless the channel's auth grants `allowAgentInfo`. Authenticate the client with an operator credential, such as Vercel OIDC, `jwtHmac()`, `jwtEcdsa()`, or a custom `AuthFn` that returns `principalType: "service"`. Any other caller gets a `ClientError` with `status` `403` and `code` `"info_forbidden"`.
|
|
54
|
+
|
|
55
|
+
The version changes only when the response shape breaks. Within a version, a server can add fields and enum values:
|
|
56
|
+
|
|
57
|
+
- The client ignores fields it doesn't know.
|
|
58
|
+
- An enum-like field with a string the client can't interpret, such as `mode`, `sourceKind`, or a channel `method`, reads as `"unrecognized"`. Handle that value when you switch on these fields.
|
|
59
|
+
- `kind` discriminants are closed. A new variant comes with a version change, and an unknown one throws `AgentInfoResponseError`.
|
|
60
|
+
|
|
61
|
+
A non-success response throws `ClientError`. Invalid JSON, a missing or non-string enum value, a different agent-info version, duplicate identities, inconsistent totals, or mismatched source provenance throws `AgentInfoResponseError`. For a version mismatch, its `issues` say which side to upgrade: eve in the agent, or the eve package the client runs from.
|
|
51
62
|
|
|
52
63
|
## Authentication
|
|
53
64
|
|
|
@@ -76,7 +87,7 @@ const client = new Client({
|
|
|
76
87
|
});
|
|
77
88
|
```
|
|
78
89
|
|
|
79
|
-
For a Vercel OIDC-protected deployment, use `vercelOidc`. The client resolves the token once per request and sends it as both the bearer credential and
|
|
90
|
+
For a Vercel OIDC-protected deployment, use `vercelOidc`. The client resolves the token once per request and sends it as both the bearer credential and the `x-vercel-trusted-oidc-idp-token` header:
|
|
80
91
|
|
|
81
92
|
```ts
|
|
82
93
|
import { getVercelOidcToken } from "@vercel/oidc";
|
|
@@ -91,7 +102,7 @@ const client = new Client({
|
|
|
91
102
|
});
|
|
92
103
|
```
|
|
93
104
|
|
|
94
|
-
Use `headers
|
|
105
|
+
Use `headers`, static or dynamic, for route-specific credentials such as bypass tokens or tenant hints:
|
|
95
106
|
|
|
96
107
|
```ts
|
|
97
108
|
const client = new Client({
|
|
@@ -103,9 +114,15 @@ const client = new Client({
|
|
|
103
114
|
});
|
|
104
115
|
```
|
|
105
116
|
|
|
106
|
-
Clients reject redirects by default (`redirect: "error"`) so fetch
|
|
117
|
+
Clients reject redirects by default (`redirect: "error"`), so fetch can't forward your custom credentials to another destination. The policy applies to every request the client makes, including event streams, and overrides per-request settings.
|
|
107
118
|
|
|
108
|
-
|
|
119
|
+
| `redirect` | Behavior |
|
|
120
|
+
| ------------------- | --------------------------------------------------------------------------------------------------------------- |
|
|
121
|
+
| `"error"` (default) | Rejects any redirect. |
|
|
122
|
+
| `"manual"` | Stops at a redirect. Node.js shows its status and headers; browsers return an opaque response with neither. |
|
|
123
|
+
| `"follow"` | Follows redirects. Use it only when you trust every possible destination with your custom headers and requests. |
|
|
124
|
+
|
|
125
|
+
Attach per-request headers to an individual turn:
|
|
109
126
|
|
|
110
127
|
```ts
|
|
111
128
|
const response = await session.send("Run the check.", {
|
|
@@ -115,36 +132,23 @@ const response = await session.send("Run the check.", {
|
|
|
115
132
|
await response.result();
|
|
116
133
|
```
|
|
117
134
|
|
|
118
|
-
Per-request headers override client-level
|
|
135
|
+
Per-request headers override client-level headers with the same name. For example, a turn can set its application user's `Authorization` header while `vercelOidc` still sends the deployment-protection credential in `x-vercel-trusted-oidc-idp-token`.
|
|
119
136
|
|
|
120
137
|
## Faster sends with `inbox`
|
|
121
138
|
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
not inspect, edit, or construct it, because eve may change or extend its contents in any release.
|
|
126
|
-
A missing, stale, or rejected value only costs a slower lookup.
|
|
139
|
+
`session.state` can include an opaque `inbox` value from the server, so save the complete state and pass it back unchanged. Later messages that carry it skip a server-side session lookup. Don't inspect, edit, or construct it, because its contents can change in any release. A missing, stale, or rejected value only costs a slower lookup.
|
|
140
|
+
|
|
141
|
+
Set `EVE_INBOX_HANDLE_SECRET` to the same server-only random secret, at least 32 characters, on every deployment that shares sessions. Omit it to disable handles. The server verifies a handle's signature before using it. After a secret rotation, the server ignores old handles and looks the session up as usual.
|
|
127
142
|
|
|
128
|
-
|
|
129
|
-
on the deployments that share sessions. Without this key, handles are neither issued nor used.
|
|
130
|
-
The signature authenticates all routing and encryption fields before use. Rotation falls back
|
|
131
|
-
to ordinary token resolution.
|
|
143
|
+
Handles also require a Workflow SDK that exports `parseHookResumeHandle`, a world adapter that declares `resolvedHookResume`, and a backend that supports resolved hook resumes. Without all three, the server neither issues nor uses handles, even with the secret set.
|
|
132
144
|
|
|
133
|
-
|
|
134
|
-
`resolvedHookResume`, and a backend with the guarded resolved-hook endpoint.
|
|
135
|
-
Older SDKs do not issue or use handles, even when the secret
|
|
136
|
-
is configured. This change keeps the released SDK dependencies; adopting the SDK update
|
|
137
|
-
enables the optimization. Handles exclude user metadata, live capabilities, and trace carriers,
|
|
138
|
-
which may contain private server baggage. The signature authenticates a handle; it does not hide its contents.
|
|
145
|
+
Handles contain no user metadata, short-lived runtime access, or trace data. The signature proves a handle is authentic but doesn't hide its contents.
|
|
139
146
|
|
|
140
|
-
|
|
141
|
-
hook, persists the message, and wakes the workflow. A definite stale-owner rejection resolves
|
|
142
|
-
the current inbox again. An uncertain write is surfaced without submitting a second delivery.
|
|
147
|
+
A handle can't route a message to a session other than the one requested. When a handle is stale, the server looks up the current session again. When a write's outcome is uncertain, the request reports an error instead of delivering the message twice.
|
|
143
148
|
|
|
144
149
|
## Sessions
|
|
145
150
|
|
|
146
|
-
Create
|
|
147
|
-
while the user is still composing:
|
|
151
|
+
Create a session before its first turn so it starts while the user is still typing:
|
|
148
152
|
|
|
149
153
|
```ts
|
|
150
154
|
const { session } = await client.sessions.create();
|
|
@@ -153,9 +157,7 @@ const response = await session.send("Summarize account A.");
|
|
|
153
157
|
await response.result();
|
|
154
158
|
```
|
|
155
159
|
|
|
156
|
-
|
|
157
|
-
event stream or wait for initialization; an early `session.send()` uses the
|
|
158
|
-
same bounded startup retries as other follow-ups.
|
|
160
|
+
`create()` resolves when the server accepts the session. It doesn't open the event stream or wait for the session to start. An early `session.send()` retries for a limited time while the session starts, like any follow-up.
|
|
159
161
|
|
|
160
162
|
To create the session and start its first turn in one request, include the message:
|
|
161
163
|
|
|
@@ -168,13 +170,13 @@ await session.compact();
|
|
|
168
170
|
await session.clear();
|
|
169
171
|
```
|
|
170
172
|
|
|
171
|
-
If you already know the
|
|
173
|
+
If you already know the session ID, attach a handle without making a request:
|
|
172
174
|
|
|
173
175
|
```ts
|
|
174
176
|
const session = client.sessions.attach("wrun_A");
|
|
175
177
|
```
|
|
176
178
|
|
|
177
|
-
The
|
|
179
|
+
The handle exposes every session operation for that ID:
|
|
178
180
|
|
|
179
181
|
```ts
|
|
180
182
|
const response = await session.send("Continue the analysis.");
|
|
@@ -191,9 +193,9 @@ for await (const event of session.stream({ follow: false })) {
|
|
|
191
193
|
await session.end({ reason: "User requested a fresh session" });
|
|
192
194
|
```
|
|
193
195
|
|
|
194
|
-
|
|
196
|
+
Each handle stores the session ID, stream cursor, and optional `inbox` value. Every method calls a `/eve/v1/session/:sessionId/...` route for that ID. Sending to an unknown or ended session fails instead of creating a new one. After `end()`, the handle keeps pointing at the retired ID; call `client.sessions.create()` to start a different session. A server must serve `/end` before a client can call `end()` on it.
|
|
195
197
|
|
|
196
|
-
|
|
198
|
+
One client can run many independent sessions at once:
|
|
197
199
|
|
|
198
200
|
```ts
|
|
199
201
|
const { session: alice, delivery: aliceDelivery } = await client.sessions.create({
|
|
@@ -206,7 +208,7 @@ const { session: bob, delivery: bobDelivery } = await client.sessions.create({
|
|
|
206
208
|
await Promise.all([aliceDelivery.result(), bobDelivery.result()]);
|
|
207
209
|
```
|
|
208
210
|
|
|
209
|
-
|
|
211
|
+
Read more about working with sessions:
|
|
210
212
|
|
|
211
213
|
- [Messages](./messages): send turns and collect results
|
|
212
214
|
- [Continuations](./continuations): persist and resume sessions
|