eve/dist/src/public/definitions/channel.d.ts

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

import { type ChannelReference } from "#channel/compiled-channel.js";
import { type ChannelCorsOptions } from "#channel/cors.js";
import type { ChannelFrom, ChannelReceiveContext, ChannelResolveSession, ChannelRespondOptions, ChannelSendOptions, ChannelSource } from "#channel/channel-operations.js";
import type { RouteDefinition } from "#channel/routes.js";
import type { Session } from "#channel/session.js";
import type { TurnPolicy } from "#channel/types.js";
import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import type { SessionContext } from "#public/definitions/callback-context.js";
import type { GenericChannelDefinition, GenericReceiveInput } from "#shared/channel-definition.js";
declare const CHANNEL_METADATA_TYPE: unique symbol;
export type { CancelTurnResult, ClearSessionResult, CompactSessionResult, GetEventStreamOptions, ResetSessionResult, SessionCallback, TurnPolicy, } from "#channel/types.js";
export type { Session, SessionHandle } from "#channel/session.js";
export type { ChannelAudience, ChannelAudienceMetadata } from "#shared/channel-audience.js";
export type { SessionRespondOptions, SessionSendOptions } from "#channel/session.js";
export type { ChannelFrom, ChannelReceiveContext, ChannelResolveSession, ChannelRespondOptions, ChannelSendOptions, ChannelSource, };
export type { ChannelCors, ChannelCorsOptions } from "#channel/cors.js";
export { DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, WS } from "#channel/routes.js";
export type { AttachSessionFn, HttpRouteDefinition, RouteDefinition, RouteHandlerArgs, WebSocketMessage, WebSocketPeer, WebSocketRouteDefinition, WebSocketRouteHandler, WebSocketRouteHooks, WebSocketUpgradeRequest, WebSocketUpgradeResult, } from "#channel/routes.js";
/**
 * HTTP method a route handles. Defaults to `"POST"` — almost every route
 * is a webhook. Override only when authoring a non-webhook route such as a
 * long-poll endpoint or an event-stream reader.
 */
export type ChannelMethod = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS";
/**
 * Method-like discriminator used by compiled channel route entries.
 *
 * WebSocket routes are not HTTP methods, but they still need a stable
 * route key in the compiler manifest and runtime route table.
 */
export type ChannelRouteMethod = ChannelMethod | "WEBSOCKET";
/**
 * Per-request surface exposed to a route's `fetch` handler. The
 * framework constructs this per request and passes it as the second
 * argument.
 *
 * Framework callback routes use this for request metadata and background work.
 */
export interface RouteContext {
    /**
     * Hands a background promise to the request host so the serverless
     * invocation stays alive until the promise resolves. Use this when the
     * route responds to the platform immediately (e.g. a Slack `200 OK`
     * acknowledgement) but still needs to finish background work.
     */
    readonly waitUntil: (task: Promise<unknown>) => void;
    /**
     * Path parameter values extracted from `[name]` segments in the route's
     * filesystem path. For `agent/channels/sessions/[sessionId]/stream.ts`
     * mounted at `GET /sessions/:sessionId/stream`, the matched value lives at
     * `params.sessionId`.
     * Empty for routes with no path parameters.
     */
    readonly params: Readonly<Record<string, string>>;
    /**
     * Trusted peer IP for this request, extracted by the host transport
     * before the route handler runs. `null` when the host can't observe a
     * peer address (e.g. unit tests calling `route.fetch` directly).
     *
     * Pass this to {@link isIpAllowed} from `eve/channels/auth`
     * when implementing IP allowlisting in a route.
     */
    readonly requestIp: string | null;
}
/**
 * Marker discriminator written into every {@link DisabledRouteSentinel}.
 */
declare const DISABLED_ROUTE_SENTINEL_KIND = "eve:disabled-channel";
/**
 * Marker value returned from {@link disableRoute}. Export this as the
 * default export of a file in `agent/channels/` to remove the framework
 * default route whose logical name matches the file's slug path.
 */
export interface DisabledRouteSentinel {
    readonly kind: typeof DISABLED_ROUTE_SENTINEL_KIND;
}
/**
 * Returns a sentinel that disables the framework route whose logical name
 * matches the containing file's slug path.
 *
 * Export it as the default export of a file in `agent/channels/`.
 */
export declare function disableRoute(): DisabledRouteSentinel;
/**
 * Type guard: returns whether `value` is a {@link DisabledRouteSentinel}
 * produced by {@link disableRoute}.
 */
export declare function isDisabledRouteSentinel(value: unknown): value is DisabledRouteSentinel;
type EventData<T extends UnstampedMessageStreamEvent["type"]> = Extract<UnstampedMessageStreamEvent, {
    type: T;
}> extends {
    data: infer D;
} ? D : undefined;
/** Continuation routing on the `channel` argument of every channel event handler. */
export interface ChannelContinuationOps {
    readonly continuation?: {
        readonly token: string;
        rekey(token: string): void;
    };
}
/**
 * Channel context passed to event handlers: `TCtx` intersected with
 * {@link ChannelContinuationOps}.
 */
