eve 0.85.0 → 0.87.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +34 -3073
- package/README.md +7 -4
- 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/commands/agent-prompt/collect-intent.md +2 -1
- package/dist/src/cli/commands/agent-prompt/scaffold.md +1 -2
- 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.d.ts +1 -1
- package/dist/src/cli/dev/tui/runner.js +2 -2
- 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/cli/run.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 +4 -4
- package/dist/src/compiled/@vercel/agent-runs/LICENSE +202 -0
- package/dist/src/compiled/@vercel/schedules/index.d.ts +45 -6
- package/dist/src/compiled/@vercel/schedules/index.js +2 -2
- 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/proxied-deliver-step.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/session/active-turn.js +1 -1
- package/dist/src/execution/session/answer-caller.d.ts +9 -5
- package/dist/src/execution/session/answer-caller.js +1 -1
- package/dist/src/execution/session/principal.d.ts +8 -0
- package/dist/src/execution/session/principal.js +1 -1
- package/dist/src/execution/session/program.js +1 -1
- package/dist/src/execution/session/turn-step.js +1 -1
- package/dist/src/execution/session/turn.js +1 -1
- package/dist/src/execution/session-callback-request.js +1 -1
- package/dist/src/execution/tools/agent-router-workflow.js +1 -1
- package/dist/src/harness/attachment-staging.d.ts +2 -2
- package/dist/src/harness/attachment-staging.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/nitro/routes/schedule-collection-consumer.js +1 -1
- package/dist/src/internal/runtime-model.d.ts +9 -4
- package/dist/src/internal/runtime-model.js +1 -1
- package/dist/src/internal/workflow-bundle/authored-workflow-directives.js +1 -1
- package/dist/src/internal/workflow-bundle/builder-support.d.ts +1 -1
- package/dist/src/internal/workflow-bundle/builder-support.js +1 -1
- package/dist/src/internal/workflow-bundle/workflow-transformer.js +1 -1
- package/dist/src/models/auto.js +1 -1
- package/dist/src/protocol/delivery.d.ts +1 -0
- package/dist/src/protocol/reset-session.d.ts +0 -2
- package/dist/src/protocol/routes.d.ts +9 -2
- package/dist/src/protocol/routes.js +1 -1
- package/dist/src/public/channels/chat-sdk/chatSdkChannel.d.ts +1 -22
- package/dist/src/public/channels/discord/discordChannel.d.ts +3 -12
- package/dist/src/public/channels/discord/gateway/{index.d.ts → relay.d.ts} +2 -2
- package/dist/src/public/channels/discord/gateway/relay.js +1 -0
- package/dist/src/public/channels/discord/messages.d.ts +4 -4
- package/dist/src/public/channels/github/state.d.ts +0 -2
- package/dist/src/public/channels/index.d.ts +1 -2
- package/dist/src/public/channels/index.js +1 -1
- package/dist/src/public/channels/linear/index.d.ts +1 -1
- package/dist/src/public/channels/linear/index.js +1 -1
- package/dist/src/public/channels/linear/linearChannel.d.ts +0 -5
- package/dist/src/public/channels/linq/index.d.ts +1 -1
- package/dist/src/public/channels/linq/linqChannel.d.ts +7 -5
- package/dist/src/public/channels/photon/index.d.ts +1 -1
- package/dist/src/public/channels/photon/photonIMessageChannel.d.ts +15 -4
- package/dist/src/public/channels/slack/api.d.ts +1 -1
- package/dist/src/public/channels/slack/api.js +1 -1
- package/dist/src/public/channels/slack/blocks.d.ts +1 -1
- package/dist/src/public/channels/slack/blocks.js +2 -2
- package/dist/src/public/channels/slack/cards.d.ts +2 -297
- package/dist/src/public/channels/slack/cards.js +1 -1
- package/dist/src/public/channels/slack/index.d.ts +2 -2
- package/dist/src/public/channels/slack/index.js +1 -1
- package/dist/src/public/channels/slack/session-operations.d.ts +2 -2
- package/dist/src/public/channels/slack/session-operations.js +1 -1
- package/dist/src/public/channels/slack/slackChannel.d.ts +11 -72
- package/dist/src/public/channels/slack/slackChannel.js +1 -1
- package/dist/src/public/channels/teams/teamsChannel.d.ts +4 -3
- package/dist/src/public/channels/telegram/hitl.d.ts +2 -9
- package/dist/src/public/channels/telegram/index.d.ts +1 -1
- package/dist/src/public/channels/telegram/telegramChannel.d.ts +0 -2
- package/dist/src/public/channels/twilio/twilioChannel.d.ts +0 -2
- package/dist/src/public/channels/undelivered-reply.d.ts +0 -5
- package/dist/src/public/definitions/agent.d.ts +15 -7
- package/dist/src/public/definitions/agent.js +1 -1
- package/dist/src/public/definitions/channel.d.ts +7 -5
- package/dist/src/public/definitions/channel.js +1 -1
- package/dist/src/public/definitions/connections/protocol.d.ts +1 -7
- package/dist/src/public/definitions/connections/protocol.js +1 -1
- package/dist/src/public/experimental/channels/discord/gateway.d.ts +1 -0
- package/dist/src/public/experimental/channels/discord/gateway.js +1 -0
- package/dist/src/public/experimental/sandbox/just-bash.d.ts +1 -0
- package/dist/src/public/experimental/sandbox/just-bash.js +1 -0
- package/dist/src/public/experimental/workspace/index.d.ts +1 -0
- package/dist/src/public/experimental/workspace/index.js +1 -0
- package/dist/src/public/index.d.ts +2 -2
- package/dist/src/public/index.js +1 -1
- package/dist/src/public/instrumentation/otel.d.ts +1 -1
- package/dist/src/public/instrumentation/provider.d.ts +1 -1
- package/dist/src/public/instrumentation/provider.js +1 -1
- package/dist/src/public/memory/file/backend.d.ts +1 -1
- package/dist/src/public/memory/file/backends/in-memory.js +1 -1
- package/dist/src/public/memory/file/backends/vercel-blob.js +1 -1
- package/dist/src/public/memory/file/provider.js +1 -1
- package/dist/src/public/memory/index.d.ts +3 -11
- package/dist/src/public/models/anthropic/index.d.ts +1 -1
- package/dist/src/public/models/index.d.ts +1 -0
- package/dist/src/public/models/openai/index.d.ts +2 -2
- package/dist/src/public/next/index.d.ts +2 -2
- package/dist/src/public/sandbox/just-bash-sandbox.d.ts +27 -20
- package/dist/src/public/sandbox/just-bash.d.ts +0 -1
- package/dist/src/public/schedules/providers/vercel.d.ts +2 -0
- package/dist/src/public/schedules/providers/vercel.js +1 -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 +15 -13
- package/docs/channels/linear.mdx +11 -0
- package/docs/channels/linq.mdx +5 -1
- package/docs/channels/photon.mdx +6 -1
- package/docs/channels/slack.mdx +73 -14
- package/docs/channels/telegram.mdx +6 -0
- package/docs/code-extension.mdx +25 -0
- package/docs/concepts/default-harness.md +2 -2
- package/docs/concepts/execution-model-and-durability.mdx +11 -11
- package/docs/concepts/project-structure.mdx +1 -1
- package/docs/concepts/security-model.md +6 -2
- package/docs/concepts/sessions-runs-and-streaming.md +23 -10
- package/docs/concepts/upgrade-to-v27-events.md +70 -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 +6 -0
- package/docs/guides/auth-and-route-protection.md +2 -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 +25 -7
- package/docs/guides/decide.md +3 -3
- package/docs/guides/deployment/self-hosting.md +1 -1
- package/docs/guides/deployment/vercel.mdx +1 -1
- package/docs/guides/dev-tui.md +2 -2
- package/docs/guides/frontend/meta.json +1 -0
- package/docs/guides/frontend/nextjs.mdx +329 -121
- package/docs/guides/frontend/overview.mdx +115 -335
- package/docs/guides/frontend/tanstack.mdx +1 -1
- package/docs/guides/frontend/use-eve-agent-svelte.mdx +18 -16
- package/docs/guides/frontend/use-eve-agent-vue.mdx +18 -16
- package/docs/guides/frontend/use-eve-agent.mdx +385 -0
- package/docs/guides/hooks.md +1 -1
- package/docs/guides/instrumentation/otel.mdx +3 -1
- package/docs/guides/prepare-for-1-0.md +255 -0
- package/docs/guides/remote-agents.md +26 -22
- package/docs/guides/self-modification.md +6 -0
- 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 +15 -11
- 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 +6 -6
- 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 +46 -27
- package/dist/src/public/channels/discord/gateway/index.js +0 -1
- package/dist/src/self-modification/agent.d.ts +0 -12
- package/dist/src/self-modification/agent.js +0 -1
|
@@ -3,40 +3,28 @@ title: "Overview"
|
|
|
3
3
|
description: "Put an eve agent behind a browser chat UI with useEveAgent."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
`useEveAgent` connects a browser UI to an eve agent. It starts a session, sends messages, and streams the agent's reply into state you can render. This page uses React; [Vue](./use-eve-agent-vue) and [Svelte](./use-eve-agent-svelte) work the same way.
|
|
7
7
|
|
|
8
|
-
##
|
|
8
|
+
## How it works
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
Your app and the agent share an origin. The browser calls the agent at `/eve/v1/*`, and a framework integration or your hosting routes those requests to the agent:
|
|
11
11
|
|
|
12
|
-
-
|
|
13
|
-
-
|
|
12
|
+
- [Next.js](./nextjs)
|
|
13
|
+
- [Nuxt](./nuxt)
|
|
14
|
+
- [SvelteKit](./sveltekit)
|
|
15
|
+
- [TanStack Start](./tanstack)
|
|
14
16
|
|
|
15
|
-
|
|
17
|
+
To generate a working chat app, run `eve add channel/web`. For scripts and server code that don't render UI, use the [Client SDK](../client/overview).
|
|
16
18
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
## Authenticate browser requests
|
|
20
|
-
|
|
21
|
-
A same-origin framework integration sends your application cookies with every eve request. For bearer tokens or another non-cookie scheme, pass `auth` or `headers` to `useEveAgent`.
|
|
22
|
-
|
|
23
|
-
The default eve channel fails closed. Without an authored `agent/channels/eve.ts`, production browser traffic receives `401` from the default `[vercelOidc(), localDev(), placeholderAuth()]` policy. Add the channel file with an `AuthFn` that verifies your application session or token.
|
|
24
|
-
|
|
25
|
-
For a public demo, use `none()` from `eve/channels/auth` to admit anonymous requests explicitly. Do not use `none()` for an agent that handles private or production data. See [Authentication](../auth-and-route-protection) for application-session examples, token verifiers, and the default policy.
|
|
26
|
-
|
|
27
|
-
## Basic chat (React)
|
|
28
|
-
|
|
29
|
-
The hook lives in `eve/react`. Render `messages`, use `activeTurn(view)` from `eve/events` to steer follow-ups into an open turn, and send text with `send`:
|
|
19
|
+
## Build a basic chat
|
|
30
20
|
|
|
31
21
|
```tsx
|
|
32
22
|
"use client";
|
|
33
23
|
|
|
34
|
-
import { activeTurn } from "eve/events";
|
|
35
24
|
import { useEveAgent } from "eve/react";
|
|
36
25
|
|
|
37
26
|
export function Chat() {
|
|
38
27
|
const agent = useEveAgent();
|
|
39
|
-
const turnOpen = activeTurn(agent.view) !== undefined;
|
|
40
28
|
const isResuming = agent.status === "resuming";
|
|
41
29
|
|
|
42
30
|
return (
|
|
@@ -46,7 +34,7 @@ export function Chat() {
|
|
|
46
34
|
const form = new FormData(event.currentTarget);
|
|
47
35
|
const message = String(form.get("message") ?? "").trim();
|
|
48
36
|
if (message.length > 0 && !isResuming) {
|
|
49
|
-
void agent.send(message
|
|
37
|
+
void agent.send(message);
|
|
50
38
|
}
|
|
51
39
|
}}
|
|
52
40
|
>
|
|
@@ -67,211 +55,31 @@ export function Chat() {
|
|
|
67
55
|
}
|
|
68
56
|
```
|
|
69
57
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
`useEveAgent()` returns the current UI state plus commands:
|
|
73
|
-
|
|
74
|
-
| Field | What it is |
|
|
75
|
-
| ------------------ | ----------------------------------------------------------------------------- |
|
|
76
|
-
| `view` | Opaque, immutable snapshot queried through `eve/events`. |
|
|
77
|
-
| `messages` | Rendered messages, including local optimistic submissions and answers. |
|
|
78
|
-
| `agents` | Followed child sessions and their independent observations. |
|
|
79
|
-
| `status` | Outstanding work: `"idle"`, `"busy"`, or `"resuming"`. Errors are separate. |
|
|
80
|
-
| `error` | The latest session creation, stream, resume, or turn failure. |
|
|
81
|
-
| `events` | Raw eve stream events for this session. |
|
|
82
|
-
| `session` | Serializable fixed session cursor (`sessionId`, `streamIndex`). |
|
|
83
|
-
| `prewarm` | Create a session or prepare its idle owner without starting a turn. |
|
|
84
|
-
| `send`, `respond` | Submit a message or answers; resolve with a `Delivery` receipt when accepted. |
|
|
85
|
-
| `resume` | Replay through the durable tail; further following obeys `followWhile`. |
|
|
86
|
-
| `follow` | Follow a same-session delivery receipt, including one sent by another store. |
|
|
87
|
-
| `cancel` | Request durable cancellation of the active turn. |
|
|
88
|
-
| `clear`, `compact` | Queue a context change and return its delivery. |
|
|
89
|
-
| `reset` | Retire the server-side session and return its delivery. |
|
|
90
|
-
| `newSession` | Clear local state and the local session cursor. |
|
|
91
|
-
|
|
92
|
-
Most chat UIs only need `messages`, `status`, and `activeTurn(view)`. Use `view` with queries from `eve/events` for lifecycle state, or `events` when you need the wire log for persistence or audit. Snapshots publish after every fact in a committed line has folded. Retained views and their observations stay unchanged after later updates; tables and preview dictionaries are not public fields.
|
|
93
|
-
|
|
94
|
-
Pass `prewarm: true` to start a workflow when the chat mounts and after each `newSession()` call:
|
|
95
|
-
|
|
96
|
-
```tsx
|
|
97
|
-
import { useEveAgent } from "eve/react";
|
|
98
|
-
|
|
99
|
-
export function Chat() {
|
|
100
|
-
const agent = useEveAgent({ prewarm: true });
|
|
101
|
-
|
|
102
|
-
return <button onClick={agent.newSession}>New chat</button>;
|
|
103
|
-
}
|
|
104
|
-
```
|
|
105
|
-
|
|
106
|
-
React can turn `prewarm` on after mount, and its initial or later `true` value also prepares a
|
|
107
|
-
restored session. Vue and Svelte read it when their binding is created, so call their returned
|
|
108
|
-
`prewarm()` method when typing starts.
|
|
109
|
-
|
|
110
|
-
Prewarming defaults to `false`: the first send creates the session. Set it to `true` only after
|
|
111
|
-
your application's auth, headers, and any chat-record binding are ready. Applications that
|
|
112
|
-
prepare those in the submit handler should keep the default until then.
|
|
113
|
-
|
|
114
|
-
Prewarming starts the workflow and establishes its inbox, then parks before session hooks or
|
|
115
|
-
dynamic definitions run. Meanwhile, it starts the agent's [sandbox](/docs/sandbox) in the
|
|
116
|
-
background. The first message passes through the channel's `onMessage` hook and supplies the
|
|
117
|
-
identity and context for initialization and `turn_0`. That turn does not wait for the sandbox;
|
|
118
|
-
only a tool or hook that uses the sandbox waits for the rest of its start. If the sandbox fails
|
|
119
|
-
to start during prewarming, the first turn that uses it starts it instead. eve deletes the
|
|
120
|
-
sandbox when the session ends, including when an unused prewarmed session times out.
|
|
121
|
-
|
|
122
|
-
For an existing session, `prewarm()` checks which deployment runs the session against the exact
|
|
123
|
-
deployment accepting that request. On Vercel, an idle session on another deployment can move to
|
|
124
|
-
the accepting deployment in the background before the next `send()`. The session ID, history,
|
|
125
|
-
stream, and expiry stay the same; no model call runs. A session already running on that
|
|
126
|
-
deployment is not woken. Active turns are never interrupted; an active turn can finish before
|
|
127
|
-
preparation, and a queued real message takes priority. A session with pending tasks or input
|
|
128
|
-
requests can skip the hint. A session started by an eve version without preparation support, or
|
|
129
|
-
running on a workflow backend without deployment routing, is not moved.
|
|
130
|
-
|
|
131
|
-
Call `agent.prewarm()` once when a new typing burst begins, with an application-level cooldown
|
|
132
|
-
if you also retry during long drafts. eve shares concurrent calls; it does not listen to inputs
|
|
133
|
-
or poll deployments. A production alias targets its current deployment; a preview alias targets
|
|
134
|
-
that preview. Requests pinned to an immutable deployment (including deployment-skew routing)
|
|
135
|
-
cannot discover a newer deployment. In local development, `prewarm()` can create a new session,
|
|
136
|
-
but does not move an existing one.
|
|
137
|
-
|
|
138
|
-
`client.sessions.attach(sessionId).prewarm({ signal })` returns `ready`, `accepted`,
|
|
139
|
-
`unsupported`, or `no_active_session`. `accepted` means the hint was persisted, not that handoff
|
|
140
|
-
has finished. It never replaces an expired session. `send()` retains its existing retry and
|
|
141
|
-
handoff behavior if preparation is unavailable, fails, or has not finished.
|
|
142
|
-
|
|
143
|
-
The explicit `prewarm()` method resolves after ingress acceptance, as does `client.sessions.create()`.
|
|
144
|
-
It does not wait for an initialization event; concurrent calls share the same request.
|
|
145
|
-
The composer stays `"idle"`, meaning it can accept input, and prewarming does not run
|
|
146
|
-
`prepareSend`. A concurrent `send()` waits for initial creation acceptance when needed, but never
|
|
147
|
-
waits for existing-session preparation.
|
|
148
|
-
If the inbox is still starting, the client retries `409 session_not_ready` with bounded
|
|
149
|
-
exponential backoff for up to 20 seconds. The caller's abort signal cancels the wait. Stream
|
|
150
|
-
events are not a prerequisite for sending.
|
|
151
|
-
|
|
152
|
-
An existing-session preparation failure rejects the explicit call without setting `error` or
|
|
153
|
-
blocking `send()`. A failed create sets `error` and calls `onError` when no send is waiting. A waiting send can
|
|
154
|
-
fall back to creating a session with its message. After creation succeeds, initialization
|
|
155
|
-
failures arrive on the stream during the first turn. The configured session timeout starts
|
|
156
|
-
at creation, so an unused prewarmed session can expire before its first message. React does not
|
|
157
|
-
retry a failed prewarm on unrelated renders while the option remains `true`; call `prewarm()`,
|
|
158
|
-
change the option from `false` to `true` again, call `newSession()`, or send a message to recover.
|
|
159
|
-
|
|
160
|
-
The hook keeps consuming one session stream across turns and idle periods. Replies,
|
|
161
|
-
authorization updates, and turns started elsewhere all update the same projection. Each message a
|
|
162
|
-
person sends is its own bubble, placed where its turn took it in: a message that arrives while the
|
|
163
|
-
turn works splits the agent's response, so what the agent did before the message shows above it
|
|
164
|
-
and the rest below. The pieces share `metadata.turnId`. A single event that coalesces multiple
|
|
165
|
-
deliveries remains one bubble. A turn settling does not close the connection. The transport reconnects from
|
|
166
|
-
its cursor after a disconnect or the
|
|
167
|
-
server's renewable 60-second lease; lease renewal does not start a turn or clear UI state.
|
|
168
|
-
Unmounting or calling `newSession()` closes the local stream without cancelling the old durable session.
|
|
169
|
-
|
|
170
|
-
By default, the stream remains open between turns, so events from schedules, channels, or other
|
|
171
|
-
clients arrive as they happen. For a help sidebar that only needs updates during machine work,
|
|
172
|
-
close it when the committed session view becomes idle. Bind both stores to the same existing
|
|
173
|
-
`ClientSession`, kept stable across renders:
|
|
174
|
-
|
|
175
|
-
```tsx
|
|
176
|
-
import type { ClientSession } from "eve/client";
|
|
177
|
-
import { idle } from "eve/events";
|
|
178
|
-
import { useEveAgent } from "eve/react";
|
|
179
|
-
|
|
180
|
-
function useSessionPanels(session: ClientSession) {
|
|
181
|
-
const chat = useEveAgent({ session });
|
|
182
|
-
const sidebar = useEveAgent({ session, followWhile: (view) => !idle(view) });
|
|
183
|
-
|
|
184
|
-
async function send(message: string) {
|
|
185
|
-
const receipt = await chat.send(message);
|
|
186
|
-
sidebar.follow(receipt);
|
|
187
|
-
return receipt;
|
|
188
|
-
}
|
|
189
|
-
|
|
190
|
-
return { chat, sidebar, send };
|
|
191
|
-
}
|
|
192
|
-
```
|
|
193
|
-
|
|
194
|
-
`followWhile(view)` closes the stream when it returns false at a complete line boundary, after catch-up and any accepted receipt being followed. It can close while a turn is active or waiting on an interaction; the UI then remains at its last observed state, including `status`, until another command or explicit follow reopens the stream. To keep following machine work and open turns, including turns waiting on a person, and close only between turns, pass `followWhile: (view) => !idle(view) || activeTurn(view) !== undefined`. React reads the latest predicate on render; Vue and Svelte read it from their options object.
|
|
195
|
-
|
|
196
|
-
Both stores must point to the same session. `follow()` tracks an accepted receipt until it settles, even if the stream catches up before admission. Pass only a receipt returned by `send`, `respond`, `clear`, `compact`, or `reset`. Because a receipt can precede its admission, the store keeps waiting for an id the stream never admits: it stays `"busy"` with the stream open until the session ends or you call `newSession()`. `follow()` does not create a session or grant access. A closed stream cannot see new activity by itself; send a command, call `resume()` or `follow()`, or leave default continuous following on when other sources can start work. Limit retries after stream errors, and resolve authorization failures before retrying.
|
|
197
|
-
|
|
198
|
-
`newSession()` reuses the hook instance and clears the local conversation. `reset()` instead retires the server-side session and returns its delivery. Call `newSession()` to clear the retired conversation and prepare a fresh one. If `prewarm` is true, that call prepares the next owned session; otherwise, the next send creates it. An explicitly
|
|
199
|
-
supplied `session` remains externally owned and is never replaced by prewarming or `newSession()`. Use
|
|
200
|
-
`initialSession` with `resume: true` to restore a saved chat.
|
|
201
|
-
|
|
202
|
-
`messages` are eve-owned `EveMessage[]`. Assistant text and reasoning parts have a stable `id` from the event that created the part. Appends and completion retain that ID. Use `part.id` to key streamed assistant content, including successive text parts within one step. Older events without an ID get a best-effort fallback. User text parts may not have an ID.
|
|
58
|
+
Most chat UIs need only a few values from the hook:
|
|
203
59
|
|
|
204
|
-
|
|
60
|
+
| Value | Use it to |
|
|
61
|
+
| ------------------ | --------------------------------------------------------------- |
|
|
62
|
+
| `messages` | Render the conversation |
|
|
63
|
+
| `status` | Disable input while `"resuming"`; show a spinner while `"busy"` |
|
|
64
|
+
| `error` | Show the latest failure |
|
|
65
|
+
| `activeTurn(view)` | Check whether a turn is open, so you can offer to cancel it |
|
|
66
|
+
| `send`, `respond` | Send a message, or answer a question |
|
|
67
|
+
| `cancel` | Stop the running turn |
|
|
68
|
+
| `newSession` | Start a new conversation |
|
|
205
69
|
|
|
206
|
-
|
|
70
|
+
See the [`useEveAgent` reference](./use-eve-agent) for everything else.
|
|
207
71
|
|
|
208
|
-
|
|
209
|
-
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
210
|
-
| `callId`, `name` | The call, and the tool, agent, or skill it invokes. |
|
|
211
|
-
| `kind` | `tool`, `agent`, `skill`, or `control` (task controls, usually hidden in activity displays). |
|
|
212
|
-
| `label` | The tool's authored label, its latest output label, or a readable name. |
|
|
213
|
-
| `state` | `streaming` while input arrives, then the shared `CallState`: `requested`, `approval`, `running`, `blocked`, `completed`, `failed`, `rejected`, or `cancelled`. |
|
|
214
|
-
| `inputText` | Partial input, only when `state` is `streaming`. |
|
|
215
|
-
| `input`, `output`, `error` | Validated input, current or final output, and error details after input streaming. |
|
|
216
|
-
| `interaction` | The latest approval or question about the call. Its status stays `open` while an answer is submitted; settlement confirms the decision. |
|
|
217
|
-
|
|
218
|
-
Read outcomes, reasons, and task identities from `call(view, part.callId)` from `eve/events`
|
|
219
|
-
instead of duplicate fields on the renderable part.
|
|
220
|
-
A call your stream stopped following stays open; decide yourself what an open call shows once the stream ended. A call a model retry replaced doesn't show: the replacement asks again.
|
|
221
|
-
|
|
222
|
-
A delegated call stays running until `call.settled`; its child's detailed events live on a separate stream. Query `call(view, callId)` for the call outcome, and `agents[sessionId]` for the opened child session.
|
|
223
|
-
|
|
224
|
-
Detailed child progress lives on the child session's stream, not in the root `messages`. Pass `followAgents: true` to recursively observe recorded children, including children opened inside workflow tools. Following is off by default. React, Vue, and Svelte use the same store-owned traversal.
|
|
225
|
-
|
|
226
|
-
To select relationships, pass a synchronous predicate. `true` and `() => true` have the same meaning; an excluded child's descendants are not discovered:
|
|
227
|
-
|
|
228
|
-
```tsx
|
|
229
|
-
const agent = useEveAgent({
|
|
230
|
-
followAgents: ({ depth }) => depth <= 3,
|
|
231
|
-
});
|
|
232
|
-
```
|
|
233
|
-
|
|
234
|
-
Root depth is zero. eve admits at most 128 child observations per root generation, follows to depth 8, and allows 8 simultaneous descendant reads independently of the root stream. Each read stops at its captured durable tail or yields its slot after 10 seconds. Caught-up observations are refreshed with delays from 1 to 10 seconds. These bounds do not limit execution or the root transcript. `newSession()` resets admission accounting. The policy is read at store creation and evaluated once per relationship at each known reachable depth; unrelated renders do not replace followers. When authorized readers establish that two paths reach the same session, the store shares its observation and considers both paths' depths.
|
|
235
|
-
|
|
236
|
-
Each `agents[sessionId]` describes an opening, with an `owner` naming its call or task. A followed `observation.conversation` has its own `agents`, `messages`, and opaque `view`. Calls that continue a task reuse its child conversation; the opening owner does not change. Read the particular call or delivery's settled result for its outcome, not the child's latest message.
|
|
237
|
-
|
|
238
|
-
To show what one call caused in a child it shares with other calls, use `agentCallActivity(state, callId)` from `eve/client`. It follows the `child.sent` links the parent recorded to each delivery the call sent and the child turns that consumed them:
|
|
239
|
-
|
|
240
|
-
```ts
|
|
241
|
-
import { agentCallActivity } from "eve/client";
|
|
242
|
-
|
|
243
|
-
const activity = agentCallActivity(agent, callId);
|
|
244
|
-
if (activity.status === "linked") {
|
|
245
|
-
for (const { sessionId, deliveries, turns } of activity.sessions) {
|
|
246
|
-
const pending = deliveries.some(({ status }) => status !== "settled");
|
|
247
|
-
const turnIds = new Set(turns.map(({ turnId }) => turnId));
|
|
248
|
-
// Render agent.agents[sessionId]'s messages whose metadata.turnId is in turnIds.
|
|
249
|
-
}
|
|
250
|
-
}
|
|
251
|
-
```
|
|
252
|
-
|
|
253
|
-
A delivery's `status` is `"unseen"` until this reader reads the child's admission, then the child's own `"admitted"`, `"consumed"`, or `"settled"`. Several calls can reach one turn, as when a call arrives while the agent works; each turn lists the other calls it answered in `sharedWith`, so render it once for all of them rather than splitting it. `"unlinked"` means the parent recorded no delivery for the call, as for a call that sent nothing or reached a remote agent on an earlier protocol.
|
|
254
|
-
|
|
255
|
-
| Observation status | Meaning |
|
|
256
|
-
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
|
|
257
|
-
| `"not-followed"` | Following is disabled, or `reason` identifies a predicate, depth/session limit, or cycle. |
|
|
258
|
-
| `"queued"` | Admitted and waiting for a read slot. |
|
|
259
|
-
| `"following"` | Reading a finite captured prefix. Silence does not imply settlement. |
|
|
260
|
-
| `"caught-up"` | Reached the tail captured for this read; the child may still be working, and another read can discover more activity. |
|
|
261
|
-
| `"interrupted"` | A retryable read failure or detached observation scope. |
|
|
262
|
-
| `"unavailable"` | History cannot currently be read. `reason` distinguishes authorization, expiry, unsupported readers, and transport failures. |
|
|
263
|
-
|
|
264
|
-
Except for `"not-followed"`, an observation exposes `position`, `caughtUp`, and its committed `conversation`, which can be empty before the first successful read. Its server-established `key` identifies the session within this store's authorized reader scope, not across principals or stores. Equal session IDs reached through different remote reader namespaces are not merged. Cursors use source-line positions and remain independent across sessions.
|
|
72
|
+
## Authenticate browser requests
|
|
265
73
|
|
|
266
|
-
|
|
74
|
+
Because the browser calls the agent on your own origin, it sends your app's cookies with every request. The agent decides whether to accept them in `agent/channels/eve.ts`.
|
|
267
75
|
|
|
268
|
-
|
|
76
|
+
Until you add an auth check there, production browser requests get `401`. Write an `AuthFn` that verifies your app's session; [Authentication](../auth-and-route-protection) shows how. For a public demo, `none()` from `eve/channels/auth` admits everyone; don't use it for private data.
|
|
269
77
|
|
|
270
|
-
If
|
|
78
|
+
If your app uses bearer tokens instead of cookies, pass them to the hook. See [Custom hosts and headers](#custom-hosts-and-headers).
|
|
271
79
|
|
|
272
|
-
##
|
|
80
|
+
## Send messages
|
|
273
81
|
|
|
274
|
-
|
|
82
|
+
Send text, or an array of parts to include files:
|
|
275
83
|
|
|
276
84
|
```tsx
|
|
277
85
|
await agent.send("Summarize this session.");
|
|
@@ -287,37 +95,15 @@ await agent.send([
|
|
|
287
95
|
]);
|
|
288
96
|
```
|
|
289
97
|
|
|
290
|
-
|
|
291
|
-
while a message, answer, or control command is pending, a followed receipt has not settled, or the
|
|
292
|
-
session has running or queued work, and `idle` otherwise. `resuming` means the hook is catching up
|
|
293
|
-
an attached session; disable message and HITL submission then. `status` describes outstanding
|
|
294
|
-
work, not whether a turn is open: a turn waiting only on a person is open while `status` is
|
|
295
|
-
`idle`, and the stream stays open by default. Use `activeTurn(view)` to decide whether a turn is
|
|
296
|
-
open, can be steered, or can be cancelled. A failure updates `error` without replacing the
|
|
297
|
-
transport status.
|
|
98
|
+
`send()` resolves as soon as eve accepts the message. The reply then streams into `messages`.
|
|
298
99
|
|
|
299
|
-
|
|
300
|
-
independent `stream({ signal })` and `result({ signal })` reads. Those can open another HTTP
|
|
301
|
-
stream and remain usable after `newSession()` or unmount; pass a signal when the read should
|
|
302
|
-
end with your component. The store's saved cursor tracks only its own committed events, never
|
|
303
|
-
another reader's progress.
|
|
304
|
-
|
|
305
|
-
To steer an active turn with a follow-up, send the message with `turnPolicy: "steer"`. Before answer output or local tool execution begins, eve interrupts pending model generation and continues the same turn with the correction. Executing tools finish and checkpoint their results first; after answer output starts, steering waits for the next committed workflow boundary. Reasoning and search progress do not count as answer output. The hook stays attached through completion:
|
|
100
|
+
A message sent while the agent is still working redirects the current turn, called steering. You don't need to do anything extra. To wait for the turn to finish instead, queue the message:
|
|
306
101
|
|
|
307
102
|
```tsx
|
|
308
|
-
await agent.send(
|
|
103
|
+
await agent.send("Then summarize the second file.", { turnPolicy: "queue" });
|
|
309
104
|
```
|
|
310
105
|
|
|
311
|
-
|
|
312
|
-
turn, or `"steer"` to guide it. Answers are accepted while other work runs. Read interactions with
|
|
313
|
-
`interaction(view, id)` from `eve/events`: their originating turn, step, task, request, and answer
|
|
314
|
-
are in one projection. `activeTurn(view)?.turnId` identifies the current root turn. Followed
|
|
315
|
-
sessions have their own view under `agents[sessionId].observation.conversation`.
|
|
316
|
-
Call `cancel()` to stop the durable turn without replacing it.
|
|
317
|
-
|
|
318
|
-
`cancel()` targets the currently observed turn and keeps the event stream attached. If no turn is active, it waits for a submission pending when you called `cancel()` to identify its turn. This includes preparation, session creation, and POST acceptance. Cancellation always names the identified turn, so a delayed request cannot stop an unrelated later turn.
|
|
319
|
-
|
|
320
|
-
The wait does not withdraw a queued message. If it never reaches a running turn, cancellation is a no-op; an idle `cancel()` does not arm a future request. Cancellation is cooperative, so a turn can finish before it takes effect.
|
|
106
|
+
To stop a running turn, call `cancel()`. Closing the page doesn't stop the turn on the server.
|
|
321
107
|
|
|
322
108
|
```tsx
|
|
323
109
|
import { activeTurn } from "eve/events";
|
|
@@ -327,18 +113,11 @@ if (activeTurn(agent.view) !== undefined) {
|
|
|
327
113
|
}
|
|
328
114
|
```
|
|
329
115
|
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
After eve confirms an attachment turn with `delivery.consumed`, each received attachment shows as
|
|
333
|
-
a `file` part on the user message. The part includes `mediaType`, optional
|
|
334
|
-
`filename` and `size`, and a `url` only when the original attachment was browser-resolvable.
|
|
116
|
+
See [Sending](./use-eve-agent#sending) and [Cancelling](./use-eve-agent#cancelling) for exact timing.
|
|
335
117
|
|
|
336
118
|
## Human-in-the-loop prompts
|
|
337
119
|
|
|
338
|
-
Tools
|
|
339
|
-
See [Human-in-the-loop](/docs/human-in-the-loop) for the server-side model. Read open prompts from
|
|
340
|
-
`view` and answer through the same session. A call's approval or question also appears as
|
|
341
|
-
`part.interaction`; other prompts are `interaction` message parts.
|
|
120
|
+
Tools can ask a person to approve a call or answer a question. See [Human-in-the-loop](/docs/human-in-the-loop) for the server side. In the UI, read open prompts from `view` and answer with `respond()`:
|
|
342
121
|
|
|
343
122
|
```tsx
|
|
344
123
|
import { openInteractions } from "eve/events";
|
|
@@ -364,11 +143,14 @@ return pendingRequests.map(({ interactionId, request }) => (
|
|
|
364
143
|
));
|
|
365
144
|
```
|
|
366
145
|
|
|
367
|
-
For free
|
|
146
|
+
- For a free-text answer, send `{ interactionId, text }`.
|
|
147
|
+
- A prompt stays `open` until eve settles it, not when you submit an answer. If the answer is refused, the prompt stays answerable.
|
|
148
|
+
- To show how a prompt ended, read its `outcome`. Only `accepted` and `declined` mean a person decided; a prompt can also end because its turn was cancelled. See [Interactions](./use-eve-agent#interactions).
|
|
149
|
+
- A prompt about a tool call also appears on that call's `tool` part as `part.interaction`. Other prompts appear as `interaction` message parts.
|
|
368
150
|
|
|
369
151
|
## Sign-ins and other interactions
|
|
370
152
|
|
|
371
|
-
|
|
153
|
+
When a tool or connection needs the user to sign in, for example with OAuth, the turn opens a sign-in prompt. It appears in `messages` as an `interaction` part. Render it like any other message; once the user signs in, the turn continues on its own.
|
|
372
154
|
|
|
373
155
|
```tsx
|
|
374
156
|
import { signInEnding, type EveMessagePart } from "eve/react";
|
|
@@ -393,11 +175,11 @@ function SignInPrompt({ part }: { part: EveMessagePart }) {
|
|
|
393
175
|
}
|
|
394
176
|
```
|
|
395
177
|
|
|
396
|
-
|
|
178
|
+
`request.signIn` holds the provider's display name, instructions, device code, and sign-in URL. To list open sign-ins, use `openInteractions(view, { kind: "sign-in" })`.
|
|
397
179
|
|
|
398
180
|
## Attach page context per turn
|
|
399
181
|
|
|
400
|
-
`clientContext`
|
|
182
|
+
`clientContext` tells the agent about the user's current page for one turn. It isn't saved to the conversation history:
|
|
401
183
|
|
|
402
184
|
```tsx
|
|
403
185
|
await agent.send("What should I do on this screen?", {
|
|
@@ -405,7 +187,9 @@ await agent.send("What should I do on this screen?", {
|
|
|
405
187
|
});
|
|
406
188
|
```
|
|
407
189
|
|
|
408
|
-
|
|
190
|
+
Pass a string, an array of strings, or an object, which eve sends as JSON. The context also rides along with `respond()`.
|
|
191
|
+
|
|
192
|
+
To add context to every message, use `prepareSend`:
|
|
409
193
|
|
|
410
194
|
```tsx
|
|
411
195
|
const agent = useEveAgent({
|
|
@@ -416,60 +200,9 @@ const agent = useEveAgent({
|
|
|
416
200
|
});
|
|
417
201
|
```
|
|
418
202
|
|
|
419
|
-
## Lifecycle callbacks
|
|
420
|
-
|
|
421
|
-
The hook accepts these lifecycle callbacks:
|
|
422
|
-
|
|
423
|
-
- `onEvent(event)`: fires for each eve stream event as it arrives.
|
|
424
|
-
- `onError(error)`: fires when session creation, streaming, resume, or a live turn fails. Restoring a historical failure updates `error` without replaying this callback. A failed prewarm reports here when no send is waiting to retry creation.
|
|
425
|
-
- `onFinish(snapshot)`: fires when a live turn settles, after its whole committed line is visible. Catch-up never fires it, including for a locally submitted turn that already settled. Use `receipt.result()` to read that delivery's result; a delivery can settle while its turn is still awaiting input.
|
|
426
|
-
- `onSessionChange(session)`: fires when a session is created, its cursor advances, or `newSession()` clears it. Persist the session state to resume across reloads.
|
|
427
|
-
|
|
428
|
-
```tsx
|
|
429
|
-
const agent = useEveAgent({
|
|
430
|
-
onEvent: (event) => console.debug(event.type),
|
|
431
|
-
onError: (error) => toast.error(error.message),
|
|
432
|
-
onFinish: (snapshot) => console.log(snapshot.status),
|
|
433
|
-
});
|
|
434
|
-
```
|
|
435
|
-
|
|
436
|
-
The `optimistic` option (default `true`) shows submitted user messages in `messages` before eve confirms them with a `delivery.consumed` fact. A follow-up sent while a turn works shows at the end of the conversation and stays there once the turn takes it in; if the send fails, the failed placeholder stays in place, with `metadata.status` `"failed"`. They show in `messages` only; `events` stays the authoritative eve stream. The hook reconciles each placeholder with the server's delivery ID, including the first message. Its message ID stays unchanged when confirmed, so an unrelated or identical message cannot consume it. While POST acknowledgements are pending, stream-driven snapshot publication waits for their identities; `onEvent` still receives the stream events.
|
|
437
|
-
|
|
438
|
-
## Derive your own state
|
|
439
|
-
|
|
440
|
-
Read lifecycle state directly from `view`. It is the shared fold's committed snapshot, not a second conversation-specific turn or task model:
|
|
441
|
-
|
|
442
|
-
```tsx
|
|
443
|
-
import { activeTurn, activity, waiting } from "eve/events";
|
|
444
|
-
|
|
445
|
-
const turn = activeTurn(agent.view);
|
|
446
|
-
const currentActivity = activity(agent.view);
|
|
447
|
-
const blocked = turn === undefined ? undefined : waiting(agent.view, turn.turnId);
|
|
448
|
-
```
|
|
449
|
-
|
|
450
|
-
For event-level queries, use `events`, the authoritative, deduplicated list of the session's stream events, which `newSession()` empties:
|
|
451
|
-
|
|
452
|
-
```tsx
|
|
453
|
-
import { useMemo } from "react";
|
|
454
|
-
import { useEveAgent } from "eve/react";
|
|
455
|
-
|
|
456
|
-
const agent = useEveAgent();
|
|
457
|
-
const toolCalls = useMemo(
|
|
458
|
-
() => agent.events.filter((event) => event.type === "call.requested").length,
|
|
459
|
-
[agent.events],
|
|
460
|
-
);
|
|
461
|
-
```
|
|
462
|
-
|
|
463
|
-
Use the snapshot's `view` instead of folding `events` again inside a component. Outside the
|
|
464
|
-
store, `foldEvents` and `emptySessionView` from `eve/events` fold received events by whole line:
|
|
465
|
-
assign `view = foldEvents(view, receivedEvents)`. The input view stays unchanged, and the returned
|
|
466
|
-
snapshot holds unfinished lines privately until they complete. Use `callPreview(view, callId)`
|
|
467
|
-
or `contentPreviews(view)` for transient progress; renderable messages still include streamed
|
|
468
|
-
input. To render a saved log, use `conversationOf(events)` from `eve/client`.
|
|
469
|
-
|
|
470
203
|
## Resumable sessions
|
|
471
204
|
|
|
472
|
-
|
|
205
|
+
eve stores every conversation on the server. To reopen one after a reload, save two things, `session` and `events`, and pass them back:
|
|
473
206
|
|
|
474
207
|
```tsx
|
|
475
208
|
import { useEffect, useState } from "react";
|
|
@@ -500,30 +233,81 @@ useEffect(() => {
|
|
|
500
233
|
}, [agent.events, agent.session]);
|
|
501
234
|
```
|
|
502
235
|
|
|
503
|
-
|
|
504
|
-
lets
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
236
|
+
- `session` tells eve which conversation to continue and where to pick up. Save the whole object, as is.
|
|
237
|
+
- `events` lets you show the saved messages immediately, before eve catches up.
|
|
238
|
+
- If you only have a session ID, pass `initialSession: { sessionId, streamIndex: 0 }` with `resume: true`; eve replays the conversation from the start.
|
|
239
|
+
|
|
240
|
+
A few rules keep restored chats correct:
|
|
241
|
+
|
|
242
|
+
- **Save as you go.** Save on every change, not only when a turn finishes. A turn waiting on the user hasn't finished, but its messages must survive a reload.
|
|
243
|
+
- **Disable input while resuming.** While `status` is `"resuming"`, show the saved messages but disable sending.
|
|
244
|
+
- **One saved chat per conversation.** To switch conversations, remount the chat component, for example with `key={chat.id}`.
|
|
245
|
+
- **Create your chat record first.** If the user can reload right after sending, create your app's chat record before `send()`, and save the session ID from `onSessionChange`.
|
|
246
|
+
|
|
247
|
+
See [Resume a saved session](./use-eve-agent#resume-a-saved-session) for exactly how saved events and catch-up fit together.
|
|
248
|
+
|
|
249
|
+
## Start a new conversation
|
|
250
|
+
|
|
251
|
+
- `newSession()` clears the chat and starts fresh. The old conversation stays on the server.
|
|
252
|
+
- `end()` ends the conversation on the server. Call `newSession()` afterward to clear it locally.
|
|
508
253
|
|
|
509
|
-
|
|
254
|
+
To make the first reply faster, pass `prewarm: true`. eve then creates the next session before the user sends anything. Turn it on only after your auth headers are ready. See [Prewarming](./use-eve-agent#prewarming).
|
|
510
255
|
|
|
511
|
-
|
|
256
|
+
## Show subagent progress
|
|
512
257
|
|
|
513
|
-
|
|
258
|
+
When the agent delegates to a subagent, `messages` shows the delegated call, not the subagent's own messages. To follow subagents too, pass `followAgents: true`, then render `agents[sessionId].observation.conversation.messages`:
|
|
259
|
+
|
|
260
|
+
```tsx
|
|
261
|
+
const agent = useEveAgent({ followAgents: true });
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
See [Child agents](./use-eve-agent#child-agents) for limits, observation states, and showing what a single call caused.
|
|
265
|
+
|
|
266
|
+
## Lifecycle callbacks
|
|
267
|
+
|
|
268
|
+
- `onEvent(event)` runs for each stream event.
|
|
269
|
+
- `onError(error)` runs when something fails.
|
|
270
|
+
- `onFinish(snapshot)` runs when a live turn finishes.
|
|
271
|
+
- `onSessionChange(session)` runs when the session cursor changes. Save it here.
|
|
514
272
|
|
|
515
273
|
```tsx
|
|
516
274
|
const agent = useEveAgent({
|
|
517
|
-
|
|
518
|
-
|
|
275
|
+
onEvent: (event) => console.debug(event.type),
|
|
276
|
+
onError: (error) => toast.error(error.message),
|
|
277
|
+
onFinish: (snapshot) => console.log(snapshot.status),
|
|
519
278
|
});
|
|
520
279
|
```
|
|
521
280
|
|
|
522
|
-
|
|
281
|
+
See [Lifecycle callbacks](./use-eve-agent#lifecycle-callbacks) for exactly when each one fires.
|
|
282
|
+
|
|
283
|
+
## Derive your own state
|
|
284
|
+
|
|
285
|
+
`view` already tracks turns, calls, and prompts. Query it with functions from `eve/events` instead of building your own state:
|
|
286
|
+
|
|
287
|
+
```tsx
|
|
288
|
+
import { activeTurn, activity, waiting } from "eve/events";
|
|
289
|
+
|
|
290
|
+
const turn = activeTurn(agent.view);
|
|
291
|
+
const currentActivity = activity(agent.view);
|
|
292
|
+
const blocked = turn === undefined ? undefined : waiting(agent.view, turn.turnId);
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
See [Use eve's answers](./use-eve-agent#use-eves-answers) for which query answers each common question, from a request's result to call timing and usage.
|
|
296
|
+
|
|
297
|
+
For something `view` doesn't cover, read the raw `events`:
|
|
298
|
+
|
|
299
|
+
```tsx
|
|
300
|
+
import { useMemo } from "react";
|
|
301
|
+
|
|
302
|
+
const toolCalls = useMemo(
|
|
303
|
+
() => agent.events.filter((event) => event.type === "call.requested").length,
|
|
304
|
+
[agent.events],
|
|
305
|
+
);
|
|
306
|
+
```
|
|
523
307
|
|
|
524
308
|
## Custom hosts and headers
|
|
525
309
|
|
|
526
|
-
Pass `baseUrl` when the
|
|
310
|
+
Pass `baseUrl` when the agent is on another origin, and `auth` or `headers` for credentials. Functions run before every request, so tokens stay fresh:
|
|
527
311
|
|
|
528
312
|
```tsx
|
|
529
313
|
const agent = useEveAgent({
|
|
@@ -534,11 +318,7 @@ const agent = useEveAgent({
|
|
|
534
318
|
});
|
|
535
319
|
```
|
|
536
320
|
|
|
537
|
-
|
|
538
|
-
continuous session stream on its next reconnect. A later send replaces them with that turn's
|
|
539
|
-
headers.
|
|
540
|
-
|
|
541
|
-
When a framework integration mounts multiple named agents, pass `agent` instead of `baseUrl`:
|
|
321
|
+
When your app mounts several named agents, select one with `agent` instead:
|
|
542
322
|
|
|
543
323
|
```tsx
|
|
544
324
|
const support = useEveAgent({ agent: "support" });
|
|
@@ -548,15 +328,15 @@ const support = useEveAgent({ agent: "support" });
|
|
|
548
328
|
|
|
549
329
|
| Framework | Integration | Hook |
|
|
550
330
|
| -------------- | ------------------------------------ | ------------------------------------------------ |
|
|
551
|
-
| Next.js | [
|
|
331
|
+
| Next.js | [Next.js guide](./nextjs) | [`useEveAgent` (React)](#build-a-basic-chat) |
|
|
552
332
|
| Nuxt | [`eve/nuxt` module](./nuxt) | [`useEveAgent` (Vue)](./use-eve-agent-vue) |
|
|
553
333
|
| SvelteKit | [`eveSvelteKit` plugin](./sveltekit) | [`useEveAgent` (Svelte)](./use-eve-agent-svelte) |
|
|
554
|
-
| TanStack Start | [`eveTanStack` plugin](./tanstack) | [`useEveAgent` (React)](#basic-chat
|
|
555
|
-
| Any React | same-origin or `baseUrl` | [`useEveAgent` (React)](#basic-chat
|
|
334
|
+
| TanStack Start | [`eveTanStack` plugin](./tanstack) | [`useEveAgent` (React)](#build-a-basic-chat) |
|
|
335
|
+
| Any React | same-origin or `baseUrl` | [`useEveAgent` (React)](#build-a-basic-chat) |
|
|
556
336
|
|
|
557
337
|
## What to read next
|
|
558
338
|
|
|
559
|
-
- [
|
|
560
|
-
- [
|
|
561
|
-
- [Client SDK](../client/overview): the
|
|
562
|
-
- [
|
|
339
|
+
- [`useEveAgent` reference](./use-eve-agent): every value, option, and behavior
|
|
340
|
+
- [Next.js](./nextjs): set up a chat app end to end
|
|
341
|
+
- [Client SDK](../client/overview): call the agent from scripts and server code
|
|
342
|
+
- [Sessions, runs & streaming](../../concepts/sessions-runs-and-streaming): how sessions and the event stream work
|
|
@@ -36,7 +36,7 @@ Rerun `eve add channel/web --skip-install` with the other choice to switch modes
|
|
|
36
36
|
|
|
37
37
|
Sign in with Vercel setup is available only for the Next.js Web Chat app, so the TanStack Start installer doesn't ask about authentication.
|
|
38
38
|
|
|
39
|
-
The chat has the same URL-addressed durable sessions as the [Next.js Web Chat](./nextjs#
|
|
39
|
+
The chat has the same URL-addressed durable sessions as the [Next.js Web Chat](./nextjs#give-each-conversation-a-url): `/`, `/s`, and `/s/$sessionId`. Before accepting production browser traffic, replace the generated placeholder authorization policy. See [Authenticate browser requests](./overview#authenticate-browser-requests).
|
|
40
40
|
|
|
41
41
|
The installer doesn't support selecting a workspace agent for single-app hosting: a workspace agent always deploys as a separate Vercel service. If you already have a TanStack Start app, skip the installer and follow the steps below.
|
|
42
42
|
|