eve/dist/src/instrumentation/state.d.ts

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

import { type JsonValue } from "#shared/json.js";
import type { InstrumentationAttemptScope } from "#instrumentation/lifecycle.js";
export { preserveSerializedInstrumentationState } from "#shared/serialized-observability-state.js";
export interface InstrumentationStateOwner {
    readonly attemptId?: string;
    readonly sessionId?: string;
    readonly turnId?: string;
}
/** One provider's view of its own state for one operation. */
export interface InstrumentationStateSlot {
    get(): JsonValue | undefined;
    /** Stages a value; `undefined` releases the slot. */
    set(value: JsonValue | undefined): void;
}
export interface InstrumentationStateLease extends InstrumentationStateSlot {
    /** Makes later reads empty and writes no-ops. */
    revoke(): void;
}
/**
 * Scopes state to one provider and one operation.
 *
 * Two providers handling the same event get separate slots, and the same
 * provider gets a separate slot per operation, so neither can read or clobber
 * the other's.
 */
export declare function instrumentationStateSlot(provider: string, idempotencyKey: string, owner?: InstrumentationStateOwner): InstrumentationStateLease;
/** Persists that a provider's start handler timed out for this operation. */
export declare function abandonInstrumentationState(provider: string, idempotencyKey: string, owner?: InstrumentationStateOwner): void;
export declare function isInstrumentationStateAbandoned(provider: string, idempotencyKey: string): boolean;
/** Releases one operation across namespaces, including providers no longer registered. */
export declare function releaseAllInstrumentationState(idempotencyKey: string): void;
/** Releases attempt-owned children across namespaces when their terminals are omitted. */
export declare function releaseAllInstrumentationAttemptState(attemptId: string): void;
export declare function releaseAllInstrumentationTurnState(sessionId: string, turnId?: string): void;
/** Remembers where a durable runtime action originated. */
export declare function rememberInstrumentationActionScope(idempotencyKey: string, scope: InstrumentationAttemptScope): void;
/** Remembers where a durable input request originated. */
export declare function rememberInstrumentationInputScope(idempotencyKey: string, scope: InstrumentationAttemptScope): void;
/** Reads and releases one durable input request's originating scope. */
export declare function takeInstrumentationInputScope(idempotencyKey: string): InstrumentationAttemptScope | undefined;
export interface InstrumentationActionCorrelation {
    readonly idempotencyKey: string;
    readonly scope: InstrumentationAttemptScope;
}
/** Binds an admitted background task to the action that started it. */
export declare function rememberInstrumentationBackgroundTask(taskId: string, correlation: InstrumentationActionCorrelation): void;
/** Binds a background task when its executor admits the originating call. */
export declare function rememberInstrumentationBackgroundTaskForCall(sessionId: string, callId: string, taskId: string): void;
export declare function findInstrumentationActionScopeForCall(sessionId: string, callId: string): InstrumentationActionCorrelation | undefined;
/** Reads and releases one durable runtime action's originating scope. */
export declare function takeInstrumentationActionScopeForCall(sessionId: string, callId: string): InstrumentationActionCorrelation | undefined;
/** Reads and releases the action correlation owned by a terminal background task. */
export declare function takeInstrumentationActionScopeForTask(taskId: string): InstrumentationActionCorrelation | undefined;
/** Takes every still-open action owned by one session or turn. */
export declare function takeInstrumentationActionScopes(sessionId: string, turnId?: string): readonly InstrumentationActionCorrelation[];