export type ChannelContext<TCtx> = TCtx & ChannelContinuationOps;
type ChannelEventHandler<T extends UnstampedMessageStreamEvent["type"], TCtx> = (data: EventData<T>, channel: ChannelContext<TCtx>, ctx: SessionContext) => void | Promise<void>;
type ChannelSessionFailedHandler<TCtx> = (data: EventData<"session.failed">, channel: ChannelContext<TCtx>) => void | Promise<void>;
/**
 * Optional handlers keyed by session lifecycle event name. Each handler receives
 * the event `data`, the {@link ChannelContext}, and a {@link SessionContext}
 * `ctx`. The `session.failed` handler is the exception: it receives only `data`
 * and the channel context, with no `ctx`; its data includes `sessionId`.
 */
export interface ChannelEvents<TCtx = void> {
    readonly "approval.candidate"?: ChannelEventHandler<"approval.candidate", TCtx>;
    readonly "approval.settled"?: ChannelEventHandler<"approval.settled", TCtx>;
    readonly "context.cleared"?: ChannelEventHandler<"context.cleared", TCtx>;
    readonly "compaction.requested"?: ChannelEventHandler<"compaction.requested", TCtx>;
    readonly "compaction.completed"?: ChannelEventHandler<"compaction.completed", TCtx>;
    readonly "turn.started"?: ChannelEventHandler<"turn.started", TCtx>;
    readonly "actions.requested"?: ChannelEventHandler<"actions.requested", TCtx>;
    readonly "action.partial"?: ChannelEventHandler<"action.partial", TCtx>;
    readonly "action.result"?: ChannelEventHandler<"action.result", TCtx>;
    readonly "message.completed"?: ChannelEventHandler<"message.completed", TCtx>;
    readonly "message.appended"?: ChannelEventHandler<"message.appended", TCtx>;
    readonly "reasoning.appended"?: ChannelEventHandler<"reasoning.appended", TCtx>;
    readonly "reasoning.completed"?: ChannelEventHandler<"reasoning.completed", TCtx>;
    readonly "input.requested"?: ChannelEventHandler<"input.requested", TCtx>;
    readonly "turn.failed"?: ChannelEventHandler<"turn.failed", TCtx>;
    readonly "turn.completed"?: ChannelEventHandler<"turn.completed", TCtx>;
    readonly "turn.cancelled"?: ChannelEventHandler<"turn.cancelled", TCtx>;
    readonly "session.failed"?: ChannelSessionFailedHandler<TCtx>;
    readonly "session.completed"?: ChannelEventHandler<"session.completed", TCtx>;
    readonly "session.waiting"?: ChannelEventHandler<"session.waiting", TCtx>;
    readonly "authorization.required"?: ChannelEventHandler<"authorization.required", TCtx>;
    readonly "authorization.completed"?: ChannelEventHandler<"authorization.completed", TCtx>;
}
/**
 * Input passed to a channel's `receive` callback when another channel or
 * schedule proactively routes a message to it.
 */
export type ReceiveInput<TReceiveTarget = Record<string, unknown>> = GenericReceiveInput<TReceiveTarget>;
/**
 * The object passed to {@link defineChannel}. `routes` is required; `state`
 * seeds durable adapter state, `context` builds the per-step `channel` argument
 * for `events` and `deliver`, `events` handle session lifecycle, `receive`
 * accepts cross-channel handoffs, `fetchFile` stages remote file URLs, and
 * `metadata` projects observability data.
 *
 * Generics: `TState` (adapter state), `TCtx` (context factory return type),
 * `TReceiveTarget` (cross-channel target shape), `TMetadata` (instrumentation
 * projection).
 */
export type ChannelDefinition<TState = undefined, TCtx = void, TReceiveTarget = Record<string, unknown>, TMetadata extends Record<string, unknown> = Record<string, unknown>> = GenericChannelDefinition<ChannelEvents<TCtx>, TState, TCtx, TReceiveTarget, TMetadata>;
/**
 * Opaque channel value produced by {@link defineChannel} and exported from
 * `agent/channels/<name>.ts`. Exposes the channel's routes, an optional
 * `receive` hook, and (via a phantom property) its metadata shape. Unlike
 * {@link ChannelDefinition} it has no `TCtx` parameter: the context type is
 * internal to the definition.
 */
export interface Channel<TState = undefined, TReceiveTarget = Record<string, unknown>, TMetadata extends Record<string, unknown> = Record<string, unknown>> extends ChannelReference<TReceiveTarget> {
    readonly [CHANNEL_METADATA_TYPE]?: TMetadata;
    readonly routes: readonly RouteDefinition<TState>[];
    readonly cors?: ChannelCorsOptions;
    readonly receive?: (input: ReceiveInput<TReceiveTarget>, ctx: ChannelReceiveContext<TState>) => Promise<Session>;
    readonly turnPolicy?: TurnPolicy;
}
/**
 * Extracts the metadata projection type (`TMetadata`) from a {@link Channel}.
 * Resolves to `Record<string, unknown>` when the value is not a Channel.
 */
export type InferChannelMetadata<TChannel> = TChannel extends Channel<any, any, infer TMetadata> ? TMetadata : Record<string, unknown>;
/**
 * Builds a {@link Channel} from a {@link ChannelDefinition}. Returns a value
 * placed at `agent/channels/<name>.ts`; the file path supplies the channel name
 * (do not add a `name` field). `TCtx` (the context factory's return type) is
 * internal to the definition and is not part of the returned Channel signature.
 */
export declare function defineChannel<TState = undefined, TCtx = void, TReceiveTarget = Record<string, unknown>, TMetadata extends Record<string, unknown> = Record<string, unknown>>(definition: ChannelDefinition<TState, TCtx, TReceiveTarget, TMetadata>): Channel<TState, TReceiveTarget, TMetadata>;