@mastra/memory 1.10.0 → 1.10.1-alpha.1

package/dist/processors/observational-memory/observation-strategies/base.d.ts

@@ -0,0 +1,102 @@
+import type { MastraDBMessage, MessageList } from '@mastra/core/agent';
+import type { MessageHistory } from '@mastra/core/processors';
+import type { MemoryStorage } from '@mastra/core/storage';
+import type { ObserverRunner } from '../observer-runner.js';
+import type { ReflectorRunner } from '../reflector-runner.js';
+import type { TokenCounter } from '../token-counter.js';
+import type { ObservationDebugEvent, ObservationMarkerConfig, ResolvedObservationConfig, ResolvedReflectionConfig } from '../types.js';
+import type { ObservationRunOpts, ObserverOutput, ProcessedObservation } from './types.js';
+/**
+ * Dependencies injected into observation strategies.
+ * Built by the factory in index.ts from the ObservationalMemory instance.
+ */
+export interface StrategyDeps {
+    storage: MemoryStorage;
+    messageHistory: MessageHistory;
+    tokenCounter: TokenCounter;
+    observationConfig: ResolvedObservationConfig;
+    reflectionConfig: ResolvedReflectionConfig;
+    scope: 'thread' | 'resource';
+    retrieval: boolean;
+    observer: ObserverRunner;
+    reflector: ReflectorRunner;
+    observedMessageIds: Set<string>;
+    obscureThreadIds: boolean;
+    emitDebugEvent: (event: ObservationDebugEvent) => void;
+}
+/**
+ * Abstract base class for observation strategies.
+ *
+ * Each strategy implements the phases of the observation lifecycle
+ * (prepare → observe → process → persist) while the base class handles
+ * the shared orchestration (lock guard, marker emission, reflection, error handling).
+ */
+export declare abstract class ObservationStrategy {
+    protected readonly deps: StrategyDeps;
+    protected readonly opts: ObservationRunOpts;
+    protected readonly storage: MemoryStorage;
+    protected readonly messageHistory: MessageHistory;
+    protected readonly tokenCounter: TokenCounter;
+    protected readonly observationConfig: ResolvedObservationConfig;
+    protected readonly reflectionConfig: ResolvedReflectionConfig;
+    protected readonly scope: 'thread' | 'resource';
+    protected readonly retrieval: boolean;
+    /** Select the right strategy based on scope and mode. Wired up by index.ts. */
+    static create: (om: unknown, opts: ObservationRunOpts) => ObservationStrategy;
+    constructor(deps: StrategyDeps, opts: ObservationRunOpts);
+    /** Run the full observation lifecycle. */
+    run(): Promise<void>;
+    protected generateCycleId(): string;
+    protected streamMarker(marker: {
+        type: string;
+        data: unknown;
+    }): Promise<void>;
+    protected getObservationMarkerConfig(): ObservationMarkerConfig;
+    protected getMaxMessageTimestamp(messages: MastraDBMessage[]): Date;
+    /**
+     * Wrap observations in a thread attribution tag.
+     * In resource scope, thread IDs can be obscured via xxhash.
+     */
+    protected wrapWithThreadTag(threadId: string, observations: string, messageRange?: string): Promise<string>;
+    /**
+     * Create a message boundary delimiter with an ISO 8601 date.
+     * Used to separate observation chunks for cache stability.
+     */
+    protected static createMessageBoundary(date: Date): string;
+    /**
+     * Wrap raw observations — in resource scope, wraps with thread tag and merges;
+     * in thread scope, simply appends with a message boundary delimiter.
+     */
+    protected wrapObservations(rawObservations: string, existingObservations: string, threadId: string, lastObservedAt?: Date, messageRange?: string): Promise<string> | string;
+    protected replaceOrAppendThreadSection(existingObservations: string, _threadId: string, newThreadSection: string, lastObservedAt?: Date): string;
+    /**
+     * Persist a marker to the last assistant message in storage.
+     * Fetches messages directly from the DB so it works even when
+     * no MessageList is available (e.g. async buffering ops).
+     */
+    protected persistMarkerToStorage(marker: {
+        type: string;
+        data: unknown;
+    }, threadId: string, resourceId?: string): Promise<void>;
+    /**
+     * Persist a marker part on the last assistant message in a MessageList
+     * AND save the updated message to the DB.
+     */
+    protected persistMarkerToMessage(marker: {
+        type: string;
+        data: unknown;
+    }, messageList: MessageList | undefined, threadId: string, resourceId?: string): Promise<void>;
+    abstract get needsLock(): boolean;
+    abstract get needsReflection(): boolean;
+    abstract prepare(): Promise<{
+        messages: MastraDBMessage[];
+        existingObservations: string;
+    }>;
+    abstract observe(existingObservations: string, messages: MastraDBMessage[]): Promise<ObserverOutput>;
+    abstract process(output: ObserverOutput, existingObservations: string): Promise<ProcessedObservation>;
+    abstract persist(processed: ProcessedObservation): Promise<void>;
+    abstract emitStartMarkers(cycleId: string): Promise<void>;
+    abstract emitEndMarkers(cycleId: string, processed: ProcessedObservation): Promise<void>;
+    abstract emitFailedMarkers(cycleId: string, error: unknown): Promise<void>;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/processors/observational-memory/observation-strategies/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../../src/processors/observational-memory/observation-strategies/base.ts"],"names":[],"mappings":"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"}

package/dist/processors/observational-memory/observation-strategies/index.d.ts

@@ -0,0 +1,7 @@
+export { ObservationStrategy } from './base.js';
+export type { StrategyDeps } from './base.js';
+export type { ObservationRunOpts, ObserverOutput, ProcessedObservation } from './types.js';
+export { SyncObservationStrategy } from './sync.js';
+export { AsyncBufferObservationStrategy } from './async-buffer.js';
+export { ResourceScopedObservationStrategy } from './resource-scoped.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/processors/observational-memory/observation-strategies/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/processors/observational-memory/observation-strategies/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAC7C,YAAY,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAC3C,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAGxF,OAAO,EAAE,uBAAuB,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,EAAE,8BAA8B,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,iCAAiC,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/processors/observational-memory/observation-strategies/resource-scoped.d.ts

@@ -0,0 +1,39 @@
+import type { MastraDBMessage } from '@mastra/core/agent';
+import { ObservationStrategy } from './base.js';
+import type { StrategyDeps } from './base.js';
+import type { ObservationRunOpts, ObserverOutput, ProcessedObservation } from './types.js';
+export declare class ResourceScopedObservationStrategy extends ObservationStrategy {
+    private readonly startedAt;
+    private cycleId?;
+    private readonly resourceId;
+    private threadsWithMessages;
+    private threadTokensToObserve;
+    private threadTokenCounts;
+    private threadOrder;
+    private messagesByThread;
+    private multiThreadResults;
+    private totalBatchUsage;
+    private observationResults;
+    private priorMetadataByThread;
+    constructor(deps: StrategyDeps, opts: ObservationRunOpts);
+    get needsLock(): boolean;
+    get needsReflection(): boolean;
+    prepare(): Promise<{
+        messages: MastraDBMessage[];
+        existingObservations: string;
+    }>;
+    emitStartMarkers(cycleId: string): Promise<void>;
+    observe(_existingObservations: string, _messages: MastraDBMessage[]): Promise<{
+        observations: string;
+        usage: {
+            inputTokens: number;
+            outputTokens: number;
+            totalTokens: number;
+        } | undefined;
+    }>;
+    process(_output: ObserverOutput, existingObservations: string): Promise<ProcessedObservation>;
+    persist(processed: ProcessedObservation): Promise<void>;
+    emitEndMarkers(cycleId: string, processed: ProcessedObservation): Promise<void>;
+    emitFailedMarkers(cycleId: string, error: unknown): Promise<void>;
+}
+//# sourceMappingURL=resource-scoped.d.ts.map

package/dist/processors/observational-memory/observation-strategies/resource-scoped.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-scoped.d.ts","sourceRoot":"","sources":["../../../../src/processors/observational-memory/observation-strategies/resource-scoped.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAc1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAC3C,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAExF,qBAAa,iCAAkC,SAAQ,mBAAmB;IACxE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4B;IACtD,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,OAAO,CAAC,mBAAmB,CAAwC;IACnE,OAAO,CAAC,qBAAqB,CAA6B;IAC1D,OAAO,CAAC,iBAAiB,CAA6B;IACtD,OAAO,CAAC,WAAW,CAAgB;IACnC,OAAO,CAAC,gBAAgB,CAAwC;IAChE,OAAO,CAAC,kBAAkB,CAGtB;IACJ,OAAO,CAAC,eAAe,CAAuD;IAC9E,OAAO,CAAC,kBAAkB,CAIlB;IACR,OAAO,CAAC,qBAAqB,CAGzB;gBAEQ,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,kBAAkB;IAKxD,IAAI,SAAS,YAEZ;IACD,IAAI,eAAe,YAElB;IAEK,OAAO;kBA+DgB,eAAe,EAAE;;;IA4DxC,gBAAgB,CAAC,OAAO,EAAE,MAAM;IAwBhC,OAAO,CAAC,qBAAqB,EAAE,MAAM,EAAE,SAAS,EAAE,eAAe,EAAE;;;;;;;;IA6DnE,OAAO,CAAC,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IA2E7F,OAAO,CAAC,SAAS,EAAE,oBAAoB;IAmDvC,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,oBAAoB;IAwB/D,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAkBxD"}

package/dist/processors/observational-memory/observation-strategies/sync.d.ts

@@ -0,0 +1,35 @@
+import type { MastraDBMessage } from '@mastra/core/agent';
+import { ObservationStrategy } from './base.js';
+import type { StrategyDeps } from './base.js';
+import type { ObservationRunOpts, ObserverOutput, ProcessedObservation } from './types.js';
+export declare class SyncObservationStrategy extends ObservationStrategy {
+    private readonly startedAt;
+    private readonly lastMessage;
+    private cycleId?;
+    private tokensToObserve;
+    private observerResult;
+    constructor(deps: StrategyDeps, opts: ObservationRunOpts);
+    get needsLock(): boolean;
+    get needsReflection(): boolean;
+    prepare(): Promise<{
+        messages: MastraDBMessage[];
+        existingObservations: string;
+    }>;
+    emitStartMarkers(cycleId: string): Promise<void>;
+    observe(existingObservations: string, messages: MastraDBMessage[]): Promise<{
+        observations: string;
+        currentTask?: string;
+        suggestedContinuation?: string;
+        threadTitle?: string;
+        usage?: {
+            inputTokens?: number;
+            outputTokens?: number;
+            totalTokens?: number;
+        };
+    }>;
+    process(output: ObserverOutput, existingObservations: string): Promise<ProcessedObservation>;
+    persist(processed: ProcessedObservation): Promise<void>;
+    emitEndMarkers(cycleId: string, processed: ProcessedObservation): Promise<void>;
+    emitFailedMarkers(cycleId: string, error: unknown): Promise<void>;
+}
+//# sourceMappingURL=sync.d.ts.map

package/dist/processors/observational-memory/observation-strategies/sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../../src/processors/observational-memory/observation-strategies/sync.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAa1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAC3C,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAExF,qBAAa,uBAAwB,SAAQ,mBAAmB;IAC9D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4B;IACtD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA8B;IAC1D,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,cAAc,CAAkB;gBAE5B,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,kBAAkB;IAKxD,IAAI,SAAS,YAEZ;IACD,IAAI,eAAe,YAElB;IAEK,OAAO;;;;IAyCP,gBAAgB,CAAC,OAAO,EAAE,MAAM;IAgBhC,OAAO,CAAC,oBAAoB,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE;;;;;;uBAhBpC,CAAC;wBACrB,CAAA;uBACP,CAAC;;;IA6BH,OAAO,CAAC,MAAM,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IA8C5F,OAAO,CAAC,SAAS,EAAE,oBAAoB;IA6CvC,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,oBAAoB;IAmB/D,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAcxD"}

package/dist/processors/observational-memory/observation-strategies/types.d.ts

@@ -0,0 +1,55 @@
+import type { MastraDBMessage } from '@mastra/core/agent';
+import type { ProcessorStreamWriter } from '@mastra/core/processors';
+import type { RequestContext } from '@mastra/core/request-context';
+import type { ObservationalMemoryRecord } from '@mastra/core/storage';
+import type { ObserveHooks } from '../types.js';
+/** Parameters for running an observation via a strategy. */
+export interface ObservationRunOpts {
+    record: ObservationalMemoryRecord;
+    threadId: string;
+    resourceId?: string;
+    messages: MastraDBMessage[];
+    /** Pre-generated cycle ID (async buffer only — sync/resource auto-generate). */
+    cycleId?: string;
+    /** Pre-captured start timestamp (async buffer only). */
+    startedAt?: string;
+    writer?: ProcessorStreamWriter;
+    abortSignal?: AbortSignal;
+    reflectionHooks?: Pick<ObserveHooks, 'onReflectionStart' | 'onReflectionEnd'>;
+    requestContext?: RequestContext;
+}
+/** Output from calling the observer agent. */
+export interface ObserverOutput {
+    observations: string;
+    currentTask?: string;
+    suggestedContinuation?: string;
+    threadTitle?: string;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    };
+}
+/** Processed observation ready for persistence. */
+export interface ProcessedObservation {
+    observations: string;
+    observationTokens: number;
+    cycleObservationTokens: number;
+    observedMessageIds: string[];
+    lastObservedAt: Date;
+    threadMetadataUpdates?: Array<{
+        threadId: string;
+        lastObservedAt: string;
+        suggestedResponse?: string;
+        currentTask?: string;
+        threadTitle?: string;
+        lastObservedMessageCursor?: {
+            createdAt: string;
+            id: string;
+        };
+    }>;
+    suggestedContinuation?: string;
+    currentTask?: string;
+    threadTitle?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/processors/observational-memory/observation-strategies/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/processors/observational-memory/observation-strategies/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAEtE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C,4DAA4D;AAC5D,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,yBAAyB,CAAC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,eAAe,EAAE,CAAC;IAE5B,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,eAAe,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,mBAAmB,GAAG,iBAAiB,CAAC,CAAC;IAC9E,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,8CAA8C;AAC9C,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/E;AAED,mDAAmD;AACnD,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,cAAc,EAAE,IAAI,CAAC;IACrB,qBAAqB,CAAC,EAAE,KAAK,CAAC;QAC5B,QAAQ,EAAE,MAAM,CAAC;QACjB,cAAc,EAAE,MAAM,CAAC;QACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,yBAAyB,CAAC,EAAE;YAAE,SAAS,EAAE,MAAM,CAAC;YAAC,EAAE,EAAE,MAAM,CAAA;SAAE,CAAC;KAC/D,CAAC,CAAC;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB"}

package/dist/processors/observational-memory/observation-turn/index.d.ts

@@ -0,0 +1,4 @@
+export { ObservationTurn } from './turn.js';
+export { ObservationStep } from './step.js';
+export type { TurnContext, StepContext, TurnResult } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/processors/observational-memory/observation-turn/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/processors/observational-memory/observation-turn/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AACzC,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC"}

package/dist/processors/observational-memory/observation-turn/step.d.ts

@@ -0,0 +1,34 @@
+import type { ObservationTurn } from './turn.js';
+import type { StepContext } from './types.js';
+/**
+ * Represents a single step in the agentic loop within an observation turn.
+ *
+ * Created via `turn.step(stepNumber)`. Call `prepare()` before the agent generates.
+ * The previous step's output is finalized automatically when the next step is created
+ * or when `turn.end()` is called.
+ */
+export declare class ObservationStep {
+    private readonly turn;
+    readonly stepNumber: number;
+    private _prepared;
+    private _context?;
+    constructor(turn: ObservationTurn, stepNumber: number);
+    /** Whether this step has been prepared. */
+    get prepared(): boolean;
+    /** Step context from prepare(). Throws if prepare() hasn't been called. */
+    get context(): StepContext;
+    /**
+     * Prepare this step for agent generation.
+     *
+     * For step 0: activates buffered chunks, checks reflection, builds system message, filters observed.
+     * For step > 0: checks thresholds, triggers buffer/observe, saves previous messages,
+     * builds system message, filters observed.
+     */
+    prepare(): Promise<StepContext>;
+    /**
+     * Run the full threshold observation pipeline:
+     * waitForBuffering → re-check → activate → reflect → blockAfter gate → observe
+     */
+    private runThresholdObservation;
+}
+//# sourceMappingURL=step.d.ts.map

package/dist/processors/observational-memory/observation-turn/step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step.d.ts","sourceRoot":"","sources":["../../../../src/processors/observational-memory/observation-turn/step.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C;;;;;;GAMG;AACH,qBAAa,eAAe;IAKxB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM;IAL7B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,CAAc;gBAGZ,IAAI,EAAE,eAAe,EAC7B,UAAU,EAAE,MAAM;IAG7B,2CAA2C;IAC3C,IAAI,QAAQ,YAEX;IAED,2EAA2E;IAC3E,IAAI,OAAO,IAAI,WAAW,CAGzB;IAED;;;;;;OAMG;IACG,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC;IAiNrC;;;OAGG;YACW,uBAAuB;CAkEtC"}

package/dist/processors/observational-memory/observation-turn/turn.d.ts

@@ -0,0 +1,84 @@
+import type { MessageList } from '@mastra/core/agent';
+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 { ObservationStep } from './step.js';
+import type { 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 {
+    readonly om: ObservationalMemory;
+    readonly threadId: string;
+    readonly resourceId: string | undefined;
+    readonly messageList: MessageList;
+    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;
+    constructor(om: ObservationalMemory, threadId: string, resourceId: string | undefined, 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;
+    /**
+     * 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, await in-flight buffering, return final 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

package/dist/processors/observational-memory/observation-turn/turn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn.d.ts","sourceRoot":"","sources":["../../../../src/processors/observational-memory/observation-turn/turn.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAEtE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE1D,OAAO,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,eAAe;IAoBxB,QAAQ,CAAC,EAAE,EAAE,mBAAmB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS;IACvC,QAAQ,CAAC,WAAW,EAAE,WAAW;IAtBnC,OAAO,CAAC,OAAO,CAAC,CAA4B;IAC5C,OAAO,CAAC,QAAQ,CAAC,CAAc;IAC/B,OAAO,CAAC,YAAY,CAAC,CAAkB;IACvC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAS;IAEvB,8FAA8F;IAC9F,OAAO,CAAC,uBAAuB,CAAM;IAErC,6FAA6F;IAC7F,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAE/B,mDAAmD;IACnD,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAE/B,sDAAsD;IACtD,cAAc,CAAC,EAAE,cAAc,CAAC;gBAGrB,EAAE,EAAE,mBAAmB,EACvB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,WAAW,EAAE,WAAW;IAGnC,uFAAuF;IACvF,IAAI,MAAM,IAAI,yBAAyB,CAGtC;IAED,yCAAyC;IACzC,IAAI,OAAO,IAAI,WAAW,CAGzB;IAED,uCAAuC;IACvC,IAAI,WAAW,IAAI,eAAe,GAAG,SAAS,CAE7C;IAED;;;;;OAKG;IACG,KAAK,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,WAAW,CAAC;IAsCjE;;;OAGG;IACH,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe;IAQzC;;OAEG;IACG,GAAG,IAAI,OAAO,CAAC,UAAU,CAAC;IAuChC;;;OAGG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAIpC;;;OAGG;IACG,0BAA0B,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;CAUhE"}

package/dist/processors/observational-memory/observation-turn/types.d.ts

@@ -0,0 +1,38 @@
+import type { MastraDBMessage } from '@mastra/core/agent';
+import type { ObservationalMemoryRecord } from '@mastra/core/storage';
+/** Returned by `turn.start()` — the loaded context for this turn. */
+export interface TurnContext {
+    messages: MastraDBMessage[];
+    systemMessage: string | undefined;
+    continuation: MastraDBMessage | undefined;
+    otherThreadsContext: string | undefined;
+    record: ObservationalMemoryRecord;
+}
+/** Returned by `step.prepare()` — what the agent needs for this step. */
+export interface StepContext {
+    /** System messages containing observations (one per cache-stable chunk). */
+    systemMessage: string[] | undefined;
+    /** Whether buffered chunks were activated in this step. */
+    activated: boolean;
+    /** Whether a sync observation was triggered in this step. */
+    observed: boolean;
+    /** Whether an async buffer was triggered in this step. */
+    buffered: boolean;
+    /** Whether reflection was triggered in this step. */
+    reflected: boolean;
+    /** Current status snapshot from getStatus(). */
+    status: {
+        pendingTokens: number;
+        threshold: number;
+        effectiveObservationTokensThreshold: number;
+        shouldObserve: boolean;
+        shouldBuffer: boolean;
+        shouldReflect: boolean;
+        canActivate: boolean;
+    };
+}
+/** Returned by `turn.end()` — final turn state. */
+export interface TurnResult {
+    record: ObservationalMemoryRecord;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/processors/observational-memory/observation-turn/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/processors/observational-memory/observation-turn/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAEtE,qEAAqE;AACrE,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,YAAY,EAAE,eAAe,GAAG,SAAS,CAAC;IAC1C,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,MAAM,EAAE,yBAAyB,CAAC;CACnC;AAED,yEAAyE;AACzE,MAAM,WAAW,WAAW;IAC1B,4EAA4E;IAC5E,aAAa,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACpC,2DAA2D;IAC3D,SAAS,EAAE,OAAO,CAAC;IACnB,6DAA6D;IAC7D,QAAQ,EAAE,OAAO,CAAC;IAClB,0DAA0D;IAC1D,QAAQ,EAAE,OAAO,CAAC;IAClB,qDAAqD;IACrD,SAAS,EAAE,OAAO,CAAC;IACnB,gDAAgD;IAChD,MAAM,EAAE;QACN,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,mCAAmC,EAAE,MAAM,CAAC;QAC5C,aAAa,EAAE,OAAO,CAAC;QACvB,YAAY,EAAE,OAAO,CAAC;QACtB,aAAa,EAAE,OAAO,CAAC;QACvB,WAAW,EAAE,OAAO,CAAC;KACtB,CAAC;CACH;AAED,mDAAmD;AACnD,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,yBAAyB,CAAC;CACnC"}