@animus-labs/cortex 0.2.0

package/dist/compaction/observational/buffering.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Buffering coordinator for the observational memory system.
+ *
+ * Manages the async lifecycle of observer and reflector operations,
+ * ensuring at-most-one-in-flight per operation type, computing dynamic
+ * buffer intervals, and handling abort/cleanup.
+ *
+ * The coordinator does not own the observation slot or conversation
+ * history. It produces observation chunks and buffered reflections that
+ * the ObservationalMemoryEngine consumes during activation.
+ *
+ * References:
+ *   - observational-memory-architecture.md (Observer System, Reflector System)
+ *   - observer.ts (runObserver)
+ *   - reflector.ts (runReflector)
+ */
+import type { CompleteFn } from '../compaction.js';
+import type { AgentMessage } from '../../context-manager.js';
+import type { ObservationChunk } from './types.js';
+/**
+ * Coordinates async observer and reflector operations for the
+ * observational memory system.
+ *
+ * Ensures at-most-one observer and at-most-one reflector call are
+ * in-flight at any time. Completed observer results are stored as
+ * {@link ObservationChunk}s until the engine activates them. Completed
+ * reflector results are stored until the engine swaps them in.
+ *
+ * All in-flight operations are fire-and-forget from the caller's
+ * perspective. The coordinator attaches `.then()` / `.catch()` handlers
+ * internally and never surfaces unhandled rejections.
+ */
+export declare class BufferingCoordinator {
+    private chunks;
+    private bufferWatermark;
+    private inFlightObserver;
+    private inFlightObserverEndIndex;
+    private inFlightReflector;
+    private bufferedReflection;
+    private bufferedReflectionCompressionLevel;
+    private aborted;
+    /**
+     * Activation epoch. Incremented each time activation consumes chunks or
+     * a sync observer trims messages. In-flight observers capture the epoch
+     * at launch and discard their result if the epoch has changed by the time
+     * they complete. This prevents stale chunks from landing after sync
+     * activation has already processed those messages.
+     */
+    private activationEpoch;
+    /**
+     * Compute the dynamic buffer interval based on current context state.
+     *
+     * The interval targets `bufferTargetCycles` observer calls between the
+     * current utilization and the activation threshold. It is clamped between
+     * `bufferMinTokens` and `effectiveBufferCap` (the lesser of
+     * `bufferTokenCap` and 60% of the utility model's context window).
+     *
+     * @param tokensUntilActivation - tokens remaining before activation threshold
+     * @param config - buffer interval configuration
+     * @returns the buffer interval in tokens
+     */
+    computeBufferInterval(tokensUntilActivation: number, config: {
+        bufferTargetCycles: number;
+        bufferTokenCap: number;
+        bufferMinTokens: number;
+        utilityModelContextWindow: number;
+    }): number;
+    /**
+     * Check if a buffer observation should be triggered based on
+     * unobserved tokens.
+     *
+     * Returns true when the unobserved token count meets or exceeds the
+     * buffer interval, no observer call is currently in flight, and the
+     * coordinator has not been aborted.
+     *
+     * @param unobservedTokens - estimated tokens of messages after the buffer watermark
+     * @param bufferInterval - computed from {@link computeBufferInterval}
+     * @returns true if a buffer observation should launch
+     */
+    shouldBuffer(unobservedTokens: number, bufferInterval: number): boolean;
+    /**
+     * Launch an async observer call. Does NOT await it.
+     *
+     * Stores the in-flight promise and tracks the end index of messages
+     * being processed. When the observer completes, its output is converted
+     * to an {@link ObservationChunk} and appended to the internal chunk
+     * list. If the coordinator has been aborted before the observer
+     * completes, the result is discarded.
+     *
+     * @param complete - the LLM completion function
+     * @param messages - the unobserved messages to process (snapshot)
+     * @param endIndex - the index in conversation history where these messages end
+     * @param previousObservations - current observation text for context
+     * @param config - observer config
+     * @param logger - optional logger for error reporting
+     */
+    launchObserver(complete: CompleteFn, messages: AgentMessage[], endIndex: number, previousObservations: string | null, config: {
+        previousObserverTokens: number;
+        observerInstruction?: string;
+    }, logger?: {
+        warn: (msg: string) => void;
+    }): void;
+    /**
+     * Check if there are completed buffer chunks ready for activation.
+     */
+    hasCompletedChunks(): boolean;
+    /**
+     * Get all completed chunks and the watermark up to which messages
+     * are covered.
+     *
+     * Does NOT clear state. Call {@link commitActivation} after
+     * successfully activating.
+     */
+    getCompletedChunks(): {
+        chunks: ObservationChunk[];
+        watermark: number;
+    };
+    /**
+     * Called after successful activation to reset buffer state.
+     *
+     * Clears accumulated chunks and resets the watermark to 0 since the
+     * messages it pointed to have been removed from the conversation
+     * history.
+     */
+    commitActivation(): void;
+    /**
+     * Check if reflection should be triggered based on observation token count.
+     *
+     * Returns:
+     * - `'sync'` when observation tokens are at or above the effective threshold
+     *   (the caller decides whether to use a buffered reflection or force a sync call)
+     * - `'async'` when observation tokens are between the buffer activation point
+     *   and the threshold, and no reflector is currently in flight
+     * - `'none'` otherwise
+     *
+     * @param observationTokens - current observation slot token count
+     * @param effectiveThreshold - from computeEffectiveReflectionThreshold
+     * @param reflectionBufferActivation - fraction at which to start async reflection
+     * @returns action indicator
+     */
+    shouldReflect(observationTokens: number, effectiveThreshold: number, reflectionBufferActivation: number): 'none' | 'async' | 'sync';
+    /**
+     * Launch an async reflector call. Does NOT await it.
+     *
+     * When the reflector completes, its result is stored in
+     * `bufferedReflection` for later consumption via
+     * {@link consumeBufferedReflection}. If the coordinator has been
+     * aborted before the reflector completes, the result is discarded.
+     *
+     * @param complete - the LLM completion function
+     * @param observations - the current observation text to consolidate
+     * @param config - reflector config
+     * @param logger - optional logger for error reporting
+     */
+    launchReflector(complete: CompleteFn, observations: string, config: {
+        reflectionThreshold: number;
+        reflectorInstruction?: string;
+    }, logger?: {
+        warn: (msg: string) => void;
+    }): void;
+    /**
+     * Check if a buffered reflection is ready to swap in.
+     */
+    hasBufferedReflection(): boolean;
+    /**
+     * Get the buffered reflection and clear it.
+     *
+     * Returns the consolidated observations and the compression level that
+     * was applied, or null if no buffered reflection is available.
+     */
+    consumeBufferedReflection(): {
+        observations: string;
+        compressionLevel: number;
+    } | null;
+    /**
+     * Get the current state for session persistence.
+     *
+     * In-flight operations are NOT included (they are lost on session
+     * save). Only completed chunks and the watermark are persisted.
+     */
+    getState(): {
+        chunks: ObservationChunk[];
+        watermark: number;
+    };
+    /**
+     * Restore state from a previous session.
+     */
+    restoreState(state: {
+        chunks: ObservationChunk[];
+        watermark: number;
+    }): void;
+    /**
+     * Abort all in-flight operations. Called on agent destruction.
+     *
+     * Sets the aborted flag so that any in-flight promise handlers
+     * discard their results when they eventually resolve.
+     */
+    abort(): void;
+    /**
+     * Whether an observer call is currently in flight.
+     */
+    isObserverInFlight(): boolean;
+    /**
+     * Whether a reflector call is currently in flight.
+     */
+    isReflectorInFlight(): boolean;
+    /**
+     * Get the buffer watermark (index into conversation history marking
+     * where the last completed observation ended).
+     */
+    getWatermark(): number;
+    /**
+     * Set the watermark. Used during initialization or after manual
+     * adjustments to the conversation history.
+     */
+    setWatermark(index: number): void;
+    /**
+     * Advance the activation epoch. Called when a sync activation trims
+     * messages outside of the normal commitActivation() flow (e.g., the
+     * engine's Step 2 sync observer path). This invalidates any in-flight
+     * observers that were launched before the sync activation.
+     */
+    advanceEpoch(): void;
+}
+//# sourceMappingURL=buffering.d.ts.map

