Ch9. Channels, Auth, Streaming

If a channel is wrong, model quality and tool safety cannot save the system. Channels decide who can enter, which session they resume, and where results or human prompts are delivered.

Channel Responsibilities

The default Eve HTTP channel exposes POST /eve/v1/session, POST /eve/v1/session/:sessionId, and GET /eve/v1/session/:sessionId/stream.

Default Eve HTTP Channel

If you do not author agent/channels/eve.ts, Eve provides a framework default. You usually author the file to customize route auth.

import { eveChannel } from "eve/channels/eve";
import { localDev, vercelOidc } from "eve/channels/auth";

export default eveChannel({
  auth: [localDev(), vercelOidc()],
});

Official Auth & Route Protection distinguishes framework default from scaffolded auth:

placeholderAuth() is a guardrail, not a production auth policy.

Route Auth Fails Closed

Anonymous access requires explicit none().

Route Auth Is Not Session Ownership

If multiple users can call the same Eve route, you still need a session ownership check.

Danger:

any signed-in user -> Eve route
knows sessionId or continuationToken
can follow up or stream another tenant session

Recommended structure:

Continuation Token Is Not A Queue

continuationToken resumes the current session hook. It is not a FIFO queue. If many messages arrive concurrently, ordering must be handled outside Eve.

Operating patterns:

• send the next user turn after session.waiting
• use per-session queues for bursty chat platforms
• separate approval responses from new messages
• persist the latest session cursor and reject stale usage

NDJSON Stream

GET /eve/v1/session/:sessionId/stream returns newline-delimited JSON events.

Reasoning events and tool results may need privacy and retention controls.

Event Dispatch Order

1. Channel handler runs and updates adapter state.
2. Stream event is durably recorded.
3. Hooks run.
4. Dynamic tool/skill/instruction resolvers run.

This lets dynamic resolvers depend on channel metadata projected by channel handlers.

Custom Channels

import { defineChannel, POST } from "eve/channels";

export default defineChannel({
  routes: [
    POST("/incident", async (req, args) => {
      const incident = await req.json();
      args.waitUntil(
        args.send(`Investigate incident ${incident.id}`, {
          auth: {
            authenticator: "incident-service",
            principalType: "service",
            principalId: incident.actorId,
            attributes: { incidentId: incident.id },
          },
          continuationToken: `incident:${incident.id}`,
        }),
      );
      return new Response("ok");
    }),
  ],
});

Review:

• HMAC/JWT/OIDC raw request authentication
• never trust body-supplied principals
• constant-time signature comparison
• continuation token stability
• file upload fetch policy
• failure delivery

Official Channel Integrations

Client And Frontend

Use TypeScript SDK for scripts, tests, and server-to-server calls. Use frontend helpers for browser chat or agent UI.

Checklist