eve/dist/src/client/session.d.ts

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

import type { HandleMessageStreamEvent } from "#protocol/message.js";
import { MessageResponse } from "#client/message-response.js";
import type { CancelSessionResult, ClientRedirectPolicy, SendTurnInput, SessionState, StreamOptions } from "#client/types.js";
/**
 * Internal interface that a {@link ClientSession} uses to access client-level
 * configuration without depending on the full {@link Client} class.
 */
interface SessionContext {
    readonly host: string;
    readonly preserveCompletedSessions: boolean;
    readonly redirect?: ClientRedirectPolicy;
    resolveHeaders(perRequest?: Readonly<Record<string, string>>): Promise<Headers>;
}
/**
 * One conversation with an eve agent.
 *
 * A session tracks conversation state (continuation token, session ID, stream
 * cursor) automatically across {@link send} calls. Read the state from
 * the {@link state} getter and serialize it to persist a session.
 */
export declare class ClientSession {
    #private;
    /** @internal */
    constructor(context: SessionContext, state: SessionState);
    /**
     * Current session cursor. The assigned session ID appears as soon as a send
     * is accepted; the continuation token and stream index advance as its event
     * stream is consumed. Serialize this to persist and resume later.
     */
    get state(): SessionState;
    /**
     * Sends one turn payload to the agent.
     *
     * Pass a string as shorthand for `{ message }`, or pass an object to submit
     * follow-up text, HITL results, client context, output schema, signal, and
     * headers in a single request.
     */
    send<TOutput = unknown>(input: SendTurnInput<TOutput>): Promise<MessageResponse<TOutput>>;
    /**
     * Requests cooperative cancellation of this session's active turn.
     *
     * Both `accepted` and `no_active_turn` are successful outcomes. The latter
     * means the active turn settled before the request arrived or the session is
     * already parked. `turnId` limits the request to the turn the caller
     * observed; a stale guard is consumed as a benign no-op. Credentials are
     * resolved immediately before the request.
     *
     * @throws {Error} If this handle has not started or attached to a session.
     * @throws {ClientError} If the cancel route returns a non-successful status.
     */
    cancel(options?: {
        turnId?: string;
    }): Promise<CancelSessionResult>;
    /**
     * Opens this session's event stream for the current session ID.
     *
     * Resumes from the session's stored stream cursor unless `options.startIndex`
     * overrides it. By default, the stream reconnects from its cursor when the
     * connection ends; pass `streamReconnectPolicy: { reconnect: false }` to use
     * one connection. Negative indices read relative to the current tail on one connection
     * and do not advance the stored absolute cursor.
     *
     * @throws {Error} If the session has no session ID (no message has been sent
     *   yet).
     */
    stream(options?: StreamOptions): AsyncIterable<HandleMessageStreamEvent>;
}
export {};