package/dist/compaction/observational/buffering.d.ts.map

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

package/dist/compaction/observational/buffering.js

@@ -0,0 +1,354 @@
+/**
+ * Buffering coordinator for the observational memory system.
+ *
+ * Manages the async lifecycle of observer and reflector operations,
+ * ensuring at-most-one-in-flight per operation type, computing dynamic
+ * buffer intervals, and handling abort/cleanup.
+ *
+ * The coordinator does not own the observation slot or conversation
+ * history. It produces observation chunks and buffered reflections that
+ * the ObservationalMemoryEngine consumes during activation.
+ *
+ * References:
+ *   - observational-memory-architecture.md (Observer System, Reflector System)
+ *   - observer.ts (runObserver)
+ *   - reflector.ts (runReflector)
+ */
+import { runObserver } from './observer.js';
+import { runReflector } from './reflector.js';
+import { estimateTokens } from '../../token-estimator.js';
+// ---------------------------------------------------------------------------
+// BufferingCoordinator
+// ---------------------------------------------------------------------------
+/**
+ * Coordinates async observer and reflector operations for the
+ * observational memory system.
+ *
+ * Ensures at-most-one observer and at-most-one reflector call are
+ * in-flight at any time. Completed observer results are stored as
+ * {@link ObservationChunk}s until the engine activates them. Completed
+ * reflector results are stored until the engine swaps them in.
+ *
+ * All in-flight operations are fire-and-forget from the caller's
+ * perspective. The coordinator attaches `.then()` / `.catch()` handlers
+ * internally and never surfaces unhandled rejections.
+ */
+export class BufferingCoordinator {
+    // --- Internal state ---
+    chunks = [];
+    bufferWatermark = 0;
+    inFlightObserver = null;
+    inFlightObserverEndIndex = null;
+    inFlightReflector = null;
+    bufferedReflection = null;
+    bufferedReflectionCompressionLevel = 0;
+    aborted = false;
+    /**
+     * Activation epoch. Incremented each time activation consumes chunks or
+     * a sync observer trims messages. In-flight observers capture the epoch
+     * at launch and discard their result if the epoch has changed by the time
+     * they complete. This prevents stale chunks from landing after sync
+     * activation has already processed those messages.
+     */
+    activationEpoch = 0;
+    // -------------------------------------------------------------------------
+    // Buffer Interval Calculation
+    // -------------------------------------------------------------------------
+    /**
+     * Compute the dynamic buffer interval based on current context state.
+     *
+     * The interval targets `bufferTargetCycles` observer calls between the
+     * current utilization and the activation threshold. It is clamped between
+     * `bufferMinTokens` and `effectiveBufferCap` (the lesser of
+     * `bufferTokenCap` and 60% of the utility model's context window).
+     *
+     * @param tokensUntilActivation - tokens remaining before activation threshold
+     * @param config - buffer interval configuration
+     * @returns the buffer interval in tokens
+     */
+    computeBufferInterval(tokensUntilActivation, config) {
+        const effectiveBufferCap = Math.min(config.bufferTokenCap, config.utilityModelContextWindow * 0.6);
+        const dynamicInterval = tokensUntilActivation / config.bufferTargetCycles;
+        return Math.max(Math.min(dynamicInterval, effectiveBufferCap), config.bufferMinTokens);
+    }
+    // -------------------------------------------------------------------------
+    // Observer Buffering
+    // -------------------------------------------------------------------------
+    /**
+     * Check if a buffer observation should be triggered based on
+     * unobserved tokens.
+     *
+     * Returns true when the unobserved token count meets or exceeds the
+     * buffer interval, no observer call is currently in flight, and the
+     * coordinator has not been aborted.
+     *
+     * @param unobservedTokens - estimated tokens of messages after the buffer watermark
+     * @param bufferInterval - computed from {@link computeBufferInterval}
+     * @returns true if a buffer observation should launch
+     */
+    shouldBuffer(unobservedTokens, bufferInterval) {
+        return (unobservedTokens >= bufferInterval &&
+            !this.isObserverInFlight() &&
+            !this.aborted);
+    }
+    /**
+     * Launch an async observer call. Does NOT await it.
+     *
+     * Stores the in-flight promise and tracks the end index of messages
+     * being processed. When the observer completes, its output is converted
+     * to an {@link ObservationChunk} and appended to the internal chunk
+     * list. If the coordinator has been aborted before the observer
+     * completes, the result is discarded.
+     *
+     * @param complete - the LLM completion function
+     * @param messages - the unobserved messages to process (snapshot)
+     * @param endIndex - the index in conversation history where these messages end
+     * @param previousObservations - current observation text for context
+     * @param config - observer config
+     * @param logger - optional logger for error reporting
+     */
+    launchObserver(complete, messages, endIndex, previousObservations, config, logger) {
+        if (this.aborted)
+            return;
+        // Estimate tokens from the message snapshot for the chunk metadata
+        const messageTokensObserved = messages.reduce((sum, msg) => {
+            if (typeof msg.content === 'string') {
+                return sum + estimateTokens(msg.content);
+            }
+            if (Array.isArray(msg.content)) {
+                const text = msg.content
+                    .map((part) => {
+                    if (typeof part.text === 'string')
+                        return part.text;
+                    return JSON.stringify(part);
+                })
+                    .join(' ');
+                return sum + estimateTokens(text);
+            }
+            return sum;
+        }, 0);
+        const promise = runObserver(complete, messages, previousObservations, config);
+        this.inFlightObserver = promise;
+        this.inFlightObserverEndIndex = endIndex;
+        // Capture the activation epoch at launch. If activation fires (sync or
+        // chunk-based) before this observer completes, the epoch will have
+        // advanced and the result is stale (those messages were already observed).
+        const launchEpoch = this.activationEpoch;
+        promise
+            .then((output) => {
+            if (this.aborted)
+                return;
+            // Discard if activation already processed these messages
+            if (this.activationEpoch !== launchEpoch) {
+                this.inFlightObserver = null;
+                this.inFlightObserverEndIndex = null;
+                return;
+            }
+            const chunk = {
+                observations: output.observations,
+                messageTokensObserved,
+                createdAt: new Date(),
+            };
+            if (output.currentTask) {
+                chunk.currentTask = output.currentTask;
+            }
+            if (output.suggestedResponse) {
+                chunk.suggestedResponse = output.suggestedResponse;
+            }
+            this.chunks.push(chunk);
+            this.bufferWatermark = this.inFlightObserverEndIndex ?? endIndex;
+            this.inFlightObserver = null;
+            this.inFlightObserverEndIndex = null;
+        })
+            .catch((err) => {
+            const message = err instanceof Error ? err.message : String(err);
+            if (logger) {
+                logger.warn(`Observer buffer call failed: ${message}`);
+            }
+            this.inFlightObserver = null;
+            this.inFlightObserverEndIndex = null;
+        });
+    }
+    /**
+     * Check if there are completed buffer chunks ready for activation.
+     */
+    hasCompletedChunks() {
+        return this.chunks.length > 0;
+    }
+    /**
+     * Get all completed chunks and the watermark up to which messages
+     * are covered.
+     *
+     * Does NOT clear state. Call {@link commitActivation} after
+     * successfully activating.
+     */
+    getCompletedChunks() {
+        return { chunks: [...this.chunks], watermark: this.bufferWatermark };
+    }
+    /**
+     * Called after successful activation to reset buffer state.
+     *
+     * Clears accumulated chunks and resets the watermark to 0 since the
+     * messages it pointed to have been removed from the conversation
+     * history.
+     */
+    commitActivation() {
+        this.chunks = [];
+        this.bufferWatermark = 0;
+        this.activationEpoch++;
+    }
+    // -------------------------------------------------------------------------
+    // Reflector Buffering
+    // -------------------------------------------------------------------------
+    /**
+     * Check if reflection should be triggered based on observation token count.
+     *
+     * Returns:
+     * - `'sync'` when observation tokens are at or above the effective threshold
+     *   (the caller decides whether to use a buffered reflection or force a sync call)
+     * - `'async'` when observation tokens are between the buffer activation point
+     *   and the threshold, and no reflector is currently in flight
+     * - `'none'` otherwise
+     *
+     * @param observationTokens - current observation slot token count
+     * @param effectiveThreshold - from computeEffectiveReflectionThreshold
+     * @param reflectionBufferActivation - fraction at which to start async reflection
+     * @returns action indicator
+     */
+    shouldReflect(observationTokens, effectiveThreshold, reflectionBufferActivation) {
+        if (observationTokens >= effectiveThreshold) {
+            return 'sync';
+        }
+        const asyncTrigger = effectiveThreshold * reflectionBufferActivation;
+        if (observationTokens >= asyncTrigger &&
+            !this.isReflectorInFlight() &&
+            !this.aborted) {
+            return 'async';
+        }
+        return 'none';
+    }
+    /**
+     * Launch an async reflector call. Does NOT await it.
+     *
+     * When the reflector completes, its result is stored in
+     * `bufferedReflection` for later consumption via
+     * {@link consumeBufferedReflection}. If the coordinator has been
+     * aborted before the reflector completes, the result is discarded.
+     *
+     * @param complete - the LLM completion function
+     * @param observations - the current observation text to consolidate
+     * @param config - reflector config
+     * @param logger - optional logger for error reporting
+     */
+    launchReflector(complete, observations, config, logger) {
+        if (this.aborted)
+            return;
+        const promise = runReflector(complete, observations, config);
+        this.inFlightReflector = promise;
+        promise
+            .then((output) => {
+            if (this.aborted)
+                return;
+            this.bufferedReflection = output.observations;
+            this.bufferedReflectionCompressionLevel = output.compressionLevel;
+            this.inFlightReflector = null;
+        })
+            .catch((err) => {
+            const message = err instanceof Error ? err.message : String(err);
+            if (logger) {
+                logger.warn(`Reflector buffer call failed: ${message}`);
+            }
+            this.inFlightReflector = null;
+        });
+    }
+    /**
+     * Check if a buffered reflection is ready to swap in.
+     */
+    hasBufferedReflection() {
+        return this.bufferedReflection !== null;
+    }
+    /**
+     * Get the buffered reflection and clear it.
+     *
+     * Returns the consolidated observations and the compression level that
+     * was applied, or null if no buffered reflection is available.
+     */
+    consumeBufferedReflection() {
+        if (this.bufferedReflection === null)
+            return null;
+        const result = {
+            observations: this.bufferedReflection,
+            compressionLevel: this.bufferedReflectionCompressionLevel,
+        };
+        this.bufferedReflection = null;
+        this.bufferedReflectionCompressionLevel = 0;
+        return result;
+    }
+    // -------------------------------------------------------------------------
+    // Lifecycle
+    // -------------------------------------------------------------------------
+    /**
+     * Get the current state for session persistence.
+     *
+     * In-flight operations are NOT included (they are lost on session
+     * save). Only completed chunks and the watermark are persisted.
+     */
+    getState() {
+        return { chunks: [...this.chunks], watermark: this.bufferWatermark };
+    }
+    /**
+     * Restore state from a previous session.
+     */
+    restoreState(state) {
+        this.chunks = [...state.chunks];
+        this.bufferWatermark = state.watermark;
+    }
+    /**
+     * Abort all in-flight operations. Called on agent destruction.
+     *
+     * Sets the aborted flag so that any in-flight promise handlers
+     * discard their results when they eventually resolve.
+     */
+    abort() {
+        this.aborted = true;
+        this.inFlightObserver = null;
+        this.inFlightObserverEndIndex = null;
+        this.inFlightReflector = null;
+    }
+    /**
+     * Whether an observer call is currently in flight.
+     */
+    isObserverInFlight() {
+        return this.inFlightObserver !== null;
+    }
+    /**
+     * Whether a reflector call is currently in flight.
+     */
+    isReflectorInFlight() {
+        return this.inFlightReflector !== null;
+    }
+    /**
+     * Get the buffer watermark (index into conversation history marking
+     * where the last completed observation ended).
+     */
+    getWatermark() {
+        return this.bufferWatermark;
+    }
+    /**
+     * Set the watermark. Used during initialization or after manual
+     * adjustments to the conversation history.
+     */
+    setWatermark(index) {
+        this.bufferWatermark = index;
+    }
+    /**
+     * Advance the activation epoch. Called when a sync activation trims
+     * messages outside of the normal commitActivation() flow (e.g., the
+     * engine's Step 2 sync observer path). This invalidates any in-flight
+     * observers that were launched before the sync activation.
+     */
+    advanceEpoch() {
+        this.activationEpoch++;
+    }
+}
+//# sourceMappingURL=buffering.js.map

package/dist/compaction/observational/buffering.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffering.js","sourceRoot":"","sources":["../../../src/compaction/observational/buffering.ts"],"names":[],"mappings":"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"}