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/channel.js";
import type { ChannelMethod } from "#public/definitions/channel.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>;
export interface EveChannelCorsOptions {
    /**
     * Allowed request origin. Pass a single origin string, an exact-origin list,
     * `"null"`, or `"*"`. Omit for `"*"`.
     */
    readonly origin?: "*" | "null" | string | readonly string[];
    /** Methods emitted on preflight responses. Omit for `"*"`. */
    readonly methods?: "*" | readonly ChannelMethod[];
    /** Request headers emitted on preflight responses. Omit for `"*"`. */
    readonly allowedHeaders?: "*" | readonly string[];
    /** Response headers exposed to browser callers. Omit for `"*"`. */
    readonly exposedHeaders?: "*" | readonly string[];
    /** Whether to emit `access-control-allow-credentials: true`. */
    readonly credentials?: boolean;
    /** Max age, in seconds, emitted on preflight responses. */
    readonly maxAge?: number | false;
    /** Preflight response status code. Defaults to 204. */
    readonly preflightStatus?: number;
}
/**
 * Higher-level CORS policy for the default eve HTTP channel. Pass `true` for
 * fully permissive browser access, or pass an options object to narrow it.
 */
export type EveChannelCors = boolean | EveChannelCorsOptions;
/** 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;
    /**
     * Browser CORS policy for the eve HTTP routes. Omit or pass `false` to leave
     * CORS untouched, pass `true` for fully permissive CORS, or pass an options
     * object to narrow the policy.
     */
    readonly cors?: EveChannelCors;
    /**
     * 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 (GET inspects the agent, POST creates a session, POST
 * delivers a follow-up, POST cancels the in-flight turn, 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;