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

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

import type { UserContent } from "ai";
import type { StandardJSONSchemaV1 } from "#compiled/@standard-schema/spec/index.js";
import type { HandleMessageStreamEvent } from "#protocol/message.js";
import type { CancelTurnStatus } from "#protocol/cancel-turn.js";
import type { InputRequest, InputResponse } from "#runtime/input/types.js";
import type { JsonObject } from "#shared/json.js";
export type { AgentInfoChannelEntry, AgentInfoChannels, AgentInfoConnectionEntry, AgentInfoDynamicResolverEntry, AgentInfoEntry, AgentInfoFrameworkChannelEntry, AgentInfoFrameworkToolEntry, AgentInfoHookEntry, AgentInfoInstructions, AgentInfoInstructionsEntry, AgentInfoResult, AgentInfoSandboxEntry, AgentInfoScheduleEntry, AgentInfoSkillEntry, AgentInfoSource, AgentInfoSubagentEntry, AgentInfoToolEntry, AgentInfoTools, } from "./agent-info-schema.js";
/**
 * Static credential value or per-request credential resolver.
 */
export type TokenValue = string | (() => string | Promise<string>);
/**
 * Static custom-headers map or per-request resolver.
 *
 * When a function is provided, it is invoked before every HTTP call so
 * callers can return short-lived values (e.g. refreshed bypass tokens)
 * without rebuilding the client.
 */
export type HeadersValue = Readonly<Record<string, string>> | (() => Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>);
/**
 * Authentication configuration for the client.
 */
export type ClientAuth = {
    readonly basic: {
        readonly username: string;
        readonly password: TokenValue;
    };
} | {
    readonly bearer: TokenValue;
} | {
    readonly vercelOidc: {
        readonly token: TokenValue;
    };
};
/**
 * Vercel header that presents a trusted OIDC token as proof the caller is
 * authorized for a protected deployment. The client emits it alongside
 * `Authorization` for the {@link ClientAuth} `vercelOidc` variant.
 */
export declare const VERCEL_TRUSTED_OIDC_IDP_TOKEN_HEADER = "x-vercel-trusted-oidc-idp-token";
/** Redirect modes supported by the configured fetch implementation. */
export type ClientRedirectPolicy = NonNullable<RequestInit["redirect"]>;
/**
 * Configuration for creating a new {@link Client}.
 */
export interface ClientOptions {
    /**
     * Base URL of the eve agent server. Query parameters are included on every
     * request; request-specific parameters override parameters with the same name.
     */
    readonly host: string;
    /**
     * Authentication configuration. The client resolves credentials before each
     * request, so token-refresh callbacks are called on every HTTP call.
     */
    readonly auth?: ClientAuth;
    /**
     * Custom headers sent with every request. Pass a function to resolve
     * the headers fresh for each request (useful for short-lived tokens
     * that need to be refreshed alongside the bearer credential).
     */
    readonly headers?: HeadersValue;
    /**
     * Redirect policy for every request, including streams. Overrides a
     * per-request `RequestInit.redirect`. Credential-bearing clients should use
     * `"manual"` or `"error"` so custom auth headers can't follow a cross-origin
     * redirect.
     */
    readonly redirect?: ClientRedirectPolicy;
    /**
     * Keep a session's continuation token after a normal `session.completed`
     * boundary.
     *
     * By default, completed turns reset the client-side session so the next
     * `send()` starts a fresh server-side conversation. Interactive clients can
     * set this to preserve durable session state, including framework-managed
     * sandbox state, across follow-up prompts until they explicitly create a new
     * session.
     *
     * @default false
     */
    readonly preserveCompletedSessions?: boolean;
}
/**
 * Input payload for {@link ClientSession.send}. Pass a string as shorthand for
 * `{ message: string }`, or pass an object to include a message, HITL input
 * responses, one-turn client context, structured-output schema, abort signal,
 * and per-turn headers.
 */
export type SendTurnInput<TOutput = unknown> = string | SendTurnPayload<TOutput>;
/**
 * Object form accepted by {@link ClientSession.send}.
 */
