# Eve Bijection-native persistence and reactive chat projections for eve agents - Package: @bijectionhq/eve - Category: AI & Agents - Status: Preview - License: Apache-2.0 - Bijection source (repository access required): https://github.com/bijectionhq/eve/tree/4117e12dc1f6219c87eded2030d578eb7c647147/packages/convex-eve - Upstream: https://github.com/dciccale/convex-eve/tree/86dd5b6ed266e4888ba0569a7c648efecf10f396/packages/convex-eve - Documentation: https://docs.bijection.com/components/using - Directory: https://bijection.com/components/eve ## Get the source Bijection repository access is required. Request access at https://bijection.com/contact. ```sh git clone https://github.com/bijectionhq/eve.git cd eve git checkout 4117e12dc1f6219c87eded2030d578eb7c647147 cd packages/convex-eve ``` ## Before using this component Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute. ## Upstream package documentation Recorded 2026-10-23. This describes convex-eve; check the Bijection adaptation separately. convex-eve provides Convex-native persistence and reactive projections for agents built on the Eve agent harness. It handles threads, messages, UI parts, pagination, and approvals inside Convex while Eve retains authority over model loops, tools, skills, subagents, and durable workflows. The component exposes ingestion via exact (eveSessionId, streamIndex) coordinates for deduplication and offers a React hook for realtime message projection in application UIs. ### Use cases - Building a chat interface backed by an Eve agent where messages need to be stored in Convex and surfaced reactively to users without polling - Adding an approval workflow to an agentic system where pending tool calls must be captured and held before external delivery - Paginating conversation history for authenticated users when agent sessions can produce large message volumes - Integrating an Eve-hosted specialist subagent into an existing Convex application without adopting @convex-dev/agent - Displaying real-time tool activity and delegation state in an ops panel alongside a user-facing agent conversation ### How it works The component installs under `components.eve` in a Convex project and exposes a Convex action that bridges to a separately deployed Eve HTTP endpoint. Authentication between the Convex deployment and the Eve agent is handled via a shared `EVE_AGENT_TOKEN` secret set on both sides using `bunx convex env set`. The token stays within host Convex functions and is never written to component tables. Message ingestion uses `(eveSessionId, streamIndex)` coordinate pairs for exact deduplication, applying Eve's `defaultMessageReducer` semantics with bounded persistence sanitization. Pending messages are captured before external delivery, and the architecture is designed to eventually support Workpool-backed bounded delivery and catch-up reconciliation once that milestone lands. The `convex-eve/react` package exports a `useUIMessages` hook that subscribes to the reactive message projection, giving frontend components live updates as agent turns complete. The example application pairs a user-facing conversation panel with an operations panel showing tool calls, delegation events, approvals, and sync state. This is an alpha-stage component. Install with `convex-eve@next` for the implemented Eve-native persistence path. The `latest` tag is a placeholder. Delivery idempotency, reconciliation, and retention controls are not yet production-hardened. ### Upstream README # convex-eve An experimental open-source Convex Agent component backed by [eve](https://github.com/vercel/eve) agent harnesses. Eve remains the authority for agent execution: model loops, instructions, skills, tools, subagents, sandboxes, and durable workflows. The component provides Convex-native threads, messages, UI parts, pagination, approvals, and realtime projections for application-facing agent experiences. > [!WARNING] > This repository is in early development. The Eve-native persistence path is > implemented, but delivery idempotency, reconciliation, and retention controls > still need production hardening. Install the alpha implementation with > `convex-eve@next`; `latest` remains the `0.0.1` name-reservation placeholder. ## Repository ```text apps/ web/ Marketing site and Fumadocs documentation example/ Next.js performance coach example with Convex eve-agent/ Native Eve coach, skills, tools, and specialist subagents (port 2000) packages/ convex-eve/ Publishable Convex persistence and React package ``` The example uses a performance coach with training, nutrition, and recovery specialists. Its user-facing conversation is paired with an operations panel that demonstrates tool activity, delegation, approvals, queued commands, and synchronization state. ## Local development Requirements: - Bun 1.3.9 or newer - Access to a Convex project - An AI Gateway key or another model configuration supported by Eve when running real agent turns Install dependencies: ```bash bun install ``` The existing development deployment is configured in the ignored `apps/example/.env.local`. On another machine: ```bash cd apps/example bunx convex dev --configure existing ``` Individual services can also be started from the repository root: ```bash bun run dev:web bun run dev:example bun run dev:convex bun run dev:eve ``` The Convex action must reach the Eve HTTP deployment. For a complete local exercise, use a public development URL/tunnel for `apps/eve-agent`, or deploy it to Vercel, then configure the Convex deployment: ```bash cd apps/example bunx convex env set EVE_AGENT_URL https://your-eve-agent.vercel.app bunx convex env set EVE_AGENT_TOKEN replace-with-a-long-random-value ``` Set the same `EVE_AGENT_TOKEN` on the Eve deployment. The secret remains in host Convex functions and is never persisted in component tables. Portless exposes the marketing/docs site at `https://convex-eve.localhost` and the coach app at `https://convex-eve-example.localhost`, assigning their underlying ports automatically. The native Eve harness continues to use port `2000`. `bun run dev:example` starts only the Next.js frontend; use `bun run dev:convex` in a second terminal when changing Convex functions, or run `bun run --cwd apps/example dev` to start both. ## Vercel The hosted project uses two Vercel projects. The example remains source-only so adopters run it with their own Convex deployment and credentials: | Project | Root directory | Build command | Configuration | | --- | --- | --- | --- | | Marketing and docs | `apps/web` | auto-detected (`bun run build`) | Next.js preset | | Eve coach | `apps/eve-agent` | `bun run build` | Link with `bun run link`; Eve emits Vercel Build Output | Do not create a public Vercel project for `apps/example`. Run it locally after selecting a Convex development deployment and configuring that deployment with the Eve URL and shared service credential. The Eve project uses Vercel AI Gateway through project OIDC with the default `openai/gpt-5.6-luna` model and high reasoning. Luna requires paid AI Gateway credits; override `EVE_MODEL` for another Eve-supported model. Set `EVE_AGENT_TOKEN` on both the Eve Vercel project and the Convex deployment. The example's authored Eve channel accepts that service credential and Eve's native local-development authentication. ## Quality checks ```bash bun run check ``` This runs formatting-independent lint checks, TypeScript validation, tests, package compilation, the Fumadocs build, the Next.js example build, and the Eve agent build through Turborepo. ## Project status Available now: - Convex component installation under `components.eve` - Eve-native `Agent` binding without model or tool configuration - Authenticated application threads and paginated `EveMessage` projections - Pending-message capture before external delivery - Exact `(eveSessionId, streamIndex)` ingestion and coordinate deduplication - Eve `defaultMessageReducer` semantics with bounded persistence sanitization - `convex-eve/react` with `useUIMessages` - Native Eve performance coach example Next milestone: - Add bridge-level create/send idempotency - Use Workpool for bounded delivery and catch-up reconciliation - Add snapshot-based projection rebuilds and retention controls - Harden input-response delivery and session controls - Expand component state-machine integration tests See the [current v0.1 PRD](docs/convex-eve-agent-v0.1-prd.md) for the focused Eve-backed Agent architecture and implementation plan. The [original control-plane PRD](docs/convex-eve-v0.1-prd.md) is retained as design history and protocol research. ## Independence This project has no dependency on `@convex-dev/agent`. It is a community project and is not an official Convex or Vercel product. Licensed under Apache-2.0.