Eve Channel

Purpose and Scope

The Eve channel is the built-in HTTP surface for talking to an eve agent. It is the default channel used when local tools, browser integrations, SDK clients, terminal UI flows, or simple HTTP clients need to start a session, send a later turn, and consume streamed agent output. Unlike optional channel adapters for third-party systems, this channel represents the canonical eve-facing API. It is enabled even when a project has no explicit channel file, so new agents can accept standard session traffic without requiring authors to write routing code first.

Sources: docs/channels/eve.mdx

Most applications only add an Eve channel file when they need to change operational policy, especially authentication or CORS. The documented convention is to create an agent channel module and export a configured channel, but the docs also make clear that deleting the file returns the project to the default route set. That behavior matters for maintainers because the Eve channel is both a developer convenience and a production boundary: it is easy to expose, but it still needs an authorization policy that matches the deployment model.

Sources: docs/channels/eve.mdx

Relevant Source Files

• docs/channels/eve.mdx - First-party documentation for the Eve channel, including default behavior, route names, session examples, CORS behavior, and authentication guidance.
• packages/eve/src/public/channels/chat-sdk/index.ts - Public export barrel for chat SDK channel APIs and types, useful when comparing the native Eve HTTP channel with SDK-oriented chat channel integrations.
• packages/eve/src/channel/session.test.ts - Unit tests for the session handle behavior that underpins session identifiers, continuation tokens, current auth, initiator auth, and safe token updates.

System-to-Code Mapping

The documentation maps the Eve channel to an HTTP route family under the versioned Eve prefix. That route family exposes health and info endpoints, plus session creation, follow-up submission, and streaming. The same docs identify the normal callers: the terminal UI, browser hooks such as useEveAgent, curl, and SDK clients. In practice, this means the Eve channel is the protocol layer that higher-level frontends rely on, while agent authors continue to focus on instructions, tools, skills, and runtime behavior elsewhere in the filesystem.

Sources: docs/channels/eve.mdx

The chat SDK export file is much narrower than the Eve channel documentation, but it is still relevant to the channel landscape. It re-exports the public chatSdkChannel function and related types such as ChatSdkChannelConfig, ChatSdkChannelContext, ChatSdkChannelEvents, ChatSdkChannelState, and ChatSdkSendOptions. Treat those exports as the public SDK-facing chat channel surface, not as the route contract for the default Eve HTTP API. The distinction helps avoid mixing two concerns: the native Eve session API and bridge-style chat channel integrations.

Sources: packages/eve/src/public/channels/chat-sdk/index.ts

Session state is not only a transport concern. The session tests show that a session handle reads sessionId, continuationToken, current auth, and initiator auth from a live context container. The handle reflects later writes through getters, so consumers can observe updated continuation state without replacing the handle. This supports channel implementations that need to keep a durable session parked or resumed while still using the latest token and authentication information associated with the current turn.

Sources: packages/eve/src/channel/session.test.ts

Route Reference

The documented Eve channel route set is intentionally small and task-oriented. Health checks confirm that the server is reachable, info requests inspect agent metadata, session creation starts a new conversation, follow-up requests add another turn to an existing session, and the stream route emits newline-delimited events for a session. The route names are stable enough that clients, local development tooling, and frontend adapters can share one integration model instead of each inventing a separate endpoint shape for the same durable agent lifecycle.

Sources: docs/channels/eve.mdx

A minimal manual session begins with a POST request that includes a message. The response includes a sessionId and a continuationToken. The session identifier selects the durable conversation, while the continuation token is reused for follow-up turns so the framework can connect later traffic to the correct continuation point. The docs show this with curl because the Eve channel is just HTTP; the same route is what a browser hook or SDK client ultimately targets when it starts a conversation.

Sources: docs/channels/eve.mdx

curl -X POST https://<deployment>/eve/v1/session \
  -H "Content-Type: application/json" \
  -d '{"message":"What is the weather in Paris?"}'
# {"continuationToken":"eve:7f3c...","ok":true,"sessionId":"ses_01h..."}

