eve
Version:
Filesystem-first framework for durable backend AI agents that run anywhere.
83 lines (82 loc) • 3.77 kB
TypeScript
import { type EveAgentStoreCallbacks, type EveAgentStoreSnapshot, type EveAgentStoreStatus, type PrepareSend } from "#client/eve-agent-store.js";
import type { EveAgentReducer } from "#client/reducer.js";
import type { ClientSession } from "#client/session.js";
import { type EveMessageData } from "#client/message-reducer.js";
import type { HandleMessageStreamEvent } from "#protocol/message.js";
import type { ClientAuth, HeadersValue, SendTurnPayload, SessionState } from "#client/types.js";
export type { PrepareSend };
/**
* Lifecycle status of an eve agent session.
*
* - `"ready"`: idle, accepting a new turn.
* - `"submitted"`: a turn was sent, no stream events received yet.
* - `"streaming"`: stream events are arriving for the active turn.
* - `"error"`: the last turn ended in a terminal failure (see `snapshot.error`).
*/
export type UseEveAgentStatus = EveAgentStoreStatus;
/**
* Snapshot of an eve agent session: `data` (the reducer projection), `events`
* (the authoritative server stream), `session` (resumable cursor), `status`,
* and `error`.
*/
export type UseEveAgentSnapshot<TData> = EveAgentStoreSnapshot<TData>;
/**
* Snapshot plus commands returned by `useEveAgent`.
*/
export interface UseEveAgentHelpers<TData> extends UseEveAgentSnapshot<TData> {
/** Resets the session: aborts any in-flight turn, recreates the owned session, and clears events and projected data. */
readonly reset: () => void;
/** Sends a turn (message, HITL responses, and/or client context). Rejects if a turn is already in flight. */
readonly send: <TOutput = unknown>(input: SendTurnPayload<TOutput>) => Promise<void>;
/** Aborts the in-flight turn's stream, if any. */
readonly stop: () => void;
}
/**
* Configuration for creating or binding a React eve agent session.
*
* Session configuration is read when the hook creates its internal store;
* remount the component to point at a different host, reducer, or session.
* Lifecycle callbacks update on every render.
*
* For credentials or headers that must change without remounting, pass function
* values to `auth` or `headers`; the client resolves those before each request.
*/
export interface UseEveAgentOptions<TData> extends EveAgentStoreCallbacks<TData> {
/**
* Named agent mounted by a framework integration such as `withEve({ agents })`.
*
* `agent: "support"` targets same-origin routes under
* `/eve/agents/support/eve/v1/...`. Do not combine with `host`.
*/
readonly agent?: string;
readonly auth?: ClientAuth;
readonly headers?: HeadersValue;
/**
* Base URL for eve client requests. Do not combine with `agent`.
*
* Defaults to same-origin eve routes such as `/eve/v1/...`. Pass a same-origin
* prefix such as `/api` for an app-owned proxy, or an absolute origin to talk
* to an eve server directly.
*
* @default ""
*/
readonly host?: string;
readonly initialEvents?: readonly HandleMessageStreamEvent[];
readonly initialSession?: SessionState;
/**
* Project submitted user messages before eve confirms them with a
* `message.received` stream event.
*
* Optimistic events are reducer-facing projection events only. They are not
* exposed through `events`, which remains the authoritative eve stream.
*
* @default true
*/
readonly optimistic?: boolean;
readonly reducer?: EveAgentReducer<TData>;
readonly session?: ClientSession;
}
export declare function useEveAgent(options?: UseEveAgentOptions<EveMessageData>): UseEveAgentHelpers<EveMessageData>;
export declare function useEveAgent<TData>(options: UseEveAgentOptions<TData> & {
readonly reducer: EveAgentReducer<TData>;
}): UseEveAgentHelpers<TData>;