eve/dist/src/public/channels/eve.d.ts

Filesystem-first framework for durable backend AI agents that run anywhere.

import { type UserContent } from "ai";
import type { SessionAuthContext } from "#channel/types.js";
import { type AuthFn } from "#public/channels/auth.js";
import { type UploadPolicyInput } from "#public/channels/upload-policy.js";
import { type Channel, type ChannelEvents, type ChannelSessionOps } from "#public/definitions/defineChannel.js";
/**
 * Event-handler channel context exposed by `eveChannel({ events })`. The default eve HTTP channel
 * has no platform-specific state, so handlers receive session continuation operations plus the `SessionContext` third arg from {@link ChannelEvents}.
 */
export type EveEventContext = ChannelSessionOps;
/** Runtime stream-event handlers supported by `eveChannel({ events })`. */
export type EveChannelEvents = ChannelEvents<EveEventContext>;
/** Low-level eve HTTP handle exposed to `eveChannel({ onMessage })`. */
export interface EveHandle {
    /** Route-auth result for the request; `onMessage` chooses session auth by returning `{ auth }`. */
    readonly caller: SessionAuthContext | null;
    readonly request: Request;
    /** Existing runtime session id for continuation requests. */
    readonly sessionId?: string;
}
/** Pre-dispatch context passed to `eveChannel({ onMessage })`. */
export interface EveMessageContext {
    readonly eve: EveHandle;
}
/**
 * Result of `eveChannel({ onMessage })`. An object dispatches the inbound message,
 * optionally prepending `context` strings as user messages; `null` accepts without dispatching.
 */
export type EveMessageResult = {
    readonly auth: SessionAuthContext | null;
    readonly context?: readonly string[];
} | null;
/** Synchronous or asynchronous `onMessage` result. */
export type EveMessageResultOrPromise = EveMessageResult | Promise<EveMessageResult>;
/**
 * Default `onMessage` auth projection: returns {@link EveHandle.caller} unchanged as the
 * runtime session auth when {@link EveChannelInput.onMessage} is omitted. Call it from a custom `onMessage` to inherit the default while adding `context`.
 */
export declare function defaultEveAuth(ctx: EveMessageContext): SessionAuthContext | null;
/**
 * Configuration for {@link eveChannel}. Only {@link auth} is required;
 * `uploadPolicy`, `onMessage`, and `events` refine the default HTTP behavior.
 */
export interface EveChannelInput {
    /**
     * Route auth policy: a single {@link AuthFn} or an ordered array walked by {@link routeAuth}.
     * The first entry returning a {@link SessionAuthContext} wins; `null` / `undefined` skips to
     * the next; exhaustion (including the empty array) rejects with 401. Include `none()` last for anonymous traffic.
     */
    readonly auth: AuthFn<Request> | readonly AuthFn<Request>[];
    /**
     * Attachment policy for inbound file parts. Omit for the framework default (25 MB cap, all media
     * types); `"disabled"` rejects every attachment; a partial config is merged onto the default. Violations reject with 413 (too large) or 415 (bad type).
     */
    readonly uploadPolicy?: UploadPolicyInput;
    /**
     * Pre-dispatch hook for inbound eve HTTP messages. Runs after route auth and body
     * parsing, before runtime dispatch.
     */
    readonly onMessage?: (ctx: EveMessageContext, message: string | UserContent) => EveMessageResultOrPromise;
    /**
     * Runtime stream-event handlers for the default eve HTTP channel. Handlers receive
     * the event data, {@link EveEventContext}, and `SessionContext` (the same shape as custom channels).
     */
    readonly events?: EveChannelEvents;
}
/**
 * Concrete return type of {@link eveChannel}. Named so consumers can default-export an
 * `eveChannel(...)` call under `declaration: true` without TypeScript falling back to an
 * internal path for `Channel`.
 */
export interface EveChannel extends Channel {
}
/**
 * Builds the default eve HTTP channel: a {@link defineChannel} instance serving the
 * built-in `/eve/v1` routes (POST creates a session, POST delivers a follow-up, GET
 * streams a session's NDJSON event feed). Every route runs {@link EveChannelInput.auth}
 * via {@link routeAuth} before dispatching. Default-export the result as your
 * `agent/channels/eve.ts` channel; reach for {@link defineChannel} directly only for a custom transport.
 */
export declare function eveChannel(input: EveChannelInput): EveChannel;