Streaming is exposed as newline-delimited JSON rather than a single buffered response. Each line is one event object, which lets clients render progress as the run proceeds. The documented examples include turn start, message delta, and message completion events. A frontend reducer can fold those events into message state, while lower-level clients can process the raw stream directly. This is why the Eve channel serves both polished web chat surfaces and debugging flows that use only command-line HTTP tools.

Sources: docs/channels/eve.mdx

curl -N https://<deployment>/eve/v1/session/ses_01h.../stream
# {"type":"turn.started",...}
# {"type":"message.appended","data":{"messageDelta":"It is ",...}}
# {"type":"message.completed",...}

Configuration, CORS, and Auth

To customize the channel, create the conventional channel module and export an Eve channel configuration. The common example combines Vercel-issued deployment identity with local development access. This keeps local tooling useful while making production behavior explicit. The important operational point is that the built-in helpers are not a substitute for end-user authentication in a public app. They are infrastructure and development helpers; browser users, tenants, or external API clients need an application-specific verifier.

Sources: docs/channels/eve.mdx

import { eveChannel } from "eve/channels/eve";
import { localDev, vercelOidc } from "eve/channels/auth";
 
export default eveChannel({
  auth: [vercelOidc(), localDev()],
});

CORS is deliberately not changed by default. That is a safer baseline because many deployments route browser traffic through same-origin framework adapters or private service rewrites, where permissive cross-origin behavior is unnecessary. When a browser calls the Eve channel directly, enable CORS explicitly or provide a narrowed options object. The docs emphasize that CORS handling is separate from route authorization: preflight behavior can allow a browser to make the request, but auth still decides whether the actual session operation is allowed.

Sources: docs/channels/eve.mdx

import { eveChannel } from "eve/channels/eve";
import { localDev, vercelOidc } from "eve/channels/auth";
 
export default eveChannel({
  auth: [vercelOidc(), localDev()],
  cors: {
    origin: "https://app.example.com",
    methods: ["GET", "POST"],
    allowedHeaders: ["authorization", "content-type"],
  },
});

The scaffolded production story is intentionally conservative. The docs state that eve init can create an Eve channel file with a production placeholder, checking Vercel OIDC before localhost access and returning a setup-focused unauthorized response until real auth is installed. That pattern prevents a developer from accidentally treating development reachability as a public production policy. If you remove the file, the default helper set still does not admit normal browser users in production, so public applications must wire their own auth either way.

Sources: docs/channels/eve.mdx

Session Handle Behavior and Edge Cases

Continuation token handling is one of the important low-level behaviors behind channel integrations. The tests show a channel-local token update preserves the channel namespace already present in the placeholder token. For example, setting a local token when the context contains a namespaced Slack placeholder results in a namespaced continuation token rather than dropping the prefix. That same test suite also checks that calling the setter without an existing placeholder token throws a clear error, which protects channel authors from silently creating malformed continuation state.

Sources: packages/eve/src/channel/session.test.ts

The tests also cover idempotency. A redundant continuation-token update does not write back to context, while a changed token does write. The comment in the test explains the motivation: authors may call setContinuationToken from hot-path event handlers, and handlers cannot always know whether the token changed. Avoiding no-op writes prevents unnecessary workflow disruption, such as tearing down and recreating a park hook when nothing meaningful changed. This is a small implementation detail, but it directly supports stable long-running session delivery.

Sources: packages/eve/src/channel/session.test.ts

Authentication context is split between the current principal and the initiator principal. The session handle exposes both, based on values stored in the context container. That distinction is useful for channels because a request may be authenticated as a user while the runtime or application that initiated work has its own identity. The Eve channel documentation focuses on route-level auth policy, while the session tests show the runtime-facing shape that channel and workflow code can read once a request is admitted.

Sources: packages/eve/src/channel/session.test.ts

Practical Next Steps

Use the Eve channel whenever an integration needs standard HTTP access to an agent rather than a third-party messaging adapter. For local development, the defaults are usually enough. For production, decide whether clients are same-origin browser hooks, server-to-server callers, internal Vercel deployments, or public users, then configure auth and CORS accordingly. When building frontend chat, pair this page with the client and frontend documentation so the route flow, stream reducer, and deployment rewrites are understood as one end-to-end path.

Sources: docs/channels/eve.mdx, packages/eve/src/channel/session.test.ts