eve/dist/src/shared/conversation-context.d.ts

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

import type { InstrumentationChannelKind } from "#public/channels/index.js";
import { ContextKey } from "#context/key.js";
import { type ChannelAudience } from "#shared/channel-audience.js";
import type { RunMode } from "#shared/run-mode.js";
import type { ForwardedTraceAssertion } from "#shared/forwarded-trace-policy.js";
export type ConversationEnvironment = "development" | "preview" | "production";
export interface ConversationContext {
    readonly channel: {
        readonly kind: InstrumentationChannelKind;
        readonly name?: string;
    };
    readonly audience: ChannelAudience;
    readonly mode: RunMode;
    readonly environment: ConversationEnvironment;
    readonly principalType: string;
}
export interface AudiencePrincipal {
    readonly principalType: string;
    readonly authenticator: string;
    readonly attributes: Readonly<Record<string, string | readonly string[]>>;
}
export type AudienceCaller = {
    readonly type: "anonymous";
} | {
    readonly type: "principal";
    readonly principal: {
        readonly kind: string;
        readonly authenticator: string;
        readonly attributes: Readonly<Record<string, string | readonly string[]>>;
    };
};
export interface AudienceInput<TState> {
    readonly state: TState;
    /** @deprecated Use `caller`; it excludes `principalId`, `issuer`, and `subject`. */
    readonly auth: AudiencePrincipal | null;
    readonly channel: ConversationContext["channel"];
    readonly mode: RunMode;
    readonly environment: ConversationEnvironment;
}
/** Preferred input type for new audience callback annotations. */
export interface AudienceContext<TState> extends AudienceInput<TState> {
    readonly caller: AudienceCaller;
}
/** Safe projection for durable sessions created before `eve.conversation` existed. */
export declare const UNKNOWN_CONVERSATION_CONTEXT: ConversationContext;
export interface ConversationContextFallback {
    readonly channelKind?: string;
    readonly environment: ConversationEnvironment;
    readonly forwardedTracePolicy?: ForwardedTraceAssertion;
    readonly mode?: RunMode;
    readonly principalType?: string;
}
/**
 * Reconstructs a durable conversation when its key predates the key itself.
 * All callers must use this helper so legacy sessions resolve privacy fields
 * from one source of truth.
 */
export declare function resolveConversationContext(stored: ConversationContext | undefined, fallback: ConversationContextFallback, options?: {
    readonly forwardedOverridesStored?: boolean;
}): ConversationContext;
export declare const ConversationContextKey: ContextKey<ConversationContext>;
export declare function normalizeConversationContext(value: unknown): ConversationContext | undefined;