export interface SendTurnPayload<TOutput = unknown> {
    /**
     * Ephemeral client/page context for the next model call only.
     *
     * Strings are rendered as user-role model context messages. Objects are
     * JSON-serialized into one user-role model context message. Client context
     * rides along with a message or HITL response; it does not dispatch a turn by
     * itself and is never persisted to durable session history.
     */
    readonly clientContext?: string | readonly string[] | JsonObject;
    /**
     * HITL responses resolving pending approvals or questions.
     */
    readonly inputResponses?: readonly InputResponse[];
    /**
     * Optional follow-up user message for the same turn.
     */
    readonly message?: string | UserContent;
    /**
     * Optional schema the harness must satisfy before this turn terminates.
     *
     * The client lowers Standard Schema implementations (Zod, Valibot,
     * ArkType, etc.) to JSON Schema before sending the request. The server is
     * authoritative for validation; {@link MessageResult.data} is typed to this
     * schema's output type and is not revalidated client-side.
     */
    readonly outputSchema?: StandardJSONSchemaV1<unknown, TOutput> | JsonObject;
    /**
     * Reconnection policy for the response event stream. Omit to use the default
     * policy, or pass `{ reconnect: false }` when the caller owns cursor recovery.
     */
    readonly streamReconnectPolicy?: StreamReconnectPolicy;
    /**
     * Abort signal for cancelling the request.
     */
    readonly signal?: AbortSignal;
    /**
     * Additional headers for this request only.
     */
    readonly headers?: Readonly<Record<string, string>>;
}
/** Retry and backoff settings for one kind of stream reconnection. */
export interface StreamReconnectRetryPolicy {
    /** Initial delay before retrying, in milliseconds. */
    readonly baseDelayMs?: number;
    /** Maximum number of attempts governed by this retry policy. */
    readonly maxAttempts?: number;
    /** Maximum delay between retries, in milliseconds. */
    readonly maxDelayMs?: number;
}
/** Configurable policy used when automatic stream reconnection is enabled. */
export interface ResolvedStreamReconnectPolicy {
    /** Retry policy for opening an HTTP stream connection. */
    readonly streamOpenReconnectPolicy?: StreamReconnectRetryPolicy;
    /** Retry policy for reconnecting streams that make no progress. */
    readonly streamIdleReconnectPolicy?: StreamReconnectRetryPolicy;
    /** HTTP response statuses that may be retried while opening a stream. */
    readonly retryableErrorStatuses?: readonly number[];
}
/** Automatic stream reconnection configuration. */
export type StreamReconnectPolicy = ResolvedStreamReconnectPolicy | {
    readonly reconnect: false;
};
/**
 * Options for {@link ClientSession.stream}.
 */
export interface StreamOptions {
    /**
     * Reconnection policy for the event stream. Omit to use the default policy,
     * or pass `{ reconnect: false }` when the caller owns cursor recovery.
     */
    readonly streamReconnectPolicy?: StreamReconnectPolicy;
    /**
     * Absolute event index to start from. Negative values read relative to the
     * current tail (`-1` starts at the latest event). Relative-tail streams do
     * not reconnect automatically because their absolute cursor is unknown.
     */
    readonly startIndex?: number;
    /**
     * Abort signal for cancelling the stream.
     */
    readonly signal?: AbortSignal;
}
/** Result of requesting cancellation for a client session's active turn. */
export interface CancelSessionResult {
    /** Session whose active turn was targeted. */
    readonly sessionId: string;
    /** Both outcomes are successful; `no_active_turn` means there was nothing left to cancel. */
    readonly status: CancelTurnStatus;
}
/**
 * Aggregated result of one message turn, returned by
 * {@link MessageResponse.result}.
 */
export interface MessageResult<TOutput = unknown> {
    /**
     * Final structured result emitted by the harness, when this turn requested
     * an output schema and the server fulfilled it.
     */
    readonly data: TOutput | undefined;
    /**
     * The final completed assistant message text, or `undefined` if no terminal
     * `message.completed` event was observed.
     */
    readonly message: string | undefined;
    /**
     * All events received during this turn.
     */
    readonly events: HandleMessageStreamEvent[];
    /**
     * HITL input requests emitted during this turn.
     */
    readonly inputRequests: readonly InputRequest[];
    /**
     * The session ID for this turn. Always populated; the post-turn handler
     * rejects responses that do not assign a session id.
     */
    readonly sessionId: string;
    /**
     * How the turn ended.
     *
     * - `"completed"`: the session finished (`session.completed`).
     * - `"waiting"`: the session is parked for the next user message
     *   (`session.waiting`).
     * - `"failed"`: the session ended in a terminal failure (`session.failed`).
     */
    readonly status: "completed" | "failed" | "waiting";
}
/**
 * Response from the health endpoint.
 */
export interface HealthResult {
    readonly ok: true;
    readonly status: "ready";
    readonly workflowId: string;
}
/**
 * Serializable session cursor. Persist this value and pass it back to
 * {@link Client.session} to resume a conversation later.
 */
export interface SessionState {
    readonly continuationToken?: string;
    readonly sessionId?: string;
    readonly streamIndex: number;
}