import type { MessageList } from '@mastra/core/agent';
import type { ObservabilityContext } from '@mastra/core/observability';
import type { ProcessorStreamWriter } from '@mastra/core/processors';
import type { RequestContext } from '@mastra/core/request-context';
import type { ObservationalMemoryRecord } from '@mastra/core/storage';
import type { ObservationalMemory } from '../observational-memory.js';
import type { MemoryContextProvider } from '../processor.js';
import type { ObservationModelContext } from '../types.js';
import { ObservationStep } from './step.js';
import type { ObservationTurnHooks, TurnContext, TurnResult } from './types.js';
/**
 * Represents a single turn in the agent conversation — one user message → agent response cycle.
 *
 * The turn manages record caching, context loading, and step lifecycle.
 * Create via `om.beginTurn(...)`, then call `start()` to load context,
 * `step(n)` to create steps, and `end()` to finalize.
 *
 * @example
 * ```ts
 * const turn = om.beginTurn({ threadId, resourceId, messageList });
 * await turn.start(memory);
 *
 * const step0 = turn.step(0);
 * const ctx = await step0.prepare();
 * // ... agent generates ...
 *
 * const step1 = turn.step(1);  // finalizes step 0
 * const ctx1 = await step1.prepare();
 * // ... agent generates ...
 *
 * await turn.end();  // finalizes last step, cleanup
 * ```
 */
export declare class ObservationTurn {
    private _record?;
    private _context?;
    private _currentStep?;
    private _started;
    private _ended;
    /** Generation count at turn start — used to detect if reflection happened during the turn. */
    private _generationCountAtStart;
    /** Memory context provider — set via start(). Used by steps for beforeBuffer persistence. */
    memory?: MemoryContextProvider;
    /** Optional stream writer for emitting markers. */
    writer?: ProcessorStreamWriter;
    /** Optional request context for observation calls. */
    requestContext?: RequestContext;
    /** Optional observability context for nested OM spans. */
    observabilityContext?: ObservabilityContext;
    /** Current actor model for this step. Updated by the processor before prepare(). */
    actorModelContext?: ObservationModelContext;
    /** Processor-provided hooks for turn/step lifecycle integration. */
    readonly hooks: ObservationTurnHooks;
    constructor(opts: {
        om: ObservationalMemory;
        threadId: string;
        resourceId?: string;
        messageList: MessageList;
        observabilityContext?: ObservabilityContext;
        hooks?: ObservationTurnHooks;
    });
    readonly om: ObservationalMemory;
    readonly threadId: string;
    readonly resourceId: string | undefined;
    readonly messageList: MessageList;
    /** The current cached record. Refreshed after mutations (activate/observe/reflect). */
    get record(): ObservationalMemoryRecord;
    /** The context loaded during start(). */
    get context(): TurnContext;
    /** The current step, if one exists. */
    get currentStep(): ObservationStep | undefined;
    addHooks(hooks?: ObservationTurnHooks): void;
    /**
     * Load context and cache the record. Call once at the start of the turn.
     *
     * If a MemoryContextProvider is passed, loads historical messages and adds
     * them to the MessageList. Without a provider, only fetches/caches the record.
     */
    start(memory?: MemoryContextProvider): Promise<TurnContext>;
    /**
     * Create a step handle. If a previous step exists, it is finalized
     * (its output messages will be saved at the start of the new step's prepare()).
     */
    step(stepNumber: number): ObservationStep;
    /**
     * Finalize the turn: save any remaining messages and return the latest record state.
     */
    end(): Promise<TurnResult>;
    /**
     * Refresh the cached record from storage. Called internally after mutations.
     * @internal
     */
    refreshRecord(): Promise<void>;
    /**
     * Refresh cross-thread context for resource scope. Called per-step.
     * @internal
     */
    refreshOtherThreadsContext(): Promise<string | undefined>;
}
//# sourceMappingURL=turn.d.ts.map