Threads and Eve sessions

An application thread is the stable product-facing conversation. An Eve session is the durable execution identity underneath a run.

Application thread
└── root Eve session
    ├── turns and steps
    ├── tool calls and input requests
    └── child Eve sessions created by specialist subagents

The public component API should use thread-oriented language where callers manage an ongoing application conversation. Internal bridge and reconciliation APIs retain precise Eve session identifiers.

A reset retires the exact Eve session. It must never silently send work to an unintended replacement session.

Application API

The installed server client supplies the namespace, so its operations use concise thread-oriented names:

export const eve = new ConvexEve(components.eve);

await eve.createThread(ctx, input);
await eve.sendMessage(ctx, input);
await eve.listMessages(ctx, input);

Applications do not also install @convex-dev/agent to manage these threads. convex-eve owns the application-facing history and realtime projections; Eve owns the agent execution and canonical session event stream.

React API

React helpers live under convex-eve/react. Because the import path already provides context, hooks describe the operation without repeating the product name:

import { useSendMessage, useUIMessages } from "convex-eve/react";

const { results, status, loadMore } = useUIMessages(
  api.chat.listMessages,
  { threadId },
  { initialNumItems: 20 },
);

Canonical application-domain types are simply Thread, Message, and MessagePart. The package import already provides the namespace, and consumers can alias an import when their application has a collision. Prefixes are reserved for genuinely source-specific types such as EveSessionEvent or protocol types such as BridgeCommandV1.

The persisted model remains independent from the AI SDK; optional conversion adapters can be provided from convex-eve/ai.