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

In 0.82.0, messages default to turnPolicy: "steer"; use "queue" to wait for the active turn to end. Steering messages from the current caller retain durable arrival order and may be combined at a boundary. Other callers' messages wait for the turn to end.

Use structured inputResponses with requestId to answer approvals unambiguously. A current caller's ordinary message that matches no approval option cancels that pending approval and steers, even with queue policy. Already-approved calls in the same batch may still run. turn.waiting does not end the turn; keep consuming the stream.

Validate x-eve-stream-version and reject unsupported contracts. Use the current client's normalization rather than combining older append events with current deltas manually.

Sessions, runs, and streaming.

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