eve/dist/src/execution/durable-session-store.d.ts

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

import { type HarnessEmissionState } from "#harness/emission.js";
import type { HarnessModelMessage } from "#harness/messages.js";
import type { HarnessSession, SessionStateMap } from "#harness/types.js";
import type { SandboxState } from "#sandbox/state.js";
import type { JsonObject } from "#shared/json.js";
/** Explicit checkpoint contract shared by deployment handoffs. */
export declare const DURABLE_SESSION_VERSION = 1;
/**
 * Serializable handle to a durable session.
 *
 * Carries the current session snapshot plus the small projections the
 * workflow body needs without taking a step boundary: identity, the
 * hook continuation token,
 * `hasProxyInputRequests` (a closed-contract short-circuit that lets
 * the owner skip a per-delivery proxy-routing step when no
 * descendant subagent is active), and `emissionState` (so workflow-body
 * framework steps can stamp protocol events
 * with `{ turnId, sequence, stepIndex }` without reading the full
 * durable session). Turn steps return state transitions to the owning
 * `SessionStateCursor`; policy-only turn outcomes never carry snapshots.
 */
export interface DurableSessionState {
    readonly version: typeof DURABLE_SESSION_VERSION;
    readonly sessionId: string;
    readonly continuationToken: string;
    readonly hasProxyInputRequests: boolean;
    readonly emissionState: HarnessEmissionState;
    readonly snapshot: DurableSessionSnapshot;
}
/**
 * Durable projection of {@link HarnessSession} embedded in state
 * snapshots.
 *
 * Omits `agent.modelReference`, `agent.tools`,
 * `agent.compactionModelReference`, and the `compaction` thresholds —
 * those are rebuilt every turn from `bundle.turnAgent` by
 * {@link import("#execution/session.js").hydrateDurableSession}.
 * `agent.system` is the last applied prompt snapshot. Before each model step,
 * the execution layer replaces it from the current deployment's
 * `bundle.turnAgent`.
 */
export interface DurableSession {
    readonly sessionId: string;
    /**
     * Top user-facing session id in the dispatch chain. Optional because
     * a top-level session is its own root. Persisted so a rehydrated
     * subagent session still knows its root after a workflow step
     * boundary.
     */
    readonly rootSessionId?: string;
    readonly continuationToken: string;
    readonly history: HarnessModelMessage[];
    readonly limits?: HarnessSession["limits"];
    readonly outputSchema?: JsonObject;
    readonly state?: SessionStateMap;
    readonly sandboxState?: SandboxState;
    readonly taskId?: string;
    readonly agent: {
        readonly system: string;
    };
    readonly compaction?: {
        readonly lastKnownInputTokens?: number;
        readonly lastKnownPromptMessageCount?: number;
    };
}
/** Session program memory persisted atomically with Workflow step results. */
export interface DurableSessionSnapshot {
    readonly session: DurableSession;
}
/** Reads only the embedded checkpoint; no stream or migration fallback exists. */
export declare function readDurableSession(state: DurableSessionState): DurableSession;
/**
 * Creates the projected {@link DurableSessionState} with the current
 * snapshot embedded in the Workflow step result.
 */
export declare function createDurableSessionState(input: {
    readonly session: HarnessSession;
}): DurableSessionState;
/** Replaces session program memory and refreshes its workflow projections. */
export declare function replaceDurableSessionSnapshot(input: {
    readonly session: DurableSession;
    readonly state: DurableSessionState;
}): DurableSessionState;