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

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

import type { TelemetryOptions } from "ai";
import type { InstrumentationEvents } from "#public/instrumentation/index.js";
import type { InstrumentationAttemptScope, InstrumentationContextRunner, InstrumentationHooks, InstrumentationSessionStartedEvent, InstrumentationTraceContext, InstrumentationTraceSeed, InstrumentationTurnStartedEvent } from "#instrumentation/lifecycle.js";
import { type BuildTelemetryRuntimeContextInput } from "#instrumentation/runtime-context.js";
import { type CreateInstrumentationHandleEventInput } from "#instrumentation/native-events.js";
import { type BackgroundTaskInstrumentation } from "#instrumentation/background-task-runtime.js";
import type { ResolvedInputBatch } from "#harness/input-requests.js";
import type { HandleEventFn } from "#harness/types.js";
import { type ChannelDeliveryStartInstrumentation, type ChannelDeliveryTerminalInstrumentation } from "#instrumentation/channel-delivery.js";
import { type PrepareTurnTraceContextInput } from "#instrumentation/prepare-trace-context.js";
import type { RuntimeTraceContext } from "#protocol/message.js";
import { AgentSpanIdGenerator } from "#tracing/agent-span-id-generator.js";
import type { OtelHarnessSettings, RuntimeContextResolver } from "#tracing/otel-declaration.js";
import { type ContextContainer } from "#context/container.js";
import { type MemoryInstrumentation } from "#instrumentation/memory.js";
import type { AgentSamplingOperation } from "#tracing/agent-span-contract.js";
interface InstrumentedStepSession {
    readonly sessionId: string;
    readonly state?: Readonly<Record<string, unknown>>;
}
export interface InstrumentationStepScope<TSession> {
    readonly createHandleEvent: (input: Omit<CreateInstrumentationHandleEventInput, "agentName" | "channelAudience" | "channelKind" | "hooks" | "parentLineage" | "parentTraceContext" | "rootSessionId" | "sessionId">) => HandleEventFn | undefined;
    readonly prepareAttempt: (input: {
        readonly attemptIndex: number;
        readonly runtimeContext?: Readonly<Record<string, unknown>>;
        readonly stepIndex: number;
        readonly turnId: string;
    }) => PreparedInstrumentationAttempt;
    readonly preparePreamble: (input: Omit<PrepareTurnTraceContextInput, "instrumentation" | "principals" | "session">) => Promise<RuntimeTraceContext | undefined>;
    readonly publishInputResolutions: (input: {
        readonly batch: ResolvedInputBatch;
        readonly sessionId: string;
    }) => Promise<void>;
    readonly recordError: (error: unknown) => void;
    readonly resolveRuntimeContext: (input: Omit<BuildTelemetryRuntimeContextInput, "capturesContent" | "context" | "providerResolvers" | "stepStartedResolver">) => Record<string, unknown> | undefined;
    readonly session: TSession;
    readonly setTurnId: (turnId: string) => void;
    readonly telemetry: () => TelemetryOptions | undefined;
    readonly traceContext?: InstrumentationTraceContext;
}
export interface PreparedInstrumentationAttempt {
    readonly complete: () => Promise<void>;
    readonly fail: (error: unknown) => Promise<void>;
    readonly scope: InstrumentationAttemptScope;
    readonly telemetry: TelemetryOptions | undefined;
}
export type InstrumentationAttempt = InstrumentationAttemptScope;
export interface BoundInstrumentationSession {
    readonly agentName: string;
    readonly rootSessionId: string;
    readonly sessionId: string;
}
/** Process-wide runtime consumed by every harness execution surface. */
export interface InstrumentationRuntime {
    /** Materializes settled invocation spans without draining the exporter pipeline. */
    readonly flushSettledInvocations?: () => Promise<void>;
    readonly forceFlush: () => Promise<void>;
    readonly hooks: InstrumentationHooks;
    readonly idGenerator?: AgentSpanIdGenerator;
    readonly instrumentationProviders?: boolean;
    readonly memoryOperations?: boolean;
    readonly ownsAgentSpans?: boolean;
    readonly prepareSessionTrace?: (event: InstrumentationSessionStartedEvent) => Promise<InstrumentationTraceSeed>;
    readonly prepareTurnTrace?: (event: InstrumentationTurnStartedEvent) => Promise<InstrumentationTraceSeed>;
    otelSettings: OtelHarnessSettings | undefined;
    readonly runtimeContextResolvers?: readonly RuntimeContextResolver[];
    readonly runInContext: InstrumentationContextRunner;
    /** Whether the installed OTel sampler would record a trace with this id. */
    readonly samplesTrace?: (traceId: string, operation?: AgentSamplingOperation) => boolean;
    readonly shutdown: () => Promise<void>;
    stepStartedRuntimeContextResolver?: InstrumentationEvents["step.started"];
}
/** Worker-bound instrumentation operations consumed by one session execution. */
export interface SessionInstrumentation {
    readonly runStep: <TSession extends InstrumentedStepSession, TResult>(input: {
        readonly environment: string;
        readonly eveVersion: string;
        readonly hasInput: boolean;
        readonly session: TSession;
    }, execute: (scope: InstrumentationStepScope<TSession>) => Promise<TResult>) => Promise<TResult>;
}
export interface ExecutionInstrumentation extends BackgroundTaskInstrumentation {
    readonly createHandleEvent: (input: {
        readonly handleEvent?: HandleEventFn;
        readonly turnId?: string;
    }) => HandleEventFn | undefined;
    readonly flush: () => Promise<void>;
    readonly instrumentChannelDelivery: (input: Omit<ChannelDeliveryStartInstrumentation, "hooks" | "policyAgentName"> | Omit<ChannelDeliveryTerminalInstrumentation, "hooks">) => Promise<void>;
    readonly memory?: MemoryInstrumentation;
    readonly prepareExecution: () => SessionInstrumentation;
    readonly preparePreamble: InstrumentationStepScope<never>["preparePreamble"];
}
export declare function bindInstrumentationRuntime(runtime: InstrumentationRuntime | undefined, ctx: ContextContainer, boundSession: BoundInstrumentationSession): ExecutionInstrumentation | undefined;
export declare function bindSessionInstrumentation(input: {
    readonly agentName: string;
    readonly ctx: ContextContainer;
    readonly rootSessionId: string;
    readonly sessionId: string;
}): ExecutionInstrumentation | undefined;
export declare function initializeSessionInstrumentation(input: {
    readonly agentName: string;
    readonly ctx: ContextContainer;
}): void;
/** Registers the process instrumentation runtime before agent execution begins. */
export declare function registerInstrumentationRuntime(runtime: InstrumentationRuntime): InstrumentationRuntime;
export declare function getInstrumentationRuntime(): InstrumentationRuntime | undefined;
export {};